flow-workflows 0.66.0 → 0.68.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.68.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
@@ -61,6 +65,15 @@ a command relies on is simply absent in that session, and nothing else will repo
   base branch — and goes out in no MR/PR at all. So a phase writing a tracked file writes it
   **here**, in the directory it is running in, and `$flow-feat-ship §5.5` is what catches the
   tools that could not be told.
+- **A fenced block in a FLOW file is an example, and an example is not configuration.** These
+  files are prose with keys in them, and the rule that decides what a key *is* — a `- key:` line
+  under a `## section` — knows nothing about triple backticks. So a block written to be pasted
+  ("add this to try it once") was read as the configuration it illustrates, for as long as it sat
+  there. It happened in a real repo: `agents.exec_cmd` came from the fenced example of a file whose
+  prose argued at length that it was deliberately unset, and every review round took the one-shot
+  path that prose warned against — with nothing anywhere to say so, because the file and the
+  configuration disagreed while both looked right. **Skip fenced regions when you read a FLOW
+  file**; `flow-workflows` does the same, so the two of you resolve the same config.
 - Merge by section and key. A key present in the active overlay replaces the base value; a key
   absent there inherits the base. **A present-but-empty overlay key masks the base** and resolves
   to the normal empty-key fallback — this is how Codex can inherit its session model while a legacy

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

@@ -129,6 +129,10 @@ Whether the world they describe exists —
 CLIs installed *and authenticated*, agents discoverable, hooks executable, the MCP reachable, the
 base branch resolvable — is §2 below; flag the key here, check the world there, never both.
 
+- **Keys inside a fenced block**: report them, one line, naming the file and the keys — they are
+  an example and resolve to nothing (flow-core §0), which is exactly what a reader who pasted a
+  block to enable it cannot tell from a key that works. Say what to do about it: move the line out
+  of the fence to make it real, leave it there to keep it an illustration.
 - **Fan-out and cost ceilings**: `agents.fanout_max` must be a positive integer; else flag and note
   the default `4` applies. `agents.budget_max` must be a non-negative integer (`0` = no ceiling);
   else flag and note the default `12`. **Both absent → say so as a finding, not a pass**: the review

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.68.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
@@ -60,6 +64,15 @@ a command relies on is simply absent in that session, and nothing else will repo
   base branch — and goes out in no MR/PR at all. So a phase writing a tracked file writes it
   **here**, in the directory it is running in, and `/flow:feat:ship §5.5` is what catches the
   tools that could not be told.
+- **A fenced block in a FLOW file is an example, and an example is not configuration.** These
+  files are prose with keys in them, and the rule that decides what a key *is* — a `- key:` line
+  under a `## section` — knows nothing about triple backticks. So a block written to be pasted
+  ("add this to try it once") was read as the configuration it illustrates, for as long as it sat
+  there. It happened in a real repo: `agents.exec_cmd` came from the fenced example of a file whose
+  prose argued at length that it was deliberately unset, and every review round took the one-shot
+  path that prose warned against — with nothing anywhere to say so, because the file and the
+  configuration disagreed while both looked right. **Skip fenced regions when you read a FLOW
+  file**; `flow-workflows` does the same, so the two of you resolve the same config.
 - Merge by section and key. A key present in the active overlay replaces the base value; a key
   absent there inherits the base. **A present-but-empty overlay key masks the base** and resolves
   to the normal empty-key fallback — this is how Codex can inherit its session model while a legacy

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

@@ -125,6 +125,10 @@ Whether the world they describe exists —
 CLIs installed *and authenticated*, agents discoverable, hooks executable, the MCP reachable, the
 base branch resolvable — is §2 below; flag the key here, check the world there, never both.
 
