flow-workflows 0.77.0 → 0.78.0

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.77.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.78.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
@@ -98,8 +98,7 @@ a command relies on is simply absent in that session, and nothing else will repo
      "general-purpose", "phase": "review" }`. Asking here would break the never-a-question contract
      (§2); recording keeps the decision readable afterwards, and `$flow-doctor` aggregates it.
 
-  **The list, and it is short on purpose**: `agents.<role>` when a panel is about to improvise that
-  role on an M/L or sensitive diff · `quality.review_depth` after a review's cost line went over
+  **The list, and it is short on purpose**: `quality.review_depth` after a review's cost line went over
   `agents.budget_max` · `data.volumes` or `data.explain_cmd` when the query duel came back
   schema-only · `quality.functional_check` when `validate` found a runnable app and no way to drive
   it · `tracker.start_cmd`/`done_cmd`/`abandon_cmd` the first time a ticket could have been
@@ -157,8 +156,8 @@ improvises, `models.workers` for the parallel fan-out rounds, and `models.superv
 bounded waits of §6.5 — the last two falling back to `models.agents`. Empty, absent, or no section
 → everything runs on the model you were launched with, and you say nothing.
 
-- Pass the resolved value to every subagent you launch, **except** an agent named in `agents.<role>`,
-  which keeps the model its own definition sets.
+- Pass the resolved value to every subagent you launch, **except** an agent named in `agents.<role>`
+  or picked from the installed ones (§6.6), which keeps the model its own definition sets.
 - **You cannot switch your own model**, so no key names the phases the main agent performs itself.
   A phase that wants another model says it in one line at the handoff (`this step reads better on
   <value>, you are on <current>` → `/model <value>`), records it in the artifact, and continues.
@@ -556,6 +555,61 @@ moving.
 than to run — the brief, the round trip and the report are the whole of the saving. And anything you
 must *react to* mid-wait is not a wait at all: it is the work, and it stays here.
 
+### 6.6 — Which agent a role resolves to
+
+**The harness already tells you which agents are installed**, each with a line on what it is for,
+and choosing the one that fits a piece of work is something you do well without being told. A rule
+that answers every empty role with `general-purpose` throws that away: a repo with a frontend
+specialist installed and no `agents.frontend` got a generalist told to act like one. So wherever a
+command says *"`agents.<role>`, empty → `Agent general-purpose` with the role"*, it means this:
+
+1. **`agents.<role>` names an agent** → that agent, as always.
+2. **Empty** → the installed agent whose description fits the role **and this work's stack** best —
+   read the list your harness gives you, never a guess at a name. None fits clearly →
+   `general-purpose` with the role in the prompt, as before. An agent that fits the role but not the
+   stack (a PHP reviewer on a React diff) does not fit.
+
+**`agents.selection`** decides how far your judgement reaches:
+
+- **`configured`** (empty → this) — the two steps above. A role you named is never second-guessed.
+- **`open`** — a named role is a default, not an order: for a piece clearly outside what it
+  covers, or where an installed agent fits this piece plainly better, take that one. And a piece
+  **no role covers** — a UI component in a work whose roles are all backend — may go to the
+  specialist that does cover it. Every substitution is **one line in the phase artifact**: role,
+  the agent configured, the agent used, and why. Unrecorded, a panel that ran with other agents
+  reads exactly like the one you configured.
+
+  **Nothing installed fits → create the specialist for this work.** An installed agent is, in the
+  end, a brief with a name; what made it good is the brief. So instead of *"act as frontend"*, write
+  the one an expert would carry — the stack and its versions as this repo uses them, what to check
+  in this piece, the mistakes typical of it, and the report contract of this section — and launch
+  `general-purpose` with it. Nothing is written to the harness's agent folders: the specialist lives
+  for the brief, and it works on every harness, because every one has a general-purpose agent.
+  Record it in `meta.json.specialists[]`:
+
+  `{ "name": "react-form-reviewer", "role": "frontend", "phase": "review", "brief": "<the full text
+  you sent>", "useful": null, "status": null }`
+
+  Once its result is in, set `useful`: `true` when something it returned was kept — a finding
+  accepted, a piece merged into the diff — `false` otherwise. Only a useful one is ever offered for
+  saving, and only **when the work ends** (`$flow-feat-ship` §5.1), never mid-phase: by then the
+  MR/PR is open and it is plain which of them earned a place among your agents.
+
+Three things this never touches, in either mode:
+
+- **The review roster** (`quality.review_skill` / `quality.reviewers`) runs as defined, with no
+  substitutions: its value is being the same panel every time, so a result can be compared.
+- **The agents that are `general-purpose` by design** — challengers, skeptics, the completeness
+  critic, the blinded contract check. They are generalists *on purpose*: a specialist brings the
+  assumptions the blinding is there to strip. A step that writes `general-purpose` with no role
+  behind it means exactly that.
+- **The budget.** A picked agent counts against `agents.budget_max` like any other. Like a named
+  agent it keeps its own model (§1), and `models.agents` reaches it only when it has none.
+
+Record what you picked where a default would be recorded (§0): *"`agents.frontend` empty → used
+`react-expert` (installed)"*. That line is also the evidence for writing the role down when the
+next stop offers it.
+
 ## 7. Deferred work — `followups[]`
 
 Every chain in this plugin reaches moments where the right call is **not to do it here**: a build

package/adapters/codex/skills/flow-bug-ship/SKILL.md

@@ -186,6 +186,7 @@ nothing was measured. A slowness bug is the case where this comment *is* the pro
 - **Cross-repo reminder**: for each `meta.json.related_repos` entry not `done`: *"you've shipped the `<this-repo>` part; `<repo>` still needs: `<scope>` → go there and run `$flow-bug-start <TICKET>` (or `$flow-feat-start`)"*. flow only reminds; this is not a hard gate.
 - **Cross-repo contract handoff**: for each such entry with `contract_handoff: "pending"` — the fix changed a surface that sibling consumes — hand the new shape over as `$flow-feat-ship` §6.3 (publish the **literal** shape to the tracker ticket, mandatory preview in every autonomy mode, then record `published → <location>`; versioned-file fallback when there is no tracker). A bug flow has no §"External contracts": take the literal from the fix itself — the actual key, code, route or event the code now emits — read it off the code, never from memory.
 - **Follow-up triage — `$flow-feat-ship` §6.4, in full and unchanged.** Read `meta.json.followups[]`; nothing `proposed` → skip silently. Otherwise §6.4 step 0 first — **3 or more candidates go to a skeptic** whose job is to refute that each deserves a ticket, and only the strongest `tracker.followup_ask_max` (empty → **2**) reach the user (flow-core §7) — then one batched `AskUserQuestion` (**Do it** / **Not worth it** / **Later**; `decision` entries asked as their question, `tooling` and everything `log`ged never asked), the accepted ones get their tracker issue created (outward-facing → **asks in every mode**), the logged ones nothing but `status: "logged"` in `meta.json`, then one offer to start the first. A bug flow is where the gate earns its keep: the prevention actions `$flow-bug-postmortem` wrote, the neighbouring bugs `$flow-bug-validate` found and the similar-risk patterns `$flow-bug-fix` flagged all land here — half a dozen of them, from one fix, and «similar risk elsewhere» that no skeptic ever read is exactly the entry that turns a closed bug into six open questions. Repeat for anything still `proposed` on the re-run that confirms the merge.
+- **Specialists created — `$flow-feat-ship` §5.1, in full and unchanged.** Read `meta.json.specialists[]` (flow-core §6.6); nothing `useful` and pending → skip silently. Otherwise one batched offer to save each as an agent, after the MR/PR and after the knowledge `$flow-bug-postmortem` §4 already consolidated — asked in every mode, never overwriting an agent that exists.
 - **Conventions learned — `$flow-feat-ship` §6.4bis, in full and unchanged.** Read `meta.json.conventions_candidates[]` (flow-core §8); nothing pending → skip silently. Otherwise: drop what `FLOW.md` already says, then one batched `AskUserQuestion` (**Add to FLOW.md** / **Not a rule** / **Later**, or **Replace** when it contradicts a line that is there). Asked in every mode — it edits a file in the tree. A fix is where the corrections land hardest: *«never mock the repository in that layer»*, *«the regression test goes next to the unit test, not in the functional suite»* — said once inside `bug:fix`, and proposed again in the next incident unless they reach the file.
 - **Close the follow-up that started this work.** `meta.json.origin` set and this ship moved `phase` to `done` → open the originating work's `meta.json` (live folder or `_archive/`) and set that `followups[]` entry to `status: "done"`. Best-effort: the originating folder is gone or unreadable → warn in one line and continue, never block. Without this the entry stays `in_progress` forever and `status`/`daily` keep reporting work that is finished.
 - **Only once `phase` is `done`**: delete the candidate anchor `$flow-bug-review §1.5` left behind — `git update-ref -d refs/flow/candidate/<TICKET>`. No question: local, never pushed, and the gate that needed it has run.

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

@@ -196,8 +196,8 @@ refuse) · **degraded** (it runs, quietly worse than the config promises), plus
 
 - Every **role** set in `agents.*` (not `fanout_max` / `fanout_tool` — not agents), plus
   `quality.reviewers` and `quality.review_skill`: discoverable in `~/.claude/agents`, the repo's
