# Using docflow This document explains how the `bootstrap` skill behaves end-to-end, what each of the 10 assessment questions (asked in full depth) actually changes in the output, and how to customise or extend the templates. The lifecycle skills are covered in §5a. ## Install (per platform) docflow runs from **one skill source** (`plugins/docflow/skills/`) on five coding agents. The scaffolded **output** (`AGENTS.md`, the ADR catalogue, `plan/`, `_agent/`) is plain Markdown read natively by any agent that loads `AGENTS.md`; the **skills** are `SKILL.md` files the host discovers. | Agent | Install | Invoke | |-------|---------|--------| | **Claude Code** | `/plugin marketplace add EvolveHQ/docflow` then `/plugin install docflow@evolvehq` | `/bootstrap` | | **Claude Cowork** | the **same** Claude Code plugin (`/plugin marketplace add …`) — Cowork shares the plugin system | `/bootstrap` | | **pi** | `pi install npm:@evolvehq/docflow` (or `pi install git:github.com/EvolveHQ/docflow`) | `/skill:bootstrap` | | **Codex** | `codex plugin marketplace add EvolveHQ/docflow` then `codex plugin add docflow@evolvehq` (native plugin) | `$bootstrap` / `/skills` | | **OpenCode** | auto-discovers `.claude`/`.agents`/`.opencode` skills (so a Claude Code / Codex install is picked up), or symlink into `~/.config/opencode/skills` | auto, by description | Notes: - **Codex** ships a native plugin (`.codex-plugin/`), so it's a one-command install like Claude Code. **OpenCode** has no marketplace command for `SKILL.md` skills (its plugin system is npm JS plugins), so it relies on skills-directory auto-discovery or a symlink. - A **shared skills directory** can serve two agents: `~/.agents/skills/` is read by Codex and OpenCode; `~/.claude/skills/` by Claude Code and OpenCode. - The scaffolded output needs no porting on any of them — it is read natively wherever `AGENTS.md` is the instruction file. See the [README](README.md#install) for the full matrix, Windows paths, and local-development options. ## 1. Triggering the skills Once docflow is installed (per the table above), the skills are available in any repo. Invocation differs per agent: | Agent | Slash / mention | Auto-trigger from description | |-------|-----------------|-------------------------------| | Claude Code / Cowork | `/bootstrap`, `/new-adr`, … | yes | | pi | `/skill:bootstrap`, `/skill:new-adr`, … | no — invoke explicitly | | Codex | `$bootstrap` / `/skills` | yes | | OpenCode | (loaded by name) | yes, by description | On agents that **auto-trigger**, natural-language matching the skill's description also works, e.g.: - "set up documentation-led conventions in this repo" - "bootstrap ADRs and a plan queue" - "scaffold AGENTS.md and the _agent/ layout" - "retrofit this existing repo with the documentation conventions" Or, on any agent, name the skill explicitly: *"invoke the `bootstrap` skill on this repository."* ## 2. The flow The skill runs in three phases. ### Phase A — Detect The skill inspects the repo and states in one line whether it is: - **Fresh** — no source, no docs. It will scaffold from zero. - **Existing** — it reads any current `README.md`, `CONTRIBUTING.md`, `AGENTS.md`, `CLAUDE.md`, `docs/`, `adr/`, `.github/` first. Existing content is preserved; merges, not overwrites. If existing ADRs use a different format, the skill proposes a migration plan (renumber, keep, translate) instead of creating a parallel tree. ### Phase B — Assess The assessment opens with a **depth selector** — one question deciding how deep to go: - **express** — no further choices; everything takes a conservative fixed profile (minimal core files, default location, direct-to-main, single writer, seed ADR on, no optional layers, standalone). Only underivable essentials (project name, description) are still asked, and the resulting defaults are summarised before sign-off. - **guided** — only the hard-to-reverse choices are asked: plan folder, coordination mode, and integration model; everything else takes its recommended default. - **full** — the complete flow below. At any question you can answer **"defaults from here"** (finish with recommended defaults) or **"go deeper"** (escalate to the fuller tier). The chosen depth is recorded in `CONVENTIONS.md` and offered as the pre-selected recommendation next time — the selector always still appears. Express and guided never set up multi-repo federation; that is a full-depth choice only. At full depth the skill asks the 10 assessment questions **one at a time**, in order. For each question it states a **recommended** option with one short sentence on why, plus the alternatives. You pick the recommended option, pick an alternative, or type a custom answer. After all 10 answers are in, the skill summarises the resulting plan in 5–10 lines and asks for sign-off. **It does not write files before sign-off.** If the host CLI supports structured single-select (e.g. Claude Code's `AskUserQuestion`), the recommended option is labelled "(Recommended)" in the picker; otherwise the recommendation is named in plain text. ### Phase C — Write After sign-off, the skill writes files in dependency order (`CONVENTIONS.md` first, then `AGENTS.md` + `CLAUDE.md`, then ADR templates, then `plan/`, then `_agent/`, then `INDEX.md` stub, optionally `_agent/prompts/autonomous.md`). For existing repos it prefers `Edit` over `Write` where files already exist, and calls out every merge decision in the commit message. If the chosen artefact root is anything other than `.docflow/`, the skill also writes a one-line `.docflow` pointer file at the repository root (`root: docs/`, `root: .`) so external tools can locate the catalogue deterministically — a `.docflow` *directory* needs no pointer, it is its own marker. The same contract locates `federation.md` for multi-repo products (it lives at the artefact root). ### Phase D — Backfill (existing repos; re-runnable to capture emergent work) Once the scaffolding has landed, the skill **offers** to backfill ADRs, `plan/done/` entries, and `CONVENTIONS.md` additions from the existing code and git history. Skipped on fresh repos. Backfill is **not adoption-only**. When a large development later lands in an already-docflow repo **without** an ADR/plan, re-run it **scoped to that development** to reconstruct its ADR(s) at `Implemented` (Revision History citing the commits, noting they were recorded after the fact) + matching `plan/done`. `/audit`'s **coverage** check flags substantial work with no owning ADR so such escapes are captured, not silently kept. (A large development is never outside the catalogue — it's an ADR not yet written.) If accepted, the backfill runs in four passes, each producing drafts you review before they commit: 1. **Scan** (read-only): `git log`, top-level source dirs, existing docs, dependency manifests. 2. **Propose ADRs.** One per distinguishable decision or capability. Capabilities go in as capability ADRs with status `Implemented` (code already exists), Revision History citing the commits that introduced the behaviour. Technology choices go in as technology ADRs with reconstructed Rationale — anything speculative is flagged so you can correct it. You see the proposed list (number + title + status + scope) before any file is written. 3. **Propose `plan/done/` entries.** One per ADR drafted as `Implemented`, dated by the implementing commit's date. Approved as a batch. 4. **Propose `CONVENTIONS.md` additions.** De-facto patterns in the repo (commit-message style, branch naming, test layout, file-naming rules, tooling defaults) promoted to written rules. Diff shown before applying. Each accepted pass commits with a Conventional Commit: `docs(adr): backfill ADRs 0001-00NN from code and history`, `docs(plan): backfill plan/done from shipped commits`, `docs: backfill conventions from de-facto patterns`. `INDEX.md` is regenerated after the ADR pass. **Guardrails.** Everything is a draft; you approve each pass. If history is sparse or unclear, the skill stops rather than invent rationale. Declining the backfill is fine — the scaffolding is already complete and the queue is just empty until the first hand-authored ADR. ## 3. The 10 assessment questions Each question's answer changes specific files. Knowing the recommendation and what it changes up front helps you answer quickly. | # | Question | Recommended | What it changes | |---|----------|-------------|-----------------| | 1 | **Project identity** — name, one-liner, doc language, existing files to preserve. | *No default — project-specific.* | Header of `AGENTS.md`, `CONVENTIONS.md`, `README.md`; language mandate (if any) added to `CONVENTIONS.md` §Project. | | 2 | **ADR shape** — single vs. capability-vs-technology split. | **Single shape.** Start simple; split later if long-lived product requirements clearly outlive their implementations. | Whether `adr/NNNN-template.md` (technology) is created in addition to `adr/0000-template.md`. Section-order rules in `CONVENTIONS.md` §ADR Shapes and `AGENTS.md` §Hard rules. | | 3 | **Status lifecycle** — full or shorter. | **Full lifecycle.** The `Implemented` rung is cheap and gives a clear "what's shipped" signal. | Status table in `CONVENTIONS.md` §ADR Files and `plan/README.md` §Status semantics. Whether the `Implemented` rung exists at all. | | 4 | **Plan folder + integration model.** Q4a: use `plan/todo/` + `plan/done/` or skip. Q4b: how work reaches `main` — **direct-to-main (fast-forward)** or **PR-based (required CI green)**. Asked after Q5, because the Q4b recommendation depends on the multi-agent mode. | **Q4a: use it.** **Q4b: direct-to-main if Q5 = single agent; PR-based if Q5 = multi-agent.** | Whether `plan/` is created. The completion-event sentence in `CONVENTIONS.md` §Plan Folder, `plan/README.md`, `AGENTS.md` §Plan folder. The integration block in `AGENTS.md` / `CONVENTIONS.md` §Git contract. Which variant of `_agent/prompts/autonomous.md` Step 6 is kept (`git merge --ff-only` vs. `gh pr create` → CI → merge). | | 5 | **Multi-agent setup** — pick one of three: (1) single agent; (2) multi-agent, shared checkout; (3) multi-agent, separate worktrees / PR branches. The three options differ in LOCKS semantics, WORKLOG layout, and CURRENT_FOCUS handling — switching later is not free. | **Single agent.** Small projects shouldn't pay the coordination cost. | `_agent/ROLES.md` content. `AGENTS.md` §Multi-agent workflow and `CONVENTIONS.md` §Multi-Agent Rules pick one of three variants. Mode 2 turns LOCKS on as a filesystem mutex. Mode 3 sets LOCKS to advisory, adds `_agent/WORKLOG.md merge=union` to `.gitattributes`, gitignores `_agent/CURRENT_FOCUS.md`, and writes `_agent/IN_FLIGHT.md` as the committed cross-worktree dashboard. | | 6 | **Git contract** — Conventional Commits, `Rationale:` footer, signed commits, ADR-revision tags, `Co-Authored-By` trailer. | **Conventional Commits ON, `Rationale:` footer ON, signed commits ON, ADR-revision tags OFF, `Co-Authored-By` trailer OFF.** | `AGENTS.md` §Git contract and `CONVENTIONS.md` §Git Contract bullets. | | 7 | **Optional artefacts** — `domains/` grouping, `GLOSSARY.md`, technology-ADR template. | **`domains/`: enable when the project has distinct areas or you expect >20 ADRs** (navigation by area). `GLOSSARY.md` / technology template: defer until terminology drift / a product–technology split appears. | Whether those files / directories are created. | | 8 | **Verify gate** — what command(s) decide a change is shippable. | *No default — project-specific.* | Whether `_agent/prompts/autonomous.md` is written. The skill **refuses** to write the autonomous prompt without a real verify gate. The Step 4 line of the prompt is filled with your command. | | 9 | **Existing-content conflicts** (existing repos only) — current commit format, branch policy, ADR style, status names the new layout must respect. | *No default — project-specific.* Skipped on fresh repos. | Merge behaviour during writes; commit-message notes calling out each compromise. | | 10 | **Domain-specific hard rules** to enforce from day one — e.g. vendor-naming restriction, regulated-evidence posture (attribution, retention, e-signatures), language mandate, mandatory user-story personas, separated audit streams. | **None from day one.** Add later when a concrete requirement appears; pre-emptive hard rules accumulate as cruft. | Additional sections in `CONVENTIONS.md` and additional bullets in `AGENTS.md` §Hard rules. | ## 4. Output files After sign-off, the skill writes: | File | Source template | Notes | |------|-----------------|-------| | `CONVENTIONS.md` | `templates/CONVENTIONS.md` | Spec the other files reference. Written first. | | `AGENTS.md` | `templates/AGENTS.md` | Hard rules entry point. | | `CLAUDE.md` | `templates/CLAUDE.md` | Single line `@AGENTS.md`. | | `adr/0000-template.md` | `templates/adr-capability.md` | Capability-ADR template. | | `adr/NNNN-template.md` | `templates/adr-technology.md` | Technology-ADR template. Only if Q2 said split. `NNNN` is the project-defined cutoff (default 0100). | | `adr/0001-record-architecture-decisions.md` | `templates/adr-0001-seed.md` | **Seed ADR** recording the decision to adopt the method (`Implemented`, references `CONVENTIONS.md`). Default on; declined at sign-off if not wanted. | | `plan/README.md` | `templates/plan-README.md` | Plus empty `plan/todo/.gitkeep` and `plan/done/.gitkeep`. | | `_agent/ROLES.md` | `templates/_agent-ROLES.md` | Single `default-agent` by default. | | `_agent/LOCKS.md` | `templates/_agent-LOCKS.md` | Empty header. Created only if Q5 enabled LOCKS discipline. | | `_agent/WORKLOG.md` | `templates/_agent-WORKLOG.md` | Empty table header. | | `_agent/CURRENT_FOCUS.md` | `templates/_agent-CURRENT_FOCUS.md` | Live snapshot, initial state "none". | | `_agent/HANDOFF.md` | `templates/_agent-HANDOFF.md` | Fresh-agent entry point. | | `_agent/IN_FLIGHT.md` | `templates/_agent-IN_FLIGHT.md` | Only in Q5 mode 3 (worktree). Committed cross-worktree dashboard. | | `.gitattributes` (entry) | (none — inline) | Only in Q5 mode 3: appends `_agent/WORKLOG.md merge=union`. | | `.gitignore` (entry) | (none — inline) | Only in Q5 mode 3: adds `_agent/CURRENT_FOCUS.md` so it stays local-only. | | `INDEX.md` | (none — generated) | Header + the seed ADR's row (empty table only if the seed was declined). | | `_agent/prompts/autonomous.md` | `templates/_agent-prompts-autonomous.md` | Only if Q8 confirmed a verify gate. | ## 5. After scaffolding The repo is now ready for ADR-driven work. Typical first steps: 1. **Author the first ADR.** Copy `adr/0000-template.md` to `adr/0001-.md`. Fill in Context, Capability statement, User stories, Acceptance criteria. Set status to `Proposed`. 2. **Get it Accepted.** Update Approvals table, change status to `Accepted`, regenerate `INDEX.md`. 3. **Queue the work.** Create `plan/todo/0001-.md` naming the owning ADR, scope, exit criteria. Lower-numbered files run first. 4. **Implement.** Code against the ADR's numbered acceptance criteria. Add tests that map back to those criteria. 5. **Integrate.** Per the Q4b integration model: fast-forward to `main` and push (direct-to-main), or open a PR, wait for CI green, and merge (PR-based). 6. **Ship.** Once on `main`: `git mv plan/todo/0001-.md plan/done/-.md`, amend the file with a "Shipped at HEAD ``" footer, advance the ADR's `status:` from `Accepted` to `Implemented`, regenerate `INDEX.md`, append a row to `_agent/WORKLOG.md`. ## 5a. Lifecycle skills The manual workflow in §5 is exactly what the lifecycle skills automate. They all share four properties: they **run a short assessment first** (see below); they **read `CONVENTIONS.md` first** and honour the repo's recorded choices (ADR shape, status lifecycle, integration model, multi-agent mode); they **refuse on an un-bootstrapped repo** and point at `/bootstrap`; and they keep `INDEX.md` and the `_agent/` coordination files in sync as a side effect. **The assessment protocol.** `new-adr`, `new-plan`, `add-convention`, `brainstorm`, and `agent-wave` each open with a brief assessment before acting — the same pattern bootstrap uses (§3): - A **depth selector** first: *express* (every choice takes its recommended default; only free-text essentials like a title are still asked), *guided* (only the high-impact questions), or *full* (everything). The recommendation follows the `Assessment depth:` recorded in your `CONVENTIONS.md` if present — otherwise it flips on context: *full* when you invoked the skill with little detail, *express* when your request already specifies everything. The selector always appears; a recorded depth is never applied silently, and at any question you can say "defaults from here" or "go deeper". - Questions are asked **one at a time**, each with a **recommended option** you can accept, override, or replace. - Answers use **scroll-to-select** (single- or multiple-choice) where the host exposes a selection tool (Claude Code's `AskUserQuestion`), falling back to plain `A/B/C` lists otherwise. Free text is used only where an enumerable set is impossible (e.g. an ADR title). - **You decide** — a skill never proceeds past a question without your input, and never guesses scope when invoked with no context. `agent-wave` additionally asks the wave parallelism and the merge / integration strategy. So a bare *"new ADR"* leads with a couple of quick picks; a fully-specified request lets you skip straight through. | Skill | Replaces these manual steps | |-------|------------------------------| | `/new-adr` | §5 steps 1–2: pick number, choose shape, fill template, set `Proposed`, regen INDEX, wire domain README, supersede linkage. Offers to walk to `Accepted` and to create the plan item. | | `/new-plan` | §5 step 3: create `plan/todo/NNNN`, name owning ADR(s), scope, exit criteria, dependencies, queue position. | | `/ship-item` | §5 steps 5–6: verify gate → integrate (ff or PR per Q4b) → `git mv` todo→done with footer → ADR `Accepted`→`Implemented` → regen INDEX → WORKLOG → live snapshot. The most order-sensitive operation; let the skill do it. | | `/add-convention` | Assesses whether a convention is worth codifying (triages out one-offs, duplicates, churn-prone, vague), routes it to AGENTS.md / CONVENTIONS.md / GLOSSARY / an ADR, then writes it. | | `/audit` | Lints the repo against its own conventions and reports a punch list — numbering, INDEX sync, plan coverage, section completeness, status validity, cross-refs, language mandate, and **ADR-privacy leaks into user-visible code**. Offers to fix the mechanical issues. | | `/brainstorm` | Decomposes a problem into candidate ADRs + plan items with dependency edges and ordering. Proposes drafts only; writes nothing until approved, then hands off to `/new-adr` and `/new-plan`. | | `/agent-wave` | Orchestrates parallel worktree subagents over the queue. Asks wave width, budget (items/waves; hours as a soft cap), and supervision (checkpoint vs. continuous). Requires multi-agent mode; refuses mode 1. | | `/rollup` | For a **multi-repo product**: from the home repo, aggregate every member repo's `INDEX` into one derived, product-wide roll-up. Members not checked out are listed as "not aggregated this run". | ### agent-wave: what it can and can't do In-session subagents are bounded by the session, not by wall-clock hours. `/agent-wave` therefore measures budget in **items and waves**, with hours as a *soft cap*. For a genuinely long-running, session- outliving fleet, schedule `_agent/prompts/autonomous.md` via `/schedule` (or use remote agents) instead — `/agent-wave` points you there rather than over-promising. It requires a multi-agent mode (Q5 mode 2 or 3) and works best in mode 3 (separate worktrees), where each subagent gets an isolated checkout. Continuous-unsupervised runs are recommended only with PR-based integration, so CI gates each merge. ### Multi-repo products (federation) A single product spread across several repos runs as a **federation**. Bootstrap asks whether the repo is standalone or part of a multi-repo product, and — if the latter — whether it is **establishing** a new federation or **joining** an existing one. A joining repo writes only its own `federation.md` back-pointer; it never writes into another repo, and it inherits the topology and identity scheme rather than re-choosing them. - **Topology** (chosen at establishment): a central decisions repo · a distributed set · or a home repo with local decisions alongside (the default). - **Identity & numbering.** Numbering stays contiguous *per repo*; a federation-wide identity — by default a repo-prefixed slug `/NNNN-slug` — is the cross-repo key, so two repos never collide. - **References.** Cross-repo links use the logical identity, resolved via the home's `federation-index.md`; same-repo links stay relative. - **Work & status.** A cross-repo decision is one plan item **per affected repo**, each tracing to the owning ADR by its federation identity (no umbrella record); the decision's aggregate status ("2 of 3 repos") is a derived roll-up column, `Implemented` only when every per-repo item ships. - **`/rollup`** aggregates every member's catalogue into one product-wide view; **`/audit`** gains cross-repo checks (bidirectional membership, identity collisions, dangling references, roll-up drift, convention drift). - **Conventions** are copied at bootstrap and kept honest by audit drift-detection — referenceable from the home, never force-pushed. No tool writes across a repo boundary: consistency is declared at the edges and enforced by audit. See the [methodology](https://evolvehq.github.io/docflow/methodology/#5-scaling-to-many-repositories) for the formal model. ### Enabling an optional layer later Deferred `plan/`, `_agent/`, `GLOSSARY.md`, `domains/`, or the technology-ADR template at bootstrap? You can add any of them later — saying no the first time doesn't lose you the option: - **Re-run `bootstrap`** on the repo. It detects your existing setup, reads the recorded choices (shape, artefact root, mode, layers present), skips the settled questions, and offers only the layers you don't have yet — adding the chosen ones by **merge**, under your recorded artefact root, without touching existing content. - **`add-convention`** creates `GLOSSARY.md` if it's absent when you add your first shared term. - **`new-adr`** offers to create a `domains//README.md` grouping when you file an ADR under a domain that doesn't exist yet. ### Enabling an optional convention later (worked example: TDD) docflow's bootstrap is deliberately lean — practices such as test-driven development are **not** baked in. You enable them whenever you want with `/add-convention`; there is no dedicated command per practice, and you don't have to re-bootstrap. Say *"add a convention: implement plan items test-first"* (or just run `/add-convention` and describe the rule). The skill will: 1. **Assess** whether it is worth codifying. TDD passes — it is a durable, repo-wide rule, not a one-off, a duplicate, or churn-prone. 2. **Route** it to the right home: a short **hard rule** in `AGENTS.md` plus the detail in `CONVENTIONS.md`. (It would not make this a GLOSSARY term, and it is not a single decision, so not an ADR.) 3. **Write** it, agent-neutral, so it holds on Claude Code and pi alike. A typical result — a new `CONVENTIONS.md` section: > ## Test-Driven Development > Implement each `plan/todo` item test-first. For every numbered > acceptance criterion in the owning ADR, write a failing test before > the code that satisfies it, then make it pass, then refactor. An item > is not shippable until its criteria have passing tests mapped back to > them. and a matching `AGENTS.md` hard-rule bullet: > - **TDD:** write the failing test for an acceptance criterion before > implementing it; map tests back to the owning ADR's criteria. This rides docflow's existing rule that *acceptance criteria are testable and numbered* — TDD simply fixes the order (test → code). To turn it off, delete those sections (or re-run `/add-convention` and say it no longer applies); to make it enforceable, add the test command to the verify gate. Any other "we should always X" practice is enabled the same way — `/add-convention` is the single path. ### Concurrent ADR/plan creation (the numbering race) ADR and `plan/todo` numbers are contiguous and chosen at authoring time, so two branches/worktrees can both grab the same "next" number and collide at merge. docflow keeps the numbers (they stay short, ordered, and the stable cross-reference key — no UUIDs, no rename-breaks-refs) and closes the race with **process guardrails** instead of a new identity scheme: - **G1 — decide before do** *(recommended):* prefer to land an ADR + its plan items on `main` before implementation work begins. - **G2 — check before merge** *(primary defence):* before integrating, sync onto the current `main` and run the audit; if your number now clashes with what landed, renumber locally **before** merging — a trivial change (a new ADR/plan names its own number only in its file and `INDEX.md`). - **G3 — gate backstop:** the single-threaded merge gate rejects a duplicate; the later author renumbers. - **G4 — claim before do:** before implementing a queued item, claim it (a draft PR referencing it, or an `IN_FLIGHT`/`owner` entry) so two writers don't build the same unclaimed `plan/todo` item — G1–G3 protect the *number*, G4 protects the *work assignment*; the audit's duplicate-plan-ownership check is the backstop. `bootstrap` **pre-wires** these into `CONVENTIONS.md` + an `AGENTS.md` hard rule **only** for multi-agent (mode 2/3) or PR-based repos. **Single-agent / direct-to-main repos have no race by construction** and get none of this ceremony. Numbers are immutable once merged. (For orchestrated runs, `agent-wave` additionally *reserves* disjoint number blocks up front, so G2/G3 rarely fire.) ### Numbering at scale, and grouping by domain ADR numbers are **integers**; the four-digit zero-padding is cosmetic and sorts **numerically**, so a catalogue is not capped at `9999` — widen the padding to five digits if you ever approach it (no real catalogue does). Two alternative identifier schemes are intentionally *not* used (the [methodology](https://evolvehq.github.io/docflow/methodology/#46-numbering-at-scale-and-alternatives-considered) has the full reasoning): **timestamp / opaque ids** — they trade away ordering and readability, and the guardrails above handle collisions instead; and **per-domain numbering** like `auth/0001` — the federation serves genuinely independent sequences, and within one repo you group rather than renumber. **Grouping by domain.** A first-class but optional way to navigate a large catalogue by area: `domains//README.md` files (e.g. `domains/auth/`, `domains/billing/`), each a curated index of that area's ADRs. It is purely organisational — every ADR keeps its flat number and its `INDEX.md` row; the domain README is a view, not a namespace (and not per-domain numbering). `new-adr` keeps it current: it files each ADR under its owning domain and offers to create a domain's README on first use. Enable it when the project has distinct areas, or the flat list grows large enough to be hard to scan. See the [methodology](https://evolvehq.github.io/docflow/methodology/#47-grouping-adrs-by-domain) for the formal treatment. ## 6. Customising or extending The templates are deliberately small and self-contained. To customise: - **Edit a template.** Files in `plugins/docflow/skills/bootstrap/templates/` are read verbatim by the `bootstrap` skill, then placeholders are filled from the assessment answers. Change the template, the next bootstrap reflects it. - **Add a new template.** Put it in `plugins/docflow/skills/bootstrap/templates/` and reference it from `bootstrap/SKILL.md` §Step 5 (Output sequence). - **Tighten a skill's auto-trigger.** Edit the `description:` frontmatter in that skill's `SKILL.md`. Skills match user requests against this string — be specific about phrasings, be terse about scope. With several skills in one plugin, watch for trigger collision (e.g. "add a convention" vs. "add an ADR") and keep descriptions distinct; the slash commands are the unambiguous entry point. - **Add a new lifecycle skill.** Create `plugins/docflow/skills//SKILL.md`. Follow the shared pattern: a Step 0 that checks the repo is bootstrapped and reads `CONVENTIONS.md`, then act in a way that honours the recorded choices. Lifecycle skills act on the target repo's own files (e.g. its `adr/0000-template.md`), so they need no templates of their own. - **Fork the plugin.** This repo is small enough to fork and host internally if you want a private convention set. ## 7. Re-running The skill is idempotent in spirit, but be careful: re-running on a repo that already has scaffolded files will trigger the "existing repo" path and ask Q9 about conflicts. Use it intentionally — to add the parts you skipped the first time, not to wipe and rebuild. ## 8. Updating the plugin ### As a recipient (someone who installed the plugin) When the plugin author pushes changes, refresh your installation: ``` /plugin marketplace update evolvehq /plugin install docflow@evolvehq ``` The first command pulls the latest marketplace listing (a `git fetch` behind the scenes against the marketplace repo). The second reinstalls the plugin at its now-current version. To pick up the changes in an *already-running* Claude Code session, run `/reload-plugins` instead of restarting. To check what's installed and the resolved version: ``` /plugin list ``` To remove the plugin entirely: ``` /plugin uninstall docflow@evolvehq ``` **Other agents:** - **Cowork** — same as Claude Code (`/plugin marketplace update` → install). - **pi** — re-run `pi install npm:@evolvehq/docflow` (or the `git:` form). - **Codex** — `codex plugin marketplace upgrade`, then re-add with `codex plugin add docflow@evolvehq`. - **OpenCode** — if installed via a clone/symlink, `git pull` the clone; skills reload on the next session. ### As the author (you, maintaining this repo) 1. Edit a skill body (`plugins/docflow/skills//SKILL.md`), the bootstrap templates (`plugins/docflow/skills/bootstrap/templates/*.md`), or supporting docs. 2. Bump the `version` field in `.claude-plugin/plugin.json` following semver — patch for fixes, minor for new questions / templates, major for breaking changes to the skill flow. 3. Update this `USAGE.md` and `README.md` if behaviour changed. 4. Commit with a Conventional Commit message (`feat(skill): ...`, `fix(template): ...`, `docs: ...`). 5. Push to `origin/main`. Recipients refresh per the section above. If you tag releases, use `git tag vX.Y.Z` matching `plugin.json`. Tags help recipients pin to a specific version via `/plugin install docflow@evolvehq@vX.Y.Z` (when supported by their Claude Code version). ## 9. Troubleshooting - **Skill not appearing in the available-skills list.** Confirm the plugin is installed (`/plugin list`) or `--plugin-dir` was passed. Restart the Claude Code session. - **Slash command not found.** The bootstrap slash form is `/bootstrap` (lowercase); lifecycle commands are `/new-adr`, `/new-plan`, `/ship-item`, `/add-convention`, `/audit`, `/brainstorm`, `/agent-wave`. - **Skill asks questions the project already answered.** That's by design — the skill does not persist state between invocations. Answer briefly; the second run is faster. - **Existing repo merge looks wrong.** Stop and surface it. The skill is instructed to preserve existing content; if it overwrote something, that's a bug — file an issue with the merge diff.