docflow

docflow

New to Docflow? Start here explains the terms, helps you choose one repository or several, and shows setup for your coding agent. Follow the prompt-first guides for a first task and expected result.

Browse the FAQ by topic or the visual explanation of federation and workspaces.

A plugin for ADR-driven, documentation-led projects, working on Claude Code, pi, Codex, OpenCode, Grok, Cursor, omp and Copilot from the same skill files (see Install). It installs a bootstrap skill that scaffolds (or retrofits) an Architecture Decision Record (ADR) catalogue, a plan queue, and AGENTS.md conventions into any repository, plus a set of lifecycle skills that author, queue, ship, and audit ADRs — so the project can be driven by both humans and coding agents from a small set of canonical files. For the formal definition of the conventions — why they help and where they fall short — see the methodology.

Skills

Slash commands below are the Claude Code form. On the pi and omp coding agents the same skills are invoked as /skill:<name> (e.g. /skill:bootstrap, /skill:new-adr); Codex uses $<name>; other hosts use their own slash menu. See Install.

The repository lifecycle skills read CONVENTIONS.md first and honour the choices the bootstrap recorded (ADR shape, status lifecycle, integration model, multi-agent mode). They refuse to run on an un-bootstrapped repo and point you at /bootstrap.

Portable workspaces

Start with the step-by-step workflow guides and 0.10.0 release notes. The Pages guide hub covers existing repositories, existing workspaces, mixed setups and new projects.

The five workspace skills — setup, status, scope, dispatch and sync — keep cross-repository memory in an adopter-owned Git workspace. Members retain their native methods, instructions and histories. The workspace can be used through ordinary files without a companion app. Authorised Docflow sessions edit canonical records and reconcile native evidence. Selection and agreement grant no execution authority, and delivery completion leaves the agreement accepted.

Install the complete workspace assets with all fourteen skills, including for detached skill copies. The seven native guides, four portable starter roles, profile examples and ordinary-file search travel in the same package. The new guides have source/help checks; full native qualification remains pending on the combined candidate.

Use /workspace-status in standalone Claude Code skill mode, the plugin-qualified form /docflow:workspace-status when exposed by the host, /skill:workspace-status in pi or omp, or $workspace-status in Codex. OpenCode and other native skill pickers use the discovered workspace-status name. The same naming applies to the other four workspace skills; verify the resolved source in the actual host before acting.

What /bootstrap installs

Only the core is always written; everything else is an opt-in layer chosen during the assessment, so a minimal repo stays as light as a classic ADR catalogue.

Core (always):

• AGENTS.md — hard rules for coding agents (the entry point).
• CLAUDE.md — one-liner re-exporting AGENTS.md so Claude Code picks it up automatically.
• CONVENTIONS.md — authoring rules for ADRs, naming, status lifecycle, audit trail, and git contract.
• INDEX.md — generated table of all ADRs.
• adr/0000-template.md — the ADR template; the catalogue starts here.

Optional layers (opt-in):

• plan/todo/ + plan/done/ — the implementation queue (Q4a). Git history and plan/done/ are the shipped record: direct-to-main footers name the HEAD SHA, while PR-based footers name the pull request.
• _agent/ — the agent operating contract: who writes what, the one real mutex, and how an unattended run behaves. It holds nothing git already records. Members follow the coordination answer (Q5): a single writer gets prompts/autonomous.md, and only where a verify gate (Q8) and the plan/todo/ queue the prompt walks (Q4a) are both recorded — otherwise no _agent/ at all; a shared checkout gets ROLES.md, LOCKS.md, and the prompt on the same condition; separate worktrees get ROLES.md and the prompt on the same condition. No mode writes a dashboard of what is in flight: a queue item is claimed by pushing a branch named for it (claim/<item-key>) and, where integration is PR-based, a draft pull request, and the live set is read back from the worktrees, those branches and those PRs.
• domains/<slug>/README.md — grouping: per-area indexes (e.g. domains/auth/) over the flat catalogue, for navigating a large catalogue by area. Organisational only — ADRs keep their number; new-adr files each under its domain. Enable it when the project has distinct areas (Q7).
• GLOSSARY.md, the technology-ADR template (adr/0000-template-technology.md — the second ADR shape, chosen at Q2 and declared per ADR by a shape: metadata field rather than by a number range), and project-specific hard rules (vendor-naming, regulated evidence, language mandate, audit-stream separation) — Q2/Q7/Q10.

