EvolveHQ/docflow

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. Reuse explicit answers and sign-off already supplied in this session; never replace them with profile defaults or ask for them again. Before writing, summarise the resolved artefact root, depth, queue, gate and coordination/integration modes against those answers. If a host mirrors a selected folder into a sandbox, identify the actual target path and how verified outputs reach the selected folder; never call an untouched target complete merely because a scratch mirror passed.

• 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.

• Already a docflow repo (carries AGENTS.md + CONVENTIONS.md + an ADR catalogue): you are adding to an existing setup, not scaffolding. Do not re-scaffold the core or re-ask settled questions — read the recorded choices from CONVENTIONS.md/AGENTS.md (ADR shape, status lifecycle, artefact root, multi-agent mode, and which optional layers already exist). Then offer to enable any opted-out optional layer still absent — plan/, _agent/, GLOSSARY.md, domains/, or the second ADR shape (the technology template) — and write only the chosen ones, by merge, under the recorded artefact root, leaving everything else untouched. Ask only the questions the new layers need (e.g. the coordination question when enabling _agent/ — where a single writer without both a recorded verify gate and a plan queue correctly ends up with no _agent/ at all, and the layer is simply not needed). This is the entry point for adding a layer you deferred at first bootstrap. A repo still carrying coordination files an earlier scaffold wrote keeps them: leave them in place here and let the audit skill report the layout.

  Enabling GLOSSARY.md writes the canonical shell, never a rewrite. When the layer is chosen and the file is absent, write it from templates/GLOSSARY.md — the optional heading and prose, then the one Term | Definition table recorded in the generated CONVENTIONS.md §Glossary. If the file already exists, leave it untouched: enabling the layer adds nothing, and add-convention extends the existing file in the canonical shape or audit offers a consented migration.

  Enabling the second ADR shape is a scheme switch, not a file copy. It is the one deferred layer that changes a choice already recorded, so write all of it in one pass or none of it: replace §ADR Shapes in CONVENTIONS.md with the two-shape text, add the technology section-order and shape bullets to AGENTS.md, write adr/0000-template-technology.md, and regenerate INDEX.md with the Shape column. Existing ADRs keep their numbers and stay capability — an absent shape: field already means capability, so no ADR is rewritten and nothing is renumbered. Half of the switch strands the repo in the state the Step 4.5 cross-check calls a contradiction: a technology template that a single-shape scheme will never select.

  A repo already on the legacy range encoding gets the migration offer instead. Some two-shape repos were scaffolded before the shape became a declared field and encode it in the number: §ADR Shapes records a cutoff (capability below it, technology at or above), and adr/ holds a template numbered other than 0000 (e.g. adr/0100-template.md). Either signal alone identifies it. Such a repo is not missing a layer — it has both shapes already — so do not offer the scheme switch above, which would strand it with two rival encodings. Offer the migration onto the declared field, on the same terms the audit skill uses:

  • Show the old-to-new number map first, as a dry run: capability ADRs keep their numbers; technology ADRs take the numbers following the highest capability ADR, in their original relative order. Alongside it, list the references that follow (depends-on, supersedes / superseded-by, relative adr/NNNN-*.md links, INDEX.md, domain README.md listings, plan/todo/ owning-ADR lines) and what is left as history (plan/done/ footers, commit messages, tags).
  • Write nothing without an explicit confirmation of that map. Declining is a valid outcome: the repo keeps the range encoding and keeps passing its own rules.
  • On confirmation, apply the migration exactly as the audit skill's migration step specifies — renumber, stamp shape: on every ADR, rewrite every in-catalogue reference, replace the boundary template with adr/0000-template-technology.md, rewrite §ADR Shapes to the declared field and drop any seed-ADR exception clause, regenerate INDEX.md with the Shape column — and land it as one commit whose message lists every old-to-new pair. That procedure is the single source of truth; do not paraphrase a second variant of it here.
  • Then continue the re-run normally for the layers that really are absent (plan/, _agent/, GLOSSARY.md, domains/).

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)
    0000-template-technology.md  # technology-ADR template (only if two shapes — 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/                # the agent operating contract (see Q5) — optional
    ROLES.md             # who writes what (several writers only)
    LOCKS.md             # the file-claim mutex (shared checkout only)
    prompts/autonomous.md  # how an unattended run behaves (only with a
                         #   verify gate — Q8 — AND a plan queue — Q4a)
  federation.md          # multi-repo only (Q11): this repo's back-pointer
  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 .docflow/, e.g. .docflow/adr/, .docflow/plan/).

