@evolvehq/docflow 0.6.0 → 0.7.1

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,22 @@ 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 | ✅ | `codex plugin marketplace add EvolveHQ/docflow` | `$bootstrap` / `/skills` |
+| OpenCode | native | ✅ | auto-discovered, or symlink into `~/.config/opencode/skills` | auto, by description |
+
+Handy: OpenCode also reads `~/.claude/skills/` and `~/.agents/skills/`, so
+a shared skills directory can serve it alongside another agent.
 
 ### Claude Code — from this marketplace
 
@@ -80,6 +94,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 +118,39 @@ 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 install docflow
+```
+
+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
+ln -s ~/.docflow-src/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.
+
 ### Claude Code — local development (no install)
 
 ```
@@ -161,10 +215,14 @@ to extend or override the templates.
 ```
 docflow/
   .claude-plugin/
-    plugin.json          # Claude Code plugin manifest
+    plugin.json          # Claude Code / Cowork plugin manifest
     marketplace.json     # Claude Code marketplace listing (repo is its own marketplace)
+  .codex-plugin/
+    plugin.json          # Codex plugin manifest (skills -> ./skills)
+  .agents/plugins/
+    marketplace.json     # Codex marketplace listing
   package.json           # pi package manifest (pi.skills -> ./skills) + npm metadata
-  skills/
+  skills/                # the one skill source, shared by every target
     bootstrap/
       SKILL.md           # bootstrap: assessment + output sequence + backfill
       templates/         # files the bootstrap reads and writes into target repos

package/USAGE.md

@@ -5,21 +5,58 @@ what each of the 10 assessment questions actually changes in the
 output, and how to customise or extend the templates. The lifecycle
 skills are covered in §5a.
 
-For installation, see the [README](README.md).
-
-## 1. Triggering the bootstrap skill
-
-Once the plugin is installed (or `--plugin-dir`'d) into a Claude Code
-session, the skill is available in any repo. Three ways to trigger:
-
-1. **Slash command:** `/bootstrap`.
-2. **Natural language** matching the skill's description, e.g.
-   - "set up documentation-led conventions in this repo"
-   - "bootstrap ADRs and a plan queue"
-   - "scaffold AGENTS.md and the _agent/ layout"
-   - "retrofit this existing repo with the documentation conventions"
-3. **From another agent's prompt** — name the skill explicitly:
-   *"invoke the `bootstrap` skill on this repository."*
+## Install (per platform)
+
+docflow runs from **one `skills/` tree** on five coding agents. 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 | Install | Invoke |
+|-------|---------|--------|
+| **Claude Code** | `/plugin marketplace add EvolveHQ/docflow` then `/plugin install docflow@evolvehq` | `/bootstrap` |
+| **Claude Cowork** | the **same** Claude Code plugin (`/plugin marketplace add …`) — Cowork shares the plugin system | `/bootstrap` |
+| **pi** | `pi install npm:@evolvehq/docflow` (or `pi install git:github.com/EvolveHQ/docflow`) | `/skill:bootstrap` |
+| **Codex** | `codex plugin marketplace add EvolveHQ/docflow` then `codex plugin install docflow` (native plugin) | `$bootstrap` / `/skills` |
+| **OpenCode** | auto-discovers `.claude`/`.agents`/`.opencode` skills (so a Claude Code / Codex install is picked up), or symlink into `~/.config/opencode/skills` | auto, by description |
+
+Notes:
+
+- **Codex** ships a native plugin (`.codex-plugin/`), so it's a one-command
+  install like Claude Code. **OpenCode** has no marketplace command for
+  `SKILL.md` skills (its plugin system is npm JS plugins), so it relies on
+  skills-directory auto-discovery or a symlink.
+- A **shared skills directory** can serve two agents: `~/.agents/skills/`
+  is read by Codex and OpenCode; `~/.claude/skills/` by Claude Code and
+  OpenCode.
+- The scaffolded output needs no porting on any of them — it is read
+  natively wherever `AGENTS.md` is the instruction file.
+
+See the [README](README.md#install) for the full matrix, Windows paths,
+and local-development options.
+
+## 1. Triggering the skills
+
+Once docflow is installed (per the table above), the skills are available
+in any repo. Invocation differs per agent:
+
+| Agent | Slash / mention | Auto-trigger from description |
+|-------|-----------------|-------------------------------|
+| Claude Code / Cowork | `/bootstrap`, `/new-adr`, … | yes |
+| pi | `/skill:bootstrap`, `/skill:new-adr`, … | no — invoke explicitly |
+| Codex | `$bootstrap` / `/skills` | yes |
+| OpenCode | (loaded by name) | yes, by description |
+
+On agents that **auto-trigger**, natural-language matching the skill's
+description also works, e.g.:
+
+- "set up documentation-led conventions in this repo"
+- "bootstrap ADRs and a plan queue"
+- "scaffold AGENTS.md and the _agent/ layout"
+- "retrofit this existing repo with the documentation conventions"
+
+Or, on any agent, name the skill explicitly: *"invoke the `bootstrap`
+skill on this repository."*
 
 ## 2. The flow
 
@@ -164,12 +201,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 |
 |-------|------------------------------|
@@ -319,6 +377,16 @@ To remove the plugin entirely:
 /plugin uninstall docflow@evolvehq
 ```
 
+**Other agents:**
+
+- **Cowork** — same as Claude Code (`/plugin marketplace update` →
+  install).
+- **pi** — re-run `pi install npm:@evolvehq/docflow` (or the `git:` form).
+- **Codex** — `codex plugin marketplace upgrade` then `codex plugin
+  install docflow`.
+- **OpenCode** — if installed via a clone/symlink, `git pull` the clone;
+  skills reload on the next session.
+
 ### As the author (you, maintaining this repo)
 
 1. Edit a skill body (`skills/<name>/SKILL.md`), the bootstrap templates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolvehq/docflow",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "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",