@evolvehq/docflow 0.9.1 → 0.9.3

package/README.md

@@ -39,23 +39,41 @@ and point you at `/bootstrap`.
 
 ## What `/bootstrap` installs
 
+Only the **core** is always written; everything else is an **opt-in layer**
+chosen during the assessment, so a minimal repo stays as light as a classic
+ADR catalogue.
+
+**Core (always):**
 - `AGENTS.md` — hard rules for coding agents (the entry point).
-- `CLAUDE.md` — one-liner re-exporting `AGENTS.md` so Claude Code picks
-  it up automatically.
-- `CONVENTIONS.md` — authoring rules for ADRs, naming, status
-  lifecycle, audit trail, and git contract.
+- `CLAUDE.md` — one-liner re-exporting `AGENTS.md` so Claude Code picks it
+  up automatically.
+- `CONVENTIONS.md` — authoring rules for ADRs, naming, status lifecycle,
+  audit trail, and git contract.
 - `INDEX.md` — generated table of all ADRs.
-- `adr/` — ADR catalogue with a capability-ADR template (and an
-  optional technology-ADR template).
-- `plan/todo/` and `plan/done/` — implementation queue. `git mv` from
-  `todo/` to `done/` is the completion event.
-- `_agent/` — multi-agent coordination: `ROLES.md`, `LOCKS.md`,
-  `WORKLOG.md`, `CURRENT_FOCUS.md`, `HANDOFF.md`, and an optional
-  unsupervised-run prompt under `prompts/`.
-
-Optional, off by default: `GLOSSARY.md`, `domains/<slug>/README.md`
-groupings, project-specific hard rules (vendor-naming restriction,
-regulated-evidence posture, language mandate, audit-stream separation).
+- `adr/0000-template.md` — the ADR template; the catalogue starts here.
+
+**Optional layers (opt-in):**
+- `plan/todo/` + `plan/done/` — the implementation queue (Q4a). `git mv`
+  from `todo/` to `done/` is the completion event.
+- `_agent/` — coordination (`ROLES`, `LOCKS`, `WORKLOG`, `CURRENT_FOCUS`,
+  `HANDOFF`, optional `prompts/`). **Q5 — choose *None* to omit it.**
+- `GLOSSARY.md`, `domains/<slug>/README.md` groupings, the technology-ADR
+  template, and project-specific hard rules (vendor-naming, regulated
+  evidence, language mandate, audit-stream separation) — Q7/Q10.
+
+Omitting any optional layer leaves a valid repo; a lifecycle skill that
+needs an absent layer refuses cleanly and says what's missing.
+
+**Placement:** `AGENTS.md` and `CLAUDE.md` always stay at the repository
+root; everything else lives under a configurable **artefact root** —
+`docs/` (the default), the repo root, or `.docflow/` — chosen at bootstrap
+and recorded in `CONVENTIONS.md`.
+
+**Seed ADR:** by default, bootstrap also writes **`adr/0001`** — a first
+ADR recording the decision to adopt this method (self-documenting, like the
+classic "use ADRs" convention). It references `CONVENTIONS.md` for the rules
+and is created `Implemented`. Decline it at sign-off if you want only the
+template.
 
 ## Why
 
@@ -80,11 +98,25 @@ 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
+roll-up drift, convention drift). Work and status cross repos the same way:
+a cross-repo decision is one plan item per affected repo, and its aggregate
+status ("2 of 3 repos") surfaces in the roll-up. 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.
 
+## No drafts in the catalogue
+
+docflow records **outcomes, not work-in-progress**. There is **no `Draft`
+status** and **no `brainstorming/` folder** — an ADR's first persisted
+status is `Proposed`, created only once a decision is approved. The
+`brainstorm` skill explores candidates **in conversation and writes
+nothing** until you approve them; only then does `new-adr` mint a numbered
+ADR. This keeps the catalogue free of half-formed drafts and the numbering
+clean — numbers go only to real decisions — following the lightweight-ADR
+tradition that an ADR captures the agreed decision, not the discussion that
+produced it.
+
 ## Install
 
 docflow ships from **one skill source** (`plugins/docflow/skills/`) to
@@ -171,6 +203,9 @@ 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.
 