Discovery. Tools locate the artefact root without reading CONVENTIONS.md first: a .docflow/ directory at the repository root is the root; for any other root, bootstrap writes a .docflow file at the repository root — a one-line pointer, root: <path> (e.g. root: docs/, root: .). Neither present means a pre-contract repo (tools probe docs/, then the repository root, for a CONVENTIONS.md naming an artefact root) or not a docflow repo.

_agent/ is the agent operating contract — who writes what, the one real mutex, and how an unattended run behaves. It holds nothing git already records: no duplicate shipped record, no dashboard of what is in flight, no snapshot of the current state, no hand-off. Which of the three files above exist follows entirely from Q5, Q8 and Q4a, and a repo with no _agent/ directory at all is a valid outcome.

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/ contract (Q5 + Q8 + Q4a — a single writer without both a verify gate and a plan queue gets none of 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. 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

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, declared by field. A repo that distinguishes the two records the distinction in each ADR's shape: metadata field (capability or technology; an absent field means capability) — never in a number range. Every ADR takes the next contiguous number whatever its shape, and each shape has its own template, both numbered 0000.
   • 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. When work ships, git mv plan/todo/X plan/done/<date>-X, any plan-item Status removal, owning ADR status advance, and INDEX.md regeneration are grouped in the completion commit. Under direct-to-main integration that commit is pushed to the integration branch and the moved file's footer names the HEAD SHA (and deploy artefact id if applicable). Under pull-request integration those changes are the last commit on the pull-request branch before it is marked ready, the footer names the pull request, and the merge is the completion event.
9. Coordination is a contract, not a log. _agent/ holds only what git cannot tell you, and each mode (Q5) prescribes exactly its own files — nothing else is written there. In a shared checkout, an agent appends a row to _agent/LOCKS.md (<agent-id> | <path> | <ISO-8601 timestamp>) before editing and removes it on commit; that ledger is the one real mutex, and a queue item is claimed on the item itself. In separate worktrees a queue item is claimed by pushing claim/<item-key> — the queue file name without its extension — plus a draft pull request from it where integration is pull-request based; the push is what excludes the second writer, and no ledger is kept. Under a single writer there is nothing to serialise and nothing to claim. No mode keeps duplicate shipped state, a dashboard of what is in flight, or a snapshot of the current state: git history and plan/done/ are the record, and the live branches and pull requests are what is in flight.
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 for compatible agents that read it.
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 (depth-tiered; 10 questions at full depth, plus federation (Q11) and placement (Q12))

Reuse supplied answers first. Summarise applicable choices already supplied in the request or session, including depth and sign-off. Defaults never replace explicit choices. If every material choice is supplied, proceed after the cross-check. Ask only about a material missing or conflicting choice.

For unresolved choices when depth is not supplied, open with one single-select question: how deep should this assessment go?

• express — no further choices. Every choice takes the fixed express profile below. Only essentials with no derivable default are still asked: project name and one-line description — and even those are derived from the repo (README, manifest) when possible and only asked when underivable.
• guided (recommend this for most repos) — only the hard-to-reverse choices are asked: plan folder (Q4a), coordination mode (Q5), and integration model (Q4b — skipped if Q4a = skip), plus the underivable essentials. Everything else takes its recommended default.
• full — the complete question set below.

If the repo's CONVENTIONS.md already records an Assessment depth: (a retrofit or re-run), pre-select that depth as the recommended option instead when asking. A recorded depth steers the recommendation and is never applied silently; it is not a current answer or execution grant.

Mid-flight switching. At any question the operator may answer "defaults from here" (remaining choices take their recommended defaults, as in express) or "go deeper" (escalate express → guided → full for the remaining questions). Honour the switch immediately.

Express profile. An express bootstrap scaffolds the conservative fixed profile for unanswered choices — preserve explicit choices, summarise the result and use applicable supplied sign-off or obtain missing sign-off before writing:

• the core only: AGENTS.md, CLAUDE.md, CONVENTIONS.md, adr/0000-template.md, INDEX.md, plus the seed ADR 0001 (Step 5 item 5b). All optional layers off: no plan/, no _agent/, no GLOSSARY.md, no domains/, no technology template.
• Default artefact root (.docflow/); single ADR shape; full status lifecycle.
• Git contract: Conventional Commits ON, Rationale: footer ON, signed commits ON, ADR-revision tags OFF, Co-Authored-By OFF.
• Integration recorded as direct-to-main, fast-forward only; Q5 recorded as single writer, which with no plan queue and no verify gate (below) means no _agent/ directory at all.
• Standalone — never part of a federation.
• Doc language: match the existing repo's content, else en-US.
• No verify gate recorded and no plan queue (so no autonomous prompt on either count); no domain-specific hard rules.

On an existing repo, express preserves and merges exactly as a full run does — depth changes how many questions are asked, never how destructive the run is.

Guided defaults. Beyond its three questions, guided takes: single shape, full lifecycle, the recommended git contract, optional artefacts deferred, no hard rules, default artefact root, standalone, and the express language rule. Q5 is one of the three it asks, and its recommended answer is single writer — so a guided run that takes the recommendation records single writer, and writes an _agent/ directory only when Q8 records a verify gate and Q4a kept the plan queue. Run the Step 4.5 cross-check on the answers before the sign-off summary.

Federation guard. Express and guided runs are always standalone: Q11 is never asked and no federation file is written. Establishing or joining a multi-repo product is available at full depth only — it is an outward-facing commitment no default may make.

Record the choice. Write the chosen depth into the scaffolded CONVENTIONS.md (Assessment depth: line in §Project — see Step 5 item 1). Later assessments read it and pre-select it as the recommendation.

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, 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 the answers are in, summarise the resulting plan in 5–10 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 (README, CONTRIBUTING, docs/, adr/, etc.) must be preserved or merged. No recommendation — project-specific.

2. ADR shape. A single shape, or two shapes declared by field — capability and technology, each ADR naming its own in a shape: metadata field? Recommended: single shape — start simple, add the second shape later if long-lived product requirements clearly outlive their implementations. Ask for no number boundary: shape is metadata, so two-shape repos keep one contiguous sequence and get a second 0000 template rather than a cutoff.

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 = single writer. 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 = shared checkout or separate worktrees. Verify gate runs in CI on the PR. Completion event: "PR merged to main + CI green". Autonomous prompt opens a draft PR, commits the completion changes as the final branch commit, waits for green, marks ready, and merges. Ask the user for merge strategy (squash / merge / rebase — default: squash for clean history, rebase if per-commit identity matters).

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. Three answers, each prescribing exactly its own _agent/ files and nothing else:

   • (Recommended) Single writer. One human/agent integrates at a time, so there is nothing to serialise: no roles list, no lock ledger. The only file written is _agent/prompts/autonomous.md, and only if the repo is eligible for the run prompt — Q8 records a real verify gate and Q4a keeps the plan queue the prompt walks. Fail either and there is no _agent/ directory at all, the lightest footprint. Right for small projects and the "one human + one agent" case.
   • Several writers, one shared checkout. Named writers in _agent/ROLES.md. _agent/LOCKS.md ON as a filesystem mutex — in one working tree it is the only thing preventing simultaneous writes to the same file. Plus the run prompt where the repo is eligible for it (gate + plan queue).
   • Several writers, separate worktrees / PR branches. Named writers in _agent/ROLES.md, plus the run prompt where the repo is eligible for it (gate + plan queue). No lock ledger: the pushed claim/<item-key> branch and its draft pull request are the claim, worktrees cannot collide on the filesystem, and an advisory ledger nobody can rely on is noise.

   No answer writes a duplicate shipped-state file, a dashboard, a live snapshot, or a hand-off, and none adds a .gitattributes or .gitignore entry for coordination files: what happened is git history and plan/done/, what is in flight is the live branches and pull requests.

   Note: shared checkout → separate worktrees is not a free upgrade later; it retires the lock ledger the shared-checkout repo relies on and moves the claim onto branches and pull requests. 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:

   • domains/<slug>/README.md grouping — per-area indexes over the flat catalogue (navigation by area, not numbering). Enable when the project has distinct areas (e.g. auth, billing, search) or you expect the catalogue to grow past ~20 ADRs; defer for a small, single-area repo. Cheap to add later.
   • GLOSSARY.md — shared term definitions, in the canonical structure recorded in the generated CONVENTIONS.md §Glossary (an optional heading and prose, then one Term | Definition table). Defer; add on terminology drift. The layer is opt-in and its absence stays valid.
   • technology-ADR template (adr/0000-template-technology.md, the second ADR shape) — defer unless technology decisions split from product decisions. Enabling it is the same choice as Q2's second shape; the cross-check in Step 4.5 keeps the two answers in step.

8. Verify gate. What command(s) decide a change is shippable (npm test, CI workflow, deploy + smoke, manual)? No recommendation — project-specific. The run prompt needs both a real gate and the plan/todo/ queue it walks: if the user has no real gate, or Q4a skipped the plan folder, the skill refuses 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.

11. Multi-repo product (optional). Is this repo part of a product that spans several repos? Recommended: No — most repos are standalone; skip the federation setup entirely. If yes, two sub-answers:

    Q11a — Establish or join? Are you establishing a new federation (this is the first repo) or joining an existing one?

    Q11b — Topology (establish only). Where do product-wide decisions live?

    • A — central decisions repo: a dedicated repo holds all product-wide decisions; code repos reference it, never duplicate.
    • B — distributed + federation: each repo owns its own decisions; a roll-up aggregates them.
    • (Recommended) C — home repo + local: one repo is the home for product-wide decisions; each repo also keeps purely-local ones.

    Q11c — Identity scheme (establish only). How are ADRs identified across the federation? (Recommended) repo-prefixed slug <repo-id>/NNNN-slug — each repo keeps local contiguous numbering with no central coordinator; the slug is the cross-federation key. The scheme is recorded in the federation config and applied by the authoring skills.

    Establish 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) .docflow/ — a hidden root that keeps the repo root clean and groups all docflow artefacts in one place (.docflow/adr/, .docflow/plan/, …).
    • docs/ — aligns with the common doc/adr / docs/ convention; records visible alongside other docs.
    • Repository root — flat layout; decisions beside the code (good for monorepos). This is docflow's own layout.

    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