-  `.agents/agents`, or a plugin. Report each missing name and that it falls back to `general-purpose`
-  (a skill: skipped) — a panel missing agents reviews less and still reports a clean pass.
+  `.agents/agents`, or a plugin. Report each missing name and that it falls back per flow-core §6.6 — the installed agent
+  that fits, else `general-purpose` (a skill: skipped) — a panel missing agents reviews less and still reports a clean pass.
 - Harness cannot set a model per subagent → note that every `models.*` value degrades to inheritance.
 - **Where the live panel will go this session** (flow-core §4): a tool whose name ends in `panel_set` / `panel_patch` — namespaced by the harness (`mcp__panel__panel_set` on Claude Code) and possibly **deferred**, which reads as absent until the list of deferred tools is checked → the terminal draws the panel and no `panel.json` is written; genuinely absent → the panel is that file, as before. Neither is a fault — one line naming the tools as they are actually called here, or saying the file is the transport.
 

package/adapters/codex/skills/flow-feat-build/SKILL.md

@@ -139,8 +139,8 @@ Take the shape from the **Access paths** table in `03-design.md`; a query matchi
 
 Execution mode:
 
-- **Single-thread (XS/S/M)**: implement yourself, step by step; subagents only as point consultants when blocked — `agents.architecture` from `FLOW.md` for layer questions, `agents.persistence` for query/mapping questions (`Agent general-purpose` if either is empty).
-- **Partial delegation (M/L with clear pieces)**: `Agent` for isolated endpoints, plus `agents.testing` from `FLOW.md` in parallel to prepare the test suite (`Agent general-purpose` if empty). Pass the full `03-design.md` in the prompt so agents do not invent things.
+- **Single-thread (XS/S/M)**: implement yourself, step by step. Delegate a piece when a specialist would do it clearly better than you — a UI component to a frontend agent in a mostly backend work, a migration to a persistence agent — not because it is tedious; consult one when blocked — `agents.architecture` from `FLOW.md` for layer questions, `agents.persistence` for query/mapping questions. Which agent each role resolves to, and whether you may pick past a named one, is flow-core §6.6. A delegated piece follows the brief rules of the next bullet and the one-writer rule of flow-core §6.
+- **Partial delegation (M/L with clear pieces)**: `Agent` for isolated endpoints, plus `agents.testing` from `FLOW.md` in parallel to prepare the test suite (empty → flow-core §6.6). Pass the full `03-design.md` in the prompt so agents do not invent things.
 
   A brief here states the **output** as explicitly as the input (flow-core §6):
   - **Name the path the agent writes**, and require it to **save after each finished piece, not at the end**. Code, tests and generated content are the deliverable; the report is not. Then **verify the file** instead of believing the report — a piece half-written on disk is recoverable, what only exists in the agent's context is lost the moment it is stopped.

package/adapters/codex/skills/flow-feat-design/SKILL.md

@@ -175,7 +175,7 @@ Save the result at the top of `03-design.md` under "## What already exists". Des
 ## 4. Work
 
 1. Load the project's skills (`FLOW.md` section `conventions`).
-2. Launch **in parallel** by feature/project type. Agent = `agents.<role>` from `FLOW.md`; empty → `Agent general-purpose` with the role in the prompt.
+2. Launch **in parallel** by feature/project type. Agent = `agents.<role>` from `FLOW.md`; empty → the installed agent that fits, else `Agent general-purpose` with the role in the prompt (flow-core §6.6).
 
 | When | Agent | Task |
 |---|---|---|

package/adapters/codex/skills/flow-feat-ship/SKILL.md

@@ -234,6 +234,29 @@ Only if `knowledge.read_staging` or `knowledge.save` is set; neither → skip wi
 3. **Combine staging + new findings** into a short list. Empty or only code-derivable → do not insist.
 4. 1+ relevant findings → ask the user whether to consolidate. Yes → run the consolidation of flow-core §0 (`read_staging`, then one decision and one `knowledge.save` per finding). No → do not insist.
 
+## 5.1 Specialists created (offer)
+
+Read `meta.json.specialists[]` (flow-core §6.6). **No entry with `useful: true` and `status` unset
+or `"later"` → skip this section and say nothing.** It comes after §5 on purpose: the MR/PR is open,
+the knowledge is saved, and what is left is whether an agent this work improvised deserves a name.
+
+1. **A harness with no file-defined agents** → the section does not exist; say so in one line if
+   there were useful specialists, so the brief is not mistaken for lost (it stays in `meta.json`).
+2. **One `AskUserQuestion`**, at most 4 entries, most useful first: its `name`, the role, the phase,
+   and in one line what it caught. Options: **Save as agent** · **Save and use it for `<role>`** ·
+   **No** · **Later**. The second option exists only when `agents.<role>` is empty.
+3. **Asked in every mode**, `auto` included: it writes to your agent configuration, outside the
+   tree, and that is never flow mechanics.
+4. **Save** → write the agent where and in the format your harness reads agents from (on Claude
+   Code, `~/.claude/agents/<name>.md`: frontmatter `name` and a one-line `description` of when to
+   use it, then the brief as the body — drop what only made sense for this ticket, keep the stack,
+   the checks and the typical mistakes). A file with that name already there → never overwrite:
+   suffix the name and say so. **Save and use it** → also write `agents.<role>: <name>` to the
+   active overlay (a harness-owned agent name, flow-core §0). Then `status: "saved"`, with the path.
+   **No** → `"declined"`, never offered again. **Later** → `"later"`, offered by the re-run of this
+   close.
+5. **One line on screen**: how many agents were saved and where.
+
 ## 5.5 A worktree does not own the tree its tools wrote into
 
 `meta.json.worktree` null → skip silently; there is nothing here that can go wrong.

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

@@ -136,6 +136,12 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
       "evidence": "the stop it came from",
       "status": "proposed" | "added" | "declined", "note": "" }
   ],
+  "specialists": [
+    { "name": "react-form-reviewer", "role": "frontend", "phase": "review",
+      "brief": "the full expert brief it was launched with",
+      "useful": true | false | null,
+      "status": null | "saved" | "declined" | "later", "path": null }
+  ],
   "origin": { "work": "{PREFIX}XXXXX", "followup": "F1" },
   "started_at": "2026-05-11T10:00:00Z",
   "updated_at": "2026-05-11T11:30:00Z",
@@ -152,6 +158,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **`followups`**: work a phase deliberately did **not** do here — a neighbouring defect found while building, a piece put out of scope while planning, a risk recorded but not mitigated, an edge case left unchecked, a prevention action from a postmortem. Written by the phase that parks it (asks nothing) when it clears the bar of flow-core §7, triaged **once** at `ship`'s Close behind a skeptic and a ceiling on how many may become questions, published in the MR/PR description while still open, and surfaced by `status`/`daily`/`next` — including from `_archive/` — until `declined` or `done`. Shape and rules: flow-core §7. `[]` when the work deferred nothing.
 - **`defaults_used`**: an empty `FLOW.md` key a phase resolved with its default instead of asking — written in `guided`/`auto`, where asking would breach the never-a-question contract (flow-core §0). Not an error and not deferred work: a record, aggregated by `$flow-doctor` across every work including `_archive/`, so a key that keeps defaulting can be pinned once instead of decided every time. `[]` when nothing defaulted.
 - **`conventions_candidates`**: rules the user taught **this repo's flow** while correcting a phase — *«not a listener, a message handler»*, *«the test command is `make test-unit`»*. Written by the phase that heard one, asking nothing, only when it would apply to an unrelated ticket in this repo; read by `review`'s idiom audit in the same work; offered once at `ship`'s Close (**Add to FLOW.md** / **Not a rule** / **Later**, or **Replace**), in every mode, because it edits a file in the tree. Never domain knowledge — that filter is unchanged. Shape and rules: flow-core §8. `[]` when the work taught nothing.
+- **`specialists`**: agents a phase **created for this work** because nothing installed fit a role, under `agents.selection: open` (flow-core §6.6) — the brief it wrote and ran on `general-purpose`, and whether anything it returned was kept. Nothing is written to the harness's agent folders while the work runs; `$flow-feat-ship` §5.1 offers the useful ones for saving as real agents once the MR/PR is open and the knowledge is saved, and records where each went.
 - **`origin`**: set when this work *is* a follow-up someone accepted — which work raised it and which entry. Lets `start` carry the recorded "why" into `01-context.md` instead of re-deriving it, and lets that entry move to `done` when this work does. Absent for a work that came straight from a ticket.
 - Ticket format follows `tracker.prefix`; empty → free-form.
 

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.77.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.78.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
@@ -97,8 +97,7 @@ a command relies on is simply absent in that session, and nothing else will repo
      "general-purpose", "phase": "review" }`. Asking here would break the never-a-question contract
      (§2); recording keeps the decision readable afterwards, and `/flow:doctor` aggregates it.
 
-  **The list, and it is short on purpose**: `agents.<role>` when a panel is about to improvise that
-  role on an M/L or sensitive diff · `quality.review_depth` after a review's cost line went over
+  **The list, and it is short on purpose**: `quality.review_depth` after a review's cost line went over
   `agents.budget_max` · `data.volumes` or `data.explain_cmd` when the query duel came back
   schema-only · `quality.functional_check` when `validate` found a runnable app and no way to drive
   it · `tracker.start_cmd`/`done_cmd`/`abandon_cmd` the first time a ticket could have been
@@ -156,8 +155,8 @@ improvises, `models.workers` for the parallel fan-out rounds, and `models.superv
 bounded waits of §6.5 — the last two falling back to `models.agents`. Empty, absent, or no section
 → everything runs on the model you were launched with, and you say nothing.
 
