@evolvehq/docflow 0.4.3 → 0.5.0

package/README.md

@@ -1,5 +1,7 @@
 # docflow
 
+![docflow — ADR-driven documentation workflow](docs/preview.png)
+
 A plugin for **ADR-driven, documentation-led projects**, working on both
 the **pi** and **Claude Code** coding agents from the same skill files.
 It installs a `bootstrap` skill that scaffolds (or retrofits) an
@@ -21,7 +23,7 @@ agent the same skills are invoked as `/skill:<name>` (e.g.
 | new-adr | `/new-adr` | Author one ADR — next contiguous number, right shape, INDEX + domain wiring, supersede linkage. |
 | new-plan | `/new-plan` | Add a `plan/todo` item tracing to its owning ADR(s). |
 | ship-item | `/ship-item` | Run the completion event: verify → integrate → `todo`→`done` → ADR `Accepted`→`Implemented` → INDEX/WORKLOG. |
-| add-convention | `/add-convention` | Assess whether a convention is worth codifying, route it to the right home (or to an ADR), then add it. |
+| add-convention | `/add-convention` | Assess whether a convention is worth codifying, route it to the right home (or to an ADR), then add it. Use it to enable optional practices (e.g. TDD) on demand — see [USAGE §5a](USAGE.md). |
 | 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. |

package/USAGE.md

@@ -195,6 +195,44 @@ It requires a multi-agent mode (Q5 mode 2 or 3) and works best in mode
 Continuous-unsupervised runs are recommended only with PR-based
 integration, so CI gates each merge.
 
+### Enabling an optional convention later (worked example: TDD)
+
+docflow's bootstrap is deliberately lean — practices such as
+test-driven development are **not** baked in. You enable them whenever
+you want with `/add-convention`; there is no dedicated command per
+practice, and you don't have to re-bootstrap.
+
+Say *"add a convention: implement plan items test-first"* (or just run
+`/add-convention` and describe the rule). The skill will:
+
+1. **Assess** whether it is worth codifying. TDD passes — it is a
+   durable, repo-wide rule, not a one-off, a duplicate, or churn-prone.
+2. **Route** it to the right home: a short **hard rule** in `AGENTS.md`
+   plus the detail in `CONVENTIONS.md`. (It would not make this a
+   GLOSSARY term, and it is not a single decision, so not an ADR.)
+3. **Write** it, agent-neutral, so it holds on Claude Code and pi alike.
+
+A typical result — a new `CONVENTIONS.md` section:
+
+> ## Test-Driven Development
+> Implement each `plan/todo` item test-first. For every numbered
+> acceptance criterion in the owning ADR, write a failing test before
+> the code that satisfies it, then make it pass, then refactor. An item
+> is not shippable until its criteria have passing tests mapped back to
+> them.
+
+and a matching `AGENTS.md` hard-rule bullet:
+
+> - **TDD:** write the failing test for an acceptance criterion before
+>   implementing it; map tests back to the owning ADR's criteria.
+
+This rides docflow's existing rule that *acceptance criteria are
+testable and numbered* — TDD simply fixes the order (test → code). To
+turn it off, delete those sections (or re-run `/add-convention` and say
+it no longer applies); to make it enforceable, add the test command to
+the verify gate. Any other "we should always X" practice is enabled the
+same way — `/add-convention` is the single path.
+
 ## 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.4.3",
+  "version": "0.5.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",
@@ -16,8 +16,13 @@
     "url": "git+https://github.com/EvolveHQ/docflow.git"
   },
   "homepage": "https://github.com/EvolveHQ/docflow",
+  "scripts": {
+    "verify": "node scripts/verify.mjs",
+    "evals": "node evals/run.mjs"
+  },
   "files": [
     "skills/",
+    "docs/preview.png",
     "README.md",
     "USAGE.md",
     "LICENSE"
@@ -26,6 +31,7 @@
     "access": "public"
   },
   "pi": {
-    "skills": ["./skills"]
+    "skills": ["./skills"],
+    "image": "https://raw.githubusercontent.com/EvolveHQ/docflow/main/docs/preview.png"
   }
 }

package/skills/add-convention/SKILL.md

@@ -15,6 +15,36 @@ stenographer.
 2. Read `CONVENTIONS.md` and `AGENTS.md` in full so you can detect
    overlap with existing rules and judge fit.
 