+**OpenCode-compatible forks** — e.g. Xiaomi's *mimocode* — inherit this
+support via the same skill-discovery path; no separate packaging.
+
 ### Claude Code — local development (no install)
 
 ```

package/USAGE.md

@@ -165,6 +165,7 @@ After sign-off, the skill writes:
 | `CLAUDE.md` | `templates/CLAUDE.md` | Single line `@AGENTS.md`. |
 | `adr/0000-template.md` | `templates/adr-capability.md` | Capability-ADR template. |
 | `adr/NNNN-template.md` | `templates/adr-technology.md` | Technology-ADR template. Only if Q2 said split. `NNNN` is the project-defined cutoff (default 0100). |
+| `adr/0001-record-architecture-decisions.md` | `templates/adr-0001-seed.md` | **Seed ADR** recording the decision to adopt the method (`Implemented`, references `CONVENTIONS.md`). Default on; declined at sign-off if not wanted. |
 | `plan/README.md` | `templates/plan-README.md` | Plus empty `plan/todo/.gitkeep` and `plan/done/.gitkeep`. |
 | `_agent/ROLES.md` | `templates/_agent-ROLES.md` | Single `default-agent` by default. |
 | `_agent/LOCKS.md` | `templates/_agent-LOCKS.md` | Empty header. Created only if Q5 enabled LOCKS discipline. |
@@ -174,7 +175,7 @@ After sign-off, the skill writes:
 | `_agent/IN_FLIGHT.md` | `templates/_agent-IN_FLIGHT.md` | Only in Q5 mode 3 (worktree). Committed cross-worktree dashboard. |
 | `.gitattributes` (entry) | (none — inline) | Only in Q5 mode 3: appends `_agent/WORKLOG.md merge=union`. |
 | `.gitignore` (entry) | (none — inline) | Only in Q5 mode 3: adds `_agent/CURRENT_FOCUS.md` so it stays local-only. |
-| `INDEX.md` | (none — generated) | Stub header + empty table. |
+| `INDEX.md` | (none — generated) | Header + the seed ADR's row (empty table only if the seed was declined). |
 | `_agent/prompts/autonomous.md` | `templates/_agent-prompts-autonomous.md` | Only if Q8 confirmed a verify gate. |
 
 ## 5. After scaffolding
@@ -273,9 +274,14 @@ it inherits the topology and identity scheme rather than re-choosing them.
   collide.
 - **References.** Cross-repo links use the logical identity, resolved via
   the home's `federation-index.md`; same-repo links stay relative.
+- **Work & status.** A cross-repo decision is one plan item **per affected
+  repo**, each tracing to the owning ADR by its federation identity (no
+  umbrella record); the decision's aggregate status ("2 of 3 repos") is a
+  derived roll-up column, `Implemented` only when every per-repo item ships.
 - **`/rollup`** aggregates every member's catalogue into one product-wide
   view; **`/audit`** gains cross-repo checks (bidirectional membership,
-  identity collisions, dangling references, roll-up drift).
+  identity collisions, dangling references, roll-up drift, convention
+  drift).
 - **Conventions** are copied at bootstrap and kept honest by audit
   drift-detection — referenceable from the home, never force-pushed.
 
@@ -340,6 +346,11 @@ scheme:
   and `INDEX.md`).
 - **G3 — gate backstop:** the single-threaded merge gate rejects a
   duplicate; the later author renumbers.
+- **G4 — claim before do:** before implementing a queued item, claim it (a
+  draft PR referencing it, or an `IN_FLIGHT`/`owner` entry) so two writers
+  don't build the same unclaimed `plan/todo` item — G1–G3 protect the
+  *number*, G4 protects the *work assignment*; the audit's
+  duplicate-plan-ownership check is the backstop.
 
 `bootstrap` **pre-wires** these into `CONVENTIONS.md` + an `AGENTS.md`
 hard rule **only** for multi-agent (mode 2/3) or PR-based repos.
@@ -348,6 +359,26 @@ get none of this ceremony. Numbers are immutable once merged. (For
 orchestrated runs, `agent-wave` additionally *reserves* disjoint number
 blocks up front, so G2/G3 rarely fire.)
 
+### Numbering at scale, and grouping by domain
+
+ADR numbers are **integers**; the four-digit zero-padding is cosmetic and
+sorts **numerically**, so a catalogue is not capped at `9999` — widen the
+padding to five digits if you ever approach it (no real catalogue does).
+
+Two alternative identifier schemes are intentionally *not* used (the
+[methodology](https://evolvehq.github.io/docflow/methodology/#46-numbering-at-scale-and-alternatives-considered)
+has the full reasoning): **timestamp / opaque ids** — they trade away
+ordering and readability, and the guardrails above handle collisions
+instead; and **per-domain numbering** like `auth/0001` — the federation
+serves genuinely independent sequences, and within one repo you group
+rather than renumber.
+
+**Grouping by domain.** Opt in to `domains/<slug>/README.md` files that
+list the ADRs for each area (e.g. `domains/auth/`, `domains/billing/`). It
+is purely organisational: each ADR keeps its flat number and its `INDEX.md`
+row; the domain README is a curated view, not a namespace. Reach for it
+when a flat catalogue grows large enough to be hard to navigate.
+
 ## 6. Customising or extending
 
 The templates are deliberately small and self-contained. To customise:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolvehq/docflow",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "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, audit, and roll up ADRs with lifecycle skills — across one repo or a multi-repo product. Works on Claude Code, Claude Cowork, pi, Codex, and OpenCode.",
   "keywords": [
     "pi-package",

package/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, 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.
+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, convention 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
@@ -14,11 +14,14 @@ This is the enforcement `AGENTS.md` cannot guarantee on its own.
 2. Read `CONVENTIONS.md` to learn what to enforce: ADR shape and
    cutoff, status lifecycle, integration model, multi-agent mode,
    language mandate, optional artefacts present (GLOSSARY, domains/),
-   and any Q10 domain hard rules.
+   and any Q10 domain hard rules, and the **artefact root** (default:
+   repository root) — resolve `adr/`, `plan/`, `INDEX.md` against it and
+   honour it in the cross-reference and INDEX-sync checks.
 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.
+   product. Note its `Role` (`central` / `home` / `coordinator`
+   index-holder, or a plain `member`) and read the recorded identity
+   scheme; the cross-repo checks (check 12) run from the index-holding
+   repo.
 
 ## Step 1 — Run the checks (read-only)
 
@@ -48,7 +51,8 @@ relevant):
    `adr-0042`, `see ADR`, ADR titles — in UI copy, API responses,
    error messages, customer-facing logs, public docs, release notes.
    Report each suspect; this rule is easy to violate by reflex.
-10. **Coordination hygiene.** `_agent/LOCKS.md` has no stale claims
+10. **Coordination hygiene.** N/A if `_agent/` was omitted at bootstrap
+    (Q5 = None). Otherwise: `_agent/LOCKS.md` has no stale claims
     (mode 2); `_agent/IN_FLIGHT.md` rows match live worktrees (mode 3).
 11. **Cross-worktree collisions** (mode 3, or when auditing across
     unmerged branches). These catch semantic conflicts that a
@@ -67,22 +71,35 @@ relevant):
     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
+    exists; run from the **index-holding** repo (`Role: central`, `home`,
+    or `coordinator` — whichever holds `federation-index.md`). 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.)
+      carries a `federation.md` back-pointer to this index-holder, and
+      every repo whose back-pointer names this repo is listed in the
+      index. Flag either half-edge (in-index-without-back-pointer, or
+      points-here-but-unlisted).
+    - **Identity collisions.** Under the repo-prefixed scheme an identity
+      is `repo-id` + local number, so the only reachable collision is a
+      **duplicate `repo-id`**. Flag any repo-id that appears on more than
+      one `federation-index.md` row or in two members' `federation.md`
+      back-pointers.
+    - **Dangling cross-repo references.** Resolve each cross-repo link
+      along `repo-id → Pointer → adr/NNNN-*.md` — look up the repo-id's
+      Pointer in `federation-index.md`, then the ADR file under that repo.
+      A repo-id with **no index row** is a dangling reference. If the row
+      exists but the **checkout is absent**, report it **"unverified this
+      run"** (not dangling); only an **absent ADR in a present checkout**
+      is a true dangling reference. (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.
+    - **Convention drift.** Compare each member's **shared** conventions
+      against the index-holder's authoritative copy; flag a member whose
+      shared conventions have drifted from the source. Members' **local-only**
+      conventions are exempt.
 
 ## Step 2 — Report
 

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

@@ -57,11 +57,27 @@ questions.
   federation-index.md    # multi-repo only (Q11): member index — home repo only
 ```
 