-- Pass the resolved value to every subagent you launch, **except** an agent named in `agents.<role>`,
-  which keeps the model its own definition sets.
+- Pass the resolved value to every subagent you launch, **except** an agent named in `agents.<role>`
+  or picked from the installed ones (§6.6), which keeps the model its own definition sets.
 - **You cannot switch your own model**, so no key names the phases the main agent performs itself.
   A phase that wants another model says it in one line at the handoff (`this step reads better on
   <value>, you are on <current>` → `/model <value>`), records it in the artifact, and continues.
@@ -555,6 +554,61 @@ moving.
 than to run — the brief, the round trip and the report are the whole of the saving. And anything you
 must *react to* mid-wait is not a wait at all: it is the work, and it stays here.
 
+### 6.6 — Which agent a role resolves to
+
+**The harness already tells you which agents are installed**, each with a line on what it is for,
+and choosing the one that fits a piece of work is something you do well without being told. A rule
+that answers every empty role with `general-purpose` throws that away: a repo with a frontend
+specialist installed and no `agents.frontend` got a generalist told to act like one. So wherever a
+command says *"`agents.<role>`, empty → `Agent general-purpose` with the role"*, it means this:
+
+1. **`agents.<role>` names an agent** → that agent, as always.
+2. **Empty** → the installed agent whose description fits the role **and this work's stack** best —
+   read the list your harness gives you, never a guess at a name. None fits clearly →
+   `general-purpose` with the role in the prompt, as before. An agent that fits the role but not the
+   stack (a PHP reviewer on a React diff) does not fit.
+
+**`agents.selection`** decides how far your judgement reaches:
+
+- **`configured`** (empty → this) — the two steps above. A role you named is never second-guessed.
+- **`open`** — a named role is a default, not an order: for a piece clearly outside what it
+  covers, or where an installed agent fits this piece plainly better, take that one. And a piece
+  **no role covers** — a UI component in a work whose roles are all backend — may go to the
+  specialist that does cover it. Every substitution is **one line in the phase artifact**: role,
+  the agent configured, the agent used, and why. Unrecorded, a panel that ran with other agents
+  reads exactly like the one you configured.
+
+  **Nothing installed fits → create the specialist for this work.** An installed agent is, in the
+  end, a brief with a name; what made it good is the brief. So instead of *"act as frontend"*, write
+  the one an expert would carry — the stack and its versions as this repo uses them, what to check
+  in this piece, the mistakes typical of it, and the report contract of this section — and launch
+  `general-purpose` with it. Nothing is written to the harness's agent folders: the specialist lives
+  for the brief, and it works on every harness, because every one has a general-purpose agent.
+  Record it in `meta.json.specialists[]`:
+
+  `{ "name": "react-form-reviewer", "role": "frontend", "phase": "review", "brief": "<the full text
+  you sent>", "useful": null, "status": null }`
+
+  Once its result is in, set `useful`: `true` when something it returned was kept — a finding
+  accepted, a piece merged into the diff — `false` otherwise. Only a useful one is ever offered for
+  saving, and only **when the work ends** (`/flow:feat:ship` §5.1), never mid-phase: by then the
+  MR/PR is open and it is plain which of them earned a place among your agents.
+
+Three things this never touches, in either mode:
+
+- **The review roster** (`quality.review_skill` / `quality.reviewers`) runs as defined, with no
+  substitutions: its value is being the same panel every time, so a result can be compared.
+- **The agents that are `general-purpose` by design** — challengers, skeptics, the completeness
+  critic, the blinded contract check. They are generalists *on purpose*: a specialist brings the
+  assumptions the blinding is there to strip. A step that writes `general-purpose` with no role
+  behind it means exactly that.
+- **The budget.** A picked agent counts against `agents.budget_max` like any other. Like a named
+  agent it keeps its own model (§1), and `models.agents` reaches it only when it has none.
+
+Record what you picked where a default would be recorded (§0): *"`agents.frontend` empty → used
+`react-expert` (installed)"*. That line is also the evidence for writing the role down when the
+next stop offers it.
+
 ## 7. Deferred work — `followups[]`
 
 Every chain in this plugin reaches moments where the right call is **not to do it here**: a build

package/adapters/gemini/commands/flow/bug/ship.toml

@@ -182,6 +182,7 @@ nothing was measured. A slowness bug is the case where this comment *is* the pro
 - **Cross-repo reminder**: for each `meta.json.related_repos` entry not `done`: *"you've shipped the `<this-repo>` part; `<repo>` still needs: `<scope>` → go there and run `/flow:bug:start <TICKET>` (or `/flow:feat:start`)"*. flow only reminds; this is not a hard gate.
 - **Cross-repo contract handoff**: for each such entry with `contract_handoff: "pending"` — the fix changed a surface that sibling consumes — hand the new shape over as `/flow:feat:ship` §6.3 (publish the **literal** shape to the tracker ticket, mandatory preview in every autonomy mode, then record `published → <location>`; versioned-file fallback when there is no tracker). A bug flow has no §"External contracts": take the literal from the fix itself — the actual key, code, route or event the code now emits — read it off the code, never from memory.
 - **Follow-up triage — `/flow:feat:ship` §6.4, in full and unchanged.** Read `meta.json.followups[]`; nothing `proposed` → skip silently. Otherwise §6.4 step 0 first — **3 or more candidates go to a skeptic** whose job is to refute that each deserves a ticket, and only the strongest `tracker.followup_ask_max` (empty → **2**) reach the user (flow-core §7) — then one batched `AskUserQuestion` (**Do it** / **Not worth it** / **Later**; `decision` entries asked as their question, `tooling` and everything `log`ged never asked), the accepted ones get their tracker issue created (outward-facing → **asks in every mode**), the logged ones nothing but `status: "logged"` in `meta.json`, then one offer to start the first. A bug flow is where the gate earns its keep: the prevention actions `/flow:bug:postmortem` wrote, the neighbouring bugs `/flow:bug:validate` found and the similar-risk patterns `/flow:bug:fix` flagged all land here — half a dozen of them, from one fix, and «similar risk elsewhere» that no skeptic ever read is exactly the entry that turns a closed bug into six open questions. Repeat for anything still `proposed` on the re-run that confirms the merge.
+- **Specialists created — `/flow:feat:ship` §5.1, in full and unchanged.** Read `meta.json.specialists[]` (flow-core §6.6); nothing `useful` and pending → skip silently. Otherwise one batched offer to save each as an agent, after the MR/PR and after the knowledge `/flow:bug:postmortem` §4 already consolidated — asked in every mode, never overwriting an agent that exists.
 - **Conventions learned — `/flow:feat:ship` §6.4bis, in full and unchanged.** Read `meta.json.conventions_candidates[]` (flow-core §8); nothing pending → skip silently. Otherwise: drop what `FLOW.md` already says, then one batched `AskUserQuestion` (**Add to FLOW.md** / **Not a rule** / **Later**, or **Replace** when it contradicts a line that is there). Asked in every mode — it edits a file in the tree. A fix is where the corrections land hardest: *«never mock the repository in that layer»*, *«the regression test goes next to the unit test, not in the functional suite»* — said once inside `bug:fix`, and proposed again in the next incident unless they reach the file.
 - **Close the follow-up that started this work.** `meta.json.origin` set and this ship moved `phase` to `done` → open the originating work's `meta.json` (live folder or `_archive/`) and set that `followups[]` entry to `status: "done"`. Best-effort: the originating folder is gone or unreadable → warn in one line and continue, never block. Without this the entry stays `in_progress` forever and `status`/`daily` keep reporting work that is finished.
 - **Only once `phase` is `done`**: delete the candidate anchor `/flow:bug:review §1.5` left behind — `git update-ref -d refs/flow/candidate/<TICKET>`. No question: local, never pushed, and the gate that needed it has run.

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

@@ -192,8 +192,8 @@ refuse) · **degraded** (it runs, quietly worse than the config promises), plus
 
 - Every **role** set in `agents.*` (not `fanout_max` / `fanout_tool` — not agents), plus
   `quality.reviewers` and `quality.review_skill`: discoverable in `~/.claude/agents`, the repo's
-  `.agents/agents`, or a plugin. Report each missing name and that it falls back to `general-purpose`
-  (a skill: skipped) — a panel missing agents reviews less and still reports a clean pass.
+  `.agents/agents`, or a plugin. Report each missing name and that it falls back per flow-core §6.6 — the installed agent
+  that fits, else `general-purpose` (a skill: skipped) — a panel missing agents reviews less and still reports a clean pass.
 - Harness cannot set a model per subagent → note that every `models.*` value degrades to inheritance.
 - **Where the live panel will go this session** (flow-core §4): a tool whose name ends in `panel_set` / `panel_patch` — namespaced by the harness (`mcp__panel__panel_set` on Claude Code) and possibly **deferred**, which reads as absent until the list of deferred tools is checked → the terminal draws the panel and no `panel.json` is written; genuinely absent → the panel is that file, as before. Neither is a fault — one line naming the tools as they are actually called here, or saying the file is the transport.
 

