docflow

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.

Skill	Slash command	Purpose
bootstrap	/bootstrap	Scaffold or retrofit the whole convention set. Start here.
new-adr	/new-adr	Author one ADR — next contiguous number, right shape, INDEX + domain wiring, supersede linkage.
new-plan	/new-plan	Add a plan/todo item tracing to its owning ADR(s).
ship-item	/ship-item	Run the completion event: verify → completion commit (todo→done, ADR Accepted→Implemented, INDEX) → push or PR merge per the recorded model.
add-convention	/add-convention	Assess whether a convention is worth codifying, route it to the right home (or to an ADR), then add it. Use it to enable optional practices (e.g. TDD) on demand — see USAGE §5a.
audit	/audit	Lint the repo against its own conventions — numbering, INDEX sync, plan coverage, ADR-privacy leaks, more.
brainstorm	/brainstorm	Decompose a problem into candidate ADRs + plan items (proposes drafts; writes nothing until approved).
agent-wave	/agent-wave	Run a bounded queue wave using available parallel agents or sequential execution, with checkpoint or continuous supervision.
rollup	/rollup	For a multi-repo product: aggregate every member repo's ADRs into one derived, product-wide roll-up (run from the home repo).
workspace-setup	/workspace-setup	Deliberately create or adopt a portable workspace home and registry.
workspace-status	/workspace-status	Read priorities, owners, authority, blockers and next actions.
workspace-scope	/workspace-scope	Record shared outcomes and native deliveries without granting execution.
workspace-dispatch	/workspace-dispatch	Check current grants, claims, dependencies and resources, then hand off a bounded brief.
workspace-sync	/workspace-sync	Reconcile returned receipts and maintain delivery state from checked native evidence; refresh INDEX.

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. Clarity integration is parked for 0.10.0; 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 status and no brainstorming/ folder — an ADR's first persisted status is Proposed, created only once a decision is approved. The brainstorm skill explores candidates in conversation and writes nothing until you approve them; only then does new-adr mint a numbered ADR. This keeps the catalogue free of half-formed drafts and the numbering clean — numbers go only to real decisions — following the lightweight-ADR tradition that an ADR captures the agreed decision, not the discussion that produced it.

Install

docflow ships from one skill source (plugins/docflow/skills/) to eight coding agents — only the packaging differs. Two surfaces: 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	Output	Skills	Install	Invoke
Claude Code	native	✅	marketplace (below)	/bootstrap
pi	native	✅	pi install npm:@evolvehq/docflow	/skill:bootstrap
Codex	native	✅	codex plugin marketplace add EvolveHQ/docflow	$bootstrap / /skills
OpenCode	native	✅	auto-discovered, or symlink into ~/.config/opencode/skills	auto, by description
Grok	native	✅	grok plugin marketplace add EvolveHQ/docflow	/bootstrap
Cursor	native	✅	cursor-agent --plugin-dir <repo>/plugins/docflow	/bootstrap
omp (oh-my-pi)	native	✅	omp plugin install npm:@evolvehq/docflow	/skill:bootstrap
GitHub Copilot CLI	native	✅	copilot plugin marketplace add EvolveHQ/docflow	/bootstrap

Handy: OpenCode and omp also read ~/.claude/skills/ and ~/.agents/skills/, so a shared skills directory can serve several agents at once.

Claude Code — from this marketplace

/plugin marketplace add EvolveHQ/docflow
/plugin install docflow@evolvehq

Invoke with /bootstrap, /new-adr, /ship-item, … (auto-triggers on matching requests too).

Grok (xAI)

docflow ships a Grok plugin (.grok-plugin/) with its own marketplace:

grok plugin marketplace add EvolveHQ/docflow
grok plugin install docflow --trust

Grok reads the scaffolded AGENTS.md natively and invokes the skills from the slash menu (/bootstrap, /new-adr, …). grok plugin validate plugins/docflow checks the manifest.

Cursor