After all answers are in, scan for contradictions before writing the plan summary. Surface each, take the correction, then proceed. (An express run is internally consistent by construction and skips this check; guided and full runs, and any run that switched tiers mid-flight, get the full scan.)

• Q5 separate worktrees + Q4b direct-to-main. Require recorded concurrency guardrails and serial integration through ship-item. This is a supported combination; retain it when already confirmed.
• Q5 shared checkout + Q4b PR-based. Ordinary sequential PR work needs an actual work branch. PR waves require separate worktrees; never generate a claim-branch workflow for a shared checkout.
• Q4a plan-folder skipped + Q8 records a real gate. The autonomous prompt walks plan/todo/; with no plan folder it has nothing to drive. Do not write the autonomous prompt — a gate alone does not make the repo eligible for it. Say so, and offer the plan queue if the user wanted an unattended run. Under a single writer this leaves no _agent/ directory at all; under several writers the mode's other files are still written.
• 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. The technology template only exists in a two-shape repo, because it is the template the shape: technology field selects. (On a re-run that enables the second shape on an existing single-shape repo, the two move together — see Step 1.)
• Q11 = join but no confirmable home pointer. Joining needs a home/federation pointer you can confirm. If none exists yet, you are really establishing — switch Q11a to establish.

The sign-off includes final/persisted Status at a glance reporting at every depth. Offer the opt-out at full depth; if explicitly declined, omit the Reporting section, AGENTS pointer and prompt Report step together. Domain reporting rules extend the one numbered Reporting list.

