flow-workflows 0.66.0 → 0.67.0

package/README.md

@@ -1,7 +1,7 @@
 # flow-workflows
 
 Guided `feat` / `bug` workflows for terminal coding agents: a ticket reaches an open MR/PR through explicit, reviewable phases, not one big prompt.
-For developers running Claude Code (or opencode, Gemini CLI, Codex CLI, Hermes Agent) on real repos with tickets, reviewers and a deploy.
+For developers running Claude Code (or zcode, opencode, Gemini CLI, Codex CLI, Hermes Agent) on real repos with tickets, reviewers and a deploy.
 You get named phases, an artifact on disk after each one, hard gates the agent never crosses alone, and an autonomy dial from "ask me everything" to "run it and record what you decided".
 
 ## Quickstart
@@ -23,6 +23,14 @@ codex plugin add flow@flow-plugins
 # then, in a new session: $flow:init · $flow:next
 ```
 
+**zcode** — same plugin, from its own marketplace
+
+```bash
+zcode plugins marketplace add mashware/flow-workflows
+zcode plugins install flow@flow-plugins
+# then, in a new session: /flow:init · /flow:next
+```
+
 **opencode, Gemini CLI, Hermes Agent** — one command, nothing to clone
 
 ```bash
@@ -194,7 +202,7 @@ Artifacts are **hand-editable**: rewrite `03-design.md` and the next phase respe
 ## Configuration: base plus harness overlay
 
 `FLOW.md` at the repo root is the shared base. `FLOW.claude.md`, `FLOW.codex.md`,
-`FLOW.opencode.md`, `FLOW.gemini.md`, or `FLOW.hermes.md` can sparsely override values for the product executing the
+`FLOW.opencode.md`, `FLOW.gemini.md`, `FLOW.hermes.md`, or `FLOW.zcode.md` can sparsely override values for the product executing the
 command. Existing repos with only `FLOW.md` behave exactly as before; anything effectively empty
 is auto-detected or asked for.
 
