Immutable. This exact content is served forever at /api/v1/blob/47445c3ab73b2c54.
---
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. Opens with an express / guided / full depth choice, so a quick conservative setup needs almost no questions.
---
# 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.
- **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 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 log of what shipped, 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.** `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. **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. In
**separate worktrees** the pushed branch and its draft pull request
are the claim, and no ledger is kept. Under **a single writer**
there is nothing to serialise. No mode keeps a log of what shipped, 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` 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 (depth-tiered; 10 questions at full depth, plus federation (Q11) and placement (Q12))
**Open with the depth selector — one single-select question before
anything else:** 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. The selector always appears — a recorded depth steers
the recommendation and is never applied silently.
**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 — summarise it and get sign-off before writing anything:
- 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 (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 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, 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. **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
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 work log, 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. *Defer; add on
terminology drift.*
- **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.** 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 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.
## 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. 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, drop `_agent/ROLES.md` unless Q5 chose several writers, drop
`_agent/LOCKS.md` unless Q5 chose a shared checkout, 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.
6. `plan/README.md` — from `templates/plan-README.md`. Create empty
`plan/todo/.gitkeep` and `plan/done/.gitkeep`.
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 work log, 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 branch and its pull request are the
claim there).
10. `_agent/prompts/autonomous.md` — from
`templates/_agent-prompts-autonomous.md`, **only** if Q8 confirmed a
verify gate **and** Q4a kept the plan queue — in every Q5 answer.
The prompt's whole loop is "take the next `plan/todo/` item, ship it
through the gate", so neither half is optional. 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.
11. `INDEX.md` — header + the seed ADR's row (item 5b); an empty table only
if the seed was declined. 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.
## 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), and write the matching `plan/done` entries;
regenerate `INDEX.md` and the worklog. A large development is never
*outside* the catalogue — it is an ADR not yet written. `/audit`'s coverage
check surfaces such gaps so they are captured, not silently kept.