Cursor loads a local plugin directory directly — no account marketplace step is required:

cursor-agent --plugin-dir <path-to-this-repo>/plugins/docflow

The skills then appear as slash commands. .cursor-plugin/ carries the Cursor plugin and marketplace manifests for repository-based installs.

omp (oh-my-pi)

omp is a pi fork and reads the same pi.skills manifest:

omp plugin install npm:@evolvehq/docflow

Invoke with /skill:bootstrap, /skill:new-adr, … A .omp-plugin/ marketplace source is also shipped for repository-based installs.

GitHub Copilot CLI

docflow ships the same Claude-compatible plugin, so Copilot installs it from the repository marketplace or loads it directly:

copilot plugin marketplace add EvolveHQ/docflow
copilot plugin install docflow@evolvehq
# or, local:
copilot --plugin-dir <path-to-this-repo>/plugins/docflow plugin list

The skills appear in copilot skill list. Copilot reads the scaffolded AGENTS.md natively.

pi coding agent

pi install npm:@evolvehq/docflow

or, from source, pi install git:github.com/EvolveHQ/docflow. Pi auto-discovers the skills via the pi.skills key in package.json. Invoke with /skill:bootstrap, /skill:new-adr, /skill:ship-item, … Pi does not auto-trigger skills from their descriptions the way Claude Code does — invoke them explicitly (the agent will also load a skill on-demand when a task clearly matches).

The scaffolded output (AGENTS.md, CONVENTIONS.md, the ADR catalogue, plan/, _agent/) is plain Markdown and is read natively by pi's hierarchical AGENTS.md loading — no porting needed.

Codex (OpenAI)

docflow ships a Codex plugin (.codex-plugin/), so it's a one-command install from this repo's marketplace:

codex plugin marketplace add EvolveHQ/docflow
codex plugin add docflow@evolvehq

Codex reads the scaffolded AGENTS.md natively. Invoke with $bootstrap / /skills, or just describe the task (Codex auto-triggers from the skill description); the assessment questions fall back to plain A/B/C text where there is no select tool. Update later with codex plugin marketplace upgrade.

OpenCode (sst)

OpenCode auto-discovers skills from .claude/skills, .agents/skills, and .opencode/skills (project and global) — so if you already run docflow on Claude Code or Codex via a shared skills directory, OpenCode picks it up with no extra step. Standalone, symlink the skills into OpenCode's global directory (one command, stays in sync with the clone):