@@ -269,7 +277,12 @@ compaction point — selective, on disk and reversible.
 → [PHILOSOPHY](docs/PHILOSOPHY.md#nothing-here-asks-you-to-compact)
 
 Cost figures in these docs are estimates, not measurements: the flow reports how many agents a
-command launched, not how many tokens they spent.
+command launched, not how many tokens they spent. **Quality used to be in the same position and no
+longer is, for one command.** `/flow:feat:review` has a bench —
+[`plugins/flow/evals/`](plugins/flow/evals/README.md) — that runs it over fixtures whose outcome is
+known: a defect seeded at a known `file:line` the review has to raise, and a clean diff where any
+blocker it reports is a false positive. Every other phase is still argued from judgement, and the
+design decisions inside `review` itself were too, until there was something to check them against.
 
 ## Other harnesses
 
@@ -279,6 +292,7 @@ The same commands, in each harness's own shape. Only the invocation syntax diffe
 |---|---|---|
 | **Codex CLI** | `codex plugin add flow@flow-plugins` (see [Quickstart](#quickstart)) | `$flow:feat-start` |
 | **Codex CLI**, one repo only | `npx flow-workflows install codex project` → `.agents/skills/` | `$flow-feat-start` |
+| **zcode** | `zcode plugins install flow@flow-plugins` (see [Quickstart](#quickstart)) | `/flow:feat:start` |
 | **opencode** | `npx flow-workflows install opencode` | `/flow-feat-start` |
 | **Gemini CLI** | `npx flow-workflows install gemini` | `/flow:feat:start` |
 | **Hermes Agent** | `npx flow-workflows install hermes` | `/flow-feat-start` |
@@ -288,6 +302,11 @@ dropped upstream does not linger. `npx flow-workflows check` compares what your
 against the newest release. From a clone, `adapters/install.sh <harness> [project]` does the same
 thing without Node; the preflight installs both ways and fails if the results differ by one byte.
 
+**zcode** reads this plugin package directly and names a command after its path, with no plugin
+prefix — so the `/flow:`-prefixed set it installs is a generated mirror living beside the Claude
+one, and the plugin's own pages also show up there unprefixed (`/feat:start`, `/init`, …). Those
+name Claude's overlay, so type the `/flow:` names.
+
 The mirrors are **generated** from the plugin commands by `script/adapter-build.py` and checked mechanically on every preflight (format, prefix, cited paths, install location).
 They have **not** been executed end to end in those harnesses — validate as you use them. → [adapters/README](adapters/README.md)
 
@@ -314,6 +333,7 @@ flow-workflows/
 ├── .github/           preflight CI · issue forms · PR template
 ├── plugins/flow/
 │   ├── commands/      feat/ bug/ work/ + next, init, doctor, news
+│   ├── codex-skills/ · zcode-commands/   # generated mirrors for the two other plugin hosts
 │   ├── skills/flow-core/             # shared rules, loaded once per session
 │   ├── hooks/         push guard · update notice · where-you-left-off notice
 │   └── examples/       FLOW.template.md · symfony/ (a worked example, never loaded)
@@ -335,9 +355,10 @@ bash script/tests/push-guard.sh      # the push guard's cases
 bash script/tests/notify-update.sh   # the update-notice hook's cases
 bash script/tests/session-start.sh   # the where-you-left-off hook's cases
 bash script/tests/review-unwrap.sh   # the answer shapes `flow review` has to unwrap
+bash script/tests/bench-compare.sh   # the reader that compares two runs of the review bench
 ```
 
-CI runs the same six on every PR. The preflight refuses what has shipped broken before: an empty tracked file, unparsable JSON or TOML, a manifest version out of step with `CHANGELOG.md`, a hook without its executable bit, a stale or unusable mirror. → [RELEASING](RELEASING.md)
+CI runs the same seven on every PR. The preflight refuses what has shipped broken before: an empty tracked file, unparsable JSON or TOML, a manifest version out of step with `CHANGELOG.md`, a hook without its executable bit, a stale or unusable mirror. → [RELEASING](RELEASING.md)
 
 ## What it does not ship (on purpose)
 

package/adapters/README.md

@@ -6,8 +6,9 @@ The `flow` plugin (in `../plugins/flow`) is for **Claude Code**. These adapters
 rules in `../plugins/flow/skills/flow-core/SKILL.md`, and writes every file under
 `opencode/commands/`, `codex/skills/`, `gemini/commands/flow/`, `hermes/skills/` plus one
 `<harness>/CORE.md` each —
-and `../plugins/flow/codex-skills/`, the same Codex skills packaged inside the plugin so
-`codex plugin add` installs them (see `codex/README.md`).
+and the two mirrors that live inside the plugin package itself: `../plugins/flow/codex-skills/`,
+the same Codex skills so `codex plugin add` installs them (see `codex/README.md`), and
+`../plugins/flow/zcode-commands/`, the `/flow:`-prefixed set zcode reads (see the zcode row below).
 The **logic and prose are the plugin's, verbatim** — only the wrapper changes.
 
 | Harness | Commands | Subagents | MCP | Autopilot watch |
@@ -17,6 +18,7 @@ The **logic and prose are the plugin's, verbatim** — only the wrapper changes.
 | **Codex CLI** | `skills/*/SKILL.md` (`$flow-feat-start`) | `[agents.*]` in `config.toml` | `[mcp_servers.*]` | cron + `codex exec` |
 | **Codex CLI, packaged** | `plugins/flow/codex-skills/` (`$flow:feat-start`) | same | same | same |
 | **Hermes Agent** | `skills/*/SKILL.md` (`/flow-feat-start`) | `delegate_task`, built from the prompt | `config.yaml` `mcp_servers` | **native** `/cron add` |
+| **zcode, packaged** | `plugins/flow/zcode-commands/flow/**` (`/flow:feat:start`) | `Agent` + `subagent_type`, as in Claude Code | `mcp.servers` in `~/.zcode/cli/config.json` | **native** `ScheduleWakeup` |
 
 ## What the generator changes per harness
 
@@ -30,7 +32,13 @@ Only the mechanics, and only these:
   Codex plugin package (Codex namespaces a plugin's skills), `/flow:feat:build` for Gemini. Hermes
   invokes its skills with a slash, so it shares opencode's `/flow-feat-build`: the file is shaped
   like Codex's, the prefix is opencode's.
-- **`$ARGUMENTS`** → `{{args}}` for Gemini.
+- **`$ARGUMENTS`** → `{{args}}` for Gemini. zcode reads `$ARGUMENTS`, like Claude Code.
+- **Nothing at all, for zcode** — it reads this plugin's own format and exposes the same
+  primitives under the same names, so its mirror is the Claude page with the overlay flag changed
+  to `--harness zcode` and one `flow/` folder above the command tree. That folder is the whole
+  trick: zcode names a command after its path under the root it was found in and adds no plugin
+  prefix, so `feat/start.md` on its own would be `/feat:start` — colliding with zcode's built-ins
+  (`/init`, `/doctor`) and with the user's own commands.
 - **The CORE pointer** — the plugin's `flow:flow-core` skill and `${CLAUDE_PLUGIN_ROOT}` become
   `~/.claude/flow/CORE.<tool>.md`, the file `install.sh` places there. In the Codex package they stay
   a skill (`$flow:flow-core`) and a relative root (`../..`), because there both actually exist.

package/adapters/codex/CORE.md

@@ -17,7 +17,7 @@ Every `$flow-*` command assumes these rules. They are stated once, here, so a co
 carries what is specific to its phase. Read this once per session; a command that says "load
 `flow-core`" means this file.
 
-**This file belongs to flow `0.66.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.67.0`.** Compare it once, at the start of the session, against
 `version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
 is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
 — which is exactly what happens when a branch or a release candidate is loaded over an installed
@@ -38,10 +38,14 @@ a command relies on is simply absent in that session, and nothing else will repo
   them. **Name the files this listing found the first time a phase reports any configured value**,
   so a missed overlay is visible in the artifact rather than invisible everywhere.
 - Read `FLOW.md` at the repo root as the base, then the optional overlay for the harness running
-  this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or
-  `FLOW.hermes.md`. The
+  this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`,
+  `FLOW.hermes.md`, or `FLOW.zcode.md`. The
   harness is the product executing the command, never guessed from a model name. An overlay is
-  valid without a base file; unknown `FLOW.*.md` names are ignored. Throughout every command,
+  valid without a base file; unknown `FLOW.*.md` names are ignored. **A page can outlive the product it
+  was written for**: zcode reads the plugin's Claude pages as well as its own `/flow:`-prefixed
+  mirror of them, so a `claude` in a path or in a `--harness` flag records where the page was
+  written, never who is running it. On zcode the overlay is `FLOW.zcode.md` and the flag is
+  `--harness zcode`, whichever of the two pages you were handed. Throughout every command,
   **"FLOW.md" means this effective merged configuration** unless the command explicitly names a
   file it will edit.
 - **"The repo root" is the main checkout's, not the worktree's.** With `git.worktree` set, every

package/adapters/codex/skills/flow-init/SKILL.md

@@ -20,9 +20,10 @@ description: "Assistant that generates FLOW.md and its optional harness overlay
 
 Creates or updates the effective FLOW configuration at the repo root: shared values in `FLOW.md`
 and optional harness-owned values in the active `FLOW.<harness>.md`. The active filename is
-`FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or `FLOW.hermes.md`;
-identify it from the
-product executing this command, never from the selected model. Every other `$flow-*` command reads
+`FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, `FLOW.hermes.md`, or
+`FLOW.zcode.md`; identify it from the
+product executing this command, never from the selected model (zcode runs the Claude pages too, so
+the page you are reading does not name the harness). Every other `$flow-*` command reads
 the base and then that overlay. The user answers the **minimum**: what the repo can tell is
 auto-detected and only confirmed.
 

package/adapters/codex/skills/flow-work-README/SKILL.md

@@ -25,7 +25,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - `FLOW.md` at the repo root is the shared base: tracker, branch and MR/PR conventions, quality
   commands, code conventions, and observability profile.
 - The active `FLOW.<harness>.md` is an optional sparse overlay (`claude`, `codex`, `opencode`,
-  `gemini`, or `hermes`) for model names, agents, skills, orchestration, knowledge tools, or any other value that
+  `gemini`, `hermes`, or `zcode`) for model names, agents, skills, orchestration, knowledge tools, or any other value that
   differs on that harness. Every command reads the base and then the active overlay in step 0;
   existing repos with only `FLOW.md` behave exactly as before.
 - An overlay key replaces the base even when explicitly empty; an absent key inherits it. Lists

package/adapters/gemini/CORE.md

@@ -16,7 +16,7 @@ Every `/flow:*` command assumes these rules. They are stated once, here, so a co
 carries what is specific to its phase. Read this once per session; a command that says "load
 `flow-core`" means this file.
 
-**This file belongs to flow `0.66.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.67.0`.** Compare it once, at the start of the session, against
 `version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
 is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
 — which is exactly what happens when a branch or a release candidate is loaded over an installed
@@ -37,10 +37,14 @@ a command relies on is simply absent in that session, and nothing else will repo
   them. **Name the files this listing found the first time a phase reports any configured value**,
   so a missed overlay is visible in the artifact rather than invisible everywhere.
 - Read `FLOW.md` at the repo root as the base, then the optional overlay for the harness running
-  this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or
-  `FLOW.hermes.md`. The
+  this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`,
+  `FLOW.hermes.md`, or `FLOW.zcode.md`. The
   harness is the product executing the command, never guessed from a model name. An overlay is
-  valid without a base file; unknown `FLOW.*.md` names are ignored. Throughout every command,
+  valid without a base file; unknown `FLOW.*.md` names are ignored. **A page can outlive the product it
+  was written for**: zcode reads the plugin's Claude pages as well as its own `/flow:`-prefixed
+  mirror of them, so a `claude` in a path or in a `--harness` flag records where the page was
+  written, never who is running it. On zcode the overlay is `FLOW.zcode.md` and the flag is
+  `--harness zcode`, whichever of the two pages you were handed. Throughout every command,
   **"FLOW.md" means this effective merged configuration** unless the command explicitly names a
   file it will edit.
 - **"The repo root" is the main checkout's, not the worktree's.** With `git.worktree` set, every

package/adapters/gemini/commands/flow/init.toml

@@ -16,9 +16,10 @@ prompt = """
 
 Creates or updates the effective FLOW configuration at the repo root: shared values in `FLOW.md`
 and optional harness-owned values in the active `FLOW.<harness>.md`. The active filename is
-`FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or `FLOW.hermes.md`;
-identify it from the
-product executing this command, never from the selected model. Every other `/flow:*` command reads
+`FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, `FLOW.hermes.md`, or
+`FLOW.zcode.md`; identify it from the
+product executing this command, never from the selected model (zcode runs the Claude pages too, so
+the page you are reading does not name the harness). Every other `/flow:*` command reads
 the base and then that overlay. The user answers the **minimum**: what the repo can tell is
 auto-detected and only confirmed.
 

package/adapters/gemini/commands/flow/work/README.toml

@@ -21,7 +21,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - `FLOW.md` at the repo root is the shared base: tracker, branch and MR/PR conventions, quality
   commands, code conventions, and observability profile.
 - The active `FLOW.<harness>.md` is an optional sparse overlay (`claude`, `codex`, `opencode`,
-  `gemini`, or `hermes`) for model names, agents, skills, orchestration, knowledge tools, or any other value that
+  `gemini`, `hermes`, or `zcode`) for model names, agents, skills, orchestration, knowledge tools, or any other value that
   differs on that harness. Every command reads the base and then the active overlay in step 0;
   existing repos with only `FLOW.md` behave exactly as before.
 - An overlay key replaces the base even when explicitly empty; an absent key inherits it. Lists

package/adapters/hermes/CORE.md

@@ -17,7 +17,7 @@ Every `/flow-*` command assumes these rules. They are stated once, here, so a co
 carries what is specific to its phase. Read this once per session; a command that says "load
 `flow-core`" means this file.
 
-**This file belongs to flow `0.66.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.67.0`.** Compare it once, at the start of the session, against
 `version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
 is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
 — which is exactly what happens when a branch or a release candidate is loaded over an installed
@@ -38,10 +38,14 @@ a command relies on is simply absent in that session, and nothing else will repo
   them. **Name the files this listing found the first time a phase reports any configured value**,
   so a missed overlay is visible in the artifact rather than invisible everywhere.
 - Read `FLOW.md` at the repo root as the base, then the optional overlay for the harness running
-  this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or
-  `FLOW.hermes.md`. The
+  this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`,
+  `FLOW.hermes.md`, or `FLOW.zcode.md`. The
   harness is the product executing the command, never guessed from a model name. An overlay is
-  valid without a base file; unknown `FLOW.*.md` names are ignored. Throughout every command,
+  valid without a base file; unknown `FLOW.*.md` names are ignored. **A page can outlive the product it
+  was written for**: zcode reads the plugin's Claude pages as well as its own `/flow:`-prefixed
+  mirror of them, so a `claude` in a path or in a `--harness` flag records where the page was
+  written, never who is running it. On zcode the overlay is `FLOW.zcode.md` and the flag is
+  `--harness zcode`, whichever of the two pages you were handed. Throughout every command,
   **"FLOW.md" means this effective merged configuration** unless the command explicitly names a
   file it will edit.
 - **"The repo root" is the main checkout's, not the worktree's.** With `git.worktree` set, every

package/adapters/hermes/skills/flow-init/SKILL.md

@@ -20,9 +20,10 @@ description: "Assistant that generates FLOW.md and its optional harness overlay
 
 Creates or updates the effective FLOW configuration at the repo root: shared values in `FLOW.md`
 and optional harness-owned values in the active `FLOW.<harness>.md`. The active filename is
-`FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or `FLOW.hermes.md`;
-identify it from the
-product executing this command, never from the selected model. Every other `/flow-*` command reads
+`FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, `FLOW.hermes.md`, or
+`FLOW.zcode.md`; identify it from the
+product executing this command, never from the selected model (zcode runs the Claude pages too, so
+the page you are reading does not name the harness). Every other `/flow-*` command reads
 the base and then that overlay. The user answers the **minimum**: what the repo can tell is
 auto-detected and only confirmed.
 

package/adapters/hermes/skills/flow-work-README/SKILL.md

@@ -25,7 +25,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - `FLOW.md` at the repo root is the shared base: tracker, branch and MR/PR conventions, quality
   commands, code conventions, and observability profile.
 - The active `FLOW.<harness>.md` is an optional sparse overlay (`claude`, `codex`, `opencode`,
-  `gemini`, or `hermes`) for model names, agents, skills, orchestration, knowledge tools, or any other value that
+  `gemini`, `hermes`, or `zcode`) for model names, agents, skills, orchestration, knowledge tools, or any other value that
   differs on that harness. Every command reads the base and then the active overlay in step 0;
   existing repos with only `FLOW.md` behave exactly as before.
 - An overlay key replaces the base even when explicitly empty; an absent key inherits it. Lists

package/adapters/opencode/CORE.md

@@ -16,7 +16,7 @@ Every `/flow-*` command assumes these rules. They are stated once, here, so a co
 carries what is specific to its phase. Read this once per session; a command that says "load
 `flow-core`" means this file.
 
-**This file belongs to flow `0.66.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.67.0`.** Compare it once, at the start of the session, against
 `version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
 is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
 — which is exactly what happens when a branch or a release candidate is loaded over an installed
@@ -37,10 +37,14 @@ a command relies on is simply absent in that session, and nothing else will repo
   them. **Name the files this listing found the first time a phase reports any configured value**,
   so a missed overlay is visible in the artifact rather than invisible everywhere.
 - Read `FLOW.md` at the repo root as the base, then the optional overlay for the harness running
-  this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or
-  `FLOW.hermes.md`. The
+  this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`,
+  `FLOW.hermes.md`, or `FLOW.zcode.md`. The
   harness is the product executing the command, never guessed from a model name. An overlay is
-  valid without a base file; unknown `FLOW.*.md` names are ignored. Throughout every command,
+  valid without a base file; unknown `FLOW.*.md` names are ignored. **A page can outlive the product it
+  was written for**: zcode reads the plugin's Claude pages as well as its own `/flow:`-prefixed
+  mirror of them, so a `claude` in a path or in a `--harness` flag records where the page was
+  written, never who is running it. On zcode the overlay is `FLOW.zcode.md` and the flag is
+  `--harness zcode`, whichever of the two pages you were handed. Throughout every command,
   **"FLOW.md" means this effective merged configuration** unless the command explicitly names a
   file it will edit.
 - **"The repo root" is the main checkout's, not the worktree's.** With `git.worktree` set, every

package/adapters/opencode/commands/flow-init.md

@@ -18,9 +18,10 @@ description: Assistant that generates FLOW.md and its optional harness overlay (
 
 Creates or updates the effective FLOW configuration at the repo root: shared values in `FLOW.md`
 and optional harness-owned values in the active `FLOW.<harness>.md`. The active filename is
-`FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or `FLOW.hermes.md`;
-identify it from the
-product executing this command, never from the selected model. Every other `/flow-*` command reads
+`FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, `FLOW.hermes.md`, or
+`FLOW.zcode.md`; identify it from the
+product executing this command, never from the selected model (zcode runs the Claude pages too, so
+the page you are reading does not name the harness). Every other `/flow-*` command reads
 the base and then that overlay. The user answers the **minimum**: what the repo can tell is
 auto-detected and only confirmed.
 

package/adapters/opencode/commands/flow-work-README.md

@@ -23,7 +23,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - `FLOW.md` at the repo root is the shared base: tracker, branch and MR/PR conventions, quality
   commands, code conventions, and observability profile.
 - The active `FLOW.<harness>.md` is an optional sparse overlay (`claude`, `codex`, `opencode`,
-  `gemini`, or `hermes`) for model names, agents, skills, orchestration, knowledge tools, or any other value that
+  `gemini`, `hermes`, or `zcode`) for model names, agents, skills, orchestration, knowledge tools, or any other value that
   differs on that harness. Every command reads the base and then the active overlay in step 0;
   existing repos with only `FLOW.md` behave exactly as before.
 - An overlay key replaces the base even when explicitly empty; an absent key inherits it. Lists

package/bin/cli.mjs

@@ -158,6 +158,17 @@ function claude() {
   console.log('Codex has its own too: codex plugin marketplace add https://github.com/mashware/flow-workflows.git')
 }
 
+function zcode() {
+  console.log('zcode reads this plugin package directly, from its own marketplace, not from npm:')
+  console.log()
+  console.log('  zcode plugins marketplace add mashware/flow-workflows')
+  console.log('  zcode plugins install flow@flow-plugins')
+  console.log()
+  console.log('Then /flow:init in your repo. Updates arrive through `zcode plugins update flow`.')
+  console.log('Type the /flow:-prefixed commands: zcode also exposes the plugin\'s Claude pages')
+  console.log('unprefixed (/feat:start, /init, …), and those carry --harness claude.')
+}
+
 function check() {
   const pkg = version()
   console.log(`this package:  v${pkg}`)
@@ -276,7 +287,7 @@ const configRoot = (repo) => rootHolding(repo, 'FLOW.md')
 // The overlay names flow-core §0 recognises. A `--harness` outside this set reads no
 // overlay and looks exactly like a repo that has none, so it stops the run instead: a typo
 // here is worth one error message and never worth a review round nobody can trust.
-const OVERLAY_HARNESSES = ['claude', 'codex', 'gemini', 'hermes', 'opencode']
+const OVERLAY_HARNESSES = ['claude', 'codex', 'gemini', 'hermes', 'opencode', 'zcode']
 
 // Every overlay sitting next to the base, whether or not this run reads one.
 function overlaysPresent(root) {
@@ -1107,8 +1118,9 @@ function usage() {
 Harnesses: ${Object.keys(HARNESSES).join(' · ')}
   "project" installs into the current repo instead of your user folder.
 
-Claude Code and Codex CLI have their own marketplaces:
+Claude Code, Codex CLI and zcode have their own marketplaces:
   npx flow-workflows install claude    shows how
+  npx flow-workflows install zcode     shows how
 
 "bundle" prints one context pack for the current branch — worklist, diff, the changed
   files in full, and the work's handoff — so a phase reads it in one call instead of
@@ -1161,10 +1173,11 @@ else if (cmd === 'cost') cost(process.argv.slice(3))
 else if (cmd === 'review') review(process.argv.slice(3)).catch((e) => { console.error(`flow review: ${e.message}`); process.exit(1) })
 else if (cmd === 'check') check()
 else if (cmd === 'install' && tool === 'claude') claude()
+else if (cmd === 'install' && tool === 'zcode') zcode()
 else if (cmd === 'install' && HARNESSES[tool]) install(tool, scope === 'project' ? 'project' : 'global')
 else if (cmd === 'install') {
   console.error(`Unknown harness: ${tool ?? '(none given)'}`)
-  console.error(`Expected one of: ${Object.keys(HARNESSES).join(', ')}, claude`)
+  console.error(`Expected one of: ${Object.keys(HARNESSES).join(', ')}, claude, zcode`)
   process.exit(1)
 } else if (cmd === '--version' || cmd === '-v') console.log(version())
 else if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') usage()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-workflows",
-  "version": "0.66.0",
+  "version": "0.67.0",
   "description": "Guided feat/bug workflows (start→ship), post-deploy monitoring and multi-agent code review, stack-agnostic. Each repo uses a shared FLOW.md plus optional harness overlay.",
   "type": "module",
   "bin": {
@@ -23,6 +23,7 @@
     "gemini-cli",
     "codex",
     "hermes",
+    "zcode",
     "coding-agent",
     "feature-flow",
     "bug-flow"

package/plugins/flow/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "flow",
   "displayName": "Flow — guided dev workflows",
   "description": "Guided feat/bug workflows (start→ship), post-deploy monitoring and multi-agent code review, stack-agnostic. Each repo uses a shared FLOW.md plus optional harness overlay.",
-  "version": "0.66.0",
+  "version": "0.67.0",
   "author": {
     "name": "Alberto Vioque",
     "email": "mashware@gmail.com"
@@ -17,5 +17,8 @@
     "git",
     "feature-flow",
     "bug-flow"
-  ]
+  ],
+  "experimental": {
+    "evals": "evals"
+  }
 }

package/plugins/flow/CHANGELOG.md

@@ -5,6 +5,90 @@ plugin and is what `/flow:news` reads to show you what changed since your previo
 
 The canonical, richest notes live in the [GitHub Releases](https://github.com/mashware/flow-workflows/releases).
 
+## v0.67.0 — Every layer of the review was argued from judgement, and none was ever checked  ·  2026-09-21
+
+**In short**
+- **The review now has a bench.** `plugins/flow/evals/` runs `/flow:feat:review` over fixtures whose outcome is known before the review starts, and scores what came back: eight cases, five with a defect seeded at a known `file:line` the review has to raise, three with a clean diff where any blocker it reports is a false positive.
+- **The seeded defects come from this repository's own history**, not from imagination — a value recorded after the mutation instead of before, a failing call reported as a clean result, a filter that drops the item it exists to carry, several writers on one shared key, a threshold that is code in one place and a literal in another. A defect we invent is a defect shaped like something we were already looking for.
+- **Deterministic graders carry the score.** No judge model decides anything: a judge introduces the variance the bench exists to measure, and it changes the measuring stick exactly when the model changes. The `llm` grader is not used, and the two artifact checks that only the plugin can pass are marked as indicators outside the score, so the no-plugin arm stays comparable.
+- **A difference inside the base's own range is not a difference.** `script/bench-compare.py` reads two runs, reports the **median** of each case rather than the mean the summary prints, and prints `—` for anything that lands inside the range the base's own runs spanned. A bench that reports every wobble as a regression is one everybody learns to ignore.
+- **zcode is a harness the plugin knows.** It reads this same plugin package, so the commands were already there — but under names that collide with its built-ins, and resolving Claude Code's overlay. It now has its own `/flow:`-prefixed command set generated into the package, and `FLOW.zcode.md` is a recognised overlay everywhere, the CLI included.
+- **Baselines are versioned and committed**, one per plugin version and model, under `evals/baselines/`. When a new model ships, the suite runs with `--model` and everything else frozen — which is the only way to find out that a layer which used to help has started costing turns.
+
+Nothing in this repository could answer whether a change to `review` found more defects, fewer, or
+the same ones more expensively. `script/check.py` proves the adapters match their sources byte for
+byte and that a cited path exists; the hook tests pin behaviour that is deterministic by
+construction. All of it checks **shape**, and the README already conceded half the gap — *"Cost
+figures in these docs are estimates, not measurements"* — while saying nothing at all about the
+other half.
+
+That gap was not abstract. The completeness sweep, the data-access duel, the idiom audit, the
+150/600/1500 thresholds, the sensitive-surface bump: every one of them was argued from judgement,
+and every one is now remembered as conviction. v0.66.0 wrote down the rule for retiring a pass —
+no exclusive surviving finding across twenty reviews and it comes out of the command — and there
+was no way to run twenty comparable reviews to trigger it. The same release made the tier
+computable and nothing could say whether the tier it computed was the right one. Both shipped
+instrumentation with no bench to read it on.
+
+**A case is a repository, not a prompt.** Each one scaffolds a small tree, a flow work parked at
+`build`, and a branch whose diff has a known outcome; the flow CLI is installed into the fixture
+from this checkout, so the round takes the CLI path and not its documented fallback. The prompt
+opens with the literal `/flow:feat:review` and then states the task in plain words — both halves
+are load-bearing. Inside an eval run the agent cannot invoke a plugin command on its own: asked in
+prose to use the review command it reads files instead and never reaches it, so only a prompt that
+*is* the command gets there. The plain-words half is what the no-plugin arm answers, which is what
+makes `Δ` mean anything.
+
+**Both kinds of case are mandatory**, and the second kind is the one that is easy to skip. Without
+a clean diff in the suite the score rewards the noisiest review there is, and noise is what makes
+people stop reading reviews at all. One of the three sits on a path `quality.sensitive_paths` names
+and moves a log level and nothing else — which is the judgement §2.0 says a CLI cannot make, checked
+for the first time.
+
+The release preflight gains the checks that keep the bench runnable — every case has its scaffold,
+its prompt and its graders, the prompt still opens with the command under test, and the suite still
+holds both kinds. Running it is deliberately **not** wired into `publish.yml`: that workflow puts
+the package on npm in minutes, and ten cases at three runs across two arms is sixty full agent
+sessions. `.github/workflows/bench.yml` runs at the release and on demand, and says so plainly when
+the repository has no credential for it rather than standing red.
+
+**What the first run said**, recorded here because a bench whose first result is left out of the
+notes is a bench nobody will believe later. 8 cases × 3 runs × 2 arms, 48 sessions, 52 minutes,
+$47.27, threshold 0.5, the CLI's default model: every case at or above the threshold, suite score
+0.96, and **mean Δ against the no-plugin arm of −0.04**. Seven of the eight cases scored 1.00 in
+both arms; the eighth (`seeded-divergent-threshold`) scored 0.67 with the plugin and 1.00 without,
+one run in three having missed it. The with-arm cost $1.57 and 4.5 minutes per run against $0.40
+and 1.9 minutes — **3.9× for the same findings**.
+
+The honest reading is about the fixtures before it is about the command, and the reason is
+mechanical: every case is tagged `xs`, and **at XS the command runs the built-in `code-review`
+alone** — no panel, and §3.5's sweep is M/L only. The layers this bench exists to judge did not run
+once in those 48 sessions, so the two arms were doing nearly the same work. Eight single-file diffs
+with a docstring stating the contract the code breaks is also a defect an unguided review finds,
+which puts both arms on the ceiling, where a delta can only fall.
+
+The second tier is written down rather than written: `deep` cases, M-sized, with a populated
+reviewer roster, a defect split across files and its contract in `03-design.md`. They cost roughly
+what they exercise, so the suite splits by tag and each tier keeps its own baseline.
+
+Nothing is retired and no threshold moves here. The first run establishes the base; it does not
+judge anything.
+
+**zcode**, separately. It reads Claude-format plugin packages — `.zcode-plugin/plugin.json` first,
+then `.claude-plugin/plugin.json` — and exposes the same primitives under the same names, so
+installing flow from the marketplace worked on the first try and hid two things. A command is named
+after its path with no plugin prefix, so the set arrived as `/feat:start`, `/next`, `/init` and
+`/doctor` — the last two losing to zcode's own built-ins. And every `flow-workflows` call in the
+pages carries `--harness claude`, which on zcode reads another product's overlay and reports, in the
+pack's own header, that an overlay was read.
+
+Both are fixed by generation, not by prose: `plugins/flow/zcode-commands/flow/**` is the same
+generator's fifth target, the `flow/` folder is what makes zcode name them `/flow:feat:start`, and
+the flag is substituted like it is for every other mirror. `FLOW.zcode.md` joins the overlay names
+in flow-core, `init`, the template and the CLI — where an unknown `--harness` has always stopped
+the run rather than silently reading the base. The plugin's own Claude pages still show up
+unprefixed in zcode, so both the mirror's legend and the docs say to type the `/flow:` names.
+
 ## v0.66.0 — Every phase read a tree, and none of them could say which one  ·  2026-09-21
 
 **In short**

package/plugins/flow/examples/FLOW.template.md

@@ -5,8 +5,8 @@ file in their step 0. Delete what does not apply; **empty or absent = auto-disco
 default behavior** (each command states what it does when a value is missing).
 
 Use this shape for the shared base `FLOW.md` and for an optional sparse harness overlay:
-`FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, or `FLOW.hermes.md`. The
-active overlay is
+`FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`, `FLOW.hermes.md`, or
+`FLOW.zcode.md`. The active overlay is
 read after the base. A key present in it replaces the base value; a present-but-empty key masks the
 base and selects the normal empty fallback; an absent key inherits the base. Lists replace whole
 lists. `conventions` is additive: overlay lines follow the base lines and both apply. Existing repos