For an existing legacy coordination layout, use audit's coordination migration procedure: show removals and content destinations, respect prior explicit migration approval or obtain it, preserve live owner/blocker content on queue items, then regenerate the prompt from recorded answers.

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.

Placement (Q12): write AGENTS.md and CLAUDE.md to the repository root; write everything below under the chosen artefact root (default .docflow/) — e.g. .docflow/adr/0000-template.md, .docflow/plan/, .docflow/INDEX.md. Record the chosen root and the chosen assessment depth in CONVENTIONS.md so every lifecycle skill resolves paths against the root and later assessments pre-select the recorded depth, and adjust the adr//plan/ cross-paths in the filled AGENTS.md (and other templates) to the chosen root (e.g. .docflow/adr/).

Discovery pointer. If the chosen root is anything other than .docflow/, also write a .docflow file at the repository root containing the single line root: <path> (root: docs/, root: .) — the marker external tools use to find the catalogue. Do not write it when the root is .docflow/ (the directory itself is the marker). Keep the pointer in sync if a later re-run migrates the root.

1. CONVENTIONS.md — from templates/CONVENTIONS.md. Spec other files reference. Record the exact Q8 verify command(s), when supplied, in its Git Contract; the phrase "verify gate" alone does not identify a command. Include the §Concurrency Guardrails section only if Q5 is shared checkout or separate worktrees or Q4b is PR-based; omit it for single-writer direct-to-main repos (no numbering race). Include the §Federation (multi-repo) section only if Q11 = yes; fill <product> and state the chosen identity scheme. Omit it for standalone repos.

