/bootstrap

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 the capability manifest and `CONVENTIONS.md`/`AGENTS.md` (the **record model**, from `docflow.yml` `model:` — a re-run **never converts it**; changing model is a separate, deliberate migration path — plus 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`, `CONSTRAINTS.md`, `goals/`, or `domains/` — plus the capability manifest `docflow.yml` where the repo predates it, and the `Assessment depth:` line (§Project) where the recorded `CONVENTIONS.md` predates that. (The technology-ADR template is **not** offered here: adding it means moving to the two-shape record model, and a re-run never converts the model.) Write only the chosen ones, by **merge**, under the recorded artefact root. Enabling a layer **includes writing its `CONVENTIONS.md` section** — each optional layer's rules live there, so the layer and its rules arrive together (likewise, a repo adopting evidence gains §Trust Posture and §Verification Evidence together — the latter cross-references the former). Everything not chosen is left untouched. Ask only the questions the new layers need (e.g. the coordination-mode question when enabling `_agent/`). This is the entry point for adding a layer you deferred at first bootstrap.

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
  docflow.yml            # capability manifest: schema, model, layers
  GLOSSARY.md            # shared terms (optional — see Q7)
  CONSTRAINTS.md         # inviolable boundaries (optional — see Q7)
  goals/G-<kebab-slug>.md    # one file per goal (optional — see Q7)
  COVERAGE.md            # generated goal→evidence walk (goals layer only)
  adr/
    0000-template.md     # capability-ADR template (always)
    NNNN-template.md     # technology-ADR template (two-shape model only — see Q2)
    NNNN-<kebab-slug>.md # one ADR per decision, contiguous numbering
  spec/                  # decisions+specs model only (see Q2)
    0000-template.md     # capability-spec template
    <kebab-slug>.md      # one living spec per capability, slug-identified
  domains/<slug>/README.md   # optional (see Q7)
  plan/
    README.md
    todo/NNNN-<slug>.md    # default scheme — a recorded convention wins
    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)
  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.

**Capability manifest.** `docflow.yml` sits **inside** the resolved artefact root — discovery finds the root; the manifest records the repo's shape: contract `schema`, record `model`, enabled `layers`. Tools read it instead of parsing `CONVE