package/adapters/gemini/commands/flow/feat/build.toml

@@ -135,8 +135,8 @@ Take the shape from the **Access paths** table in `03-design.md`; a query matchi
 
 Execution mode:
 
-- **Single-thread (XS/S/M)**: implement yourself, step by step; subagents only as point consultants when blocked — `agents.architecture` from `FLOW.md` for layer questions, `agents.persistence` for query/mapping questions (`Agent general-purpose` if either is empty).
-- **Partial delegation (M/L with clear pieces)**: `Agent` for isolated endpoints, plus `agents.testing` from `FLOW.md` in parallel to prepare the test suite (`Agent general-purpose` if empty). Pass the full `03-design.md` in the prompt so agents do not invent things.
+- **Single-thread (XS/S/M)**: implement yourself, step by step. Delegate a piece when a specialist would do it clearly better than you — a UI component to a frontend agent in a mostly backend work, a migration to a persistence agent — not because it is tedious; consult one when blocked — `agents.architecture` from `FLOW.md` for layer questions, `agents.persistence` for query/mapping questions. Which agent each role resolves to, and whether you may pick past a named one, is flow-core §6.6. A delegated piece follows the brief rules of the next bullet and the one-writer rule of flow-core §6.
+- **Partial delegation (M/L with clear pieces)**: `Agent` for isolated endpoints, plus `agents.testing` from `FLOW.md` in parallel to prepare the test suite (empty → flow-core §6.6). Pass the full `03-design.md` in the prompt so agents do not invent things.
 
   A brief here states the **output** as explicitly as the input (flow-core §6):
   - **Name the path the agent writes**, and require it to **save after each finished piece, not at the end**. Code, tests and generated content are the deliverable; the report is not. Then **verify the file** instead of believing the report — a piece half-written on disk is recoverable, what only exists in the agent's context is lost the moment it is stopped.

package/adapters/gemini/commands/flow/feat/design.toml

@@ -171,7 +171,7 @@ Save the result at the top of `03-design.md` under "## What already exists". Des
 ## 4. Work
 
 1. Load the project's skills (`FLOW.md` section `conventions`).
-2. Launch **in parallel** by feature/project type. Agent = `agents.<role>` from `FLOW.md`; empty → `Agent general-purpose` with the role in the prompt.
+2. Launch **in parallel** by feature/project type. Agent = `agents.<role>` from `FLOW.md`; empty → the installed agent that fits, else `Agent general-purpose` with the role in the prompt (flow-core §6.6).
 
 | When | Agent | Task |
 |---|---|---|

package/adapters/gemini/commands/flow/feat/ship.toml

@@ -230,6 +230,29 @@ Only if `knowledge.read_staging` or `knowledge.save` is set; neither → skip wi
 3. **Combine staging + new findings** into a short list. Empty or only code-derivable → do not insist.
 4. 1+ relevant findings → ask the user whether to consolidate. Yes → run the consolidation of flow-core §0 (`read_staging`, then one decision and one `knowledge.save` per finding). No → do not insist.
 
+## 5.1 Specialists created (offer)
+
+Read `meta.json.specialists[]` (flow-core §6.6). **No entry with `useful: true` and `status` unset
+or `"later"` → skip this section and say nothing.** It comes after §5 on purpose: the MR/PR is open,
+the knowledge is saved, and what is left is whether an agent this work improvised deserves a name.
+
+1. **A harness with no file-defined agents** → the section does not exist; say so in one line if
+   there were useful specialists, so the brief is not mistaken for lost (it stays in `meta.json`).
+2. **One `AskUserQuestion`**, at most 4 entries, most useful first: its `name`, the role, the phase,
+   and in one line what it caught. Options: **Save as agent** · **Save and use it for `<role>`** ·
+   **No** · **Later**. The second option exists only when `agents.<role>` is empty.
+3. **Asked in every mode**, `auto` included: it writes to your agent configuration, outside the
+   tree, and that is never flow mechanics.
+4. **Save** → write the agent where and in the format your harness reads agents from (on Claude
+   Code, `~/.claude/agents/<name>.md`: frontmatter `name` and a one-line `description` of when to
+   use it, then the brief as the body — drop what only made sense for this ticket, keep the stack,
+   the checks and the typical mistakes). A file with that name already there → never overwrite:
+   suffix the name and say so. **Save and use it** → also write `agents.<role>: <name>` to the
+   active overlay (a harness-owned agent name, flow-core §0). Then `status: "saved"`, with the path.
+   **No** → `"declined"`, never offered again. **Later** → `"later"`, offered by the re-run of this
+   close.
+5. **One line on screen**: how many agents were saved and where.
+
 ## 5.5 A worktree does not own the tree its tools wrote into
 
 `meta.json.worktree` null → skip silently; there is nothing here that can go wrong.

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

@@ -132,6 +132,12 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
       "evidence": "the stop it came from",
       "status": "proposed" | "added" | "declined", "note": "" }
   ],
+  "specialists": [
+    { "name": "react-form-reviewer", "role": "frontend", "phase": "review",
+      "brief": "the full expert brief it was launched with",
+      "useful": true | false | null,
+      "status": null | "saved" | "declined" | "later", "path": null }
+  ],
   "origin": { "work": "{PREFIX}XXXXX", "followup": "F1" },
   "started_at": "2026-05-11T10:00:00Z",
   "updated_at": "2026-05-11T11:30:00Z",
@@ -148,6 +154,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **`followups`**: work a phase deliberately did **not** do here — a neighbouring defect found while building, a piece put out of scope while planning, a risk recorded but not mitigated, an edge case left unchecked, a prevention action from a postmortem. Written by the phase that parks it (asks nothing) when it clears the bar of flow-core §7, triaged **once** at `ship`'s Close behind a skeptic and a ceiling on how many may become questions, published in the MR/PR description while still open, and surfaced by `status`/`daily`/`next` — including from `_archive/` — until `declined` or `done`. Shape and rules: flow-core §7. `[]` when the work deferred nothing.
 - **`defaults_used`**: an empty `FLOW.md` key a phase resolved with its default instead of asking — written in `guided`/`auto`, where asking would breach the never-a-question contract (flow-core §0). Not an error and not deferred work: a record, aggregated by `/flow:doctor` across every work including `_archive/`, so a key that keeps defaulting can be pinned once instead of decided every time. `[]` when nothing defaulted.
 - **`conventions_candidates`**: rules the user taught **this repo's flow** while correcting a phase — *«not a listener, a message handler»*, *«the test command is `make test-unit`»*. Written by the phase that heard one, asking nothing, only when it would apply to an unrelated ticket in this repo; read by `review`'s idiom audit in the same work; offered once at `ship`'s Close (**Add to FLOW.md** / **Not a rule** / **Later**, or **Replace**), in every mode, because it edits a file in the tree. Never domain knowledge — that filter is unchanged. Shape and rules: flow-core §8. `[]` when the work taught nothing.
+- **`specialists`**: agents a phase **created for this work** because nothing installed fit a role, under `agents.selection: open` (flow-core §6.6) — the brief it wrote and ran on `general-purpose`, and whether anything it returned was kept. Nothing is written to the harness's agent folders while the work runs; `/flow:feat:ship` §5.1 offers the useful ones for saving as real agents once the MR/PR is open and the knowledge is saved, and records where each went.
 - **`origin`**: set when this work *is* a follow-up someone accepted — which work raised it and which entry. Lets `start` carry the recorded "why" into `01-context.md` instead of re-deriving it, and lets that entry move to `done` when this work does. Absent for a work that came straight from a ticket.
 - Ticket format follows `tracker.prefix`; empty → free-form.
 

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.77.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.78.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
@@ -98,8 +98,7 @@ a command relies on is simply absent in that session, and nothing else will repo
      "general-purpose", "phase": "review" }`. Asking here would break the never-a-question contract
      (§2); recording keeps the decision readable afterwards, and `/flow-doctor` aggregates it.
 
-  **The list, and it is short on purpose**: `agents.<role>` when a panel is about to improvise that
-  role on an M/L or sensitive diff · `quality.review_depth` after a review's cost line went over
+  **The list, and it is short on purpose**: `quality.review_depth` after a review's cost line went over
   `agents.budget_max` · `data.volumes` or `data.explain_cmd` when the query duel came back
   schema-only · `quality.functional_check` when `validate` found a runnable app and no way to drive
   it · `tracker.start_cmd`/`done_cmd`/`abandon_cmd` the first time a ticket could have been
@@ -157,8 +156,8 @@ improvises, `models.workers` for the parallel fan-out rounds, and `models.superv
 bounded waits of §6.5 — the last two falling back to `models.agents`. Empty, absent, or no section
 → everything runs on the model you were launched with, and you say nothing.
 
-- Pass the resolved value to every subagent you launch, **except** an agent named in `agents.<role>`,
-  which keeps the model its own definition sets.
+- Pass the resolved value to every subagent you launch, **except** an agent named in `agents.<role>`
+  or picked from the installed ones (§6.6), which keeps the model its own definition sets.
 - **You cannot switch your own model**, so no key names the phases the main agent performs itself.
   A phase that wants another model says it in one line at the handoff (`this step reads better on
   <value>, you are on <current>` → `/model <value>`), records it in the artifact, and continues.
