@evolvehq/docflow 0.4.3

package/skills/agent-wave/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: agent-wave
+description: Orchestrate a wave of parallel agents over the plan/todo queue in a documentation-led repo — asks how many agents, the budget (items/waves, with hours as a soft cap), and whether to checkpoint after each wave or run continuously. Spawns isolated worktree subagents, assigns one queue item each, collects results. Use when the user says "spawn a wave of agents", "run the queue in parallel", "fan out the work", "agent wave", or invokes /agent-wave.
+---
+
+# agent-wave
+
+Drive the implementation queue with parallel subagents, in waves.
+
+## Honest scope (read first)
+
+In-session subagents are bounded by **this session**, not by wall-clock
+hours. So this skill measures budget reliably in **items and waves**,
+with hours as a *soft cap* (stop starting new waves once elapsed time
+passes it). For a true multi-hour unsupervised fleet that outlives a
+session, use remote agents or a scheduled run of
+`_agent/prompts/autonomous.md` (`/schedule`) instead — this skill points
+you there rather than pretending to be it.
+
+## Step 0 — Preconditions and context
+
+1. Confirm the repo is bootstrapped with a `plan/` queue and that
+   `_agent/prompts/autonomous.md` exists (a real verify gate is
+   required — see the **bootstrap** skill, Q8).
+2. Read `CONVENTIONS.md` for the **multi-agent mode** and **integration
+   model**.
+   - **Mode 1 (single agent):** refuse. Parallel agents in one checkout
+     clobber each other. Tell the user to re-bootstrap as mode 2/3, or
+     run the autonomous prompt sequentially instead.
+   - **Mode 2 (shared checkout):** allowed but warn — file contention is
+     real; LOCKS must be respected and wave width kept low.
+   - **Mode 3 (worktrees):** the intended mode. Each subagent works in
+     its own isolated worktree.
+
+## Step 1 — Ask the wave parameters (one at a time, recommend)
+
+1. **Wave width N** — how many agents per wave.
+   *Recommended: min(queue depth, 3)* — modest, keeps review tractable.
+2. **Budget** — total items (or waves) to attempt this run.
+   *Recommended: one wave, then reassess.* Optionally a soft hours cap.
+3. **Supervision** — **checkpoint** (review after each wave, then
+   continue) or **continuous** (run wave after wave until budget/queue
+   exhausted).
+   *Recommended: checkpoint* for the first run on a repo.
+
+Cross-check: **continuous + direct-to-main** is risky — nothing gates
+each merge. If the repo is direct-to-main, recommend either switching
+this run to checkpoint, or that the repo move to PR-based so CI gates
+every merge.
+
+## Step 2 — Plan the wave
+
+- 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.
+- Record the assignment in `_agent/IN_FLIGHT.md` (mode 3) so the wave is
+  visible.
+
+## Step 3 — Spawn the wave
+
+Spawn N subagents in parallel, each in an isolated worktree
+(`isolation: worktree`). Brief each with: its assigned queue item, the
+instruction to follow `_agent/prompts/autonomous.md` end-to-end for that
+one item (orient → implement → verify → integrate per the repo's model →
+ship), and to report back a structured result (item, pass/fail, HEAD or
+PR link, any blocker).
+
+## Step 4 — Collect and checkpoint
+
+When the wave returns, summarise: shipped, failed, blocked, with links.
+Update `_agent/IN_FLIGHT.md` (remove finished rows). Then:
+- **Checkpoint mode:** present the summary and ask whether to launch the
+  next wave.
+- **Continuous mode:** launch the next wave with the next N items,
+  unless a stop condition fired.
+
+## Stop conditions
+
+Stop the run (do not start another wave) when any holds:
+- Queue empty, or budget (items/waves) reached, or soft hours cap passed.
+- Failure rate exceeds a sane threshold (e.g. >½ the wave failed) —
+  something systemic is wrong; surface it.
+- Repeated merge conflicts on the same files — the queue partition is
+  wrong; re-plan.
+- An item's ADR is not `Accepted`, or its acceptance criteria are
+  ambiguous.
+
+On stop, leave every worktree in a committed or cleanly-abandoned state,
+record the outcome in the WORKLOG, and report.

