docflow

docflow

A plugin for ADR-driven, documentation-led projects, working on both the pi and Claude Code coding agents from the same skill files. 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.

Skills

Slash commands below are the Claude Code form. On the pi coding agent the same skills are invoked as /skill:<name> (e.g. /skill:bootstrap, /skill:new-adr). 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 → integrate → todo→done → ADR Accepted→Implemented → INDEX/WORKLOG.
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	Orchestrate a wave of parallel worktree subagents over the queue, with checkpoint or continuous supervision.

The lifecycle skills all 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.

What /bootstrap installs

• 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/ — ADR catalogue with a capability-ADR template (and an optional technology-ADR template).
• plan/todo/ and plan/done/ — implementation queue. git mv from todo/ to done/ is the completion event.
• _agent/ — multi-agent coordination: ROLES.md, LOCKS.md, WORKLOG.md, CURRENT_FOCUS.md, HANDOFF.md, and an optional unsupervised-run prompt under prompts/.

Optional, off by default: GLOSSARY.md, domains/<slug>/README.md groupings, project-specific hard rules (vendor-naming restriction, regulated-evidence posture, language mandate, audit-stream separation).

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

Install

docflow ships for two coding agents from the same skill files — only the manifest differs (.claude-plugin/ for Claude Code, package.json for pi).

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

pi coding agent

pi install git:github.com/EvolveHQ/docflow

or, once published to npm, pi install npm:@evolvehq/docflow. Pi auto-discovers the skills/ directory via the pi 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.

Claude Code — local development (no install)

claude --plugin-dir <path-to-this-repo>

Direct skill clone (no plugin lifecycle)

git clone https://github.com/EvolveHQ/docflow ~/.claude/skills/docflow-src
ln -s ~/.claude/skills/docflow-src/skills/bootstrap ~/.claude/skills/bootstrap