@@ -556,6 +555,61 @@ moving.
 than to run — the brief, the round trip and the report are the whole of the saving. And anything you
 must *react to* mid-wait is not a wait at all: it is the work, and it stays here.
 
+### 6.6 — Which agent a role resolves to
+
+**The harness already tells you which agents are installed**, each with a line on what it is for,
+and choosing the one that fits a piece of work is something you do well without being told. A rule
+that answers every empty role with `general-purpose` throws that away: a repo with a frontend
+specialist installed and no `agents.frontend` got a generalist told to act like one. So wherever a
+command says *"`agents.<role>`, empty → `Agent general-purpose` with the role"*, it means this:
+
+1. **`agents.<role>` names an agent** → that agent, as always.
+2. **Empty** → the installed agent whose description fits the role **and this work's stack** best —
+   read the list your harness gives you, never a guess at a name. None fits clearly →
+   `general-purpose` with the role in the prompt, as before. An agent that fits the role but not the
+   stack (a PHP reviewer on a React diff) does not fit.
+
+**`agents.selection`** decides how far your judgement reaches:
+
+- **`configured`** (empty → this) — the two steps above. A role you named is never second-guessed.
+- **`open`** — a named role is a default, not an order: for a piece clearly outside what it
+  covers, or where an installed agent fits this piece plainly better, take that one. And a piece
+  **no role covers** — a UI component in a work whose roles are all backend — may go to the
+  specialist that does cover it. Every substitution is **one line in the phase artifact**: role,
+  the agent configured, the agent used, and why. Unrecorded, a panel that ran with other agents
+  reads exactly like the one you configured.
+
+  **Nothing installed fits → create the specialist for this work.** An installed agent is, in the
+  end, a brief with a name; what made it good is the brief. So instead of *"act as frontend"*, write
+  the one an expert would carry — the stack and its versions as this repo uses them, what to check
+  in this piece, the mistakes typical of it, and the report contract of this section — and launch
+  `general-purpose` with it. Nothing is written to the harness's agent folders: the specialist lives
+  for the brief, and it works on every harness, because every one has a general-purpose agent.
+  Record it in `meta.json.specialists[]`:
+
+  `{ "name": "react-form-reviewer", "role": "frontend", "phase": "review", "brief": "<the full text
+  you sent>", "useful": null, "status": null }`
+
+  Once its result is in, set `useful`: `true` when something it returned was kept — a finding
+  accepted, a piece merged into the diff — `false` otherwise. Only a useful one is ever offered for
+  saving, and only **when the work ends** (`/flow-feat-ship` §5.1), never mid-phase: by then the
+  MR/PR is open and it is plain which of them earned a place among your agents.
+
+Three things this never touches, in either mode:
+
+- **The review roster** (`quality.review_skill` / `quality.reviewers`) runs as defined, with no
+  substitutions: its value is being the same panel every time, so a result can be compared.
+- **The agents that are `general-purpose` by design** — challengers, skeptics, the completeness
+  critic, the blinded contract check. They are generalists *on purpose*: a specialist brings the
+  assumptions the blinding is there to strip. A step that writes `general-purpose` with no role
+  behind it means exactly that.
+- **The budget.** A picked agent counts against `agents.budget_max` like any other. Like a named
+  agent it keeps its own model (§1), and `models.agents` reaches it only when it has none.
+
+Record what you picked where a default would be recorded (§0): *"`agents.frontend` empty → used
+`react-expert` (installed)"*. That line is also the evidence for writing the role down when the
+next stop offers it.
+
 ## 7. Deferred work — `followups[]`
 
 Every chain in this plugin reaches moments where the right call is **not to do it here**: a build

package/adapters/hermes/skills/flow-bug-ship/SKILL.md

@@ -186,6 +186,7 @@ nothing was measured. A slowness bug is the case where this comment *is* the pro
 - **Cross-repo reminder**: for each `meta.json.related_repos` entry not `done`: *"you've shipped the `<this-repo>` part; `<repo>` still needs: `<scope>` → go there and run `/flow-bug-start <TICKET>` (or `/flow-feat-start`)"*. flow only reminds; this is not a hard gate.
 - **Cross-repo contract handoff**: for each such entry with `contract_handoff: "pending"` — the fix changed a surface that sibling consumes — hand the new shape over as `/flow-feat-ship` §6.3 (publish the **literal** shape to the tracker ticket, mandatory preview in every autonomy mode, then record `published → <location>`; versioned-file fallback when there is no tracker). A bug flow has no §"External contracts": take the literal from the fix itself — the actual key, code, route or event the code now emits — read it off the code, never from memory.
 - **Follow-up triage — `/flow-feat-ship` §6.4, in full and unchanged.** Read `meta.json.followups[]`; nothing `proposed` → skip silently. Otherwise §6.4 step 0 first — **3 or more candidates go to a skeptic** whose job is to refute that each deserves a ticket, and only the strongest `tracker.followup_ask_max` (empty → **2**) reach the user (flow-core §7) — then one batched `AskUserQuestion` (**Do it** / **Not worth it** / **Later**; `decision` entries asked as their question, `tooling` and everything `log`ged never asked), the accepted ones get their tracker issue created (outward-facing → **asks in every mode**), the logged ones nothing but `status: "logged"` in `meta.json`, then one offer to start the first. A bug flow is where the gate earns its keep: the prevention actions `/flow-bug-postmortem` wrote, the neighbouring bugs `/flow-bug-validate` found and the similar-risk patterns `/flow-bug-fix` flagged all land here — half a dozen of them, from one fix, and «similar risk elsewhere» that no skeptic ever read is exactly the entry that turns a closed bug into six open questions. Repeat for anything still `proposed` on the re-run that confirms the merge.
+- **Specialists created — `/flow-feat-ship` §5.1, in full and unchanged.** Read `meta.json.specialists[]` (flow-core §6.6); nothing `useful` and pending → skip silently. Otherwise one batched offer to save each as an agent, after the MR/PR and after the knowledge `/flow-bug-postmortem` §4 already consolidated — asked in every mode, never overwriting an agent that exists.
 - **Conventions learned — `/flow-feat-ship` §6.4bis, in full and unchanged.** Read `meta.json.conventions_candidates[]` (flow-core §8); nothing pending → skip silently. Otherwise: drop what `FLOW.md` already says, then one batched `AskUserQuestion` (**Add to FLOW.md** / **Not a rule** / **Later**, or **Replace** when it contradicts a line that is there). Asked in every mode — it edits a file in the tree. A fix is where the corrections land hardest: *«never mock the repository in that layer»*, *«the regression test goes next to the unit test, not in the functional suite»* — said once inside `bug:fix`, and proposed again in the next incident unless they reach the file.
 - **Close the follow-up that started this work.** `meta.json.origin` set and this ship moved `phase` to `done` → open the originating work's `meta.json` (live folder or `_archive/`) and set that `followups[]` entry to `status: "done"`. Best-effort: the originating folder is gone or unreadable → warn in one line and continue, never block. Without this the entry stays `in_progress` forever and `status`/`daily` keep reporting work that is finished.
 - **Only once `phase` is `done`**: delete the candidate anchor `/flow-bug-review §1.5` left behind — `git update-ref -d refs/flow/candidate/<TICKET>`. No question: local, never pushed, and the gate that needed it has run.

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

@@ -196,8 +196,8 @@ refuse) · **degraded** (it runs, quietly worse than the config promises), plus
 
 - Every **role** set in `agents.*` (not `fanout_max` / `fanout_tool` — not agents), plus
   `quality.reviewers` and `quality.review_skill`: discoverable in `~/.claude/agents`, the repo's
-  `.agents/agents`, or a plugin. Report each missing name and that it falls back to `general-purpose`
-  (a skill: skipped) — a panel missing agents reviews less and still reports a clean pass.
+  `.agents/agents`, or a plugin. Report each missing name and that it falls back per flow-core §6.6 — the installed agent
+  that fits, else `general-purpose` (a skill: skipped) — a panel missing agents reviews less and still reports a clean pass.
 - Harness cannot set a model per subagent → note that every `models.*` value degrades to inheritance.
 - **Where the live panel will go this session** (flow-core §4): a tool whose name ends in `panel_set` / `panel_patch` — namespaced by the harness (`mcp__panel__panel_set` on Claude Code) and possibly **deferred**, which reads as absent until the list of deferred tools is checked → the terminal draws the panel and no `panel.json` is written; genuinely absent → the panel is that file, as before. Neither is a fault — one line naming the tools as they are actually called here, or saying the file is the transport.
 

package/adapters/hermes/skills/flow-feat-build/SKILL.md

@@ -139,8 +139,8 @@ Take the shape from the **Access paths** table in `03-design.md`; a query matchi
 
 Execution mode:
 
