@evolvehq/docflow 0.5.0 → 0.7.0

package/README.md

@@ -2,8 +2,9 @@
 
 ![docflow — ADR-driven documentation workflow](docs/preview.png)
 
-A plugin for **ADR-driven, documentation-led projects**, working on both
-the **pi** and **Claude Code** coding agents from the same skill files.
+A plugin for **ADR-driven, documentation-led projects**, working on
+**Claude Code, Claude Cowork, pi, Codex, and OpenCode** from the same
+skill files (see [Install](#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
@@ -66,9 +67,23 @@ 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).
+docflow ships from **one `skills/` tree** to five 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` |
+| Claude Cowork | native | ✅ | same Claude Code plugin | `/bootstrap` |
+| pi | native | ✅ | `pi install npm:@evolvehq/docflow` | `/skill:bootstrap` |
+| Codex | native | ✅ | copy into `~/.agents/skills/` | `$bootstrap` / `/skills` |
+| OpenCode | native | ✅ | reads `.claude`/`.agents`/`.opencode` skills | auto, by description |
+
+Handy: `~/.agents/skills/` is read by **both Codex and OpenCode**, and
+`~/.claude/skills/` by **both Claude Code and OpenCode** — so one install
+often serves two agents.
 
 ### Claude Code — from this marketplace
 
@@ -80,6 +95,13 @@ for pi).
 Invoke with `/bootstrap`, `/new-adr`, `/ship-item`, … (auto-triggers on
 matching requests too).
 
+### Claude Cowork
+
+Cowork uses the **same plugin system** as Claude Code, so install the
+docflow plugin exactly as above (`/plugin marketplace add
+EvolveHQ/docflow`, then install) — or from Anthropic's community
+marketplace once listed. No separate packaging.
+
 ### pi coding agent
 
 ```
@@ -97,6 +119,32 @@ 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)
+
+Codex reads `AGENTS.md` natively and discovers skills from `.agents/skills`.
+Copy docflow's skills into a path Codex scans:
+
+```
+# user-wide (all projects), from a clone of this repo:
+mkdir -p ~/.agents/skills && cp -r <docflow>/skills/* ~/.agents/skills/
+# or from npm:
+npm install @evolvehq/docflow
+cp -r node_modules/@evolvehq/docflow/skills/* ~/.agents/skills/
+```
+
+On Windows, copy `skills\*` into `%USERPROFILE%\.agents\skills\`. Invoke
+with `$bootstrap` / `/skills`, or just describe the task (Codex
+auto-triggers from the skill description). The structured assessment
+questions fall back to plain `A/B/C` text where there is no select tool.
+
+### OpenCode (sst)
+
+OpenCode scans `.opencode/skills/`, **`.claude/skills/`, and
+`.agents/skills/`** (project and global), so a Claude Code or Codex
+install is **picked up automatically** — or copy `skills/*` into
+`~/.config/opencode/skills/` (or per-project `.opencode/skills/`). Skills
+auto-load by description.
+
 ### Claude Code — local development (no install)
 
 ```

package/USAGE.md

@@ -164,12 +164,33 @@ The repo is now ready for ADR-driven work. Typical first steps:
 ## 5a. Lifecycle skills
 
 The manual workflow in §5 is exactly what the lifecycle skills
-automate. They all share three properties: 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.
+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):
+
+- An **opt-out gate** first: *run the assessment, or skip it?* The
+  recommended default flips on context — *run* when you invoked the skill
+  with little detail, *skip* when your request already specifies
+  everything.
+- 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 |
 |-------|------------------------------|
@@ -233,6 +254,32 @@ 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.
+
+`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.)
+
 ## 6. Customising or extending
 
 The templates are deliberately small and self-contained. To customise:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolvehq/docflow",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "ADR-driven documentation workflow: scaffold an Architecture Decision Record (ADR) catalogue, a plan/ queue, and AGENTS.md conventions into any repo, then author, queue, ship, and audit ADRs with lifecycle skills. Works with the pi coding agent and Claude Code.",
   "keywords": [
     "pi-package",

package/skills/agent-wave/SKILL.md

@@ -102,9 +102,14 @@ every merge.
 Spawn N subagents in parallel, each in an isolated worktree
 (`isolation: worktree`). Brief each with: its assigned queue item, the
 instruction to follow `_agent/prompts/autonomous.md` end-to-end for that
-one item (orient → implement → verify → integrate per the repo's model →
-ship), and to report back a structured result (item, pass/fail, HEAD or
-PR link, any blocker).
+one item (orient → implement → verify → **check before merge (G2)** →
+integrate per the repo's model → ship), and to report back a structured
+result (item, pass/fail, HEAD or PR link, any blocker). The G2 step:
+before integrating, sync onto the current `main` and run the **audit**
+skill; if the item's new ADR/plan number now clashes with what landed,
+renumber locally
+before merging. (Reservation in Step 2 makes this rare; G2 catches what
+slips through, e.g. an out-of-band ADR landing mid-wave.)
 
 ## Step 4 — Collect and checkpoint
 

package/skills/audit/SKILL.md

@@ -49,9 +49,11 @@ relevant):
 11. **Cross-worktree collisions** (mode 3, or when auditing across
     unmerged branches). These catch semantic conflicts that a
     line-level git merge cannot:
-    - **Duplicate ADR numbers** — two ADR files (across branches/
-      worktrees) claiming the same `NNNN`. Distinct from check 1, which
-      only sees one tree.
+    - **Duplicate ADR or plan/todo numbers** — two ADR files, or two
+      `plan/todo/` items, (across branches/worktrees) claiming the same
+      `NNNN`. Distinct from check 1, which only sees one tree. This is the
+      collision the concurrency guardrails (G2 pre-merge / G3 gate) guard
+      against; flag it so the later author renumbers.
     - **Duplicate plan ownership** — two `plan/todo/` items naming the
       same owning ADR for the same scope, i.e. two worktrees building
       the same thing.

package/skills/bootstrap/SKILL.md

@@ -240,8 +240,12 @@ template, fill its placeholders from the assessment answers, then
 write it into the repo.
 
 1. `CONVENTIONS.md` — from `templates/CONVENTIONS.md`. Spec other files
-   reference.
-2. `AGENTS.md` — from `templates/AGENTS.md`.
+   reference. Include the **§Concurrency Guardrails** section only if Q5
+   is mode 2/3 **or** Q4b is PR-based; omit it for single-agent
+   direct-to-main repos (no numbering race).
+2. `AGENTS.md` — from `templates/AGENTS.md`. Include the concurrency
+   guardrails hard-rule bullet (G2/G3) under the same condition as the
+   CONVENTIONS section above; omit otherwise.
 3. `CLAUDE.md` — from `templates/CLAUDE.md` (single line `@AGENTS.md`).
 4. `adr/0000-template.md` — from `templates/adr-capability.md`.
 5. `adr/NNNN-template.md` — from `templates/adr-technology.md`, only if

package/skills/bootstrap/templates/AGENTS.md

@@ -118,6 +118,18 @@ Coordination rules:
   Add your row when you start, remove it when the worktree closes.
 -->
 
+<!-- Concurrency guardrails hard rule — bootstrap INCLUDES this bullet
+ONLY for multi-agent (mode 2/3) OR PR-based repos (omit for single-agent
+direct-to-main). See CONVENTIONS.md §Concurrency Guardrails.
+
+- **Before integrating, check for number collisions (G2/G3).** Sync onto
+  the current `main` and run `/audit`; if your ADR or `plan/todo` number
+  now clashes with what landed on `main`, renumber locally before
+  integrating. The single-threaded merge gate rejects a duplicate as the
+  backstop. Numbers are immutable once merged. (G1 — landing the ADR
+  before implementation — is recommended guidance, in CONVENTIONS.md.)
+-->
+
 ## Plan folder
 
 - A pending item gets a `plan/todo/NNNN-<slug>.md` file BEFORE work

package/skills/bootstrap/templates/CONVENTIONS.md

@@ -139,6 +139,34 @@ When a `plan/todo/` item ships, the file moves to `plan/done/` AND the
 owning ADR(s)' `status:` advances from `Accepted` to `Implemented`.
 `INDEX.md` is regenerated to match.
 
+<!-- Concurrency Guardrails — bootstrap INCLUDES this section (uncommented)
+ONLY for multi-agent (mode 2/3) OR PR-based repos. Single-agent
+direct-to-main repos have no numbering race by construction and OMIT it.
+Adapt "integrate" to the integration model (PR merge / ff-push / pull
+before commit in a shared checkout).
+
+## Concurrency Guardrails
+
+ADR and `plan/todo` numbers are contiguous and assigned at authoring
+time, so concurrent branches can pick the same next number. These
+guardrails keep numbering collision-free **without changing the identity
+scheme** — the number stays the stable cross-reference key, immutable
+once merged:
+
+- **G1 — decide before do (recommended).** Prefer to merge an ADR and its
+  plan items to `main` before implementation work begins, so work
+  branches start from a `main` that already carries the numbered ADR.
+- **G2 — check before merge.** Before integrating, sync onto the current
+  `main` (`git fetch` + rebase, or pull in a shared checkout) and run
+  `/audit`. If your ADR number or `plan/todo` slot now clashes with what
+  landed on `main`, renumber locally **before** integrating — a trivial,
+  local change (a new ADR/plan names its own number only in its own file
+  and `INDEX.md`).
+- **G3 — gate backstop.** Integration is single-threaded; it rejects a
+  duplicate number as the last line of defence, and the later author
+  renumbers.
+-->
+
 ## Audit Trail Policy
 
 Every substantive change to an Accepted ADR appends a new row to its

package/skills/bootstrap/templates/_agent-prompts-autonomous.md

@@ -42,6 +42,18 @@ footer required on any commit touching an ADR.
 
 ## Step 6 — Integrate
 
+<!-- Concurrency guardrail G2 (multi-agent / PR-based repos) — keep this
+step if CONVENTIONS.md has a §Concurrency Guardrails section; drop it for
+single-agent direct-to-main repos:
+
+- **Check before merge (G2).** Sync onto the current `main`
+  (`git fetch` + rebase, or pull in a shared checkout) and run `/audit`.
+  If your new ADR or `plan/todo` number now clashes with what landed on
+  `main`, renumber locally — in your ADR/plan file and `INDEX.md` —
+  before integrating. The merge gate (G3) rejects a duplicate as the
+  backstop.
+-->
+
 <!-- Integration model per Q4b — keep ONE of the two blocks below,
 delete the other. -->