package/skills/audit/SKILL.md

@@ -0,0 +1,65 @@
+---
+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.

package/skills/bootstrap/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: bootstrap
+description: Scaffold or retrofit documentation-led conventions (AGENTS.md, CLAUDE.md, CONVENTIONS.md, ADR catalogue, plan/ queue, _agent/ coordination) into a repo. Use when the user asks to "set up conventions", "bootstrap ADRs", "scaffold the documentation-led layout", "add AGENTS.md and a plan queue", or invokes /bootstrap. Works on fresh repos and existing ones — preserves existing content and merges rather than overwrites.
+---
+
+# bootstrap
+
+You are installing (or retrofitting) a documentation-led convention set
+in the current repo. The end state is a repo that can be driven by
+both humans and coding agents off a small set of canonical files. Carry
+over the *mechanism* described here — nothing about any other project.
+
+## Step 1 — Detect the situation
+
+Inspect the repo before asking anything.
+
+- **Fresh repo** (no source, no docs): you are scaffolding from zero.
+- **Existing repo**: you are retrofitting.
+  - Read any current `README.md`, `CONTRIBUTING.md`, `AGENTS.md`,
+    `CLAUDE.md`, `docs/`, `adr/`, `.github/` before proposing changes.
+  - Preserve existing content. Merge, don't overwrite. If existing
+    conventions conflict with the ones below, surface the conflict in
+    your assessment summary.
+  - If ADRs already exist in another format, propose a migration plan
+    (renumber, keep, translate) rather than creating a parallel tree.
+
+State which situation applies in one line before asking the assessment
+questions.
+
+## Step 2 — Target layout
+
+```
+<repo>/
+  AGENTS.md              # hard rules for coding agents — entry point
+  CLAUDE.md              # one-liner: @AGENTS.md
+  README.md              # human-facing project summary (preserve if exists)
+  CONVENTIONS.md         # authoring rules: ADRs, naming, status, audit, git
+  INDEX.md               # generated table of all ADRs
+  GLOSSARY.md            # shared terms (optional — see Q7)
+  adr/
+    0000-template.md     # capability-ADR template (always)
+    NNNN-template.md     # technology-ADR template (only if split — see Q2)
+    NNNN-<kebab-slug>.md # one ADR per decision, contiguous numbering
+  domains/<slug>/README.md   # optional (see Q7)
+  plan/
+    README.md
+    todo/NNNN-<slug>.md
+    done/<YYYY-MM-DD>-<slug>.md
+  _agent/
+    ROLES.md             # named agents and what each owns
+    LOCKS.md             # file-claim ledger
+    WORKLOG.md           # append-only ship log
+    CURRENT_FOCUS.md     # slim live snapshot
+    HANDOFF.md           # fresh-agent entry point
+    prompts/autonomous.md  # only if a verify gate exists (see Q8)
+```
+
+## Step 3 — Conventions to install
+
+1. **ADRs are the source of truth.** One decision per ADR. Splits become
+   new ADRs that supersede; never expand scope inside an existing one.
+2. **Up to two ADR shapes:**
+   - **Capability ADR** (what the system must do). Section order:
+     metadata → Context → Capability statement → User stories / scenarios
+     → Acceptance criteria → Out of scope → Open questions → References →
+     Revision History → Approvals.
+   - **Technology ADR** (how it's built). Section order:
+     metadata → Context → Decision → Rationale → Consequences →
+     Acceptance criteria → Out of scope → Open questions → References →
+     Revision History → Approvals. Rationale must name alternatives
+     considered and give specific rejection reasons (not "simpler" /
+     "more idiomatic").
+3. **Status lifecycle:** `Proposed → Accepted → Implemented →
+   (Superseded | Deprecated)`. Terminal states reachable from any prior
+   state. Status drives plan-folder placement: `Accepted` →
+   `plan/todo/`, `Implemented` → `plan/done/`.
+4. **Filenames:** `adr/NNNN-kebab-slug.md`, zero-padded 4 digits,
+   contiguous, no reserved gaps. Cross-references use relative paths.
+5. **Acceptance criteria are testable and numbered.** Tests map back to
+   them where practical.
+6. **Audit discipline.** Substantive ADR changes append a Revision
+   History row. 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.
+7. **INDEX.md is regenerated** from ADR metadata after any ADR change.
+   Treat as derived, not hand-edited.
+8. **`plan/` is the work queue.** `git mv plan/todo/X plan/done/<date>-X`
+   is the completion event; the moved file gets a footer naming the HEAD
+   SHA (and deploy artefact id if applicable). Owning ADR(s) advance
+   `Accepted → Implemented` on the same commit.
+9. **Multi-agent coordination.** Before editing, an agent appends a row
+   to `_agent/LOCKS.md` (`<agent-id> | <path> | <ISO-8601 timestamp>`)
+   and removes it on commit. On commit, append one line to
+   `_agent/WORKLOG.md`. `CURRENT_FOCUS.md` is the live snapshot; if it
+   disagrees with git, git wins and `CURRENT_FOCUS.md` is corrected.
+10. **Git contract.** Conventional Commits. Mandatory `Rationale:`
+    footer on commits touching an ADR. Signed commits unless the user
+    opts out. No `Co-Authored-By` trailer for agent work unless the user
+    asks for one.
+11. **AGENTS.md is the hard-rules entry point;** **CLAUDE.md** is the
+    one-liner `@AGENTS.md` so the Claude Code CLI picks it up.
+12. **ADRs are internal artefacts — never user-visible.** ADR numbers,
+    ADR titles, and the existence of the ADR catalogue must NEVER
+    appear in product code paths that reach a user: UI strings, API
+    response bodies, error messages, log lines emitted to customers,
+    public documentation, release notes, marketing copy, or support
+    communications. ADRs are for builders, not users. 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. When in
+    doubt, ask whether a non-builder would ever see this string — if
+    yes, the ADR reference comes out.
+
+## Step 4 — Assessment (10 questions)
+
+**Ask the questions one at a time, not in a batch.** For each question,
+state a **recommended** option (label it "Recommended") with one short
+sentence on why; the user picks it, picks an alternative, or types a
+custom answer. Wait for the answer before moving to the next question.
+
+If the host CLI exposes a structured single-select question tool (e.g.
+Claude Code's `AskUserQuestion`), use it and mark the recommended
+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
+lines and ask for sign-off before writing any files.
+
+1. **Project identity.** Name, one-line description, doc language
+   (en-GB / en-US / other), and — if existing repo — what current files
+   (README, CONTRIBUTING, docs/, adr/, etc.) must be preserved or
+   merged. *No recommendation — project-specific.*
+2. **ADR shape.** Single shape, or capability-vs-technology split?
+   **Recommended: single shape** — start simple, split later if
+   long-lived product requirements clearly outlive their
+   implementations.
+3. **Status lifecycle.** Full `Proposed → Accepted → Implemented →
+   (Superseded | Deprecated)`, or shorter (drop `Implemented`)?
+   **Recommended: full lifecycle** — the `Implemented` rung is cheap
+   and gives a clear "what's shipped" signal.
+4. **Plan folder + integration model.** Two sub-answers. **Ask Q5
+   before Q4b — the integration recommendation depends on the
+   multi-agent mode chosen in Q5.** When asking sequentially, the
+   order is: Q1 → Q2 → Q3 → Q4a → Q5 → Q4b → Q6 → Q7 → Q8 → Q9 → Q10.
+
+   **Q4a — Plan folder.** Use `plan/todo/` + `plan/done/`, or skip it
+   because work is tracked elsewhere?
+   **Recommended: use it** — the queue is what makes the convention
+   set actionable for agents.
+
+   **Q4b — Integration model.** *Skip if Q4a = skip.* Two options:
+   - **Direct-to-main, fast-forward only.**
+     *Recommended if Q5 = mode 1 (single agent).* Local verify gate
+     runs before push. Completion event: "fast-forwarded to main +
+     remote push succeeded". Autonomous prompt uses
+     `git merge --ff-only`. Trunk-based development; no PRs.
+   - **PR-based, required CI green.**
+     *Recommended if Q5 = mode 2 or 3 (multi-agent).* Verify gate
+     runs in CI on the PR. Completion event: "PR merged to main + CI
+     green". Autonomous prompt opens a draft PR, waits for green,
+     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:
+   - **(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
+     agent" case.
+   - **Multi-agent, shared checkout.** Named agents in ROLES. LOCKS
+     ON as a filesystem mutex (prevents simultaneous writes to the
+     same file). WORKLOG append-on-commit, single file.
+     CURRENT_FOCUS as the single in-flight snapshot. Right when
+     several agents serialise through one working tree.
+   - **Multi-agent, separate worktrees / PR branches.** Named agents
+     in ROLES. LOCKS *advisory only* — GitHub draft PRs / branch
+     assignment are the real lock; pick one signal, not two.
+     `_agent/WORKLOG.md` gets `merge=union` via `.gitattributes` so
+     concurrent appends concatenate instead of conflicting (or split
+     to `_agent/worklog/<agent-id>.md` if agent set is fixed).
+     `_agent/CURRENT_FOCUS.md` becomes local-only (added to
+     `.gitignore`); a committed `_agent/IN_FLIGHT.md` dashboard
+     aggregates per-worktree state.
+
+   Note: option 2 → option 3 is not a free upgrade later; it means
+   splitting WORKLOG (or adding the merge driver) and rethinking
+   CURRENT_FOCUS. Choose deliberately.
+6. **Git contract.** Confirm or override each — Conventional Commits;
+   mandatory `Rationale:` footer on ADR-touching commits; signed
+   commits; ADR-revision tags `adr-NNNN-rN`; whether agent commits
+   carry a `Co-Authored-By` trailer. **Recommended: Conventional
+   Commits ON, `Rationale:` footer ON, signed commits ON, ADR-revision
+   tags OFF, `Co-Authored-By` trailer OFF.**
+7. **Optional artefacts.** Which now vs. defer: `GLOSSARY.md`,
+   `domains/<slug>/README.md` groupings, technology-ADR template?
+   **Recommended: defer all three** — add when scale demands
+   (terminology drift, >20 ADRs, or technology decisions splitting
+   from product decisions).
+8. **Verify gate.** What command(s) decide a change is shippable
+   (`npm test`, CI workflow, deploy + smoke, manual)? *No
+   recommendation — project-specific.* If the user has no real gate,
+   the skill will refuse to write `_agent/prompts/autonomous.md`.
+9. **Existing-content conflicts** (existing repos only). Any
+   conventions already in place (commit format, branch policy, ADR
+   style, status names) the new layout must defer to or merge with?
+   *No recommendation — project-specific.* Skip this question on a
+   fresh repo.
+10. **Domain-specific hard rules to bake in.** Any project-specific
+    constraints to enforce in `AGENTS.md` / `CONVENTIONS.md` from day
+    one — e.g. vendor-naming restriction, regulated-evidence posture
+    (attribution, retention, e-signatures), language mandate,
+    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.
+
+## Step 4.5 — Cross-check before sign-off
+
+After all answers are in, scan for contradictions before writing the
+plan summary. Surface each, take the correction, then proceed:
+
+- **Q5 mode 3 (worktrees) + Q4b direct-to-main.** Unusual: each
+  worktree would have to rebase onto main before fast-forwarding.
+  Ask the user to confirm or switch to PR-based — PR-based is the
+  near-universal fit for worktree work.
+- **Q4a plan-folder skipped + Q8 autonomous prompt expected.** The
+  autonomous prompt walks `plan/todo/`; with no plan folder it has
+  nothing to drive. Do not write the autonomous prompt.
+- **Q8 has no real verify gate + Q4b PR-based with required CI.**
+  "Required CI green" needs a CI gate. Confirm what the CI actually
+  runs, or downgrade the completion event.
+- **Q2 single ADR shape + Q7 technology-ADR template requested.**
+  Contradiction — pick one.
+
+## Step 5 — Output sequence (after sign-off)
+
+Templates live in this skill's `templates/` directory. Read each
+template, fill its placeholders from the assessment answers, then
+write it into the repo.
+
+1. `CONVENTIONS.md` — from `templates/CONVENTIONS.md`. Spec other files
+   reference.
+2. `AGENTS.md` — from `templates/AGENTS.md`.
+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).
+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
+   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
+   mode 1.** **Mode 3** writes it with an advisory header noting
+   PRs are the authoritative lock.
+9. `_agent/WORKLOG.md` — from `templates/_agent-WORKLOG.md`. In
+   **mode 3**, also write a `.gitattributes` entry:
+   `_agent/WORKLOG.md merge=union`.
+10. `_agent/CURRENT_FOCUS.md` — from
+    `templates/_agent-CURRENT_FOCUS.md`. In **mode 3**, add
+    `_agent/CURRENT_FOCUS.md` to `.gitignore` (the file stays
+    local-only per worktree) and write
+    `_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.
+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
+    **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.
+
+Commit each file (or logical group) with a Conventional Commit message;
+no `Co-Authored-By` trailer unless Q6 asked for one.
+
+For an existing repo, prefer Edit over Write where files exist, and
+call out every merge decision in the commit message.
+
+## Step 6 — Offer backfill (existing repos only)
+
+Once the scaffolding commit has landed, **offer to backfill** the ADR
+catalogue, the plan folder, and `CONVENTIONS.md` from the existing
+code and git history. Skip this step entirely on a fresh repo.
+
+Phrase the offer like this:
+
+> The scaffolding is in. Want me to backfill ADRs, plan/done entries,
+> and CONVENTIONS additions from the existing code and commit history?
+> I'll propose drafts; you approve in batches before anything lands.
+
+If the user accepts, run the backfill in four passes. Each pass
+produces drafts the user reviews before they are committed.
+
+1. **Scan inputs (read-only).**
+   - `git log --oneline --reverse main` (or the default branch) — the
+     decision and shipped-work trail.
+   - Major modules / packages / top-level source directories — the
+     surface of what exists.
+   - Any existing docs (`README`, `docs/`, design notes, RFCs) — prior
+     decision records, even informal ones.
+   - `package.json` / `pyproject.toml` / `go.mod` etc. — declared
+     dependencies often map to technology decisions.
+
+2. **Propose ADRs.** For each distinguishable decision or capability
+   evident from the scan, draft an ADR using the appropriate template.
+   - Capabilities (what the system does) → capability ADR, status
+     `Implemented` (the code already exists), Revision History row
+     citing the commit(s) that introduced the behaviour.
+   - Technology choices (framework, persistence, deployment target) →
+     technology ADR, status `Accepted` or `Implemented` as appropriate,
+     Rationale section reconstructed from commit messages and code
+     comments — flag any speculative rationale clearly so the human
+     can correct it.
+   - Number contiguously from `0001`. Show the user the proposed list
+     (number + title + status + one-line scope) before writing files.
+
+3. **Propose plan/done entries.** For each ADR drafted as
+   `Implemented`, generate a corresponding `plan/done/<date>-<slug>.md`
+   file using the commit date of the implementing commit (or the
+   merge commit) as the date prefix. Body: short summary, owning ADR,
+   "Shipped at HEAD `<sha>`" footer. Group these into a single
+   approval prompt — they are mechanical once the ADRs are agreed.
+
+4. **Propose CONVENTIONS additions.** Identify patterns in the existing
+   repo that should be promoted to written conventions: commit-message
+   style, branch naming, test layout, file-naming rules, language /
+   tooling choices that are de-facto standards. Draft additions to
+   `CONVENTIONS.md` (and corresponding bullets in `AGENTS.md` §Hard
+   rules if they should be enforced). Show the diff before applying.
+
+After each pass, commit the approved drafts with a Conventional Commit
+(`docs(adr): backfill ADRs 0001-00NN from code and history`,
+`docs(plan): backfill plan/done from shipped commits`,
+`docs: backfill conventions from de-facto patterns`). Regenerate
+`INDEX.md` after the ADR pass.
+
+**Important guardrails.**
+- The backfill produces *drafts*. Every commit is reviewable; the user
+  is the authority on whether an inferred decision is real.
+- If commit history is sparse or unclear, say so and stop — do not
+  invent rationale to fill gaps.
+- If the user declines the backfill, the scaffolding is still
+  complete; the queue is just empty until the first hand-authored ADR
+  lands.

package/skills/bootstrap/templates/AGENTS.md

@@ -0,0 +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.
+-->
+

package/skills/bootstrap/templates/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md