-- **Single-thread (XS/S/M)**: implement yourself, step by step; subagents only as point consultants when blocked — `agents.architecture` from `FLOW.md` for layer questions, `agents.persistence` for query/mapping questions (`Agent general-purpose` if either is empty).
-- **Partial delegation (M/L with clear pieces)**: `Agent` for isolated endpoints, plus `agents.testing` from `FLOW.md` in parallel to prepare the test suite (`Agent general-purpose` if empty). Pass the full `03-design.md` in the prompt so agents do not invent things.
+- **Single-thread (XS/S/M)**: implement yourself, step by step. Delegate a piece when a specialist would do it clearly better than you — a UI component to a frontend agent in a mostly backend work, a migration to a persistence agent — not because it is tedious; consult one when blocked — `agents.architecture` from `FLOW.md` for layer questions, `agents.persistence` for query/mapping questions. Which agent each role resolves to, and whether you may pick past a named one, is flow-core §6.6. A delegated piece follows the brief rules of the next bullet and the one-writer rule of flow-core §6.
+- **Partial delegation (M/L with clear pieces)**: `Agent` for isolated endpoints, plus `agents.testing` from `FLOW.md` in parallel to prepare the test suite (empty → flow-core §6.6). Pass the full `03-design.md` in the prompt so agents do not invent things.
 
   A brief here states the **output** as explicitly as the input (flow-core §6):
   - **Name the path the agent writes**, and require it to **save after each finished piece, not at the end**. Code, tests and generated content are the deliverable; the report is not. Then **verify the file** instead of believing the report — a piece half-written on disk is recoverable, what only exists in the agent's context is lost the moment it is stopped.

package/adapters/hermes/skills/flow-feat-design/SKILL.md

@@ -175,7 +175,7 @@ Save the result at the top of `03-design.md` under "## What already exists". Des
 ## 4. Work
 
 1. Load the project's skills (`FLOW.md` section `conventions`).
-2. Launch **in parallel** by feature/project type. Agent = `agents.<role>` from `FLOW.md`; empty → `Agent general-purpose` with the role in the prompt.
+2. Launch **in parallel** by feature/project type. Agent = `agents.<role>` from `FLOW.md`; empty → the installed agent that fits, else `Agent general-purpose` with the role in the prompt (flow-core §6.6).
 
 | When | Agent | Task |
 |---|---|---|

package/adapters/hermes/skills/flow-feat-ship/SKILL.md

@@ -234,6 +234,29 @@ Only if `knowledge.read_staging` or `knowledge.save` is set; neither → skip wi
 3. **Combine staging + new findings** into a short list. Empty or only code-derivable → do not insist.
 4. 1+ relevant findings → ask the user whether to consolidate. Yes → run the consolidation of flow-core §0 (`read_staging`, then one decision and one `knowledge.save` per finding). No → do not insist.
 
+## 5.1 Specialists created (offer)
+
+Read `meta.json.specialists[]` (flow-core §6.6). **No entry with `useful: true` and `status` unset
+or `"later"` → skip this section and say nothing.** It comes after §5 on purpose: the MR/PR is open,
+the knowledge is saved, and what is left is whether an agent this work improvised deserves a name.
+
+1. **A harness with no file-defined agents** → the section does not exist; say so in one line if
+   there were useful specialists, so the brief is not mistaken for lost (it stays in `meta.json`).
+2. **One `AskUserQuestion`**, at most 4 entries, most useful first: its `name`, the role, the phase,
+   and in one line what it caught. Options: **Save as agent** · **Save and use it for `<role>`** ·
+   **No** · **Later**. The second option exists only when `agents.<role>` is empty.
+3. **Asked in every mode**, `auto` included: it writes to your agent configuration, outside the
+   tree, and that is never flow mechanics.
+4. **Save** → write the agent where and in the format your harness reads agents from (on Claude
+   Code, `~/.claude/agents/<name>.md`: frontmatter `name` and a one-line `description` of when to
+   use it, then the brief as the body — drop what only made sense for this ticket, keep the stack,
+   the checks and the typical mistakes). A file with that name already there → never overwrite:
+   suffix the name and say so. **Save and use it** → also write `agents.<role>: <name>` to the
+   active overlay (a harness-owned agent name, flow-core §0). Then `status: "saved"`, with the path.
+   **No** → `"declined"`, never offered again. **Later** → `"later"`, offered by the re-run of this
+   close.
+5. **One line on screen**: how many agents were saved and where.
+
 ## 5.5 A worktree does not own the tree its tools wrote into
 
 `meta.json.worktree` null → skip silently; there is nothing here that can go wrong.

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

@@ -136,6 +136,12 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
       "evidence": "the stop it came from",
       "status": "proposed" | "added" | "declined", "note": "" }
   ],
+  "specialists": [
+    { "name": "react-form-reviewer", "role": "frontend", "phase": "review",
+      "brief": "the full expert brief it was launched with",
+      "useful": true | false | null,
+      "status": null | "saved" | "declined" | "later", "path": null }
+  ],
   "origin": { "work": "{PREFIX}XXXXX", "followup": "F1" },
   "started_at": "2026-05-11T10:00:00Z",
   "updated_at": "2026-05-11T11:30:00Z",
@@ -152,6 +158,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **`followups`**: work a phase deliberately did **not** do here — a neighbouring defect found while building, a piece put out of scope while planning, a risk recorded but not mitigated, an edge case left unchecked, a prevention action from a postmortem. Written by the phase that parks it (asks nothing) when it clears the bar of flow-core §7, triaged **once** at `ship`'s Close behind a skeptic and a ceiling on how many may become questions, published in the MR/PR description while still open, and surfaced by `status`/`daily`/`next` — including from `_archive/` — until `declined` or `done`. Shape and rules: flow-core §7. `[]` when the work deferred nothing.
 - **`defaults_used`**: an empty `FLOW.md` key a phase resolved with its default instead of asking — written in `guided`/`auto`, where asking would breach the never-a-question contract (flow-core §0). Not an error and not deferred work: a record, aggregated by `/flow-doctor` across every work including `_archive/`, so a key that keeps defaulting can be pinned once instead of decided every time. `[]` when nothing defaulted.
 - **`conventions_candidates`**: rules the user taught **this repo's flow** while correcting a phase — *«not a listener, a message handler»*, *«the test command is `make test-unit`»*. Written by the phase that heard one, asking nothing, only when it would apply to an unrelated ticket in this repo; read by `review`'s idiom audit in the same work; offered once at `ship`'s Close (**Add to FLOW.md** / **Not a rule** / **Later**, or **Replace**), in every mode, because it edits a file in the tree. Never domain knowledge — that filter is unchanged. Shape and rules: flow-core §8. `[]` when the work taught nothing.
+- **`specialists`**: agents a phase **created for this work** because nothing installed fit a role, under `agents.selection: open` (flow-core §6.6) — the brief it wrote and ran on `general-purpose`, and whether anything it returned was kept. Nothing is written to the harness's agent folders while the work runs; `/flow-feat-ship` §5.1 offers the useful ones for saving as real agents once the MR/PR is open and the knowledge is saved, and records where each went.
 - **`origin`**: set when this work *is* a follow-up someone accepted — which work raised it and which entry. Lets `start` carry the recorded "why" into `01-context.md` instead of re-deriving it, and lets that entry move to `done` when this work does. Absent for a work that came straight from a ticket.
 - Ticket format follows `tracker.prefix`; empty → free-form.
 

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.77.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.78.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
@@ -97,8 +97,7 @@ a command relies on is simply absent in that session, and nothing else will repo
      "general-purpose", "phase": "review" }`. Asking here would break the never-a-question contract
      (§2); recording keeps the decision readable afterwards, and `/flow-doctor` aggregates it.
 
-  **The list, and it is short on purpose**: `agents.<role>` when a panel is about to improvise that
-  role on an M/L or sensitive diff · `quality.review_depth` after a review's cost line went over
+  **The list, and it is short on purpose**: `quality.review_depth` after a review's cost line went over
   `agents.budget_max` · `data.volumes` or `data.explain_cmd` when the query duel came back
   schema-only · `quality.functional_check` when `validate` found a runnable app and no way to drive
   it · `tracker.start_cmd`/`done_cmd`/`abandon_cmd` the first time a ticket could have been
@@ -156,8 +155,8 @@ improvises, `models.workers` for the parallel fan-out rounds, and `models.superv
 bounded waits of §6.5 — the last two falling back to `models.agents`. Empty, absent, or no section
 → everything runs on the model you were launched with, and you say nothing.
 
-- Pass the resolved value to every subagent you launch, **except** an agent named in `agents.<role>`,
-  which keeps the model its own definition sets.
+- Pass the resolved value to every subagent you launch, **except** an agent named in `agents.<role>`
+  or picked from the installed ones (§6.6), which keeps the model its own definition sets.
 - **You cannot switch your own model**, so no key names the phases the main agent performs itself.
   A phase that wants another model says it in one line at the handoff (`this step reads better on
   <value>, you are on <current>` → `/model <value>`), records it in the artifact, and continues.
@@ -555,6 +554,61 @@ moving.
 than to run — the brief, the round trip and the report are the whole of the saving. And anything you
 must *react to* mid-wait is not a wait at all: it is the work, and it stays here.
 