+- **Keys inside a fenced block**: report them, one line, naming the file and the keys — they are
+  an example and resolve to nothing (flow-core §0), which is exactly what a reader who pasted a
+  block to enable it cannot tell from a key that works. Say what to do about it: move the line out
+  of the fence to make it real, leave it there to keep it an illustration.
 - **Fan-out and cost ceilings**: `agents.fanout_max` must be a positive integer; else flag and note
   the default `4` applies. `agents.budget_max` must be a non-negative integer (`0` = no ceiling);
   else flag and note the default `12`. **Both absent → say so as a finding, not a pass**: the review

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.68.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
@@ -61,6 +65,15 @@ a command relies on is simply absent in that session, and nothing else will repo
   base branch — and goes out in no MR/PR at all. So a phase writing a tracked file writes it
   **here**, in the directory it is running in, and `/flow-feat-ship §5.5` is what catches the
   tools that could not be told.
+- **A fenced block in a FLOW file is an example, and an example is not configuration.** These
+  files are prose with keys in them, and the rule that decides what a key *is* — a `- key:` line
+  under a `## section` — knows nothing about triple backticks. So a block written to be pasted
+  ("add this to try it once") was read as the configuration it illustrates, for as long as it sat
+  there. It happened in a real repo: `agents.exec_cmd` came from the fenced example of a file whose
+  prose argued at length that it was deliberately unset, and every review round took the one-shot
+  path that prose warned against — with nothing anywhere to say so, because the file and the
+  configuration disagreed while both looked right. **Skip fenced regions when you read a FLOW
+  file**; `flow-workflows` does the same, so the two of you resolve the same config.
 - Merge by section and key. A key present in the active overlay replaces the base value; a key
   absent there inherits the base. **A present-but-empty overlay key masks the base** and resolves
   to the normal empty-key fallback — this is how Codex can inherit its session model while a legacy

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

@@ -129,6 +129,10 @@ Whether the world they describe exists —
 CLIs installed *and authenticated*, agents discoverable, hooks executable, the MCP reachable, the
 base branch resolvable — is §2 below; flag the key here, check the world there, never both.
 
+- **Keys inside a fenced block**: report them, one line, naming the file and the keys — they are
+  an example and resolve to nothing (flow-core §0), which is exactly what a reader who pasted a
+  block to enable it cannot tell from a key that works. Say what to do about it: move the line out
+  of the fence to make it real, leave it there to keep it an illustration.
 - **Fan-out and cost ceilings**: `agents.fanout_max` must be a positive integer; else flag and note
   the default `4` applies. `agents.budget_max` must be a non-negative integer (`0` = no ceiling);
   else flag and note the default `12`. **Both absent → say so as a finding, not a pass**: the review

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.68.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
@@ -60,6 +64,15 @@ a command relies on is simply absent in that session, and nothing else will repo
   base branch — and goes out in no MR/PR at all. So a phase writing a tracked file writes it
   **here**, in the directory it is running in, and `/flow-feat-ship §5.5` is what catches the
   tools that could not be told.
+- **A fenced block in a FLOW file is an example, and an example is not configuration.** These
+  files are prose with keys in them, and the rule that decides what a key *is* — a `- key:` line
+  under a `## section` — knows nothing about triple backticks. So a block written to be pasted
+  ("add this to try it once") was read as the configuration it illustrates, for as long as it sat
+  there. It happened in a real repo: `agents.exec_cmd` came from the fenced example of a file whose
+  prose argued at length that it was deliberately unset, and every review round took the one-shot
+  path that prose warned against — with nothing anywhere to say so, because the file and the
+  configuration disagreed while both looked right. **Skip fenced regions when you read a FLOW
+  file**; `flow-workflows` does the same, so the two of you resolve the same config.
 - Merge by section and key. A key present in the active overlay replaces the base value; a key
   absent there inherits the base. **A present-but-empty overlay key masks the base** and resolves
   to the normal empty-key fallback — this is how Codex can inherit its session model while a legacy

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

@@ -127,6 +127,10 @@ Whether the world they describe exists —
 CLIs installed *and authenticated*, agents discoverable, hooks executable, the MCP reachable, the
 base branch resolvable — is §2 below; flag the key here, check the world there, never both.
 
