bootstrap

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 technology-ADR template/split — 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-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
  GLOSSARY.md            # shared terms (optional — see Q7)
  adr/
    0000-template.md     # capability-ADR template (always)
    NNNN-template.md     # technology-ADR template (only if split — see Q2)
    NNNN-<kebab-slug>.md # one ADR per decision, contiguous numbering
  domains/<slug>/README.md   # optional (see Q7)
  plan/
    README.md
    todo/NNNN-<slug>.md
    done/<YYYY-MM-DD>-<slug>.md
  _agent/
    ROLES.md             # named agents and what each owns
    LOCKS.md             # file-claim ledger
    WORKLOG.md           # append-only ship log
    CURRENT_FOCUS.md     # slim live snapshot
    HANDOFF.md           # fresh-agent entry point
    prompts/autonomous.md  # only if a verify gate exists (see Q8)
  federation.md          # multi-repo only (Q11): this repo's back-pointer
  federation-index.md    # multi-repo only (Q11): member index — home repo only