+**Placement.** The tree above shows the **root** option. `AGENTS.md` and
+`CLAUDE.md` always sit at the repository root; `adr/`, `plan/`, `_agent/`,
+`INDEX.md`, and `CONVENTIONS.md` go under the **artefact root** chosen in
+Q12 (default `docs/`, e.g. `docs/adr/`, `docs/plan/`).
+
+**Core vs optional layers.** Only the **core** is always written:
+`AGENTS.md`, `CLAUDE.md`, `CONVENTIONS.md`, `adr/0000-template.md`, and
+`INDEX.md`. A repo with just these is a valid, lightweight docflow repo — a
+classic ADR catalogue with conventions. Everything else is an **opt-in
+layer**: the `plan/` queue (Q4a), the `_agent/` coordination set (Q5 —
+choose *None* to omit it), `GLOSSARY.md` and `domains/` (Q7). Omitting any
+optional layer is a valid state, not an error; a lifecycle skill that needs
+an absent layer refuses cleanly and names what is missing.
+
 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.
+member list that lives only in the home/establishing repo. All federation
+artefacts — `federation.md`, `federation-index.md`, and the derived
+roll-up `ROLLUP.md` — are placed under the **configured artefact root**.
+A standalone repo has none of them.
 
 ## Step 3 — Conventions to install
 