2. AGENTS.md — from templates/AGENTS.md. Include the concurrency guardrails hard-rule bullet (G2–G4) under the same condition as the CONVENTIONS section above; omit otherwise. Generate the "Picking up this repo" section from the answers rather than copying the template list verbatim: keep one line per file this run actually writes, in read order, with every path resolved against the chosen artefact root (Q12) — drop the plan/ lines if Q4a skipped the queue; when the queue exists, include the newest plan/done/ entries and a first-parent git log command as the shipped record; drop _agent/ROLES.md unless Q5 chose several writers; drop _agent/LOCKS.md unless Q5 chose a shared checkout; keep the derived in-flight line — worktrees, remote claim branches, draft pull requests — in separate-worktree mode and in any pull-request repo, and drop it elsewhere; and renumber what remains. The section must never name a file this repo does not have; it is the only read order, and no hand-off file is written.

3. CLAUDE.md — from templates/CLAUDE.md (single line @AGENTS.md).

4. adr/0000-template.md — from templates/adr-capability.md.

5. adr/0000-template-technology.md — from templates/adr-technology.md, only if Q2 chose two shapes. It ships with shape: technology pre-filled. Both templates are numbered 0000; no number boundary is chosen and none is recorded, and no template is written under any other number. 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. In a two-shape repo (Q2) the seed stays 0001 and carries shape: technology. Uncomment that field and swap the body: delete Capability statement and User stories / scenarios, and uncomment the Decision / Rationale / Consequences block the seed template already ships. Do not recast the capability sections — they have no technology content — and do not leave the capability headings in place after stamping the field; audit validates section order from the declared shape, so a field-only uncomment fails the section check. Adopting the method is a decision about how the repo is built. Because the shape is declared in the metadata, the scaffolded conventions need no exception clause for it. 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.

   Seed completion evidence. Keep the complete scaffold atomic; do not split it into an incomplete intermediate tree to make a supplied gate pass. For a direct-integration seed created in that same commit, use this seed-only footer, replacing the path with the actual repository-relative adoption record and quoting it for the host:

   Shipped by bootstrap introduction: `<repo-relative done path>`.
   Resolve: `git log --follow --diff-filter=A --format=%H -- "<repo-relative done path>"`
   

   After committing, resolve that exact path to one introducing commit. Require it to be reachable and to contain this adoption record, the Implemented seed, its INDEX row and the complete verified scaffold; verify its signature when signing is required. Report the resolved SHA. A generic description such as "the bootstrap commit" is insufficient. If later repairs changed the scaffold, cite the existing verified repair HEAD in a subsequent record commit instead. Never invent a future/self SHA. Ordinary shipped items still name their existing verified implementation tip. Under pull-request integration use the actual pull-request reference; a missing reference or unconfirmed merge remains explicitly unverified.

6. plan/README.md — from templates/plan-README.md. Create empty plan/todo/.gitkeep and plan/done/.gitkeep. 6b. GLOSSARY.md — from templates/GLOSSARY.md, only if Q7 enabled the shared-terms layer. Write the canonical shell (optional heading and prose, then one Term | Definition table) and the matching §Glossary section in CONVENTIONS.md. Never overwrite an existing GLOSSARY.md: leave it for add-convention or audit to extend or offer a migration.

7. _agent/ — write exactly what Q5, Q8 and Q4a prescribe, and nothing else. The run prompt is written only when the repo is eligible for it: Q8 recorded a real verify gate and Q4a kept the plan/todo/ queue the prompt walks. Fail either and no prompt is written. The whole set is:

   Q5 answer	_agent/ contents
   Single writer	prompts/autonomous.md iff eligible (gate + plan queue) — otherwise no _agent/ directory at all
   Several writers, shared checkout	ROLES.md, LOCKS.md, and prompts/autonomous.md iff eligible
   Several writers, separate worktrees	ROLES.md, and prompts/autonomous.md iff eligible

   Write no duplicate shipped-state file, no dashboard, no live snapshot and no hand-off in any mode, and add no .gitattributes union entry or .gitignore entry for coordination files. There is no template for any of them: git history, plan/done/, and the live branches and pull requests are that record.

8. _agent/ROLES.md — from templates/_agent-ROLES.md, skipped for a single writer. One section per named writer, naming what each is the single writer of, from the Q5 answer.

9. _agent/LOCKS.md — from templates/_agent-LOCKS.md, shared checkout only. Not written for a single writer, and not in separate-worktree mode (the pushed claim/<item-key> branch and its pull request are the claim there).