Omitting any optional layer leaves a valid repo; a lifecycle skill that needs an absent layer refuses cleanly and says what's missing.

GLOSSARY.md has one canonical shape: an optional heading and short introductory prose, then a single two-column Term | Definition table. add-convention creates it on your first shared term and appends later terms in that shape; if an existing glossary uses bullets, prose or a mixed shape, audit reports it read-only and offers a migration with a concrete proposed diff — nothing is rewritten without your consent.

Enable a deferred layer later: re-run bootstrap on the repo — it detects your existing setup, skips the settled questions, and offers only the optional layers you don't have yet, adding the chosen ones by merge. (Two shortcuts: add-convention creates GLOSSARY.md on your first shared term, and new-adr offers to create a domains/<slug>/ grouping when you file an ADR under a new domain.)

On an older number-range catalogue? Early two-shape repos encoded the shape in the number — a cutoff in CONVENTIONS.md, a technology template at the boundary (adr/0100-template.md or your own number), technology records above it. That still works: audit recognises it, keeps checking it by its own range rules, and reports it as a single non-failing "migration available" note. Accept the offer (from audit or a bootstrap re-run) and the move is mechanical: your technology records are renumbered onto the end of the sequence in their original order, capability numbers stay put, shape: is written on every record, every in-repo reference follows, the boundary template is retired, and it lands as one commit listing every old-to-new pair. You see that map and confirm it before anything is written — and declining is a perfectly good answer.

Placement: AGENTS.md and CLAUDE.md always stay at the repository root; everything else lives under a configurable artefact root — .docflow/ (the default), docs/, or the repo root — chosen at bootstrap and recorded in CONVENTIONS.md. Discovery is deterministic for tools (the same pattern as git's .git): a .docflow/ directory is the root; any other choice gets a one-line .docflow pointer file at the repo root (root: docs/), written by bootstrap.

Seed ADR: by default, bootstrap also writes adr/0001 — a first ADR recording the decision to adopt this method (self-documenting, like the classic "use ADRs" convention). It references CONVENTIONS.md for the rules and is created Implemented. Decline it at sign-off if you want only the template.

Why

Documentation-led projects rot when conventions live in someone's head. This plugin makes the conventions explicit, machine-readable, and applied uniformly — so a fresh contributor (human or agent) can pick up the repo with no oral handover.

It works equally well on fresh repos (scaffolds from zero) and on existing repos (retrofits, preserving and merging existing files rather than overwriting them).

Multi-repo products

A single product spread across several repositories can run as a federation. At bootstrap a repo declares whether it is standalone or part of a multi-repo product, and whether it is establishing a new federation or joining one — a joining repo only ever writes its own back-pointer, never into another repo. You pick a topology (central decisions repo · distributed · home-repo-plus-local), and the convention set keeps numbering contiguous per repo while a federation-wide identity is the cross-repo key. The rollup skill aggregates every member's catalogue into one product-wide view, and audit gains cross-repo checks (membership, identity collisions, dangling references, roll-up drift, convention drift). Work and status cross repos the same way: a cross-repo decision is one plan item per affected repo, and its aggregate status ("2 of 3 repos") surfaces in the roll-up. No tool writes across a repo boundary; consistency is declared at the edges and enforced by audit. See the methodology for the full model.

No drafts in the catalogue

docflow records outcomes, not work-in-progress. There is **no Draft