@@ -120,7 +136,7 @@ repo has neither.
     doubt, ask whether a non-builder would ever see this string — if
     yes, the ADR reference comes out.
 
-## Step 4 — Assessment (10 questions, plus an optional federation question)
+## Step 4 — Assessment (10 questions, plus federation (Q11) and placement (Q12))
 
 **Ask the questions one at a time, not in a batch.** For each question,
 state a **recommended** option (label it "Recommended") with one short
@@ -134,7 +150,9 @@ ask in plain text, listing options as A/B/C and naming the recommended
 one.
 
 After the answers are in, summarise the resulting plan in 5–10
-lines and ask for sign-off before writing any files.
+lines and ask for sign-off before writing any files. Note in the summary
+that a **seed ADR `0001`** recording the adopted method is created by
+default (the operator may decline it — see Step 5 item 5b).
 
 1. **Project identity.** Name, one-line description, doc language
    (en-GB / en-US / other), and — if existing repo — what current files
@@ -171,8 +189,16 @@ lines and ask for sign-off before writing any files.
      marks ready, merges. Ask the user for merge strategy
      (squash / merge / rebase — default: squash for clean history,
      rebase if per-commit identity matters).
-5. **Multi-agent setup.** Pick one — the three options have different
-   coordination-file shapes, and switching later is not free:
+5. **Coordination — by number of writers.** Pick by how many people/agents
+   *write* to this repo and how they integrate — **writers (integration
+   concurrency), not how many agents you run.** A team of several developers
+   is multi-writer even with one agent each, and wants the worktree/PR
+   shape. This sets the `_agent/` shape (or omits it); switching later is
+   not free:
+   - **None — omit `_agent/`.** A solo human/agent with no coordination
+     need; no `_agent/` directory is written, and lifecycle skills skip the
+     WORKLOG/snapshot steps. The lightest footprint (the optional `_agent/`
+     layer is left out — see the core-vs-optional note in Step 2).
    - **(Recommended) Single agent.** `default-agent` in ROLES.
      LOCKS skipped. WORKLOG / CURRENT_FOCUS as standard single-file
      snapshots. Right for small projects and the "one human + one
@@ -246,15 +272,31 @@ lines and ask for sign-off before writing any files.
     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
+    **Establish** sets this repo's role from the chosen topology —
+    **central** (A), **coordinator** (B), or **home** (C) — writes the
+    member index here, and records the topology **and identity scheme**
+    in the federation config. **Join** asks for the home pointer **and the federation's topology +
+    identity scheme** — **you supply them; the skill performs no
+    cross-repo read and no host API call** — then writes **only this
+    repo's** back-pointer config, recording those values (it does not
+    re-choose the topology). 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.
+12. **Artefact placement.** Where the non-entry artefacts live — `adr/`,
+    `plan/`, `_agent/`, `INDEX.md`, `CONVENTIONS.md`:
+    - **(Recommended) `docs/`** — aligns with the common `doc/adr` / `docs/`
+      convention; keeps the repo root clean (`docs/adr/`, `docs/plan/`, …).
+    - **Repository root** — flat layout; decisions beside the code (good for
+      monorepos). This is docflow's own layout.
+    - **`.docflow/`** — hidden root; quietest footprint.
+
+    `AGENTS.md` and `CLAUDE.md` are **always** written to the repository
+    root (coding agents discover them there). The chosen root is recorded in
+    `CONVENTIONS.md`, and every lifecycle skill resolves `adr/`, `plan/`,
+    and `INDEX.md` against it. For an existing repo already laid out
+    differently, offer a documented migration (`git mv` into the chosen root
+    + update `CONVENTIONS.md`) — never force it.
 
 ## Step 4.5 — Cross-check before sign-off
 
@@ -283,6 +325,13 @@ Templates live in this skill's `templates/` directory. Read each
 template, fill its placeholders from the assessment answers, then
 write it into the repo.
 