+### 6.6 — Which agent a role resolves to
+
+**The harness already tells you which agents are installed**, each with a line on what it is for,
+and choosing the one that fits a piece of work is something you do well without being told. A rule
+that answers every empty role with `general-purpose` throws that away: a repo with a frontend
+specialist installed and no `agents.frontend` got a generalist told to act like one. So wherever a
+command says *"`agents.<role>`, empty → `Agent general-purpose` with the role"*, it means this:
+
+1. **`agents.<role>` names an agent** → that agent, as always.
+2. **Empty** → the installed agent whose description fits the role **and this work's stack** best —
+   read the list your harness gives you, never a guess at a name. None fits clearly →
+   `general-purpose` with the role in the prompt, as before. An agent that fits the role but not the
+   stack (a PHP reviewer on a React diff) does not fit.
+
+**`agents.selection`** decides how far your judgement reaches:
+
+- **`configured`** (empty → this) — the two steps above. A role you named is never second-guessed.
+- **`open`** — a named role is a default, not an order: for a piece clearly outside what it
+  covers, or where an installed agent fits this piece plainly better, take that one. And a piece
+  **no role covers** — a UI component in a work whose roles are all backend — may go to the
+  specialist that does cover it. Every substitution is **one line in the phase artifact**: role,
+  the agent configured, the agent used, and why. Unrecorded, a panel that ran with other agents
+  reads exactly like the one you configured.
+
+  **Nothing installed fits → create the specialist for this work.** An installed agent is, in the
+  end, a brief with a name; what made it good is the brief. So instead of *"act as frontend"*, write
+  the one an expert would carry — the stack and its versions as this repo uses them, what to check
+  in this piece, the mistakes typical of it, and the report contract of this section — and launch
+  `general-purpose` with it. Nothing is written to the harness's agent folders: the specialist lives
+  for the brief, and it works on every harness, because every one has a general-purpose agent.
+  Record it in `meta.json.specialists[]`:
+
+  `{ "name": "react-form-reviewer", "role": "frontend", "phase": "review", "brief": "<the full text
+  you sent>", "useful": null, "status": null }`
+
+  Once its result is in, set `useful`: `true` when something it returned was kept — a finding
+  accepted, a piece merged into the diff — `false` otherwise. Only a useful one is ever offered for
+  saving, and only **when the work ends** (`/flow-feat-ship` §5.1), never mid-phase: by then the
+  MR/PR is open and it is plain which of them earned a place among your agents.
+
+Three things this never touches, in either mode:
+
+- **The review roster** (`quality.review_skill` / `quality.reviewers`) runs as defined, with no
+  substitutions: its value is being the same panel every time, so a result can be compared.
+- **The agents that are `general-purpose` by design** — challengers, skeptics, the completeness
+  critic, the blinded contract check. They are generalists *on purpose*: a specialist brings the
+  assumptions the blinding is there to strip. A step that writes `general-purpose` with no role
+  behind it means exactly that.
+- **The budget.** A picked agent counts against `agents.budget_max` like any other. Like a named
+  agent it keeps its own model (§1), and `models.agents` reaches it only when it has none.
+
+Record what you picked where a default would be recorded (§0): *"`agents.frontend` empty → used
+`react-expert` (installed)"*. That line is also the evidence for writing the role down when the
+next stop offers it.
+
 ## 7. Deferred work — `followups[]`
 
 Every chain in this plugin reaches moments where the right call is **not to do it here**: a build

package/adapters/opencode/commands/flow-bug-ship.md

@@ -184,6 +184,7 @@ nothing was measured. A slowness bug is the case where this comment *is* the pro
 - **Cross-repo reminder**: for each `meta.json.related_repos` entry not `done`: *"you've shipped the `<this-repo>` part; `<repo>` still needs: `<scope>` → go there and run `/flow-bug-start <TICKET>` (or `/flow-feat-start`)"*. flow only reminds; this is not a hard gate.
 - **Cross-repo contract handoff**: for each such entry with `contract_handoff: "pending"` — the fix changed a surface that sibling consumes — hand the new shape over as `/flow-feat-ship` §6.3 (publish the **literal** shape to the tracker ticket, mandatory preview in every autonomy mode, then record `published → <location>`; versioned-file fallback when there is no tracker). A bug flow has no §"External contracts": take the literal from the fix itself — the actual key, code, route or event the code now emits — read it off the code, never from memory.
 - **Follow-up triage — `/flow-feat-ship` §6.4, in full and unchanged.** Read `meta.json.followups[]`; nothing `proposed` → skip silently. Otherwise §6.4 step 0 first — **3 or more candidates go to a skeptic** whose job is to refute that each deserves a ticket, and only the strongest `tracker.followup_ask_max` (empty → **2**) reach the user (flow-core §7) — then one batched `AskUserQuestion` (**Do it** / **Not worth it** / **Later**; `decision` entries asked as their question, `tooling` and everything `log`ged never asked), the accepted ones get their tracker issue created (outward-facing → **asks in every mode**), the logged ones nothing but `status: "logged"` in `meta.json`, then one offer to start the first. A bug flow is where the gate earns its keep: the prevention actions `/flow-bug-postmortem` wrote, the neighbouring bugs `/flow-bug-validate` found and the similar-risk patterns `/flow-bug-fix` flagged all land here — half a dozen of them, from one fix, and «similar risk elsewhere» that no skeptic ever read is exactly the entry that turns a closed bug into six open questions. Repeat for anything still `proposed` on the re-run that confirms the merge.
+- **Specialists created — `/flow-feat-ship` §5.1, in full and unchanged.** Read `meta.json.specialists[]` (flow-core §6.6); nothing `useful` and pending → skip silently. Otherwise one batched offer to save each as an agent, after the MR/PR and after the knowledge `/flow-bug-postmortem` §4 already consolidated — asked in every mode, never overwriting an agent that exists.
 - **Conventions learned — `/flow-feat-ship` §6.4bis, in full and unchanged.** Read `meta.json.conventions_candidates[]` (flow-core §8); nothing pending → skip silently. Otherwise: drop what `FLOW.md` already says, then one batched `AskUserQuestion` (**Add to FLOW.md** / **Not a rule** / **Later**, or **Replace** when it contradicts a line that is there). Asked in every mode — it edits a file in the tree. A fix is where the corrections land hardest: *«never mock the repository in that layer»*, *«the regression test goes next to the unit test, not in the functional suite»* — said once inside `bug:fix`, and proposed again in the next incident unless they reach the file.
 - **Close the follow-up that started this work.** `meta.json.origin` set and this ship moved `phase` to `done` → open the originating work's `meta.json` (live folder or `_archive/`) and set that `followups[]` entry to `status: "done"`. Best-effort: the originating folder is gone or unreadable → warn in one line and continue, never block. Without this the entry stays `in_progress` forever and `status`/`daily` keep reporting work that is finished.
 - **Only once `phase` is `done`**: delete the candidate anchor `/flow-bug-review §1.5` left behind — `git update-ref -d refs/flow/candidate/<TICKET>`. No question: local, never pushed, and the gate that needed it has run.

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

@@ -194,8 +194,8 @@ refuse) · **degraded** (it runs, quietly worse than the config promises), plus
 
 - Every **role** set in `agents.*` (not `fanout_max` / `fanout_tool` — not agents), plus
   `quality.reviewers` and `quality.review_skill`: discoverable in `~/.claude/agents`, the repo's
-  `.agents/agents`, or a plugin. Report each missing name and that it falls back to `general-purpose`
-  (a skill: skipped) — a panel missing agents reviews less and still reports a clean pass.
+  `.agents/agents`, or a plugin. Report each missing name and that it falls back per flow-core §6.6 — the installed agent
+  that fits, else `general-purpose` (a skill: skipped) — a panel missing agents reviews less and still reports a clean pass.
 - Harness cannot set a model per subagent → note that every `models.*` value degrades to inheritance.
 - **Where the live panel will go this session** (flow-core §4): a tool whose name ends in `panel_set` / `panel_patch` — namespaced by the harness (`mcp__panel__panel_set` on Claude Code) and possibly **deferred**, which reads as absent until the list of deferred tools is checked → the terminal draws the panel and no `panel.json` is written; genuinely absent → the panel is that file, as before. Neither is a fault — one line naming the tools as they are actually called here, or saying the file is the transport.
 

package/adapters/opencode/commands/flow-feat-build.md

@@ -137,8 +137,8 @@ Take the shape from the **Access paths** table in `03-design.md`; a query matchi
 
 Execution mode:
 
-- **Single-thread (XS/S/M)**: implement yourself, step by step; subagents only as point consultants when blocked — `agents.architecture` from `FLOW.md` for layer questions, `agents.persistence` for query/mapping questions (`Agent general-purpose` if either is empty).
-- **Partial delegation (M/L with clear pieces)**: `Agent` for isolated endpoints, plus `agents.testing` from `FLOW.md` in parallel to prepare the test suite (`Agent general-purpose` if empty). Pass the full `03-design.md` in the prompt so agents do not invent things.
+- **Single-thread (XS/S/M)**: implement yourself, step by step. Delegate a piece when a specialist would do it clearly better than you — a UI component to a frontend agent in a mostly backend work, a migration to a persistence agent — not because it is tedious; consult one when blocked — `agents.architecture` from `FLOW.md` for layer questions, `agents.persistence` for query/mapping questions. Which agent each role resolves to, and whether you may pick past a named one, is flow-core §6.6. A delegated piece follows the brief rules of the next bullet and the one-writer rule of flow-core §6.
+- **Partial delegation (M/L with clear pieces)**: `Agent` for isolated endpoints, plus `agents.testing` from `FLOW.md` in parallel to prepare the test suite (empty → flow-core §6.6). Pass the full `03-design.md` in the prompt so agents do not invent things.
 
   A brief here states the **output** as explicitly as the input (flow-core §6):
   - **Name the path the agent writes**, and require it to **save after each finished piece, not at the end**. Code, tests and generated content are the deliverable; the report is not. Then **verify the file** instead of believing the report — a piece half-written on disk is recoverable, what only exists in the agent's context is lost the moment it is stopped.