+## Step 0.5 — Assessment (run first)
+
+Run the shared assessment protocol; the triage (Step 1) and routing
+(Step 2) questions are asked under it:
+
+- **Opt-out gate first.** Ask whether to run the assessment or skip to
+  drafting. Recommend **running** it when the request arrived with little
+  or no context; recommend **skipping** when the convention and its home
+  are already clear.
+- Ask questions **one at a time**, each with a **recommended option** and
+  a one-line reason; wait for each answer.
+- Use **structured selection** (single- or multiple-choice). If the host
+  exposes a structured single-/multi-select question tool, use it and
+  mark the recommended option; otherwise list options A/B/C in plain text
+  and name the recommended one. Use **free text only** where an
+  enumerable set is impossible (e.g. the exact wording).
+- **The operator decides.** Never proceed past a question without an
+  answer, and never guess scope when invoked with no context.
+
+Questions (skip any the request already answers):
+1. **Worth codifying?** — yes (recurring, stable, testable) or no
+   (one-off, duplicate, churn-prone, vague). *Recommended: per the Step 1
+   triage; this question gates the rest.*
+2. **Home** — `AGENTS.md` hard rule / `CONVENTIONS.md` guidance /
+   `GLOSSARY.md` term / actually a decision (hand off to the **new-adr**
+   skill). *Recommended: per the rule's nature (see Step 2).*
+3. **Enforce in the verify gate?** — yes / no. *Recommended: no, unless
+   the rule is mechanically checkable.*
+4. **Wording** — free text (the rule statement itself).
+
 ## Step 1 — Assess: is this worth codifying?
 
 Apply triage. Recommend **against** adding when:

package/skills/agent-wave/SKILL.md

@@ -32,6 +32,25 @@ you there rather than pretending to be it.
    - **Mode 3 (worktrees):** the intended mode. Each subagent works in
      its own isolated worktree.
 
+## Step 0.5 — Assessment (run first)
+
+Run the shared assessment protocol before spawning anything:
+
+- **Opt-out gate first.** Ask whether to run the assessment or proceed on
+  recommended defaults. Recommend **running** it when the request arrived
+  with little or no context (e.g. a bare "fan out the queue"); recommend
+  **skipping** when width, budget, supervision, and merge strategy were
+  all specified.
+- The Step 1 parameters **are** the assessment questions: ask them **one
+  at a time**, each with a **recommended option** and a one-line reason;
+  wait for each answer.
+- Use **structured selection** (single- or multiple-choice). If the host
+  exposes a structured single-/multi-select question tool, use it and
+  mark the recommended option; otherwise list options A/B/C in plain text
+  and name the recommended one. Use free text only where unavoidable.
+- **The operator decides.** Never spawn a wave without confirmed
+  parameters, and never guess when invoked with no context.
+
 ## Step 1 — Ask the wave parameters (one at a time, recommend)
 
 1. **Wave width N** — how many agents per wave.
@@ -42,6 +61,11 @@ you there rather than pretending to be it.
    continue) or **continuous** (run wave after wave until budget/queue
    exhausted).
    *Recommended: checkpoint* for the first run on a repo.
+4. **Merge / integration strategy** — how each shipped item lands.
+   *Recommended: follow the repo's integration model* (read it from
+   `CONVENTIONS.md`). Override options: **local fast-forward**,
+   **PR-based**, or **other**. This sets how each subagent integrates in
+   Step 3 and what "shipped" means for the wave.
 
 Cross-check: **continuous + direct-to-main** is risky — nothing gates
 each merge. If the repo is direct-to-main, recommend either switching
@@ -53,8 +77,25 @@ every merge.
 - Read `plan/todo/`; take the lowest-numbered N items with no unmet
   dependencies. Two agents must never get the same item or items that
   edit the same files — partition by item and, in mode 2, by LOCKS.
+- **Reserve identifiers before spawning.** Parallel worktrees that each
+  author an ADR or a `plan/` item will otherwise collide on the same
+  next number — each worktree computes "next" against its own checkout,
+  so two will pick the same one and break the contiguous-numbering
+  invariant at merge. Before the wave:
+  - Compute the current highest ADR number and `plan/todo` slot.
+  - Hand each agent a **disjoint reserved block** — e.g. agent A may
+    create ADRs `0042+` and plan slots `0007+`, agent B `0043+` /
+    `0008+`, interleaved so no two blocks overlap. Most queue items
+    implement an existing ADR and need none — reserve only for items
+    that will author new ADRs/plans.
+  - An agent uses only its reserved identifiers; if it needs more than
+    reserved, it stops and reports rather than guessing.
+- **Single writer per artefact.** An ADR body (or a given `plan/` item)
+  is edited by at most one worktree per wave. Never put two items that
+  both edit the same ADR in one wave — a `merge=union` would silently
+  concatenate contradictory edits into an incoherent document.
 - Record the assignment in `_agent/IN_FLIGHT.md` (mode 3) so the wave is
-  visible.
+  visible — including each agent's reserved identifier block.
 
 ## Step 3 — Spawn the wave
 

package/skills/audit/SKILL.md