git clone https://github.com/EvolveHQ/docflow ~/.docflow-src
mkdir -p ~/.config/opencode/skills
ln -s ~/.docflow-src/plugins/docflow/skills/* ~/.config/opencode/skills/

OpenCode has no marketplace command for SKILL.md skills (its plugin system is for npm JS plugins), so a shared skills directory is the clean path. Skills auto-load by description.

OpenCode-compatible forks — e.g. Xiaomi's mimocode — inherit this support via the same skill-discovery path; no separate packaging.

Claude Code — local development (no install)

claude --plugin-dir <path-to-this-repo>/plugins/docflow

Direct skill clone (no plugin lifecycle)

git clone https://github.com/EvolveHQ/docflow ~/.docflow-src
mkdir -p ~/.claude/skills
ln -s ~/.docflow-src/plugins/docflow/skills/* ~/.claude/skills/

On Windows, copy plugins\docflow\skills\* into %USERPROFILE%\.claude\skills\ instead of symlinking.

Workspace foundation assets

The package also includes the portable workspace contract, validator and producer fixtures in plugins/docflow/workspace/, with record templates in bootstrap's existing template directory. Keep workspace/ beside skills/ for plugin/npm installations. For standalone skill copies, also copy the complete workspace/ directory as docflow-workspace/ beside the host's skills/ directory; this applies to shared Codex/OpenCode copies too. See the installation and assembly guide. The five workspace operating skills act on those assets; native host and Clarity qualification stay separate from the deterministic package checks.

Quick start

In any repo, run:

/bootstrap

or just say "set up documentation-led conventions in this repo", "bootstrap ADRs and a plan queue", or "scaffold AGENTS.md and the _agent/ layout". The skill auto-triggers on those phrasings.

The skill will:

1. Detect whether the repo is fresh or existing, and state which.
2. Ask how deep to go — express (one question, conservative defaults, minimal footprint), guided (only the hard-to-reverse choices: integration model, coordination mode, plan queue), or full (all 10 assessment questions) — then ask that tier's questions one at a time, with a recommended option for each. You can switch depth mid-way ("defaults from here" / "go deeper"), and the choice is remembered as the recommendation for next time.
3. Summarise the resulting plan and ask for sign-off.
4. Write (or Edit, for existing repos) the files.
5. Commit each logical group with a Conventional Commit message.
6. On existing repos — and re-runnable later to capture a large development that bypassed the process — offer to backfill ADRs, plan/done/, and CONVENTIONS.md additions from the existing code and git history — drafts only, approved in batches. A reconstructed decision lands at Implemented with a matching plan/done; /audit's coverage check surfaces undocumented work to capture.

Updating

Recipients refresh installations with:

/plugin marketplace update evolvehq
/plugin install docflow@evolvehq

See USAGE.md §Updating the plugin for the author-side flow (version bumps, release tags) and recipient options including /reload-plugins for live sessions.

Docflow package releases use v<version>. Clarity desktop installers use separate clarity-v<version> releases in the same repository, with their compatible Docflow version recorded in the manifest. Select the product before choosing a release; the repository-wide latest release is not a package update signal. See Clarity downloads and release preparation for exact product lookup, installer selection, checksums and current verification limits.

Full usage and customisation guide

See USAGE.md for the assessment questions, what each answer changes, the file-by-file output, the backfill flow, and how to extend or override the templates.

Layout

docflow/
  .claude-plugin/marketplace.json   # Claude Code / Copilot marketplace (-> ./plugins/docflow)
  .agents/plugins/marketplace.json  # Codex marketplace (-> ./plugins/docflow)
  .grok-plugin/marketplace.json     # Grok marketplace (-> ./plugins/docflow)
  .cursor-plugin/marketplace.json   # Cursor marketplace (-> ./plugins/docflow)
  .omp-plugin/marketplace.json      # omp marketplace (-> ./plugins/docflow)
  package.json                      # pi/omp manifest (pi.skills -> ./plugins/docflow/skills) + npm
  plugins/docflow/                  # the plugin — one source, every target
    .claude-plugin/plugin.json      #   Claude Code / Copilot plugin manifest
    .codex-plugin/plugin.json       #   Codex plugin manifest (skills -> ./skills)
    .grok-plugin/plugin.json        #   Grok plugin manifest
    .cursor-plugin/plugin.json      #   Cursor plugin manifest
    .omp-plugin/plugin.json         #   omp plugin manifest
    skills/                         #   the one skill source
      bootstrap/
        SKILL.md                    #   bootstrap: assessment + output sequence + backfill
        agents/openai.yaml          #   optional declarative host interface
        templates/                  #   files the bootstrap reads and writes into target repos
      new-adr/SKILL.md              #   lifecycle skills — operate on a bootstrapped repo,
      new-adr/agents/openai.yaml
      new-plan/SKILL.md             #     read CONVENTIONS.md, honour its choices
      new-plan/agents/openai.yaml
      ship-item/SKILL.md
      ship-item/agents/openai.yaml
      add-convention/SKILL.md
      add-convention/agents/openai.yaml
      audit/SKILL.md
      audit/agents/openai.yaml
      brainstorm/SKILL.md
      brainstorm/agents/openai.yaml
      agent-wave/SKILL.md
      agent-wave/agents/openai.yaml
      rollup/SKILL.md
      rollup/agents/openai.yaml
  README.md
  USAGE.md

Only the bootstrap skill uses plugins/docflow/skills/bootstrap/templates/. The lifecycle skills act on the copies the bootstrap wrote into the target repo (e.g. its adr/0000-template.md), so they carry no templates of their own.

License

MIT. Use it, fork it, change it. If you improve a template, a PR is welcome.

Runtime verification

The same files install on all eight targets; behaviour also depends on the selected model and the host's permissions. Independent vendor-host tests on 2026-09-13–14 checked frozen source snapshots of the five original targets (Claude Code, pi, Codex, OpenCode, Cowork) and the actual target Git state:

Host / model	Observed result	Limit
Claude Code 2.1.269 / Opus 5	Bootstrap/new-adr, native Workflow rung 1 and Agent rung 2 passed; workers signed and pushed to local remotes.	Ordinary manual permissions with fixture tools allowed; one worktree guard denial recovered through permitted commands. Hosted PR operations untested.
Codex 0.154.0 / GPT-6 Astra	Bootstrap/new-adr and native rung 2 passed; signed concurrent work survived the whole-wave gate failure.	Native dispatch needed session storage on the disposable home; ephemeral dispatch failed. Workers used explicitly assigned Git worktrees, without host-enforced isolation.
OpenCode 1.18.30 / Big Pickle	Fresh bootstrap/new-adr and native Task rung 2 pass target checks, preserving signed concurrent claims after the gate-environment failure. Full native worker records establish acquisition ordering.	A later attempt wrongly integrates another item after the failure and remains rejected. The fresh retry passes state, initial-claim and final-report checks; a separate native follow-up adds missing labels to the persisted stop entry. Workers use explicitly assigned Git worktrees; this is staged verification, not an uninterrupted pass.
pi 0.84.4 / local Qwen coding route	Fresh native-high bootstrap/new-adr, normal completion and a bootstrap-derived blocked wave pass. Initial published metadata, acquisition-before-write, signed recovery, held-claim exclusion, persisted reports and fresh-clone gates are independently checked.	Earlier missing metadata, interruptions and local-backend 503 failures remain recorded. The final bootstrap and blocked wave ran serially on the same local route. Signed transport is local; unauthenticated CLI probes do not establish hosted PR capability or external PR state.

Grok, Cursor, omp and Copilot were added to the V1 target set after those runs. They carry package-level proof — manifest validation, marketplace listing and plugin-directory loading (see the plan receipt) — while the behavioural runs above remain the historical five-target record. Full native qualification on the eight-target package remains pending.

The six core model-driven cases have independent target assertions through the vendor-host runner, including express bootstrap, signed item completion and both migrations. Historical failures remain recorded. Later source changes received targeted checks; the receipts identify the exact snapshot for each run. Pi used the operator's configured llama-server/qwen3.8-27b-coding selection; the server identifies its response model as qwen3.8-27b. Earlier cloud-provider failures remain historical and do not require a cloud login for this route. The runner now preserves the native thinking setting; earlier off results do not establish the operator's full high-thinking configuration. Each continuation records exact installed bytes and independent assertions; earlier failures and infrastructure interruptions remain separate. The isolated existing-repository pilot preserves real history through checked completion and a recoverable stop; it is controlled verification, not independent human adoption.

Signed transport tests used isolated local bare remotes. They do not prove a hosted GitHub PR workflow or GitHub authentication. Selection reused explicitly supplied inputs; interactive selection controls were not exercised.

These are scoped observations, not a guarantee for every host capability. The repeatable test method and newer receipts live under evals/hosts/. Wave execution reports the observed capability rung and falls back to one executor where delegation is unavailable. A failed gate stops the run.

Optional agents/openai.yaml files under each skill are declarative interface metadata. Every target receives them; SKILL.md remains sufficient alone.

Each queued item carries Claimed by, Blockers, and Stopped. Final skill results and persisted reports end with Status at a glance: This run, Overall, Yet to do. Routine progress is exempt; a ready PR is not shipped work.