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

/
  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-.md # one ADR per decision, contiguous numbering
  domains//README.md   # optional (see Q7)
  plan/
    README.md
    todo/NNNN-.md
    done/-.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/).

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/ coordination set (Q5 — choose None to omit 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.

1. Up to two ADR shapes:

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

1. 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/`.

1. Filenames: adr/NNNN-kebab-slug.md, zero-padded 4 digits,

contiguous, no reserved gaps. Cross-references use relative paths.

1. Acceptance criteria are testable and numbered. Tests map back to

them where practical.

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

1. INDEX.md is regenerated from ADR metadata after any ADR change.

Treat as derived, not hand-edited.

1. plan/ is the work queue. git mv plan/todo/X plan/done/-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.

1. Multi-agent coordination. Before editing, an agent appends a row

to _agent/LOCKS.md ( | | ) and removes it on commit. On commit, append one line to _agent/WORKLOG.md. CURRENT_FOCUS.md is the live snapshot; if it disagrees with git, git wins and CURRENT_FOCUS.md is corrected.

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

1. AGENTS.md is the hard-rules entry point; CLAUDE.md is the

one-liner @AGENTS.md so the Claude Code CLI picks it up.

1. 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 (10 questions, plus federation (Q11) and placement (Q12))

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.

1. ADR shape. Single shape, or capability-vs-technology split?

Recommended: single shape — start simple, split later if long-lived product requirements clearly outlive their implementations.

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

1. 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 = mode 1 (single agent). 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 = mode 2 or 3 (multi-agent). 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).

1. 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. This sets the _agent/ shape (or omits it); switching later is not free:

• None — omit _agent/. A solo human/agent with no coordination

need; no _agent/ directory is written, and lifecycle skills skip the WORKLOG/snapshot steps. The lightest footprint (the optional _agent/ layer is left out — see the core-vs-optional note in Step 2).

• (Recommended) Single agent. default-agent in ROLES.

LOCKS skipped. WORKLOG / CURRENT_FOCUS as standard single-file snapshots. Right for small projects and the "one human + one agent" case.

• Multi-agent, shared checkout. Named agents in ROLES. LOCKS

ON as a filesystem mutex (prevents simultaneous writes to the same file). WORKLOG append-on-commit, single file. CURRENT_FOCUS as the single in-flight snapshot. Right when several agents serialise through one working tree.

• Multi-agent, separate worktrees / PR branches. Named agents

in ROLES. LOCKS advisory only — GitHub draft PRs / branch assignment are the real lock; pick one signal, not two. _agent/WORKLOG.md gets merge=union via .gitattributes so concurrent appends concatenate instead of conflicting (or split to _agent/worklog/.md if agent set is fixed). _agent/CURRENT_FOCUS.md becomes local-only (added to .gitignore); a committed _agent/IN_FLIGHT.md dashboard aggregates per-worktree state.

Note: option 2 → option 3 is not a free upgrade later; it means splitting WORKLOG (or adding the merge driver) and rethinking CURRENT_FOCUS. Choose deliberately.

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

1. Optional artefacts. Which now vs. defer:

• domains//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 — *defer unless technology decisions split

from product decisions.*

1. Verify gate. What command(s) decide a change is shippable

(npm test, CI workflow, deploy + smoke, manual)? No recommendation — project-specific. If the user has no real gate, the skill will refuse to write _agent/prompts/autonomous.md.

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

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

1. 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 /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

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: EvolveHQ
• Source: EvolveHQ/docflow
• License: MIT
• Homepage: https://evolvehq.github.io/docflow/

Install and usage instructions live in the source repository linked above.