/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", or "add AGENTS.md and a plan queue". 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. 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 declar