skills.rest
the-homeless-god
the-homeless-godCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

umbrella-repository-setup

Designs and audits umbrella repositories coordinating multiple pinned component repositories.

Updated Aug 6, 2021
Search Tags:#spec-driven#monorepo#git submodules#workspace bootstrap#cross-repository#umbrella repository#revision pinning
One-click install
npx skills add https://github.com/the-homeless-god/dotfiles --skill umbrella-repository-setup-the-homeless-god
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: umbrella-repository-setup
Source: https://github.com/the-homeless-god/dotfiles/tree/main/skills/umbrella-repository-setup
Command: npx skills add https://github.com/the-homeless-god/dotfiles --skill umbrella-repository-setup-the-homeless-god

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Cross-repository initiatives often lack a reproducible coordination layer: component revisions drift, agent rules conflict, and analysis artifacts scatter across repos. This Skill establishes an umbrella repository that pins component revisions, defines shared agent rules, and organizes spec-driven artifacts without turning components into a monorepo. ## Core Features & Use Cases - Repository model decision support: Compares pinned submodules, specification-only workspaces, monorepos, and coordinated independent repositories with recorded trade-offs and exit criteria. - Bootstrap runbook: Guides inventory, safe submodule registration, root AGENTS.md hierarchy, constitution and memory files, spec layout, and fresh-clone verification. - Cross-repository analyst protocol: Freezes a revision manifest, builds evidence-based AS-IS architecture views, organizes capability specs, and enforces owned technical-debt tracking. - Use Case: A platform team coordinating five microservice repositories uses this Skill to create an umbrella workspace with pinned submodule SHAs, shared agent rules, an initiative spec with traceability, and a verified fresh-clone onboarding path. ## Quick Start Use the umbrella-repository-setup skill to design an umbrella workspace that pins my three service repositories and sets up shared agent rules and an initiative spec.

Frequently Asked Questions about umbrella-repository-setup

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I coordinate multiple repositories without creating a monorepo?▼

Create an umbrella repository that pins each component as a git submodule at an exact revision, stores shared agent rules and specs at the root, and keeps component source changes in their own repositories and PRs. The umbrella owns coordination artifacts, not component code.

Git submodules vs monorepo for cross-repository projects?▼

Submodules fit when components keep independent lifecycles, owners, and CI but cross-repo work needs one reproducible revision set. A monorepo fits only when one owner, release process, permissions model, and build graph genuinely apply to all components.

How do I safely add existing repositories as git submodules?▼

Verify the umbrella remote and clean worktree, confirm each component remote and chosen revision, then run git submodule add into a new empty path and commit the gitlink pointers. Never delete an existing checkout's .git directory or hand-edit gitlinks to force registration.

Should I use submodule update --remote to keep components current?▼

Avoid automated submodule update --remote in reproducible analysis workflows. Advancing a component should be an explicit reviewed change: select a named branch, tag, or commit, inspect the diff and contract impact, run mapped checks, and commit the pointer with revision evidence.

When should I not use an umbrella repository?▼

Skip the umbrella when one repository already owns the whole change, or when the initiative is small enough that a shared analysis and spec layer adds no lasting value. In those cases coordinated independent repositories with distributed decisions are sufficient.

Related Skills

Explore More Software Engineering Skills→
HiveSpaceTeamHiveSpaceTeam

create-pr

Create pull requests with builds, branches, commits, and pushes.

Official
Advanced
mortenbroesbymortenbroesby
1

planning-and-task-breakdown

Break down complex requests into ordered, verifiable slices with acceptance criteria.

Community
Intermediate
MichaelSolatiMichaelSolati

propagate-design-change

Identify stale architecture decision records affected by game design document revisions.

Community
Advanced
kimen-devkimen-dev

nx-workspace

Explore and analyze Nx monorepo workspaces via CLI JSON output.

Official
Intermediate