10. _agent/prompts/autonomous.md — from its template, only when Q8 names a real gate and Q4a retains the queue. Resolve every artefact path including _agent/ beneath Q12's root. Keep and uncomment exactly one mode block: SEPARATE WORKTREES, SHARED CHECKOUT or SINGLE WRITER. Keep PR START plus PR INTEGRATION only for PR mode; otherwise keep DIRECT INTEGRATION. Drop the unused blocks and all generation comments. Single-writer PRs create ordinary work branches; only separate worktrees acquire claim branches. Shared PR waves require separate worktrees, while ordinary shared PR work remains serialised. Keep the item Status, Stop and final Report instructions in every eligible mode.

11. INDEX.md — header + the seed ADR's row (item 5b); an empty table only if the seed was declined. Link each row's number or title to the actual ADR file using a path relative to INDEX. Check that every link resolves and the row's title, status and date match the file's metadata. In a two-shape repo (Q2) the table carries a Shape column, filled from each ADR's shape: field (blank field → capability); a single-shape repo has no such column. Neither 0000- template appears in the table — templates are not decisions.

12. Federation files — only if Q11 = yes. Place both at the configured artefact root (repository root by default).

    • Establish: write federation-index.md (the member index, a Markdown table) from templates/federation-index.md into this repo, seeded with this repo as the 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 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.

For an existing repo, prefer Edit over Write where files exist, and call out every merge decision in the commit message.

Verify the generated result

Before claiming bootstrap complete, compare the actual output with the confirmed answers: root pointer, assessment depth, ADR shape and metadata, seed and INDEX row, plan queue, coordination files and mode-specific branch instructions. Confirm the exact supplied gate command appears consistently in CONVENTIONS.md, AGENTS.md and the autonomous prompt when written. Run the recorded gate if present and retain its exact output and exit code. A wrong root, missing requested queue/seed or failed gate is an incomplete scaffold, not a host limitation. Correct it before reporting. When the plan layer includes the seed adoption record, also verify its completion reference as described above. Do not claim complete when the reference is missing, ambiguous, unreachable or points to an earlier incomplete scaffold. Preserve the failed observation and report the remaining repair.

Step 6 — Offer backfill (existing repos; re-runnable for emergent work)

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.

Tier the offer by the assessment depth. At full, make the offer as phrased below. At guided, ask it as one brief yes/no ("Backfill decision records from the existing history? I'll propose drafts for approval."). At express, do not run it now — close with a one-line pointer instead: undocumented history can be captured later by re-running this skill.

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, irrespective of shape. In a two-shape repo, stamp each draft's shape: field to match the template it was drafted from. 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.

Re-running to capture a development that bypassed the process. This backfill is not adoption-only. When a substantial development later lands in an already-docflow repo without an owning ADR or plan item — a large feature built ahead of the process — run the same passes again, scoped to that development: limit the scan (passes 1–3) to its commits and the area it touched, reconstruct just the decision(s) it embodies as Implemented ADR(s) (Revision History citing the implementing commits and noting they were recorded after the fact), write the matching plan/done entries, and regenerate INDEX.md. A large development is never outside the catalogue — it is an ADR not yet written. The audit skill's coverage check surfaces such gaps so they are captured, not silently kept.

Name the scaffold, preserved content, chosen profile/root and any incomplete setup.

Host permission boundary

An explicit host/tool permission denial stops the affected operation immediately, including receipt export and cleanup. Do not retry through another tool, shell, staging directory, move, archive, symlink or delegate, or probe writes to the denied destination. Report the denied action and destination, actual partial effects and missing permission as stopped/blocked. If recording Status or committing/exporting would cross that boundary, report in the current response and leave persistence pending. Resume only after explicit permission for that action. A gate environment failure is distinct and never overrides a denial.

Closing report

End every run, including blocked, failed and stopped runs, with a section headed exactly Status at a glance, containing these three labels:

• This run: only actions actually attempted and their outcomes; quote each verify gate's exact output and exit code, including timeouts or interruptions.
• Overall: implemented, partially verified, verified, blocked, failed or unknown. A passing sub-step is not an overall pass; incomplete or missing evidence never becomes success.
• Yet to do: every remaining action, unresolved finding, verification, cleanup or required input. Write None only when the whole task is verifiably complete; never omit work because a budget ended.

Routine progress messages need no block. Keep final results brief and distinguish work prepared on a PR from work confirmed shipped.