multi-repo-discipline

# Multi-Repo Discipline Roles and commit boundaries when multiple repositories share a parent workspace. Pairs with `configure-plugin:config-sync` — that skill propagates mechanical config; this one defines the discipline layer that says who owns what and when a cross-repo commit needs user confirmation. ## When to Use This Skill | Use this skill when… | Skip when… | |---------------------|------------| | The cwd is inside a parent directory that contains other git repos | Working in a single isolated repo | | A sibling `CLAUDE.md` names the current repo | No cross-repo relationship exists | | Dispatching agents whose scope could span sibling repos | Single-repo agent fan-out | | Updating a shared spec that other repos consume | Internal change with no downstream | | About to edit a sibling's `CLAUDE.md` or `.claude/` config | Edits confined to current repo | ## Detection Heuristic Run before applying any discipline: ```bash # Parent directory contains other git repos? find "$(git rev-parse --show-toplevel)/.." -maxdepth 2 -name .git -type d # Any sibling CLAUDE.md names this repo by directory name? grep -l "$(basename "$(git rev-parse --show-toplevel)")" ../*/CLAUDE.md 2>/dev/null ``` If neither detector produces output, **exit silently** — the rule does not apply to single-repo work. Do not load discipline that does not apply. ## Workspace Roles Classify every repository in the workspace into one of three roles. ### Read-only fixtures Inputs the current project depends on but must never mutate: - Licensed datasets (e.g. game data archives, ML training sets) - Shipped third-party binaries used as reference - Vendored upstream sources consulted for comparison only - Historical snapshots of a migrated-away-from system Discipline: treat as immutable. Never commit to a fixture. If an agent proposes an edit, the edit is a misdirection — redirect to the working repo. ### Upstream / downstream pair Two repositories in the same domain where one derives from the other. Examples: | Upstream | Downstream | |----------|-----------| | Workbench / toolkit | Shipped native port | | Schema-owning repo | Generated client library | | Design tokens | Component library | | Contract repo | Consumer service | Discipline: the downstream may lag the upstream by design. Changes in the upstream **do not** automatically propagate — the orchestrator surfaces the required downstream diff and the human decides when to land it. ### Authoritative repo Single source of truth for shared specs, schemas, or interface contracts. Sibling repos that carry copies of the same material are explicitly downstream. Discipline: updates to the authoritative surface are deliberate. The authoritative repo's commit lands first; downstream updates follow in their own PRs against the sibling repos. ## Commit Boundaries ### Same-repo commits Follow the repo's own conventions. No cross-repo confirmation needed. ### Sibling-repo commits during agent dispatch Cross-repo **edits** during a dispatched agent's run are acceptable when the scope explicitly names the sibling path. Cross-repo **commits in sibling repos require user confirmation** before they land. The pattern: 1. Agent performs the edit in a worktree of the sibling repo. 2. Agent returns the diff in its Return Contract's `Orchestrator action needed` field (see `agent-patterns-plugin:parallel-agent-dispatch` §Verbatim patches). 3. Orchestrator surfaces the diff to the user and requests confirmation. 4. Human decides whether the downstream commit lands now or later. Automatic downstream commits are the failure mode this rule prevents — they drift schemas silently and the next reviewer cannot tell which commit shipped the decision vs which shipped the propagation. ### Sibling's `CLAUDE.md` / `.claude/` / `docs/` Never modify a sibling repo's `CLAUDE.md`, `.claude/` config, or `docs/` as a **side-effect of unrelated work**. These are the sibling repo's authoritative surfaces; touching them mid-unrelated-task is a side-effect bug. When a sibling's Claude configuration genuinely needs an update, dispatch a targeted agent whose scope names the sibling's config explicitly. `configure-plugin:config-sync` handles the mechanical propagation; this rule sets the boundary. ## Authoritative → downstream propagation When the current repo is authoritative and a change affects downstream consumers: 1. Land the change in the authoritative repo first (its own PR, its own review). 2. In the Return Contract (or PR description), cite the downstream repos and the exact change each needs. 3. File follow-up issues or work-orders in the downstream repos — do not inline the propagation. 4. If multiple downstream repos consume the same change, each propagation is its own PR. Checklists embedded in the authoritative PR description often get lost when the PR merges. Prefer follow-up issues per downstream repo, linked from the authoritative PR description. ## Quick Reference ### Decision table | Scenario | Action | |----------|--------| | Edit in current repo | Normal commit | | Agent edit in sibling worktree | OK; commit only with user confirmation | | Sibling's `CLAUDE.md` changed as side-effect | Revert; redirect scope | | Spec change in authoritative repo | Land here; file follow-up in downstream | | Fixture repo edit proposed | Refuse; redirect | ### Checklist before cross-repo commit - [ ] User confirmed the sibling-repo commit? - [ ] Sibling's conventions followed (commit type, scope, PR title)? - [ ] Downstream propagation handled in its own PR, not inlined? - [ ] No unrelated sibling config files touched? ## Related - `configure-plugin:config-sync` — mechanical propagation that this rule gates - `agent-patterns-plugin:parallel-agent-dispatch` — Return Contract's "Orchestrator action needed" field carries cross-repo diffs - `git-plugin:git-coworker-check` — concurrent-writer detection in shared checkouts - `.claude/rules/docs-currency.md` — same-commit discipline (applies to each repo individually) > Evidence: multi-repo sessions where downstream propagation was auto-committed > produced a week-long schema drift that took two follow-up PRs to reconcile. > Surfacing the diff and letting the human decide when to land it avoided > the drift entirely on the next cycle.