package/adapters/opencode/commands/flow-feat-design.md

@@ -173,7 +173,7 @@ Save the result at the top of `03-design.md` under "## What already exists". Des
 ## 4. Work
 
 1. Load the project's skills (`FLOW.md` section `conventions`).
-2. Launch **in parallel** by feature/project type. Agent = `agents.<role>` from `FLOW.md`; empty → `Agent general-purpose` with the role in the prompt.
+2. Launch **in parallel** by feature/project type. Agent = `agents.<role>` from `FLOW.md`; empty → the installed agent that fits, else `Agent general-purpose` with the role in the prompt (flow-core §6.6).
 
 | When | Agent | Task |
 |---|---|---|

package/adapters/opencode/commands/flow-feat-ship.md

@@ -232,6 +232,29 @@ Only if `knowledge.read_staging` or `knowledge.save` is set; neither → skip wi
 3. **Combine staging + new findings** into a short list. Empty or only code-derivable → do not insist.
 4. 1+ relevant findings → ask the user whether to consolidate. Yes → run the consolidation of flow-core §0 (`read_staging`, then one decision and one `knowledge.save` per finding). No → do not insist.
 
+## 5.1 Specialists created (offer)
+
+Read `meta.json.specialists[]` (flow-core §6.6). **No entry with `useful: true` and `status` unset
+or `"later"` → skip this section and say nothing.** It comes after §5 on purpose: the MR/PR is open,
+the knowledge is saved, and what is left is whether an agent this work improvised deserves a name.
+
+1. **A harness with no file-defined agents** → the section does not exist; say so in one line if
+   there were useful specialists, so the brief is not mistaken for lost (it stays in `meta.json`).
+2. **One `AskUserQuestion`**, at most 4 entries, most useful first: its `name`, the role, the phase,
+   and in one line what it caught. Options: **Save as agent** · **Save and use it for `<role>`** ·
+   **No** · **Later**. The second option exists only when `agents.<role>` is empty.
+3. **Asked in every mode**, `auto` included: it writes to your agent configuration, outside the
+   tree, and that is never flow mechanics.
+4. **Save** → write the agent where and in the format your harness reads agents from (on Claude
+   Code, `~/.claude/agents/<name>.md`: frontmatter `name` and a one-line `description` of when to
+   use it, then the brief as the body — drop what only made sense for this ticket, keep the stack,
+   the checks and the typical mistakes). A file with that name already there → never overwrite:
+   suffix the name and say so. **Save and use it** → also write `agents.<role>: <name>` to the
+   active overlay (a harness-owned agent name, flow-core §0). Then `status: "saved"`, with the path.
+   **No** → `"declined"`, never offered again. **Later** → `"later"`, offered by the re-run of this
+   close.
+5. **One line on screen**: how many agents were saved and where.
+
 ## 5.5 A worktree does not own the tree its tools wrote into
 
 `meta.json.worktree` null → skip silently; there is nothing here that can go wrong.

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

@@ -134,6 +134,12 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
       "evidence": "the stop it came from",
       "status": "proposed" | "added" | "declined", "note": "" }
   ],
+  "specialists": [
+    { "name": "react-form-reviewer", "role": "frontend", "phase": "review",
+      "brief": "the full expert brief it was launched with",
+      "useful": true | false | null,
+      "status": null | "saved" | "declined" | "later", "path": null }
+  ],
   "origin": { "work": "{PREFIX}XXXXX", "followup": "F1" },
   "started_at": "2026-05-11T10:00:00Z",
   "updated_at": "2026-05-11T11:30:00Z",
@@ -150,6 +156,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **`followups`**: work a phase deliberately did **not** do here — a neighbouring defect found while building, a piece put out of scope while planning, a risk recorded but not mitigated, an edge case left unchecked, a prevention action from a postmortem. Written by the phase that parks it (asks nothing) when it clears the bar of flow-core §7, triaged **once** at `ship`'s Close behind a skeptic and a ceiling on how many may become questions, published in the MR/PR description while still open, and surfaced by `status`/`daily`/`next` — including from `_archive/` — until `declined` or `done`. Shape and rules: flow-core §7. `[]` when the work deferred nothing.
 - **`defaults_used`**: an empty `FLOW.md` key a phase resolved with its default instead of asking — written in `guided`/`auto`, where asking would breach the never-a-question contract (flow-core §0). Not an error and not deferred work: a record, aggregated by `/flow-doctor` across every work including `_archive/`, so a key that keeps defaulting can be pinned once instead of decided every time. `[]` when nothing defaulted.
 - **`conventions_candidates`**: rules the user taught **this repo's flow** while correcting a phase — *«not a listener, a message handler»*, *«the test command is `make test-unit`»*. Written by the phase that heard one, asking nothing, only when it would apply to an unrelated ticket in this repo; read by `review`'s idiom audit in the same work; offered once at `ship`'s Close (**Add to FLOW.md** / **Not a rule** / **Later**, or **Replace**), in every mode, because it edits a file in the tree. Never domain knowledge — that filter is unchanged. Shape and rules: flow-core §8. `[]` when the work taught nothing.
+- **`specialists`**: agents a phase **created for this work** because nothing installed fit a role, under `agents.selection: open` (flow-core §6.6) — the brief it wrote and ran on `general-purpose`, and whether anything it returned was kept. Nothing is written to the harness's agent folders while the work runs; `/flow-feat-ship` §5.1 offers the useful ones for saving as real agents once the MR/PR is open and the knowledge is saved, and records where each went.
 - **`origin`**: set when this work *is* a follow-up someone accepted — which work raised it and which entry. Lets `start` carry the recorded "why" into `01-context.md` instead of re-deriving it, and lets that entry move to `done` when this work does. Absent for a work that came straight from a ticket.
 - Ticket format follows `tracker.prefix`; empty → free-form.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-workflows",
-  "version": "0.77.0",
+  "version": "0.78.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": {

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.77.0",
+  "version": "0.78.0",
   "author": {
     "name": "Alberto Vioque",
     "email": "mashware@gmail.com"

package/plugins/flow/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.78.0 — The specialist was installed; the flow asked for a generalist  ·  2026-09-23
+
+**In short**
+- **An empty agent role now goes to the installed agent that fits it.** The harness already lists
+  your agents with what each is for; a role you left blank picks from that list, by role and by
+  stack, and falls back to `general-purpose` only when nothing fits clearly.
+- **`agents.selection: open` lets the model pick past the roles you named** — a better-fitting
+  installed agent for a piece, or a specialist for a piece no role covers — recording each
+  substitution in the phase artifact. Empty keeps your roles as orders.
+- **With `open`, a missing specialist is created for the work** — an expert brief written for this
+  stack and this piece, run on the general-purpose agent — and **offered for saving as a real agent
+  when `ship` closes**, after the MR/PR and the knowledge save, only if it contributed something.
+- **Flow stops offering to fill agent roles mid-phase**: they are optional overrides now, not gaps.
+- **`build` may delegate on small works too**, when a specialist would clearly do a piece better,
+  instead of only consulting one when blocked.
+
+Left alone, a current model reads the agent list and hands a React component to the React expert.
+Inside a flow command it could not: every empty role said `general-purpose`, so the command's text
+overrode the judgement the harness was set up to use. The review roster is untouched — it runs as
+defined in both modes — and the challengers and blinded checks stay generalists on purpose.
+
 ## v0.77.0 — The steps of the MR/PR you are on are on the panel  ·  2026-09-22
 
 **In short**

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

@@ -170,8 +170,16 @@ scripts, Gradle, dotnet, Xcode, Flutter, pyproject, Cargo, go.mod) and reports w
 Role→agent map for steps that delegate to a specialist (`design`, `investigate`,
 `validate`, `plan`, `build`, `fix`, `watch`, and the area reinforcements in `review`). Agents
 must exist and be discoverable on the machine (`~/.claude/agents`, `.agents/agents` in the repo, or
-another plugin) — this only states **which** one to invoke, it does not create it. **Empty role = the command uses
-`Agent general-purpose` with the role in the prompt, or skips the step if it was optional.**
+another plugin) — this only states **which** one to invoke, it does not create it. **Empty role = the command picks
+the installed agent that fits the role and the stack, else `Agent general-purpose` with the role in the prompt, or skips
+the step if it was optional** (flow-core §6.6).
+
+- `selection:`      # your roles as orders or as defaults. Empty = `configured` (named roles used as is); `open` = the model may pick past them
+                    #   Empty roles are picked from the installed agents either way. `open` = a named role is a default: the model
+                    #   may use an installed agent that fits a piece plainly better, or a specialist for a piece no role
+                    #   covers, and records each substitution. Nothing installed fits → it writes an expert brief and runs it
+                    #   on the general-purpose agent; a useful one is offered for saving as an agent when `ship` closes.
+                    #   Never touches `quality.reviewers`/`review_skill`
 
 - `architecture:`   # design/layers/architecture
 - `persistence:`    # DB/ORM/mappings/migrations/queries