@evolvehq/docflow 0.7.0 → 0.9.0

package/README.md

@@ -10,7 +10,9 @@ It installs a `bootstrap` skill that scaffolds (or retrofits) an
 `AGENTS.md` conventions into any repository, plus a set of **lifecycle
 skills** that author, queue, ship, and audit ADRs — so the project can
 be driven by both humans and coding agents from a small set of canonical
-files.
+files. For the formal definition of the conventions — why they help and
+where they fall short — see the
+[methodology](https://evolvehq.github.io/docflow/methodology/).
 
 ## Skills
 
@@ -28,6 +30,7 @@ agent the same skills are invoked as `/skill:<name>` (e.g.
 | audit | `/audit` | Lint the repo against its own conventions — numbering, INDEX sync, plan coverage, **ADR-privacy leaks**, more. |
 | brainstorm | `/brainstorm` | Decompose a problem into candidate ADRs + plan items (proposes drafts; writes nothing until approved). |
 | agent-wave | `/agent-wave` | Orchestrate a wave of parallel worktree subagents over the queue, with checkpoint or continuous supervision. |
+| rollup | `/rollup` | For a multi-repo product: aggregate every member repo's ADRs into one derived, product-wide roll-up (run from the home repo). |
 
 The lifecycle skills all **read `CONVENTIONS.md` first** and honour the
 choices the bootstrap recorded (ADR shape, status lifecycle, integration
@@ -65,10 +68,27 @@ It works equally well on **fresh repos** (scaffolds from zero) and on
 **existing repos** (retrofits, preserving and merging existing files
 rather than overwriting them).
 
+## Multi-repo products
+
+A single product spread across several repositories can run as a
+**federation**. At bootstrap a repo declares whether it is standalone or
+part of a multi-repo product, and whether it is **establishing** a new
+federation or **joining** one — a joining repo only ever writes its own
+back-pointer, never into another repo. You pick a **topology** (central
+decisions repo · distributed · home-repo-plus-local), and the convention
+set keeps numbering contiguous **per repo** while a federation-wide
+identity is the cross-repo key. The `rollup` skill aggregates every
+member's catalogue into one product-wide view, and `audit` gains
+cross-repo checks (membership, identity collisions, dangling references,
+roll-up drift). No tool writes across a repo boundary; consistency is
+declared at the edges and enforced by audit. See the
+[methodology](https://evolvehq.github.io/docflow/methodology/#5-scaling-to-many-repositories)
+for the full model.
+
 ## Install
 
-docflow ships from **one `skills/` tree** to five coding agents — only
-the packaging differs. Two surfaces: the scaffolded **output**
+docflow ships from **one skill source** (`plugins/docflow/skills/`) to
+five coding agents — only the packaging differs. Two surfaces: the scaffolded **output**
 (`AGENTS.md`, the ADR catalogue, `plan/`, `_agent/`) is plain Markdown
 read natively by any agent that loads `AGENTS.md`; the **skills** are
 `SKILL.md` files the host discovers.
@@ -78,12 +98,11 @@ read natively by any agent that loads `AGENTS.md`; the **skills** are
 | Claude Code | native | ✅ | marketplace (below) | `/bootstrap` |
 | Claude Cowork | native | ✅ | same Claude Code plugin | `/bootstrap` |
 | pi | native | ✅ | `pi install npm:@evolvehq/docflow` | `/skill:bootstrap` |
-| Codex | native | ✅ | copy into `~/.agents/skills/` | `$bootstrap` / `/skills` |
-| OpenCode | native | ✅ | reads `.claude`/`.agents`/`.opencode` skills | auto, by description |
+| Codex | native | ✅ | `codex plugin marketplace add EvolveHQ/docflow` | `$bootstrap` / `/skills` |
+| OpenCode | native | ✅ | auto-discovered, or symlink into `~/.config/opencode/skills` | auto, by description |
 
-Handy: `~/.agents/skills/` is read by **both Codex and OpenCode**, and
-`~/.claude/skills/` by **both Claude Code and OpenCode** — so one install
-often serves two agents.
+Handy: OpenCode also reads `~/.claude/skills/` and `~/.agents/skills/`, so
+a shared skills directory can serve it alongside another agent.
 
 ### Claude Code — from this marketplace
 
@@ -109,7 +128,7 @@ pi install git:github.com/EvolveHQ/docflow
 ```
 
 or, once published to npm, `pi install npm:@evolvehq/docflow`. Pi
-auto-discovers the `skills/` directory via the `pi` key in
+auto-discovers the skills via the `pi.skills` key in
 `package.json`. Invoke with `/skill:bootstrap`, `/skill:new-adr`,
 `/skill:ship-item`, … Pi does **not** auto-trigger skills from their
 descriptions the way Claude Code does — invoke them explicitly (the
@@ -121,29 +140,36 @@ hierarchical `AGENTS.md` loading — no porting needed.
 
 ### Codex (OpenAI)
 
-Codex reads `AGENTS.md` natively and discovers skills from `.agents/skills`.
-Copy docflow's skills into a path Codex scans:
+docflow ships a Codex plugin (`.codex-plugin/`), so it's a one-command
+install from this repo's marketplace:
 
 ```
-# user-wide (all projects), from a clone of this repo:
-mkdir -p ~/.agents/skills && cp -r <docflow>/skills/* ~/.agents/skills/
-# or from npm:
-npm install @evolvehq/docflow
-cp -r node_modules/@evolvehq/docflow/skills/* ~/.agents/skills/
+codex plugin marketplace add EvolveHQ/docflow
+codex plugin add docflow@evolvehq
 ```
 
-On Windows, copy `skills\*` into `%USERPROFILE%\.agents\skills\`. Invoke
-with `$bootstrap` / `/skills`, or just describe the task (Codex
-auto-triggers from the skill description). The structured assessment
-questions fall back to plain `A/B/C` text where there is no select tool.
+Codex reads the scaffolded `AGENTS.md` natively. Invoke with `$bootstrap`
+/ `/skills`, or just describe the task (Codex auto-triggers from the skill
+description); the assessment questions fall back to plain `A/B/C` text
+where there is no select tool. Update later with `codex plugin
+marketplace upgrade`.
 
 ### OpenCode (sst)
 
-OpenCode scans `.opencode/skills/`, **`.claude/skills/`, and
-`.agents/skills/`** (project and global), so a Claude Code or Codex
-install is **picked up automatically** — or copy `skills/*` into
-`~/.config/opencode/skills/` (or per-project `.opencode/skills/`). Skills
-auto-load by description.
+OpenCode auto-discovers skills from `.claude/skills`, `.agents/skills`,
+and `.opencode/skills` (project and global) — so **if you already run
+docflow on Claude Code or Codex via a shared skills directory, OpenCode
+picks it up with no extra step.** Standalone, symlink the skills into
+OpenCode's global directory (one command, stays in sync with the clone):
+
+```
+git clone https://github.com/EvolveHQ/docflow ~/.docflow-src
+ln -s ~/.docflow-src/plugins/docflow/skills/* ~/.config/opencode/skills/
+```
+
+OpenCode has no marketplace command for `SKILL.md` skills (its plugin
+system is for npm JS plugins), so a shared skills directory is the clean
+path. Skills auto-load by description.
 
 ### Claude Code — local development (no install)
 
@@ -154,12 +180,12 @@ claude --plugin-dir <path-to-this-repo>
 ### Direct skill clone (no plugin lifecycle)
 
 ```
-git clone https://github.com/EvolveHQ/docflow ~/.claude/skills/docflow-src
-ln -s ~/.claude/skills/docflow-src/skills/bootstrap ~/.claude/skills/bootstrap
+git clone https://github.com/EvolveHQ/docflow ~/.docflow-src
+ln -s ~/.docflow-src/plugins/docflow/skills/* ~/.claude/skills/
 ```
 
-On Windows, copy `skills/bootstrap/` (and the other `skills/*` dirs you
-want) into `%USERPROFILE%\.claude\skills\` instead of symlinking.
+On Windows, copy `plugins\docflow\skills\*` into
+`%USERPROFILE%\.claude\skills\` instead of symlinking.
 
 ## Quick start
 
@@ -208,26 +234,29 @@ to extend or override the templates.
 
 ```
 docflow/
-  .claude-plugin/
-    plugin.json          # Claude Code plugin manifest
-    marketplace.json     # Claude Code marketplace listing (repo is its own marketplace)
-  package.json           # pi package manifest (pi.skills -> ./skills) + npm metadata
-  skills/
-    bootstrap/
-      SKILL.md           # bootstrap: assessment + output sequence + backfill
-      templates/         # files the bootstrap reads and writes into target repos
-    new-adr/SKILL.md     # lifecycle skills — operate on a bootstrapped repo,
-    new-plan/SKILL.md    #   read CONVENTIONS.md, honour its choices
-    ship-item/SKILL.md
-    add-convention/SKILL.md
-    audit/SKILL.md
-    brainstorm/SKILL.md
-    agent-wave/SKILL.md
+  .claude-plugin/marketplace.json   # Claude Code / Cowork marketplace (-> ./plugins/docflow)
+  .agents/plugins/marketplace.json  # Codex marketplace (-> ./plugins/docflow)
+  package.json                      # pi manifest (pi.skills -> ./plugins/docflow/skills) + npm
+  plugins/docflow/                  # the plugin — one source, every target
+    .claude-plugin/plugin.json      #   Claude Code / Cowork plugin manifest
+    .codex-plugin/plugin.json       #   Codex plugin manifest (skills -> ./skills)
+    skills/                         #   the one skill source
+      bootstrap/
+        SKILL.md                    #   bootstrap: assessment + output sequence + backfill
+        templates/                  #   files the bootstrap reads and writes into target repos
+      new-adr/SKILL.md              #   lifecycle skills — operate on a bootstrapped repo,
+      new-plan/SKILL.md             #     read CONVENTIONS.md, honour its choices
+      ship-item/SKILL.md
+      add-convention/SKILL.md
+      audit/SKILL.md
+      brainstorm/SKILL.md
+      agent-wave/SKILL.md
+      rollup/SKILL.md
   README.md
   USAGE.md
 ```
 
-Only the `bootstrap` skill uses `skills/bootstrap/templates/`. The
+Only the `bootstrap` skill uses `plugins/docflow/skills/bootstrap/templates/`. The
 lifecycle skills act on the copies the bootstrap wrote into the target
 repo (e.g. its `adr/0000-template.md`), so they carry no templates of
 their own.

package/USAGE.md

@@ -5,21 +5,59 @@ what each of the 10 assessment questions actually changes in the
 output, and how to customise or extend the templates. The lifecycle
 skills are covered in §5a.
 
-For installation, see the [README](README.md).
-
-## 1. Triggering the bootstrap skill
-
-Once the plugin is installed (or `--plugin-dir`'d) into a Claude Code
-session, the skill is available in any repo. Three ways to trigger:
-
-1. **Slash command:** `/bootstrap`.
-2. **Natural language** matching the skill's description, e.g.
-   - "set up documentation-led conventions in this repo"
-   - "bootstrap ADRs and a plan queue"
-   - "scaffold AGENTS.md and the _agent/ layout"
-   - "retrofit this existing repo with the documentation conventions"
-3. **From another agent's prompt** — name the skill explicitly:
-   *"invoke the `bootstrap` skill on this repository."*
+## Install (per platform)
+
+docflow runs from **one skill source** (`plugins/docflow/skills/`) on
+five coding agents. The
+scaffolded **output** (`AGENTS.md`, the ADR catalogue, `plan/`, `_agent/`)
+is plain Markdown read natively by any agent that loads `AGENTS.md`; the
+**skills** are `SKILL.md` files the host discovers.
+
+| Agent | Install | Invoke |
+|-------|---------|--------|
+| **Claude Code** | `/plugin marketplace add EvolveHQ/docflow` then `/plugin install docflow@evolvehq` | `/bootstrap` |
+| **Claude Cowork** | the **same** Claude Code plugin (`/plugin marketplace add …`) — Cowork shares the plugin system | `/bootstrap` |
+| **pi** | `pi install npm:@evolvehq/docflow` (or `pi install git:github.com/EvolveHQ/docflow`) | `/skill:bootstrap` |
+| **Codex** | `codex plugin marketplace add EvolveHQ/docflow` then `codex plugin add docflow@evolvehq` (native plugin) | `$bootstrap` / `/skills` |
+| **OpenCode** | auto-discovers `.claude`/`.agents`/`.opencode` skills (so a Claude Code / Codex install is picked up), or symlink into `~/.config/opencode/skills` | auto, by description |
+
+Notes:
+
+- **Codex** ships a native plugin (`.codex-plugin/`), so it's a one-command
+  install like Claude Code. **OpenCode** has no marketplace command for
+  `SKILL.md` skills (its plugin system is npm JS plugins), so it relies on
+  skills-directory auto-discovery or a symlink.
+- A **shared skills directory** can serve two agents: `~/.agents/skills/`
+  is read by Codex and OpenCode; `~/.claude/skills/` by Claude Code and
+  OpenCode.
+- The scaffolded output needs no porting on any of them — it is read
+  natively wherever `AGENTS.md` is the instruction file.
+
+See the [README](README.md#install) for the full matrix, Windows paths,
+and local-development options.
+
+## 1. Triggering the skills
+
+Once docflow is installed (per the table above), the skills are available
+in any repo. Invocation differs per agent:
+
+| Agent | Slash / mention | Auto-trigger from description |
+|-------|-----------------|-------------------------------|
+| Claude Code / Cowork | `/bootstrap`, `/new-adr`, … | yes |
+| pi | `/skill:bootstrap`, `/skill:new-adr`, … | no — invoke explicitly |
+| Codex | `$bootstrap` / `/skills` | yes |
+| OpenCode | (loaded by name) | yes, by description |
+
+On agents that **auto-trigger**, natural-language matching the skill's
+description also works, e.g.:
+
+- "set up documentation-led conventions in this repo"
+- "bootstrap ADRs and a plan queue"
+- "scaffold AGENTS.md and the _agent/ layout"
+- "retrofit this existing repo with the documentation conventions"
+
+Or, on any agent, name the skill explicitly: *"invoke the `bootstrap`
+skill on this repository."*
 
 ## 2. The flow
 
@@ -284,11 +322,11 @@ blocks up front, so G2/G3 rarely fire.)
 
 The templates are deliberately small and self-contained. To customise:
 
-- **Edit a template.** Files in `skills/bootstrap/templates/` are read
+- **Edit a template.** Files in `plugins/docflow/skills/bootstrap/templates/` are read
   verbatim by the `bootstrap` skill, then placeholders are filled from
   the assessment answers. Change the template, the next bootstrap
   reflects it.
-- **Add a new template.** Put it in `skills/bootstrap/templates/` and
+- **Add a new template.** Put it in `plugins/docflow/skills/bootstrap/templates/` and
   reference it from `bootstrap/SKILL.md` §Step 5 (Output sequence).
 - **Tighten a skill's auto-trigger.** Edit the `description:`
   frontmatter in that skill's `SKILL.md`. Skills match user requests
@@ -296,7 +334,7 @@ The templates are deliberately small and self-contained. To customise:
   scope. With several skills in one plugin, watch for trigger collision
   (e.g. "add a convention" vs. "add an ADR") and keep descriptions
   distinct; the slash commands are the unambiguous entry point.
-- **Add a new lifecycle skill.** Create `skills/<name>/SKILL.md`. Follow
+- **Add a new lifecycle skill.** Create `plugins/docflow/skills/<name>/SKILL.md`. Follow
   the shared pattern: a Step 0 that checks the repo is bootstrapped and
   reads `CONVENTIONS.md`, then act in a way that honours the recorded
   choices. Lifecycle skills act on the target repo's own files (e.g. its
@@ -340,10 +378,20 @@ To remove the plugin entirely:
 /plugin uninstall docflow@evolvehq
 ```
 
+**Other agents:**
+
+- **Cowork** — same as Claude Code (`/plugin marketplace update` →
+  install).
+- **pi** — re-run `pi install npm:@evolvehq/docflow` (or the `git:` form).
+- **Codex** — `codex plugin marketplace upgrade`, then re-add with
+  `codex plugin add docflow@evolvehq`.
+- **OpenCode** — if installed via a clone/symlink, `git pull` the clone;
+  skills reload on the next session.
+
 ### As the author (you, maintaining this repo)
 
-1. Edit a skill body (`skills/<name>/SKILL.md`), the bootstrap templates
-   (`skills/bootstrap/templates/*.md`), or supporting docs.
+1. Edit a skill body (`plugins/docflow/skills/<name>/SKILL.md`), the bootstrap templates
+   (`plugins/docflow/skills/bootstrap/templates/*.md`), or supporting docs.
 2. Bump the `version` field in `.claude-plugin/plugin.json` following
    semver — patch for fixes, minor for new questions / templates,
    major for breaking changes to the skill flow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolvehq/docflow",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "ADR-driven documentation workflow: scaffold an Architecture Decision Record (ADR) catalogue, a plan/ queue, and AGENTS.md conventions into any repo, then author, queue, ship, and audit ADRs with lifecycle skills. Works with the pi coding agent and Claude Code.",
   "keywords": [
     "pi-package",
@@ -21,7 +21,7 @@
     "evals": "node evals/run.mjs"
   },
   "files": [
-    "skills/",
+    "plugins/docflow/skills/",
     "docs/preview.png",
     "README.md",
     "USAGE.md",
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "pi": {
-    "skills": ["./skills"],
+    "skills": ["./plugins/docflow/skills"],
     "image": "https://raw.githubusercontent.com/EvolveHQ/docflow/main/docs/preview.png"
   }
 }

package/plugins/docflow/skills/add-convention/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "docflow: add-convention"
+  short_description: "Assess whether a convention is worth codifying, then route it to the right home (AGENTS.md, CONVENTIONS.md, GLOSSARY, or an ADR)."
+  default_prompt: "Add a convention to this repository."

package/plugins/docflow/skills/agent-wave/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "docflow: agent-wave"
+  short_description: "Orchestrate a wave of parallel worktree subagents over the plan/todo queue."
+  default_prompt: "Run the plan queue with a wave of parallel agents."

package/{skills → plugins/docflow/skills}/audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit
-description: Audit a documentation-led repo against its own conventions — contiguous ADR numbering, INDEX sync, plan/ coverage, required sections, status validity, cross-reference resolution, language mandate, ADR-privacy leaks into user-visible code, and cross-worktree collisions (duplicate numbers, duplicate plan ownership, same ADR edited on two branches). Reports a punch list and offers to fix the mechanical issues. Use when the user says "audit the ADRs", "lint the conventions", "check repo consistency", "are the ADRs in sync", or invokes /audit.
+description: Audit a documentation-led repo against its own conventions — contiguous ADR numbering, INDEX sync, plan/ coverage, required sections, status validity, cross-reference resolution, language mandate, ADR-privacy leaks into user-visible code, cross-worktree collisions (duplicate numbers, duplicate plan ownership, same ADR edited on two branches), and — for a multi-repo product — cross-repo federation checks (bidirectional membership, identity collisions, dangling cross-repo references, roll-up drift). Reports a punch list and offers to fix the mechanical issues. Use when the user says "audit the ADRs", "lint the conventions", "check repo consistency", "are the ADRs in sync", or invokes /audit.
 ---
 
 # audit
@@ -15,6 +15,10 @@ This is the enforcement `AGENTS.md` cannot guarantee on its own.
    cutoff, status lifecycle, integration model, multi-agent mode,
    language mandate, optional artefacts present (GLOSSARY, domains/),
    and any Q10 domain hard rules.
+3. If a `federation.md` exists, this repo is part of a multi-repo
+   product. Note whether it is the **home** or a **member** and read the
+   recorded identity scheme; the cross-repo checks (check 12) run from
+   the home repo.
 
 ## Step 1 — Run the checks (read-only)
 
@@ -62,6 +66,23 @@ relevant):
       more than one. A `merge=union` would concatenate them silently.
     Cross-check against `_agent/IN_FLIGHT.md`: every collision should
     correspond to a reservation/ownership violation recorded there.
+12. **Cross-repo (federation) checks** — only when a `federation.md`
+    exists; run from the **home** repo. Reach each member through the
+    local checkout named in `federation-index.md`. A member not checked
+    out locally is reported **"unverified this run"** — never silently
+    passed, never a hard failure.
+    - **Bidirectional membership.** Every repo listed in the member index
+      carries a `federation.md` back-pointer to this home, and every repo
+      whose back-pointer names this home is listed in the index. Flag
+      either half-edge (in-index-without-back-pointer, or
+      points-home-but-unlisted).
+    - **Identity collisions.** No two ADRs across the federation resolve
+      to the same identity under the recorded identity scheme.
+    - **Dangling cross-repo references.** Every cross-repo link resolves
+      to a real ADR in the named member; flag a target that does not
+      exist. (Same-repo relative links are check 7.)
+    - **Roll-up drift.** The roll-up agrees with each member's `INDEX.md`
+      metadata; flag rows that are stale, missing, or extra.
 
 ## Step 2 — Report
 

package/plugins/docflow/skills/audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "docflow: audit"
+  short_description: "Lint the repo against its own conventions — ADR numbering, INDEX sync, plan coverage, privacy leaks, and more."
+  default_prompt: "Audit this repository against its documentation conventions."

package/{skills → plugins/docflow/skills}/bootstrap/SKILL.md

@@ -53,8 +53,16 @@ questions.
     CURRENT_FOCUS.md     # slim live snapshot
     HANDOFF.md           # fresh-agent entry point
     prompts/autonomous.md  # only if a verify gate exists (see Q8)
+  federation.md          # multi-repo only (Q11): this repo's back-pointer
+  federation-index.md    # multi-repo only (Q11): member index — home repo only
 ```
 
+For a **multi-repo product** (one product spread across several repos —
+see Q11), two extra files appear: `federation.md`, a small back-pointer
+every member repo carries, and `federation-index.md`, the authoritative
+member list that lives only in the home/establishing repo. A standalone
+repo has neither.
+
 ## Step 3 — Conventions to install
 
 1. **ADRs are the source of truth.** One decision per ADR. Splits become
@@ -112,7 +120,7 @@ questions.
     doubt, ask whether a non-builder would ever see this string — if
     yes, the ADR reference comes out.
 
-## Step 4 — Assessment (10 questions)
+## Step 4 — Assessment (10 questions, plus an optional federation question)
 
 **Ask the questions one at a time, not in a batch.** For each question,
 state a **recommended** option (label it "Recommended") with one short
@@ -125,7 +133,7 @@ option with the literal "(Recommended)" suffix in its label. Otherwise
 ask in plain text, listing options as A/B/C and naming the recommended
 one.
 
-After all 10 answers are in, summarise the resulting plan in 5–10
+After the answers are in, summarise the resulting plan in 5–10
 lines and ask for sign-off before writing any files.
 
 1. **Project identity.** Name, one-line description, doc language
@@ -214,6 +222,39 @@ lines and ask for sign-off before writing any files.
     mandatory user-story personas, separated audit streams?
     **Recommended: none from day one** — add later when a concrete
     requirement appears; pre-emptive hard rules accumulate as cruft.
+11. **Multi-repo product (optional).** Is this repo part of a product
+    that spans several repos? **Recommended: No** — most repos are
+    standalone; skip the federation setup entirely. If **yes**, two
+    sub-answers:
+
+    **Q11a — Establish or join?** Are you **establishing** a new
+    federation (this is the first repo) or **joining** an existing one?
+
+    **Q11b — Topology (establish only).** Where do product-wide
+    decisions live?
+    - **A — central decisions repo:** a dedicated repo holds all
+      product-wide decisions; code repos reference it, never duplicate.
+    - **B — distributed + federation:** each repo owns its own
+      decisions; a roll-up aggregates them.
+    - **(Recommended) C — home repo + local:** one repo is the home for
+      product-wide decisions; each repo also keeps purely-local ones.
+
+    **Q11c — Identity scheme (establish only).** How are ADRs identified
+    across the federation? **(Recommended) repo-prefixed slug**
+    `<repo-id>/NNNN-slug` — each repo keeps local contiguous numbering
+    with no central coordinator; the slug is the cross-federation key.
+    The scheme is recorded in the federation config and applied by the
+    authoring skills.
+
+    **Establish** designates this repo as the home/central repo, writes
+    the member index here, and records the topology **and identity
+    scheme** in the federation config. **Join** asks for the home pointer — **you confirm it; the
+    skill performs no cross-repo read and no host API call** — then
+    writes **only this repo's** back-pointer config and inherits the
+    topology without re-asking it. Joining never writes into any other
+    repo; adding this repo to the member index is a deliberate edit in
+    the home repo. A standalone repo (Q11 = No) writes none of these
+    files and behaves exactly as a single-repo bootstrap.
 
 ## Step 4.5 — Cross-check before sign-off
 
@@ -232,6 +273,9 @@ plan summary. Surface each, take the correction, then proceed:
   runs, or downgrade the completion event.
 - **Q2 single ADR shape + Q7 technology-ADR template requested.**
   Contradiction — pick one.
+- **Q11 = join but no confirmable home pointer.** Joining needs a
+  home/federation pointer you can confirm. If none exists yet, you are
+  really *establishing* — switch Q11a to establish.
 
 ## Step 5 — Output sequence (after sign-off)
 
@@ -242,7 +286,9 @@ write it into the repo.
 1. `CONVENTIONS.md` — from `templates/CONVENTIONS.md`. Spec other files
    reference. Include the **§Concurrency Guardrails** section only if Q5
    is mode 2/3 **or** Q4b is PR-based; omit it for single-agent
-   direct-to-main repos (no numbering race).
+   direct-to-main repos (no numbering race). Include the **§Federation
+   (multi-repo)** section only if Q11 = yes; fill `<product>` and state
+   the chosen identity scheme. Omit it for standalone repos.
 2. `AGENTS.md` — from `templates/AGENTS.md`. Include the concurrency
    guardrails hard-rule bullet (G2/G3) under the same condition as the
    CONVENTIONS section above; omit otherwise.
@@ -276,6 +322,22 @@ write it into the repo.
     **direct-to-main** variant (`git merge --ff-only` then push) or
     the **PR-based** variant (`gh pr create --draft` → wait for CI →
     mark ready → `gh pr merge`). Drop the unused variant.
+14. **Federation files** — **only if Q11 = yes.** Place both at the
+    configured artefact root (repository root by default).
+    - **Establish:** write `federation-index.md` (the member index, a
+      Markdown table) from `templates/federation-index.md` into this
+      repo, seeded with this repo as the home member; and write
+      `federation.md` from `templates/federation-config.md` with
+      `Role: home`, the chosen topology, and the chosen identity scheme
+      (default repo-prefixed slug). Record the identity scheme in both
+      files so it is the same on every read.
+    - **Join:** write **only** `federation.md` from
+      `templates/federation-config.md` with `Role: member`, the
+      confirmed home pointer, and the topology **and identity scheme**
+      inherited from the federation (read them from the home, do not
+      re-ask). Write nothing into any other repo, and do **not** create a
+      member index. Tell the user to add this repo to the home repo's
+      `federation-index.md` (a deliberate edit there).
 
 Commit each file (or logical group) with a Conventional Commit message;
 no `Co-Authored-By` trailer unless Q6 asked for one.

package/plugins/docflow/skills/bootstrap/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "docflow: bootstrap"
+  short_description: "Scaffold (or retrofit) ADR-driven documentation conventions — an ADR catalogue, a plan/ queue, AGENTS.md, and _agent/ coordination — into a repo."
+  default_prompt: "Set up documentation-led ADR conventions in this repository."

package/{skills → plugins/docflow/skills}/bootstrap/templates/CONVENTIONS.md

@@ -167,6 +167,32 @@ once merged:
   renumbers.
 -->
 
+<!-- Federation (multi-repo) — bootstrap INCLUDES this section
+(uncommented) ONLY when this repo is part of a multi-repo product (Q11).
+Standalone repos OMIT it entirely.
+
+## Federation (multi-repo)
+
+This repo belongs to the **<product>** federation. Topology and the
+identity scheme are recorded in `federation.md`; the home repo's
+`federation-index.md` is the authoritative member list.
+
+- **Numbering is per-repo contiguous.** Each member repo numbers its own
+  ADRs contiguously from `0001`; numbers are **not** unique across the
+  federation. The cross-federation key is the **identity scheme** recorded
+  in `federation.md` — default repo-prefixed slug `<repo-id>/NNNN-slug`.
+- **Cross-repo references use the logical identity**, resolved through the
+  member index (`repo-id → location`); they survive a target repo move
+  (edit one index row, not the references). **Same-repo references stay
+  relative paths** (`adr/NNNN-*.md`).
+- `supersedes:` / `superseded-by:` may point across repos using the
+  logical identity.
+- **Membership is declared, not discovered.** A member repo carries a
+  `federation.md` back-pointer; adding it to the home's
+  `federation-index.md` is a deliberate edit there. The two must agree —
+  audit cross-checks both directions.
+-->
+
 ## Audit Trail Policy
 
 Every substantive change to an Accepted ADR appends a new row to its

package/plugins/docflow/skills/bootstrap/templates/federation-config.md

@@ -0,0 +1,17 @@
+# Federation
+
+This repo is part of a multi-repo product. Lifecycle skills read this
+back-pointer to resolve cross-repo behaviour. It is the answer to "what
+is my home?"; the home repo's `federation-index.md` is the answer to
+"which repos are in this product?".
+
+- **Product:** <product-name>
+- **Topology:** <A — central decisions repo | B — distributed + federation | C — home repo + local>
+- **Identity scheme:** <repo-prefixed slug `<repo-id>/NNNN-slug` (default) | other scheme chosen at establishment>
+- **Home:** <pointer to the home/central repo — URL or path; for the home repo itself, `this repo`>
+- **Role:** <home | member>
+- **Repo id:** <short identifier for this repo, used to qualify its records across the federation>
+
+<!-- Hand-maintained. Membership is declared, not auto-discovered: a
+member's bootstrap writes only this file in its own repo; adding the
+repo to the home's federation-index.md is a deliberate edit there. -->

package/plugins/docflow/skills/bootstrap/templates/federation-index.md

@@ -0,0 +1,17 @@
+# Federation member index
+
+Authoritative list of the repos in this product. Lives only in the
+home/central repo. **Hand-maintained:** adding a member is a deliberate
+edit here — no lifecycle skill writes across repos to update it. Lifecycle
+skills read this to enumerate the product's repos.
+
+- **Product:** <product-name>
+- **Topology:** <A — central decisions repo | B — distributed + federation | C — home repo + local>
+- **Identity scheme:** <repo-prefixed slug `<repo-id>/NNNN-slug` (default) | other scheme chosen at establishment>
+
+| Repo id | Repo | Role | Pointer |
+|---------|------|------|---------|
+| <id>    | <this repo> | home | this repo |
+
+<!-- Each row should have a matching federation.md back-pointer in the
+named repo, and vice versa. The audit step cross-checks both directions. -->

package/plugins/docflow/skills/brainstorm/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "docflow: brainstorm"
+  short_description: "Decompose a problem into candidate ADRs and plan items with dependency edges; proposes drafts, writes nothing until approved."
+  default_prompt: "Break this problem into candidate ADRs and plan items."

package/{skills → plugins/docflow/skills}/new-adr/SKILL.md

@@ -17,6 +17,9 @@ Author one new ADR, consistent with this repo's conventions.
    status lifecycle, language mandate (if any), whether `domains/`
    groupings exist, and the multi-agent mode.
 3. Read `INDEX.md` and `ls adr/` to learn existing numbers and titles.
+4. If a `federation.md` exists, this repo is part of a multi-repo
+   product. Note the **identity scheme** and the **home** it records —
+   they govern numbering and cross-repo references below.
 
 ## Step 0.5 — Assessment (run first)
 
@@ -56,6 +59,10 @@ Questions (skip any the request already answers):
 - **Number.** Next contiguous integer after the highest existing ADR,
   zero-padded to 4 digits. No gaps, no reuse. For a split repo, keep
   capability ADRs below the cutoff and technology ADRs at/above it.
+  **In a federation** (a `federation.md` exists), number contiguously
+  **within this repo** — numbers are not unique across the federation.
+  The ADR's federation identity is the recorded scheme applied to this
+  number (default repo-prefixed slug `<repo-id>/NNNN-slug`).
 
 ## Step 2 — Gather content
 
@@ -75,6 +82,10 @@ If this ADR replaces an existing one:
 - Set `supersedes:` on the new ADR and `superseded-by:` on the old.
 - Advance the old ADR's `status:` to `Superseded`, append a Revision
   History row noting the successor.
+- **Same-repo** links use relative paths (`adr/NNNN-*.md`). **In a
+  federation**, a link to an ADR in another repo uses the logical
+  identity (`<repo-id>/NNNN-slug`), resolved via the member index — not
+  a relative path.
 - A pure deprecation (no successor) sets the target to `Deprecated`
   with a Revision History row — and is usually done directly, not via
   this skill.

package/plugins/docflow/skills/new-adr/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "docflow: new-adr"
+  short_description: "Author one ADR — next contiguous number, right shape, INDEX wiring, supersede linkage."
+  default_prompt: "Record a new architecture decision as an ADR."

package/plugins/docflow/skills/new-plan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "docflow: new-plan"
+  short_description: "Queue a unit of work in plan/todo, tracing to an owning ADR."
+  default_prompt: "Queue a plan item for an existing ADR."

package/plugins/docflow/skills/rollup/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: rollup
+description: Generate the federation roll-up catalogue for a multi-repo product — aggregate every member repo's ADR metadata into one derived, product-wide view, run from the home repo. Use when the user says "roll up the federation", "generate the product-wide ADR view", "aggregate ADRs across the repos", "refresh the roll-up", or invokes /rollup. NOT for regenerating a single repo's own INDEX (that happens in place during authoring/ship) and NOT for linting consistency (use the audit skill).
+---
+
+# rollup
+
+Aggregate the ADR catalogues of every repo in a multi-repo product into
+one **derived, read-only** product-wide view. The roll-up is regenerated
+from source, never hand-edited — treat it exactly like a repo's own
+`INDEX.md`.
+
+## Step 0 — Preconditions
+
+1. This skill runs in the **home repo** of a federation. Confirm a
+   `federation-index.md` (the authoritative member list) and a
+   `federation.md` with `Role: home` exist. If they do not, stop: either
+   this repo is standalone (nothing to roll up) or it is a member, not the
+   home — point the user at the home repo.
+2. Read `federation.md` to learn the **identity scheme** (default
+   repo-prefixed slug `<repo-id>/NNNN-slug`); roll-up rows use it.
+
+## Step 1 — Enumerate members
+
+Read `federation-index.md`. For each row, take the `Repo id` and the
+`Pointer` (the path/URL of that member's checkout). The member index is
+the **only** source of membership — do not auto-discover repos.
+
+## Step 2 — Collect each member's catalogue
+
+For every member whose checkout is **locally available** at its pointer:
+
+- Read that member's `INDEX.md` (its authoritative local catalogue).
+- For each ADR row, capture the number, title, status, date, and
+  dependencies, and attach the **owning repo id** and the **federation
+  identity** (the scheme from Step 0 applied to the local number).
+
+A member's own `INDEX.md` stays authoritative for that member; this skill
+only reads it.
+
+## Step 3 — Handle unreachable members
+
+A member named in the index whose checkout is **not locally available** is
+**not** dropped and **not** a failure. Record it in a clearly separated
+"Not aggregated this run" list with its repo id and pointer, so the gap is
+visible rather than silent.
+
+## Step 4 — Write the roll-up
+
+Write the aggregate to a derived file in the home repo (e.g. `ROLLUP.md`):
+
+- A header stating it is **generated — do not hand-edit**, with the run
+  date and the set of members aggregated.
+- One table across the whole product: federation identity, title, status,
+  owning repo, date. Group or sort by owning repo for readability.
+- The "Not aggregated this run" list from Step 3.
+
+Do not alter any member's `INDEX.md` and do not write into any other repo.
+
+## Step 5 — Report
+
+Tell the user how many members were aggregated, how many were skipped as
+unreachable (and which), and the total ADR count in the roll-up. Remind
+them the file is derived: re-run this skill to refresh it rather than
+editing it by hand.

package/plugins/docflow/skills/rollup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "docflow: rollup"
+  short_description: "Aggregate every member repo's ADRs into one product-wide federation roll-up (run from the home repo)."
+  default_prompt: "Generate the federation roll-up catalogue across the member repos."

package/plugins/docflow/skills/ship-item/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "docflow: ship-item"
+  short_description: "Run the completion event for a plan item: verify, integrate, todo→done, advance the owning ADR."
+  default_prompt: "Ship the next plan item."