+- **Keys inside a fenced block**: report them, one line, naming the file and the keys — they are
+  an example and resolve to nothing (flow-core §0), which is exactly what a reader who pasted a
+  block to enable it cannot tell from a key that works. Say what to do about it: move the line out
+  of the fence to make it real, leave it there to keep it an illustration.
 - **Fan-out and cost ceilings**: `agents.fanout_max` must be a positive integer; else flag and note
   the default `4` applies. `agents.budget_max` must be a non-negative integer (`0` = no ceiling);
   else flag and note the default `12`. **Both absent → say so as a finding, not a pass**: the review

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}`)
@@ -229,7 +240,22 @@ function parseFlow(text) {
   const out = {}
   let section = null
   let listKey = null
+  let fence = null
   for (const line of text.split('\n')) {
+    // A fenced block is an illustration, not configuration. This reader knows headings and
+    // `- key:` lines and nothing else, so an example written the way `docs/CONFIGURATION.md`
+    // and every FLOW.md in the wild write one — keys inside triple backticks, under a sentence
+    // saying "paste this to try it" — was live config the whole time. A real repo had
+    // `agents.exec_cmd` set from the block of a file whose prose argued, at length, that it was
+    // deliberately unset, and every review round took the one-shot path it warned against.
+    // Closing fence: same character, at least as long as the opening one (CommonMark).
+    const f = /^\s{0,3}(`{3,}|~{3,})/.exec(line)
+    if (f) {
+      if (!fence) fence = f[1]
+      else if (f[1][0] === fence[0] && f[1].length >= fence.length) fence = null
+      continue
+    }
+    if (fence) continue
     const heading = /^##\s+(\S+)/.exec(line)
     if (heading) {
       section = heading[1]
@@ -276,7 +302,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 +1133,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 +1188,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.68.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.68.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,117 @@ 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.68.0 — The block written to be pasted was the configuration  ·  2026-09-21
+
+**In short**
+- **A fenced block in a FLOW file is an example again.** `- key:` lines inside triple backticks (or tildes) are skipped by `bin/cli.mjs` and by flow-core §0, so the two resolve the same configuration. Until now they were read as the config they illustrate.
+- **This was found in a live repo, not imagined.** `agents.exec_cmd` was set from the fenced example of a file whose prose argued, at length, that it was deliberately unset — so every review round took the one-shot path that prose warned against, and nothing anywhere said so.
+- **`/flow:doctor` reports keys found inside a fence**, names the file and says what to do: move the line out to make it real, leave it to keep it an illustration.
+- **`script/tests/flow-config.sh`** pins it — fenced values never leak, `~~~` and four-backtick blocks are fences, a closed fence does not swallow the keys after it. Every case fails against the old reader.
+- **Two tests now actually run in CI**: the new one and `tier.sh`, which existed and was wired into nothing.
+
+A `FLOW.md` is prose with keys in it, and that is the point of it: the keys are the contract, the
+prose is why the value is what it is. What decides which is which is shape alone — a `- key:` line
+under a `## section` — and shape is exactly what a documented example shares with the thing it
+documents. `docs/CONFIGURATION.md` teaches keys in fenced blocks. The template's own comments do.
+So does every real `FLOW.md` that explains an option before enabling it.
+
+The repo where this surfaced had a Claude overlay with three paragraphs on why `agents.exec_cmd`
+stays unset — cost against the panel that had been finding the defects — followed by a block
+introduced with *"to try it once, add both blocks below and take them out again afterwards"*. The
+block was live from the moment it was written: `exec_cmd` set, `quality.reviewers` masked with four
+role descriptions instead of the four agents the base names. The file and its configuration said
+opposite things, and both looked right.
+
+Nothing warns about that class of mistake, because the file is valid and the round it produces is
+green. So the reader changes: fenced regions are skipped, by the CLI and by the command pages that
+read the file themselves, and `doctor` reports what it found in one — a reader who pasted a block
+to enable it needs to be told why it does nothing, which is the mirror of the same problem.
+
+## 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