Fleet overlay: conventions for multi-repo projects (hub-and-spoke)

[PBNZ]

Retrospective finding — refs #10 (post-retrospective addendum: multi-repo migration, day 2).

Context

RepoKit is repo-scoped: every convention (AGENTS/CLAUDE pairing, START-HERE, checkpoint, changelog, ADRs) lives and terminates inside one repository. A real migration — one product outgrowing its single repo into several (apps in an organization, an infra repo deliberately kept on a personal account, a coordination repo) — showed the standard has nothing to say the moment a second repo exists. The cross-repo layer had to be invented ad hoc mid-migration. What was invented worked on first contact and is worth standardising:

• A hub repo as the fleet router. One coordination repo owns everything spanning repos: the working agreement, cross-cutting ADRs, venture-level documents, cross-repo issues, and a fleet-level agent file. Its AGENTS.md declares itself the router: placement/lookup questions any spoke can't answer resolve there.
• The scope test — one sentence that settles every placement question for docs and issues: "would this still matter if the repo you're sitting in didn't exist? Yes → hub; no → stays here." Written into every spoke's AGENTS.md.
• Sibling-clone convention. All fleet repos clone as sibling directories, so the hub is always at a fixed relative path from any spoke — agents know where to look on disk and to clone it if missing.
• Spoke inheritance is three lines. A new spoke repo joins the fleet by copying the router pointer, the scope test, and the sibling-clone line into its AGENTS.md. No other ongoing cost.
• Docs follow ownership, with pointer stubs. When a doc's scope turns out to be venture-level, it moves to the hub and a short stub stays at the old path so existing links (issues, commits) keep resolving. Git history of the pre-move file stays in the old repo — noted in the stub.
• One project board spans the fleet (org-owned; cross-owner items verified working — issues from a personal-account repo sit on an org project fine).

Tasks

• Author a fleet overlay reference (e.g. standard/fleet.md): when to split (a repo earns existence by own deployable or own audience), the hub's minimal contents, the router/scope-test/sibling-clone/inheritance conventions, docs-move-with-stub rule.
• Define the hub as a repo type or profile (docs-only collection + the router role) so scaffolding can offer it.
• Cross-reference the labelling standard (Define a RepoKit labelling standard (issues/PRs) with per-repo bootstrap #11: identical label set per fleet repo) and the agent-collaboration reference (Add an agent-collaboration reference: board discipline, pickup/handoff, signatures, preflight #15: one board, fleet-wide loop).

Acceptance criteria

• A second repo joining an existing RepoKit project has a documented path: what to create, what moves, what each AGENTS.md must say.
• The scope test appears verbatim in the standard so every fleet states it identically.

— 🤖 Claude, on behalf of @PBNZ

[PBNZ]

Triage: accepted (adapted: the hub ships as a documented profile of the collection type — /new-repo can offer it once that type's stub scaffolding is filled in; no half-built templates).

Landed on PR #18 (commit a0fb270): standard/fleet.md — when a repo earns existence (own deployable or own audience), the hub's minimal contents and router declaration, the scope test verbatim ("would this still matter if the repo you're sitting in didn't exist? Yes → hub; no → stays here"), the sibling-clone convention (../<hub-name>/), the copy-paste three-line spoke-inheritance block, docs-move-with-stub (including the git-history note), and fleet-wide consistency cross-refs to labels.md (#11, identical label set via gh label clone) and agent-collaboration.md (#15, one board fleet-wide).

— 🤖 Claude, on behalf of @PBNZ

[PBNZ]

Verified on main (f7ab31c): standard/fleet.md with the scope test verbatim, sibling-clone + three-line spoke inheritance, docs-move-with-stub; hub defined as the fleet-hub profile of collection. Closing on @PBNZ's instruction.

— 🤖 Claude, on behalf of @PBNZ