{"id":51223041,"url":"https://github.com/EvolveHQ/docflow","last_synced_at":"2026-07-09T07:00:30.492Z","repository":{"id":359491591,"uuid":"1245999813","full_name":"EvolveHQ/docflow","owner":"EvolveHQ","description":"ADR-driven documentation workflow for the Claude Code and pi coding agents: scaffold and manage Architecture Decision Records (ADRs), a plan queue, and AGENTS.md conventions — a bootstrap skill plus lifecycle skills to author, queue, ship, and audit ADRs.","archived":false,"fork":false,"pushed_at":"2026-07-02T23:10:23.000Z","size":3016,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T23:25:47.062Z","etag":null,"topics":["adr","architecture-decision-records","claude-code","claude-code-plugin","documentation"],"latest_commit_sha":null,"homepage":"https://evolvehq.github.io/docflow/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EvolveHQ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-21T19:17:39.000Z","updated_at":"2026-07-02T23:10:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/EvolveHQ/docflow","commit_stats":null,"previous_names":["evolvehq/project-bootstrap-plugin","evolvehq/docflow"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/EvolveHQ/docflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvolveHQ%2Fdocflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvolveHQ%2Fdocflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvolveHQ%2Fdocflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvolveHQ%2Fdocflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EvolveHQ","download_url":"https://codeload.github.com/EvolveHQ/docflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvolveHQ%2Fdocflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35290235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adr","architecture-decision-records","claude-code","claude-code-plugin","documentation"],"created_at":"2026-06-28T09:00:31.116Z","updated_at":"2026-07-09T07:00:30.481Z","avatar_url":"https://github.com/EvolveHQ.png","language":"JavaScript","funding_links":[],"categories":["Source Catalog"],"sub_categories":[],"readme":"# docflow\n\n![docflow — ADR-driven documentation workflow](docs/preview.png)\n\nA plugin for **ADR-driven, documentation-led projects**, working on\n**Claude Code, Claude Cowork, pi, Codex, and OpenCode** from the same\nskill files (see [Install](#install)).\nIt installs a `bootstrap` skill that scaffolds (or retrofits) an\n**Architecture Decision Record (ADR)** catalogue, a plan queue, and\n`AGENTS.md` conventions into any repository, plus a set of **lifecycle\nskills** that author, queue, ship, and audit ADRs — so the project can\nbe driven by both humans and coding agents from a small set of canonical\nfiles. For the formal definition of the conventions — why they help and\nwhere they fall short — see the\n[methodology](https://evolvehq.github.io/docflow/methodology/).\n\n## Skills\n\nSlash commands below are the **Claude Code** form. On the **pi** coding\nagent the same skills are invoked as `/skill:\u003cname\u003e` (e.g.\n`/skill:bootstrap`, `/skill:new-adr`). See [Install](#install).\n\n| Skill | Slash command | Purpose |\n|-------|---------------|---------|\n| bootstrap | `/bootstrap` | Scaffold or retrofit the whole convention set. Start here. |\n| new-adr | `/new-adr` | Author one ADR — next contiguous number, right shape, INDEX + domain wiring, supersede linkage. |\n| new-plan | `/new-plan` | Add a `plan/todo` item tracing to its owning ADR(s). |\n| ship-item | `/ship-item` | Run the completion event: verify → integrate → `todo`→`done` → ADR `Accepted`→`Implemented` → INDEX/WORKLOG. |\n| 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](USAGE.md). |\n| audit | `/audit` | Lint the repo against its own conventions — numbering, INDEX sync, plan coverage, **ADR-privacy leaks**, more. |\n| brainstorm | `/brainstorm` | Decompose a problem into candidate ADRs + plan items (proposes drafts; writes nothing until approved). |\n| agent-wave | `/agent-wave` | Orchestrate a wave of parallel worktree subagents over the queue, with checkpoint or continuous supervision. |\n| 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). |\n\nThe lifecycle skills all **read `CONVENTIONS.md` first** and honour the\nchoices the bootstrap recorded (ADR shape, status lifecycle, integration\nmodel, multi-agent mode). They refuse to run on an un-bootstrapped repo\nand point you at `/bootstrap`.\n\n## What `/bootstrap` installs\n\nOnly the **core** is always written; everything else is an **opt-in layer**\nchosen during the assessment, so a minimal repo stays as light as a classic\nADR catalogue.\n\n**Core (always):**\n- `AGENTS.md` — hard rules for coding agents (the entry point).\n- `CLAUDE.md` — one-liner re-exporting `AGENTS.md` so Claude Code picks it\n  up automatically.\n- `CONVENTIONS.md` — authoring rules for ADRs, naming, status lifecycle,\n  audit trail, and git contract.\n- `INDEX.md` — generated table of all ADRs.\n- `adr/0000-template.md` — the ADR template; the catalogue starts here.\n\n**Optional layers (opt-in):**\n- `plan/todo/` + `plan/done/` — the implementation queue (Q4a). `git mv`\n  from `todo/` to `done/` is the completion event.\n- `_agent/` — coordination (`ROLES`, `LOCKS`, `WORKLOG`, `CURRENT_FOCUS`,\n  `HANDOFF`, optional `prompts/`). **Q5 — choose *None* to omit it.**\n- `domains/\u003cslug\u003e/README.md` — **grouping**: per-area indexes (e.g.\n  `domains/auth/`) over the flat catalogue, for navigating a large catalogue\n  by area. Organisational only — ADRs keep their number; `new-adr` files\n  each under its domain. Enable it when the project has distinct areas (Q7).\n- `GLOSSARY.md`, the technology-ADR template, and project-specific hard\n  rules (vendor-naming, regulated evidence, language mandate, audit-stream\n  separation) — Q7/Q10.\n\nOmitting any optional layer leaves a valid repo; a lifecycle skill that\nneeds an absent layer refuses cleanly and says what's missing.\n\n**Enable a deferred layer later:** re-run **bootstrap** on the repo — it\ndetects your existing setup, skips the settled questions, and offers only\nthe optional layers you don't have yet, adding the chosen ones by merge.\n(Two shortcuts: `add-convention` creates `GLOSSARY.md` on your first shared\nterm, and `new-adr` offers to create a `domains/\u003cslug\u003e/` grouping when you\nfile an ADR under a new domain.)\n\n**Placement:** `AGENTS.md` and `CLAUDE.md` always stay at the repository\nroot; everything else lives under a configurable **artefact root** —\n`.docflow/` (the default), `docs/`, or the repo root — chosen at bootstrap\nand recorded in `CONVENTIONS.md`. Discovery is deterministic for tools\n(the same pattern as git's `.git`): a `.docflow/` directory *is* the\nroot; any other choice gets a one-line `.docflow` pointer file at the\nrepo root (`root: docs/`), written by bootstrap.\n\n**Seed ADR:** by default, bootstrap also writes **`adr/0001`** — a first\nADR recording the decision to adopt this method (self-documenting, like the\nclassic \"use ADRs\" convention). It references `CONVENTIONS.md` for the rules\nand is created `Implemented`. Decline it at sign-off if you want only the\ntemplate.\n\n## Why\n\nDocumentation-led projects rot when conventions live in someone's head.\nThis plugin makes the conventions explicit, machine-readable, and\napplied uniformly — so a fresh contributor (human or agent) can pick up\nthe repo with no oral handover.\n\nIt works equally well on **fresh repos** (scaffolds from zero) and on\n**existing repos** (retrofits, preserving and merging existing files\nrather than overwriting them).\n\n## Multi-repo products\n\nA single product spread across several repositories can run as a\n**federation**. At bootstrap a repo declares whether it is standalone or\npart of a multi-repo product, and whether it is **establishing** a new\nfederation or **joining** one — a joining repo only ever writes its own\nback-pointer, never into another repo. You pick a **topology** (central\ndecisions repo · distributed · home-repo-plus-local), and the convention\nset keeps numbering contiguous **per repo** while a federation-wide\nidentity is the cross-repo key. The `rollup` skill aggregates every\nmember's catalogue into one product-wide view, and `audit` gains\ncross-repo checks (membership, identity collisions, dangling references,\nroll-up drift, convention drift). Work and status cross repos the same way:\na cross-repo decision is one plan item per affected repo, and its aggregate\nstatus (\"2 of 3 repos\") surfaces in the roll-up. No tool writes across a\nrepo boundary; consistency is declared at the edges and enforced by audit. See the\n[methodology](https://evolvehq.github.io/docflow/methodology/#5-scaling-to-many-repositories)\nfor the full model.\n\n## No drafts in the catalogue\n\ndocflow records **outcomes, not work-in-progress**. There is **no `Draft`\nstatus** and **no `brainstorming/` folder** — an ADR's first persisted\nstatus is `Proposed`, created only once a decision is approved. The\n`brainstorm` skill explores candidates **in conversation and writes\nnothing** until you approve them; only then does `new-adr` mint a numbered\nADR. This keeps the catalogue free of half-formed drafts and the numbering\nclean — numbers go only to real decisions — following the lightweight-ADR\ntradition that an ADR captures the agreed decision, not the discussion that\nproduced it.\n\n## Install\n\ndocflow ships from **one skill source** (`plugins/docflow/skills/`) to\nfive coding agents — only the packaging differs. Two surfaces: the scaffolded **output**\n(`AGENTS.md`, the ADR catalogue, `plan/`, `_agent/`) is plain Markdown\nread natively by any agent that loads `AGENTS.md`; the **skills** are\n`SKILL.md` files the host discovers.\n\n| Agent | Output | Skills | Install | Invoke |\n|-------|:------:|:------:|---------|--------|\n| Claude Code | native | ✅ | marketplace (below) | `/bootstrap` |\n| Claude Cowork | native | ✅ | same Claude Code plugin | `/bootstrap` |\n| pi | native | ✅ | `pi install npm:@evolvehq/docflow` | `/skill:bootstrap` |\n| Codex | native | ✅ | `codex plugin marketplace add EvolveHQ/docflow` | `$bootstrap` / `/skills` |\n| OpenCode | native | ✅ | auto-discovered, or symlink into `~/.config/opencode/skills` | auto, by description |\n\nHandy: OpenCode also reads `~/.claude/skills/` and `~/.agents/skills/`, so\na shared skills directory can serve it alongside another agent.\n\n### Claude Code — from this marketplace\n\n```\n/plugin marketplace add EvolveHQ/docflow\n/plugin install docflow@evolvehq\n```\n\nInvoke with `/bootstrap`, `/new-adr`, `/ship-item`, … (auto-triggers on\nmatching requests too).\n\n### Claude Cowork\n\nCowork uses the **same plugin system** as Claude Code, so install the\ndocflow plugin exactly as above (`/plugin marketplace add\nEvolveHQ/docflow`, then install) — or from Anthropic's community\nmarketplace once listed. No separate packaging.\n\n### pi coding agent\n\n```\npi install npm:@evolvehq/docflow\n```\n\nor, from source, `pi install git:github.com/EvolveHQ/docflow`. Pi\nauto-discovers the skills via the `pi.skills` key in\n`package.json`. Invoke with `/skill:bootstrap`, `/skill:new-adr`,\n`/skill:ship-item`, … Pi does **not** auto-trigger skills from their\ndescriptions the way Claude Code does — invoke them explicitly (the\nagent will also load a skill on-demand when a task clearly matches).\n\nThe scaffolded output (`AGENTS.md`, `CONVENTIONS.md`, the ADR catalogue,\n`plan/`, `_agent/`) is plain Markdown and is read natively by pi's\nhierarchical `AGENTS.md` loading — no porting needed.\n\n### Codex (OpenAI)\n\ndocflow ships a Codex plugin (`.codex-plugin/`), so it's a one-command\ninstall from this repo's marketplace:\n\n```\ncodex plugin marketplace add EvolveHQ/docflow\ncodex plugin add docflow@evolvehq\n```\n\nCodex reads the scaffolded `AGENTS.md` natively. Invoke with `$bootstrap`\n/ `/skills`, or just describe the task (Codex auto-triggers from the skill\ndescription); the assessment questions fall back to plain `A/B/C` text\nwhere there is no select tool. Update later with `codex plugin\nmarketplace upgrade`.\n\n### OpenCode (sst)\n\nOpenCode auto-discovers skills from `.claude/skills`, `.agents/skills`,\nand `.opencode/skills` (project and global) — so **if you already run\ndocflow on Claude Code or Codex via a shared skills directory, OpenCode\npicks it up with no extra step.** Standalone, symlink the skills into\nOpenCode's global directory (one command, stays in sync with the clone):\n\n```\ngit clone https://github.com/EvolveHQ/docflow ~/.docflow-src\nln -s ~/.docflow-src/plugins/docflow/skills/* ~/.config/opencode/skills/\n```\n\nOpenCode has no marketplace command for `SKILL.md` skills (its plugin\nsystem is for npm JS plugins), so a shared skills directory is the clean\npath. Skills auto-load by description.\n\n**OpenCode-compatible forks** — e.g. Xiaomi's *mimocode* — inherit this\nsupport via the same skill-discovery path; no separate packaging.\n\n### Claude Code — local development (no install)\n\n```\nclaude --plugin-dir \u003cpath-to-this-repo\u003e\n```\n\n### Direct skill clone (no plugin lifecycle)\n\n```\ngit clone https://github.com/EvolveHQ/docflow ~/.docflow-src\nln -s ~/.docflow-src/plugins/docflow/skills/* ~/.claude/skills/\n```\n\nOn Windows, copy `plugins\\docflow\\skills\\*` into\n`%USERPROFILE%\\.claude\\skills\\` instead of symlinking.\n\n## Quick start\n\nIn any repo, run:\n\n```\n/bootstrap\n```\n\nor just say *\"set up documentation-led conventions in this repo\"*,\n*\"bootstrap ADRs and a plan queue\"*, or *\"scaffold AGENTS.md and the\n_agent/ layout\"*. The skill auto-triggers on those phrasings.\n\nThe skill will:\n\n1. Detect whether the repo is fresh or existing, and state which.\n2. Ask how deep to go — **express** (one question, conservative\n   defaults, minimal footprint), **guided** (only the hard-to-reverse\n   choices: integration model, coordination mode, plan queue), or\n   **full** (all 10 assessment questions) — then ask that tier's\n   questions one at a time, with a recommended option for each. You\n   can switch depth mid-way (\"defaults from here\" / \"go deeper\"), and\n   the choice is remembered as the recommendation for next time.\n3. Summarise the resulting plan and ask for sign-off.\n4. Write (or Edit, for existing repos) the files.\n5. Commit each logical group with a Conventional Commit message.\n6. **On existing repos** — and re-runnable later to **capture a large\n   development that bypassed the process** — offer to backfill ADRs,\n   `plan/done/`, and `CONVENTIONS.md` additions from the existing code and\n   git history — drafts only, approved in batches. A reconstructed decision\n   lands at `Implemented` with a matching `plan/done`; `/audit`'s coverage\n   check surfaces undocumented work to capture.\n\n## Updating\n\nRecipients refresh installations with:\n\n```\n/plugin marketplace update evolvehq\n/plugin install docflow@evolvehq\n```\n\nSee [USAGE.md §Updating the plugin](USAGE.md#8-updating-the-plugin)\nfor the author-side flow (version bumps, release tags) and recipient\noptions including `/reload-plugins` for live sessions.\n\n## Full usage and customisation guide\n\nSee [USAGE.md](USAGE.md) for the assessment questions, what each\nanswer changes, the file-by-file output, the backfill flow, and how\nto extend or override the templates.\n\n## Layout\n\n```\ndocflow/\n  .claude-plugin/marketplace.json   # Claude Code / Cowork marketplace (-\u003e ./plugins/docflow)\n  .agents/plugins/marketplace.json  # Codex marketplace (-\u003e ./plugins/docflow)\n  package.json                      # pi manifest (pi.skills -\u003e ./plugins/docflow/skills) + npm\n  plugins/docflow/                  # the plugin — one source, every target\n    .claude-plugin/plugin.json      #   Claude Code / Cowork plugin manifest\n    .codex-plugin/plugin.json       #   Codex plugin manifest (skills -\u003e ./skills)\n    skills/                         #   the one skill source\n      bootstrap/\n        SKILL.md                    #   bootstrap: assessment + output sequence + backfill\n        templates/                  #   files the bootstrap reads and writes into target repos\n      new-adr/SKILL.md              #   lifecycle skills — operate on a bootstrapped repo,\n      new-plan/SKILL.md             #     read CONVENTIONS.md, honour its choices\n      ship-item/SKILL.md\n      add-convention/SKILL.md\n      audit/SKILL.md\n      brainstorm/SKILL.md\n      agent-wave/SKILL.md\n      rollup/SKILL.md\n  README.md\n  USAGE.md\n```\n\nOnly the `bootstrap` skill uses `plugins/docflow/skills/bootstrap/templates/`. The\nlifecycle skills act on the copies the bootstrap wrote into the target\nrepo (e.g. its `adr/0000-template.md`), so they carry no templates of\ntheir own.\n\n## License\n\nMIT. Use it, fork it, change it. If you improve a template, a PR is\nwelcome.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEvolveHQ%2Fdocflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEvolveHQ%2Fdocflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEvolveHQ%2Fdocflow/lists"}