+**Placement (Q12):** write `AGENTS.md` and `CLAUDE.md` to the repository
+root; write everything below under the chosen **artefact root** (default
+`docs/`) — e.g. `docs/adr/0000-template.md`, `docs/plan/`, `docs/INDEX.md`.
+Record the chosen root in `CONVENTIONS.md` so every lifecycle skill resolves
+paths against it, and adjust the `adr/`/`plan/` cross-paths in the filled
+`AGENTS.md` (and other templates) to the chosen root (e.g. `docs/adr/`).
+
 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
@@ -290,16 +339,29 @@ write it into the repo.
    (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
+   guardrails hard-rule bullet (G2–G4) under the same condition as the
    CONVENTIONS section above; omit otherwise.
 3. `CLAUDE.md` — from `templates/CLAUDE.md` (single line `@AGENTS.md`).
 4. `adr/0000-template.md` — from `templates/adr-capability.md`.
 5. `adr/NNNN-template.md` — from `templates/adr-technology.md`, only if
    Q2 said split. `NNNN` is the number where capability ADRs end
    (project-defined, e.g. 0091; default 0100 if unspecified).
+5b. **Seed ADR (default on; opt-out at sign-off).** Write the seed
+   `adr/0001-record-architecture-decisions.md` from
+   `templates/adr-0001-seed.md`, filled from the assessment answers — it
+   records the **decision to adopt** the documentation-led, ADR-driven
+   method, status **`Implemented`**, and **references `CONVENTIONS.md`** for
+   the rules (it does not duplicate them). Keep it generic — no other
+   project's ADR numbers. **Skip only if the operator opted out.** For a
+   **split** repo (Q2) use the technology-ADR shape for the seed. If `plan/`
+   exists, also write a matching `plan/done/<date>-adopt-adr-method.md` (the
+   seed's completion event is this bootstrap), so plan-coverage stays
+   satisfied. On a **retrofit/backfill** (Step 6), the seed is `0001`, ahead
+   of the reconstructed decisions.
 6. `plan/README.md` — from `templates/plan-README.md`. Create empty
    `plan/todo/.gitkeep` and `plan/done/.gitkeep`.
-7. `_agent/ROLES.md` — from `templates/_agent-ROLES.md`. Mode 1
+7. `_agent/ROLES.md` — from `templates/_agent-ROLES.md`. **If Q5 = None,
+   skip items 7–11 entirely — no `_agent/` directory.** Otherwise: Mode 1
    keeps the `default-agent` block; modes 2 and 3 expand to named
    agents per Q5.
 8. `_agent/LOCKS.md` — from `templates/_agent-LOCKS.md`. **Skip in
@@ -315,7 +377,8 @@ write it into the repo.
     `_agent/IN_FLIGHT.md` from `templates/_agent-IN_FLIGHT.md` as
     the committed cross-worktree dashboard.
 11. `_agent/HANDOFF.md` — from `templates/_agent-HANDOFF.md`.
-12. Stub `INDEX.md` — header + empty table.
+12. `INDEX.md` — header + the seed ADR's row (item 5b); an empty table only
+    if the seed was declined.
 13. `_agent/prompts/autonomous.md` — from
     `templates/_agent-prompts-autonomous.md`, **only** if Q8 confirmed a
     verify gate. Keep the integration block matching Q4b: the
@@ -326,18 +389,30 @@ write it into the repo.
     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.
+      repo, seeded with this repo as the first member; and write
+      `federation.md` from `templates/federation-config.md` with the
+      chosen topology, the chosen identity scheme (default repo-prefixed
+      slug), and this repo's **`Role` set from the topology**:
+      `central` for **A** (this repo holds all product-wide ADRs),
+      `coordinator` for **B** (this repo holds only the member index —
+      product-wide decisions are distributed and the roll-up is the
+      product-wide view), or `home` for **C** (this repo holds
+      product-wide ADRs; members keep local ADRs alongside). 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).
+      for the federation, **supplied by the operator at join** (recorded
+      into this repo's `federation.md`; no cross-repo read). Then apply
+      the **topology's member rule**: for **A**, this
+      repo references the central repo and does **not** hold product-wide
+      ADRs locally (its `adr/` is for local-implementation decisions
+      only); for **B**, this repo owns its own catalogue in full; for
+      **C**, this repo keeps local ADRs and references the home for
+      product-wide ones. Write nothing into any other repo, and do **not**
+      create a member index. Tell the user to add this repo to the
+      **index-holding repo's** `federation-index.md` — the home (C),
+      central (A), or coordinator (B) repo — 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/templates/CONVENTIONS.md

@@ -4,6 +4,10 @@
 
 Project name: <name>.
 
+Artefact root: `<docs/ | . | .docflow/>` — `adr/`, `plan/`, `INDEX.md`, and
+this file live under this root; `AGENTS.md` and `CLAUDE.md` always stay at
+the repository root. Every lifecycle skill resolves paths against this root.
+
 <!-- Q1 language: if a language mandate is set, state it here.
 Example: "Language: en-GB throughout. Use forms such as organisation,
 behaviour, prioritise, catalogue, authorisation consistently across all
@@ -14,6 +18,14 @@ files." -->
 ADR filenames use `NNNN-kebab-case-slug.md`, zero-padded to 4 digits,
 with contiguous numbering and no reserved gaps.
 
+The number is an **integer**; the four-digit zero-padding is a display
+convention only — tools sort ADRs **numerically**, not lexically, so the
+catalogue is not capped at `9999` (widen the padding to five digits if you
+ever approach it; none do). Related ADRs may be **grouped** under
+`domains/<slug>/README.md` without changing their numbers — grouping is a
+curated view, not a separate namespace; the contiguous number stays the
+single identity.
+
 Each ADR describes one decision. If a decision splits, supersede the
 original ADR and create new ADRs rather than expanding scope inside a
 single document.
@@ -31,6 +43,11 @@ Status lifecycle: `<from Q3>`.
 Terminal states (Superseded / Deprecated) are reachable from any prior
 state.
 
+The first **persisted** status is `Proposed` — there is no separate `Draft`
+state and no `brainstorming/`/`drafts/` folder. Work-in-progress lives in
+the brainstorm conversation; only an approved decision is written, as a
+numbered `Proposed` ADR.
+
 Cross-references link by relative path to `adr/NNNN-*.md`.
 
 ## ADR Shapes
@@ -165,6 +182,13 @@ once merged:
 - **G3 — gate backstop.** Integration is single-threaded; it rejects a
   duplicate number as the last line of defence, and the later author
   renumbers.
+- **G4 — claim before do.** Before implementing a queued item, **claim it**
+  so two writers don't build the same thing: open a draft PR referencing
+  the item (the authoritative claim in PR-based / worktree repos), or record
+  an `owner` / `_agent/IN_FLIGHT.md` entry. An unclaimed `plan/todo` item on
+  `main` (which G1 deliberately puts there) is otherwise an open invitation
+  to duplicate effort. G1–G3 protect the *number*; G4 protects the *work
+  assignment*. `/audit`'s duplicate-plan-ownership check is the backstop.
 -->
 
 <!-- Federation (multi-repo) — bootstrap INCLUDES this section
@@ -177,13 +201,27 @@ 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.
 
+- **Where product-wide decisions live depends on the topology** (recorded
+  in `federation.md`):
+  - **A — central:** a single central repo holds **all** product-wide
+    ADRs; every other repo references them and never duplicates a
+    product-wide decision locally.
+  - **B — distributed:** **no** repo holds product-wide ADRs; each repo
+    owns its own catalogue and the roll-up is the product-wide view.
+  - **C — home + local:** the home repo holds product-wide ADRs; members
+    keep purely-local ADRs alongside and reference the home for
+    product-wide ones.
 - **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
+  member index along `repo-id → Pointer (repo root) → adr/NNNN-*.md`: look
+  up the repo-id's `Pointer` in `federation-index.md`, then find
+  `adr/NNNN-*.md` under that repo. They survive a target repo move (edit
+  one index row, not the references). A **member repo holds no index**, so
+  it first reaches `federation-index.md` via its own `federation.md`
+  `Home` pointer, then resolves as above. **Same-repo references stay
   relative paths** (`adr/NNNN-*.md`).
 - `supersedes:` / `superseded-by:` may point across repos using the
   logical identity.
@@ -191,6 +229,24 @@ identity scheme are recorded in `federation.md`; the home repo's
   `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.
+- **Cross-repo work is one plan item per repo.** A decision implemented in
+  several repos gets one `plan/todo` item **per affected repo**, each in
+  the repo whose code it changes and naming the owning ADR by its
+  federation identity. The owning ADR is the single grouping point — its
+  per-repo items are discoverable from it; there is **no umbrella record**.
+  Per-repo "lower numbers first" ordering is unchanged.
+- **Aggregate status is derived in the roll-up.** A cross-repo decision is
+  `Implemented` only when **every** owning per-repo plan item has shipped
+  (each under its own repo's completion event); until then it is partially
+  implemented. The aggregate ("2 of 3 repos") is a **derived column in the
+  roll-up**, computed from per-repo plan-item state — never hand-written
+  into the ADR, so no cross-repo writes.
+- **Shared conventions come from one source.** Shared conventions and
+  templates are authoritative in the index-holding repo; members **copy
+  them at bootstrap** and may keep **local-only** conventions alongside.
+  Updates are **not** force-pushed — drift between a member's copy and the
+  source is **detected by audit**. Referenceable, not enforced; no
+  cross-repo writes.
 -->
 
 ## Audit Trail Policy

package/plugins/docflow/skills/bootstrap/templates/adr-0001-seed.md

@@ -0,0 +1,81 @@
+---
+adr: 0001
+title: Record architecture decisions as ADRs
+status: Implemented
+date: <YYYY-MM-DD>
+owner: <agent-id or human>
+supersedes:
+superseded-by:
+depends-on: []
+tags: [process, conventions]
+---
+
+# ADR 0001 — Record architecture decisions as ADRs
+
+<!-- Bootstrap writes this as the seed ADR (adr/0001) by default. It records
+the *decision* to adopt the method; the operative rules live in
+CONVENTIONS.md. Keep it generic — do not reference another project's ADR
+numbers. For a split-shape repo, adapt to the technology-ADR shape. -->
+
+## Context
+
+<Project> needs its significant decisions to be **discoverable, traceable,
+and durable** — not held in chat logs, pull-request threads, or one
+person's memory. The lightweight Architecture Decision Record practice
+(Michael Nygard, 2011; the markdown-ADR convention) records each decision
+as one small, numbered, immutable file stored beside the code, so the
+reasons behind the system are part of the repository.
+
+## Capability statement
+
+This repository is **documentation-led and ADR-driven**: every significant
+decision is recorded as a numbered ADR under `adr/`; the catalogue is the
+**source of truth** the running system is expected to match; and a status
+lifecycle drives a `plan/` work queue. The authoring rules — ADR shape,
+status lifecycle, numbering, audit trail, and git contract — live in
+`CONVENTIONS.md`. This ADR records the **decision to adopt the practice**,
+not the rules themselves.
+
+## User stories / scenarios
+
+- As a contributor, I find the reasons behind this system in the catalogue,
+  not by asking someone.
+- As a maintainer, each decision, the work that implements it, and the
+  commit that ships it are linked through one stable identifier.
+- As a new reader, the first ADR explains why this repository uses ADRs and
+  points me at where the rules live.
+
+## Acceptance criteria
+
+1. Significant decisions are recorded as numbered ADRs under `adr/`,
+   following `CONVENTIONS.md`.
+2. The catalogue is the source of truth; code is expected to match the
+   decisions it records.
+3. ADR authoring, the status lifecycle, and the `plan/` queue follow
+   `CONVENTIONS.md`.
+
+## Out of scope
+
+- The detailed authoring rules (ADR shape, lifecycle, numbering, git
+  contract) — these live in `CONVENTIONS.md`, not here.
+
+## Open questions
+
+- None.
+
+## References / cross-links
+
+- CONVENTIONS.md (the operative authoring rules)
+- Michael Nygard, "Documenting Architecture Decisions" — https://adr.github.io
+
+## Revision History
+
+| Date | Revision | Author | Change |
+|------|----------|--------|--------|
+| <YYYY-MM-DD> | r1 | <owner> | Adopted the documentation-led, ADR-driven method (seeded at bootstrap). |
+
+## Approvals
+
+| Role | Name | Date | Signature |
+|------|------|------|-----------|
+| <role> | <name> | <YYYY-MM-DD> | — |

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

@@ -9,7 +9,7 @@ is my home?"; the home repo's `federation-index.md` is the answer to
 - **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>
+- **Role:** <central | home | coordinator | member — the establishing repo's role is set by the topology (central for A, coordinator for B, home for C); every joining repo is `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

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

@@ -11,7 +11,12 @@ skills read this to enumerate the product's repos.
 
 | Repo id | Repo | Role | Pointer |
 |---------|------|------|---------|
-| <id>    | <this repo> | home | this repo |
+| <id>    | <this repo> | <central\|home\|coordinator> | this repo |
+
+<!-- Role values: the establishing repo is `central` (topology A),
+`coordinator` (B), or `home` (C); every other member is `member`.
+Pointer `this repo` means the repo that holds this index (the
+index-holder); resolve every other Pointer relative to it. -->
 
 <!-- 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/new-adr/SKILL.md

@@ -15,7 +15,9 @@ Author one new ADR, consistent with this repo's conventions.
 2. Read `CONVENTIONS.md` to learn this repo's choices: ADR shape
    (single vs. capability/technology split and the cutoff number),
    status lifecycle, language mandate (if any), whether `domains/`
-   groupings exist, and the multi-agent mode.
+   groupings exist, the multi-agent mode, and the **artefact root**
+   (default: repository root) — resolve `adr/` and `INDEX.md` against it
+   (`AGENTS.md`/`CLAUDE.md` stay at the repo root).
 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 —
@@ -84,8 +86,8 @@ If this ADR replaces an existing one:
   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.
+  identity (`<repo-id>/NNNN-slug`), resolved via the member index along
+  `repo-id → Pointer → adr/NNNN-*.md` — 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-plan/SKILL.md

@@ -13,7 +13,8 @@ Add one item to the implementation queue.
    repo was bootstrapped without a plan folder (Q4a = skip), stop and
    say so — there is no queue to add to.
 2. Read `CONVENTIONS.md` for the plan-folder convention and the
-   completion event, and `plan/README.md` if present.
+   completion event, and `plan/README.md` if present. Resolve `plan/`
+   against the **artefact root** recorded there (default: repository root).
 3. `ls plan/todo/` to learn existing numbers and priority ordering.
 
 ## Step 0.5 — Assessment (run first)
@@ -52,6 +53,12 @@ Questions (skip any the request already answers):
   still `Proposed`, warn — you can queue ahead of acceptance, but the
   work is not yet authorised. If it has no ADR at all, suggest running
   the **new-adr** skill first; plan items should trace to a decision.
+- **In a federation** (a `federation.md` exists): the owning ADR may live
+  in **another** repo (the home/central). Name it by its **federation
+  identity** (`<repo-id>/NNNN-slug`); the plan item itself lives in **this**
+  repo — the one whose code the work changes. A decision spanning several
+  repos gets **one item per affected repo**, each tracing to the same
+  owning ADR (the grouping point — no umbrella record).
 
 ## Step 2 — Pick number and position
 

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

@@ -12,11 +12,13 @@ from source, never hand-edited — treat it exactly like a repo's own
 
 ## 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.
+1. This skill runs in the **index-holding repo** of a federation — the one
+   that carries `federation-index.md` (its `Role` is `central` for
+   topology A, `coordinator` for B, or `home` for C). Confirm
+   `federation-index.md` and a `federation.md` whose `Role` is `central`,
+   `home`, or `coordinator` exist. If they do not, stop: either this repo
+   is standalone (nothing to roll up) or it is a plain member — point the
+   user at the index-holding repo.
 2. Read `federation.md` to learn the **identity scheme** (default
    repo-prefixed slug `<repo-id>/NNNN-slug`); roll-up rows use it.
 
@@ -38,6 +40,12 @@ For every member whose checkout is **locally available** at its pointer:
 A member's own `INDEX.md` stays authoritative for that member; this skill
 only reads it.
 
+For the **aggregate status** of a product-wide decision (one with owning
+per-repo plan items across several members), also scan each member's
+`plan/todo/` (pending) and `plan/done/` (shipped) for items naming that
+decision's federation identity — that per-repo state feeds the aggregate
+column in Step 4.
+
 ## Step 3 — Handle unreachable members
 
 A member named in the index whose checkout is **not locally available** is
@@ -47,12 +55,17 @@ 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`):
+Write the aggregate to **`ROLLUP.md`** at the configured artefact root (the
+same root as `INDEX.md`), so every re-run overwrites the same file:
 
 - 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.
+- For product-wide decisions, an **aggregate status** column **derived**
+  from per-repo plan-item state: `Implemented` only when every owning
+  per-repo plan item is in a member's `plan/done/`, otherwise `N of M
+  repos` shipped. This column is derived — never written back into any ADR.
 - 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.

package/plugins/docflow/skills/ship-item/SKILL.md

@@ -14,7 +14,9 @@ order-sensitive operation in the system — follow the steps exactly.
 2. Read `CONVENTIONS.md` and `AGENTS.md` for: the **integration model**
    (direct-to-main fast-forward vs. PR-based with required CI), the
    **verify gate** command, the **multi-agent mode**, and the Git
-   contract (signed commits, tags, trailers).
+   contract (signed commits, tags, trailers). Resolve `adr/`, `plan/`, and
+   `INDEX.md` against the **artefact root** recorded in `CONVENTIONS.md`
+   (default: repository root).
 
 ## Step 1 — Select the item
 
@@ -53,6 +55,9 @@ Once the change is on `main`:
 
 ## Step 6 — Record
 
+**If `_agent/` was omitted at bootstrap (Q5 = None), skip this step** — git
+history is the record.
+
 - Append a one-line `_agent/WORKLOG.md` row: branch, HEAD, verify
   result, any deferral.
 - Update the live snapshot: `_agent/CURRENT_FOCUS.md` in single-checkout