# Bootstrap > 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 rat… - **Type:** Skill - **Install:** `agentstack add skill-evolvehq-docflow-bootstrap` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [EvolveHQ](https://agentstack.voostack.com/s/evolvehq) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [EvolveHQ](https://github.com/EvolveHQ) - **Source:** https://github.com/EvolveHQ/docflow/tree/main/plugins/docflow/skills/bootstrap - **Website:** https://evolvehq.github.io/docflow/ ## Install ```sh agentstack add skill-evolvehq-docflow-bootstrap ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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. 2. **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"). 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/-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. **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. 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 (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.* 2. **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. 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 = 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). 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. 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. 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//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.* 8. **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`. 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** `/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](https://github.com/EvolveHQ) - **Source:** [EvolveHQ/docflow](https://github.com/EvolveHQ/docflow) - **License:** MIT - **Homepage:** https://evolvehq.github.io/docflow/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-evolvehq-docflow-bootstrap - Seller: https://agentstack.voostack.com/s/evolvehq - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.