@@ -1,65 +1,79 @@
----
-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, and ADR-privacy leaks into user-visible code. 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
-
-Check a documentation-led repo against the conventions it declares.
-This is the enforcement `AGENTS.md` cannot guarantee on its own.
-
-## Step 0 — Preconditions and context
-
-1. Confirm the repo is bootstrapped.
-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.
-
-## Step 1 — Run the checks (read-only)
-
-Report each as PASS / FAIL / N/A with specifics (file + line where
-relevant):
-
-1. **Numbering.** ADR filenames contiguous, zero-padded, no gaps, no
-   duplicates. Split repos: capability below cutoff, technology at/above.
-2. **INDEX sync.** Every ADR appears in `INDEX.md`; every INDEX row has
-   a matching file; metadata fields (status, title, date) agree.
-3. **Plan coverage.** Every `Accepted` ADR has a `plan/todo/` item;
-   every `Implemented` ADR has a `plan/done/` entry. Flag orphans both
-   ways.
-4. **Section completeness.** Each ADR has the required sections in the
-   order its shape mandates. Acceptance criteria are numbered.
-5. **Status validity.** Every `status:` is in the declared lifecycle.
-   `Superseded` ADRs name a successor in `superseded-by:`; the successor
-   names them in `supersedes:` (symmetry).
-6. **Revision/Approvals.** Revision History present; Approvals populated
-   for ADRs at `Accepted` or beyond.
-7. **Cross-references.** Relative `adr/NNNN-*.md` links resolve to real
-   files. Glossary anchors (if used) resolve.
-8. **Language mandate.** If set, spot-check user-facing docs for the
-   required spellings.
-9. **ADR-privacy leaks.** Grep source / product directories for ADR
-   identifiers in user-visible strings — patterns like `ADR 0042`,
-   `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
-    (mode 2); `_agent/IN_FLIGHT.md` rows match live worktrees (mode 3).
-
-## Step 2 — Report
-
-Lead with a one-line verdict (clean / N issues). Then the punch list,
-grouped by severity: **blocking** (privacy leaks, status/lifecycle
-violations, broken cross-refs), **drift** (INDEX out of sync, missing
-plan files), **hygiene** (stale locks, formatting).
-
-## Step 3 — Offer fixes
-
-Offer to fix the **mechanical** issues automatically: regenerate
-`INDEX.md`, create missing `plan/todo` stubs, clear stale locks, fix
-broken relative links. **Do not** auto-edit ADR content, rewrite
-acceptance criteria, or remove suspected privacy leaks without the
-user confirming each — those need judgement. Commit fixes as
-`fix(adr): ...` / `docs: ...` with a `Rationale:` footer where an ADR
-is touched.
+---
+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.
+---
+
+# audit
+
+Check a documentation-led repo against the conventions it declares.
+This is the enforcement `AGENTS.md` cannot guarantee on its own.
+
+## Step 0 — Preconditions and context
+
+1. Confirm the repo is bootstrapped.
+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.
+
+## Step 1 — Run the checks (read-only)
+
+Report each as PASS / FAIL / N/A with specifics (file + line where
+relevant):
+
+1. **Numbering.** ADR filenames contiguous, zero-padded, no gaps, no
+   duplicates. Split repos: capability below cutoff, technology at/above.
+2. **INDEX sync.** Every ADR appears in `INDEX.md`; every INDEX row has
+   a matching file; metadata fields (status, title, date) agree.
+3. **Plan coverage.** Every `Accepted` ADR has a `plan/todo/` item;
+   every `Implemented` ADR has a `plan/done/` entry. Flag orphans both
+   ways.
+4. **Section completeness.** Each ADR has the required sections in the
+   order its shape mandates. Acceptance criteria are numbered.
+5. **Status validity.** Every `status:` is in the declared lifecycle.
+   `Superseded` ADRs name a successor in `superseded-by:`; the successor
+   names them in `supersedes:` (symmetry).
+6. **Revision/Approvals.** Revision History present; Approvals populated
+   for ADRs at `Accepted` or beyond.
+7. **Cross-references.** Relative `adr/NNNN-*.md` links resolve to real
+   files. Glossary anchors (if used) resolve.
+8. **Language mandate.** If set, spot-check user-facing docs for the
+   required spellings.
+9. **ADR-privacy leaks.** Grep source / product directories for ADR
+   identifiers in user-visible strings — patterns like `ADR 0042`,
+   `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
+    (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
+    line-level git merge cannot:
+    - **Duplicate ADR numbers** — two ADR files (across branches/
+      worktrees) claiming the same `NNNN`. Distinct from check 1, which
+      only sees one tree.
+    - **Duplicate plan ownership** — two `plan/todo/` items naming the
+      same owning ADR for the same scope, i.e. two worktrees building
+      the same thing.
+    - **Same ADR edited on two unmerged branches** — compare ADR files
+      across the live worktrees / open PRs; flag any ADR modified in
+      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.
+
+## Step 2 — Report
+
+Lead with a one-line verdict (clean / N issues). Then the punch list,
+grouped by severity: **blocking** (privacy leaks, status/lifecycle
+violations, broken cross-refs), **drift** (INDEX out of sync, missing
+plan files), **hygiene** (stale locks, formatting).
+
+## Step 3 — Offer fixes
+
+Offer to fix the **mechanical** issues automatically: regenerate
+`INDEX.md`, create missing `plan/todo` stubs, clear stale locks, fix
+broken relative links. **Do not** auto-edit ADR content, rewrite
+acceptance criteria, or remove suspected privacy leaks without the
+user confirming each — those need judgement. Commit fixes as
+`fix(adr): ...` / `docs: ...` with a `Rationale:` footer where an ADR
+is touched.

package/skills/bootstrap/templates/AGENTS.md

@@ -1,157 +1,157 @@
-# AGENTS.md
-
-This file provides guidance to coding agents working in this repository.
-
-## What this repository is
-
-<One paragraph. Project purpose, current baseline, what the artefacts in
-this repo represent.>
-
-## Repository structure
-
-- `adr/0000-template.md` — canonical ADR template.
-<!-- If technology-ADR split (Q2): also include `adr/NNNN-template.md` for technology ADRs. -->
-- `adr/NNNN-<kebab-slug>.md` — one ADR per decision, contiguous
-  numbering, no gaps.
-- `INDEX.md` — table regenerated from every ADR's metadata block.
-- `CONVENTIONS.md` — authoring rules (read before editing anything).
-- `plan/todo/NNNN-<slug>.md` — pending work, lower numbers run first.
-- `plan/done/<YYYY-MM-DD>-<slug>.md` — shipped work, chronological.
-- `_agent/` — multi-agent coordination: `ROLES.md`, `LOCKS.md`,
-  `WORKLOG.md`, `CURRENT_FOCUS.md`, `HANDOFF.md`, `prompts/`.
-<!-- If GLOSSARY.md (Q7): also include `GLOSSARY.md` — shared terms. -->
-<!-- If domains/ (Q7): also include `domains/<slug>/README.md`. -->
-
-## Hard rules when editing ADRs
-
-These come from `CONVENTIONS.md` and override default behaviour:
-
-- **One decision per ADR.** Splits become new ADRs that supersede;
-  never expand scope inside an existing one.
-- **Status lifecycle:** `<from Q3>`.
-- **Capability ADR section order:** metadata → Context → Capability
-  statement → User stories / scenarios → Acceptance criteria → Out of
-  scope → Open questions → References → Revision History → Approvals.
-<!-- If technology-ADR split (Q2): -->
-- **Technology ADR section order:** metadata → Context → Decision →
-  Rationale → Consequences → Acceptance criteria → Out of scope → Open
-  questions → References → Revision History → Approvals. Rationale must
-  name alternatives considered with specific rejection reasons.
-- **Acceptance criteria are testable and numbered.**
-- **ADRs are internal artefacts — never user-visible.** ADR numbers,
-  ADR titles, and the existence of the ADR catalogue must NEVER appear
-  in any string the product emits to users: UI copy, API response
-  bodies, error messages, customer-visible log lines, public
-  documentation, release notes, marketing copy, or support
-  communications. The catalogue is a builder's tool, not a user-facing
-  surface. References ARE allowed in: code comments
-  (`// see adr/0042-foo.md`), commit messages, PR descriptions,
-  internal docs, `AGENTS.md`, `CONVENTIONS.md`, `INDEX.md`, and the
-  `plan/` queue. Rule of thumb: if a non-builder could ever see the
-  string, the ADR reference comes out.
-<!-- Insert any Q10 domain-specific hard rules here as additional bullets. -->
-
-## Implementation work
-
-- Start from the ADRs. Identify which ADRs a code change implements or
-  affects before changing behaviour.
-- If implementation reveals a capability gap or changed decision, update
-  the relevant ADR rather than silently diverging.
-- Add or update tests for implemented behaviour. Map tests back to ADR
-  acceptance criteria where practical.
-- **Do not leak ADR identifiers into user-visible surfaces.** When
-  writing error messages, UI copy, API responses, log lines that ship
-  to customers, public docs, or release notes, refer to the behaviour
-  by its product-level name — never by ADR number, ADR title, or
-  phrases like "per the ADR catalogue". The ADR link belongs in the
-  commit message and (optionally) an inline code comment, not in the
-  string the user reads.
-
-## Audit trail and revision discipline
-
-- Substantive ADR changes append a row to the Revision History table.
-  Editorial changes (typos, formatting, link fixes) are excluded but
-  flagged `editorial` in the commit message.
-- Approvals table populates when an ADR is Accepted and updates on each
-  later substantive revision.
-- Regenerate `INDEX.md` from ADR metadata after any ADR status change
-  or new ADR.
-
-## Multi-agent workflow
-
-<!-- Mode 1 — single agent (Q5 default). Keep this block. -->
-A single agent owns this repo. The `_agent/` directory tracks live
-state and history; LOCKS discipline is not in use.
-
-<!-- Mode 2 — multi-agent, shared checkout. Replace the block above with: -->
-<!--
-Work is partitioned across named agents (see `_agent/ROLES.md`).
-Coordination rules:
-- Before editing a file, claim it in `_agent/LOCKS.md` by appending
-  `<agent-id> | <path> | <ISO-8601 timestamp>`. Remove the line on
-  commit. LOCKS is a filesystem mutex — it prevents simultaneous
-  writes to the same file.
-- Append a one-line entry to `_agent/WORKLOG.md` on every commit.
-- `_agent/CURRENT_FOCUS.md` is the single in-flight snapshot
-  (branch, active queue item, blockers, uncommitted work). Update it
-  when state changes.
--->
-
-<!-- Mode 3 — multi-agent, separate worktrees / PR branches. Replace
-the block above with: -->
-<!--
-Work is partitioned across named agents (see `_agent/ROLES.md`).
-Each agent works in its own git worktree or PR branch.
-Coordination rules:
-- **GitHub draft PRs / branch assignment are the authoritative lock.**
-  `_agent/LOCKS.md` is advisory only — append an intent declaration
-  if it helps coordinate before a PR exists; do not rely on it as a
-  mutex. The filesystem can't conflict across worktrees, but
-  duplicated work and contradictory merges still can.
-- Append a one-line entry to `_agent/WORKLOG.md` on every commit.
-  The repo's `.gitattributes` sets `_agent/WORKLOG.md merge=union`
-  so concurrent appends concatenate instead of conflicting.
-- `_agent/CURRENT_FOCUS.md` is local-only per worktree (gitignored).
-  Update it freely; it never merges.
-- The committed cross-worktree dashboard is `_agent/IN_FLIGHT.md` —
-  one row per active worktree (agent, branch, queue item, started).
-  Add your row when you start, remove it when the worktree closes.
--->
-
-## Plan folder
-
-- A pending item gets a `plan/todo/NNNN-<slug>.md` file BEFORE work
-  starts, naming the owning ADR(s), scope, and exit criteria.
-- The completion event is: `<from Q4 — e.g. merge to main, deploy +
-  smoke passes, release tag>`. On completion, `git mv` the file to
-  `plan/done/<YYYY-MM-DD>-<slug>.md` with a footer naming the HEAD SHA
-  and any artefact id.
-- The owning ADR(s) advance `Accepted → Implemented` on the same
-  commit. Regenerate `INDEX.md`.
-
-## Git contract
-
-- Commit messages follow **Conventional Commits**.
-- Mandatory `Rationale:` footer on any commit touching an ADR.
-- <Signed commits: yes/no per Q6.>
-- <ADR-revision tags `adr-NNNN-rN`: yes/no per Q6.>
-- <Co-Authored-By trailer: yes/no per Q6 — default no.>
-- Cross-references between ADRs use relative paths (`adr/NNNN-*.md`).
-
-<!-- Integration model per Q4b — keep one block. -->
-
-<!-- Direct-to-main:
-- **Integration:** direct-to-main, **fast-forward only**. No merge
-  commits on `main`. The verify gate (`<command from Q8>`) runs
-  locally and must pass before push. Completion event:
-  fast-forwarded to `main` + remote push succeeded.
--->
-
-<!-- PR-based:
-- **Integration:** every change ships via a pull request. CI must be
-  green before merge — the verify gate (`<command from Q8>`) runs in
-  CI on the PR, not (only) locally. Merge strategy:
-  <squash | merge | rebase>. Completion event: PR merged to `main`
-  with CI green.
--->
-
+# AGENTS.md
+
+This file provides guidance to coding agents working in this repository.
+
+## What this repository is
+
+<One paragraph. Project purpose, current baseline, what the artefacts in
+this repo represent.>
+
+## Repository structure
+
+- `adr/0000-template.md` — canonical ADR template.
+<!-- If technology-ADR split (Q2): also include `adr/NNNN-template.md` for technology ADRs. -->
+- `adr/NNNN-<kebab-slug>.md` — one ADR per decision, contiguous
+  numbering, no gaps.
+- `INDEX.md` — table regenerated from every ADR's metadata block.
+- `CONVENTIONS.md` — authoring rules (read before editing anything).
+- `plan/todo/NNNN-<slug>.md` — pending work, lower numbers run first.
+- `plan/done/<YYYY-MM-DD>-<slug>.md` — shipped work, chronological.
+- `_agent/` — multi-agent coordination: `ROLES.md`, `LOCKS.md`,
+  `WORKLOG.md`, `CURRENT_FOCUS.md`, `HANDOFF.md`, `prompts/`.
+<!-- If GLOSSARY.md (Q7): also include `GLOSSARY.md` — shared terms. -->
+<!-- If domains/ (Q7): also include `domains/<slug>/README.md`. -->
+
+## Hard rules when editing ADRs
+
+These come from `CONVENTIONS.md` and override default behaviour:
+
+- **One decision per ADR.** Splits become new ADRs that supersede;
+  never expand scope inside an existing one.
+- **Status lifecycle:** `<from Q3>`.
+- **Capability ADR section order:** metadata → Context → Capability
+  statement → User stories / scenarios → Acceptance criteria → Out of
+  scope → Open questions → References → Revision History → Approvals.
+<!-- If technology-ADR split (Q2): -->
+- **Technology ADR section order:** metadata → Context → Decision →
+  Rationale → Consequences → Acceptance criteria → Out of scope → Open
+  questions → References → Revision History → Approvals. Rationale must
+  name alternatives considered with specific rejection reasons.
+- **Acceptance criteria are testable and numbered.**
+- **ADRs are internal artefacts — never user-visible.** ADR numbers,
+  ADR titles, and the existence of the ADR catalogue must NEVER appear
+  in any string the product emits to users: UI copy, API response
+  bodies, error messages, customer-visible log lines, public
+  documentation, release notes, marketing copy, or support
+  communications. The catalogue is a builder's tool, not a user-facing
+  surface. References ARE allowed in: code comments
+  (`// see adr/0042-foo.md`), commit messages, PR descriptions,
+  internal docs, `AGENTS.md`, `CONVENTIONS.md`, `INDEX.md`, and the
+  `plan/` queue. Rule of thumb: if a non-builder could ever see the
+  string, the ADR reference comes out.
+<!-- Insert any Q10 domain-specific hard rules here as additional bullets. -->
+
+## Implementation work
+
+- Start from the ADRs. Identify which ADRs a code change implements or
+  affects before changing behaviour.
+- If implementation reveals a capability gap or changed decision, update
+  the relevant ADR rather than silently diverging.
+- Add or update tests for implemented behaviour. Map tests back to ADR
+  acceptance criteria where practical.
+- **Do not leak ADR identifiers into user-visible surfaces.** When
+  writing error messages, UI copy, API responses, log lines that ship
+  to customers, public docs, or release notes, refer to the behaviour
+  by its product-level name — never by ADR number, ADR title, or
+  phrases like "per the ADR catalogue". The ADR link belongs in the
+  commit message and (optionally) an inline code comment, not in the
+  string the user reads.
+
+## Audit trail and revision discipline
+
+- Substantive ADR changes append a row to the Revision History table.
+  Editorial changes (typos, formatting, link fixes) are excluded but
+  flagged `editorial` in the commit message.
+- Approvals table populates when an ADR is Accepted and updates on each
+  later substantive revision.
+- Regenerate `INDEX.md` from ADR metadata after any ADR status change
+  or new ADR.
+
+## Multi-agent workflow
+
+<!-- Mode 1 — single agent (Q5 default). Keep this block. -->
+A single agent owns this repo. The `_agent/` directory tracks live
+state and history; LOCKS discipline is not in use.
+
+<!-- Mode 2 — multi-agent, shared checkout. Replace the block above with: -->
+<!--
+Work is partitioned across named agents (see `_agent/ROLES.md`).
+Coordination rules:
+- Before editing a file, claim it in `_agent/LOCKS.md` by appending
+  `<agent-id> | <path> | <ISO-8601 timestamp>`. Remove the line on
+  commit. LOCKS is a filesystem mutex — it prevents simultaneous
+  writes to the same file.
+- Append a one-line entry to `_agent/WORKLOG.md` on every commit.
+- `_agent/CURRENT_FOCUS.md` is the single in-flight snapshot
+  (branch, active queue item, blockers, uncommitted work). Update it
+  when state changes.
+-->
+
+<!-- Mode 3 — multi-agent, separate worktrees / PR branches. Replace
+the block above with: -->
+<!--
+Work is partitioned across named agents (see `_agent/ROLES.md`).
+Each agent works in its own git worktree or PR branch.
+Coordination rules:
+- **GitHub draft PRs / branch assignment are the authoritative lock.**
+  `_agent/LOCKS.md` is advisory only — append an intent declaration
+  if it helps coordinate before a PR exists; do not rely on it as a
+  mutex. The filesystem can't conflict across worktrees, but
+  duplicated work and contradictory merges still can.
+- Append a one-line entry to `_agent/WORKLOG.md` on every commit.
+  The repo's `.gitattributes` sets `_agent/WORKLOG.md merge=union`
+  so concurrent appends concatenate instead of conflicting.
+- `_agent/CURRENT_FOCUS.md` is local-only per worktree (gitignored).
+  Update it freely; it never merges.
+- The committed cross-worktree dashboard is `_agent/IN_FLIGHT.md` —
+  one row per active worktree (agent, branch, queue item, started).
+  Add your row when you start, remove it when the worktree closes.
+-->
+
+## Plan folder
+
+- A pending item gets a `plan/todo/NNNN-<slug>.md` file BEFORE work
+  starts, naming the owning ADR(s), scope, and exit criteria.
+- The completion event is: `<from Q4 — e.g. merge to main, deploy +
+  smoke passes, release tag>`. On completion, `git mv` the file to
+  `plan/done/<YYYY-MM-DD>-<slug>.md` with a footer naming the HEAD SHA
+  and any artefact id.
+- The owning ADR(s) advance `Accepted → Implemented` on the same
+  commit. Regenerate `INDEX.md`.
+
+## Git contract
+
+- Commit messages follow **Conventional Commits**.
+- Mandatory `Rationale:` footer on any commit touching an ADR.
+- <Signed commits: yes/no per Q6.>
+- <ADR-revision tags `adr-NNNN-rN`: yes/no per Q6.>
+- <Co-Authored-By trailer: yes/no per Q6 — default no.>
+- Cross-references between ADRs use relative paths (`adr/NNNN-*.md`).
+
+<!-- Integration model per Q4b — keep one block. -->
+
+<!-- Direct-to-main:
+- **Integration:** direct-to-main, **fast-forward only**. No merge
+  commits on `main`. The verify gate (`<command from Q8>`) runs
+  locally and must pass before push. Completion event:
+  fast-forwarded to `main` + remote push succeeded.
+-->
+
+<!-- PR-based:
+- **Integration:** every change ships via a pull request. CI must be
+  green before merge — the verify gate (`<command from Q8>`) runs in
+  CI on the PR, not (only) locally. Merge strategy:
+  <squash | merge | rebase>. Completion event: PR merged to `main`
+  with CI green.
+-->
+

package/skills/bootstrap/templates/CONVENTIONS.md

@@ -110,6 +110,17 @@ Each agent works in its own worktree / PR branch.
 - `_agent/CURRENT_FOCUS.md` is gitignored (local-only per worktree);
   the committed cross-worktree dashboard is `_agent/IN_FLIGHT.md` —
   one row per active worktree.
+- **Identifier reservation.** Before parallel worktrees are spawned,
+  each is assigned a disjoint block of ADR numbers / `plan/todo` slots
+  (recorded in `_agent/IN_FLIGHT.md`). An agent creates new ADRs/plans
+  only from its reserved block, so two worktrees never claim the same
+  next number. `agent-wave` performs the reservation.
+- **Single writer per artefact.** An ADR body or a given `plan/` item
+  is edited by at most one worktree at a time (its owner, per
+  `_agent/IN_FLIGHT.md`). Contradictory edits to one ADR across two
+  worktrees must never happen — `merge=union` would concatenate them
+  silently. `/audit` flags duplicate numbers, duplicate plan ownership,
+  and the same ADR edited on two unmerged branches.
 - Regenerate `INDEX.md` after any ADR status change or new ADR.
 -->
 

package/skills/bootstrap/templates/_agent-IN_FLIGHT.md

@@ -12,5 +12,12 @@ gitignored under this mode and stays local to each worktree.
 If this file disagrees with reality, reality wins — check
 `git worktree list` and the live PRs, then correct here.
 
-| Agent | Worktree branch | Queue item | Started (ISO-8601) | PR link |
-|-------|-----------------|------------|---------------------|---------|
+The **Reserved IDs** column records the disjoint block of ADR numbers /
+`plan/todo` slots an agent may create this wave (assigned by `agent-wave`
+before spawning), so two worktrees never claim the same next number. The
+**Owns** column names the ADR(s) / plan item(s) that worktree is the
+single writer of — no other worktree edits those artefacts until the row
+clears.
+
+| Agent | Worktree branch | Queue item | Reserved IDs | Owns | Started (ISO-8601) | PR link |
+|-------|-----------------|------------|--------------|------|---------------------|---------|

package/skills/brainstorm/SKILL.md

@@ -19,6 +19,34 @@ to the **new-adr** and **new-plan** skills.
    contradict what already exists, and so dependencies point at real
    ADRs.
 
+## Step 0.5 — Assessment (run first)
+
+Run the shared assessment protocol before decomposing:
+
+- **Opt-out gate first.** Ask whether to run the assessment or go
+  straight to decomposing. Recommend **running** it when the request
+  arrived with little or no context; recommend **skipping** when the goal
+  and scope are already clear.
+- Ask the questions below **one at a time**, each with a **recommended
+  option** and a one-line reason; wait for each answer.
+- Use **structured selection** (single- or multiple-choice). If the host
+  exposes a structured single-/multi-select question tool, use it and
+  mark the recommended option; otherwise list options A/B/C in plain text
+  and name the recommended one. Use **free text only** where an
+  enumerable set is impossible (e.g. the goal statement).
+- **The operator decides.** Never proceed past a question without an
+  answer, and never guess scope when invoked with no context.
+
+Questions (skip any the request already answers):
+1. **Goal / problem** — free text (the unavoidable open answer) if not
+   already given.
+2. **Output** — candidate ADRs only, or ADRs + plan items.
+   *Recommended: ADRs + plan items.*
+3. **Depth** — quick (top candidates) or thorough (full decomposition).
+   *Recommended: quick first, expand on request.*
+
+This skill still **writes nothing** until you approve the outline.
+
 ## Step 1 — Understand the problem
 
 Ask for the goal/feature/problem if not given. Probe for scope

package/skills/new-adr/SKILL.md

@@ -18,6 +18,33 @@ Author one new ADR, consistent with this repo's conventions.
    groupings exist, and the multi-agent mode.
 3. Read `INDEX.md` and `ls adr/` to learn existing numbers and titles.
 
+## Step 0.5 — Assessment (run first)
+
+Run the shared assessment protocol before authoring:
+
+- **Opt-out gate first.** Ask whether to run the assessment or skip
+  straight to authoring. Recommend **running** it when the request
+  arrived with little or no context; recommend **skipping** when the
+  decision is already fully specified.
+- Ask the questions below **one at a time**, each with a **recommended
+  option** and a one-line reason; wait for each answer.
+- Use **structured selection** (single- or multiple-choice). If the host
+  exposes a structured single-/multi-select question tool, use it and
+  mark the recommended option; otherwise list options A/B/C in plain text
+  and name the recommended one. Use **free text only** where an
+  enumerable set is impossible (e.g. the title).
+- **The operator decides.** Never proceed past a question without an
+  answer, and never guess scope when invoked with no context.
+
+Questions (skip any the request already answers):
+1. **Shape** — capability or technology (only if the repo splits shapes;
+   single-shape repos skip this). *Recommended: per the request's intent.*
+2. **Supersede?** — none, or select the ADR(s) this replaces.
+   *Recommended: none.*
+3. **Initial status** — Proposed or Accepted. *Recommended: Proposed.*
+4. **Create a plan item now?** — yes / no. *Recommended: yes when Accepted.*
+5. **Title** — free text (the one unavoidable open answer).
+
 ## Step 1 — Determine shape and number
 
 - **Shape.** If the repo uses a single ADR shape, use

package/skills/new-plan/SKILL.md

@@ -16,6 +16,34 @@ Add one item to the implementation queue.
    completion event, and `plan/README.md` if present.
 3. `ls plan/todo/` to learn existing numbers and priority ordering.
 
+## Step 0.5 — Assessment (run first)
+
+Run the shared assessment protocol before queueing:
+
+- **Opt-out gate first.** Ask whether to run the assessment or skip to
+  writing the item. Recommend **running** it when the request arrived
+  with little or no context; recommend **skipping** when the item is
+  already fully specified.
+- Ask the questions below **one at a time**, each with a **recommended
+  option** and a one-line reason; wait for each answer.
+- Use **structured selection** (single- or multiple-choice). If the host
+  exposes a structured single-/multi-select question tool, use it and
+  mark the recommended option; otherwise list options A/B/C in plain text
+  and name the recommended one. Use **free text only** where an
+  enumerable set is impossible (e.g. the scope summary).
+- **The operator decides.** Never proceed past a question without an
+  answer, and never guess scope when invoked with no context.
+
+Questions (skip any the request already answers):
+1. **Owning ADR(s)** — select from the catalogue (single or multiple).
+   *Recommended: the ADR named in the request.*
+2. **Dependencies** — none, or select the plan items / ADRs that must
+   land first. *Recommended: none.*
+3. **Priority / position** — next number, or insert ahead of existing
+   items. *Recommended: next number.*
+4. **Scope & exit criteria** — free text, mapped to the owning ADR's
+   numbered acceptance criteria where possible.
+
 ## Step 1 — Identify the owning ADR(s)
 
 - Ask which ADR(s) this work implements. Validate they exist in