flow-workflows 0.77.0 → 0.79.0

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

@@ -230,6 +230,54 @@ 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`, a one-line `description` of when to
+   use it and `created_by: flow` (flow-core §6.7 reads 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.2 What the agents missed (offer)
+
+Read `meta.json.agent_lessons[]` (flow-core §6.7). `agents.learn: off`, or no entry with `status`
+unset or `"later"` → skip this section and say nothing. Last of the three offers on purpose: the
+MR/PR is open, the knowledge is saved, the specialists have their files — now the agents that
+exist get what this work showed they lacked.
+
+1. **Group by agent**, and resolve each agent's file (`~/.claude/agents`, the repo's agent folder,
+   the overlay's harness equivalent). Plugin- or marketplace-installed, a skill, or no file →
+   `status: "not-editable"` with which, and one line on screen; the lesson stays readable in
+   `meta.json`.
+2. **Apply the size rules of §6.7 before asking** — drop what the file already says (and turn it
+   into the "promote to a check" option instead), consolidate when the section is at
+   `agents.lessons_max` — so the question shows the section as it would end up, not a line to append.
+3. **One `AskUserQuestion`**, one entry per agent (at most 4, most lessons first): the agent, the
+   evidence in one line per lesson, and the resulting `## Lessons from past work` section. Options:
+   **Write it** · **No** · **Later**. Your agents are asked **in every mode**; agents with
+   `created_by: flow` are asked in `manual` and written directly in `guided`/`auto`.
+4. **Write it** → back up the file (§6.7), replace only that section, record the path and the
+   backup in each entry, `status: "written"`. A file tracked by the repo is left modified in the
+   tree, uncommitted, and said so in one line: it is the team's file and the team's commit.
+   **No** → `"declined"`. **Later** → `"later"`, offered again by the re-run of this close or by
+   `/flow:work:respond`.
+5. **One line on screen**: how many agents learned something, and where the backups are.
+
 ## 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,19 @@ 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 }
+  ],
+  "agent_lessons": [
+    { "agent": "query-reviewer", "signal": "missed" | "produced" | "human",
+      "phase": "review", "evidence": "finding or thread, one line, file:line or URL",
+      "lesson": "one imperative line, general, no ticket id",
+      "status": null | "written" | "declined" | "later" | "not-editable",
+      "path": null, "backup": null }
+  ],
   "origin": { "work": "{PREFIX}XXXXX", "followup": "F1" },
   "started_at": "2026-05-11T10:00:00Z",
   "updated_at": "2026-05-11T11:30:00Z",
@@ -148,6 +161,8 @@ 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.
+- **`agent_lessons`**: what an agent was shown to lack **by evidence from outside it** — a surviving finding in its category that it did not report, a finding in code it wrote, a human review thread in its category that ended in a change (flow-core §6.7). Written by `review` and `respond` asking nothing; offered for the agent's file by `/flow:feat:ship` §5.2 and at `respond`'s close, with a backup under `agent-backups/`, never on plugin-installed agents or skills.
 - **`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/commands/flow/work/respond.toml

@@ -161,12 +161,13 @@ After the push (or immediately, for reply-only threads), post the agreed respons
 ## 8. Log, loop, and domain knowledge
 
 - **Artifact.** Append this round to `.claude/work/<TICKET>/08-feedback.md` (create it the first round). Per round: the date, and per thread — location, category, decision (reply-only / code-change / defer / held / handled-by-user), the reply posted, and the commit/edit if any. **For a `G` thread, the measurement table goes in whole** — variants, plans, timings, keys served, how the data set was built — plus what stayed unresolved. A later round reads it to avoid re-litigating settled threads.
+- **What the panel missed.** Each thread this round that ended in a code change and falls in a category a `quality.reviewers` member or a named `agents.<role>` owns → one `meta.json.agent_lessons[]` row, `signal: "human"` (flow-core §6.7), when the lesson passes that section's test. A human had to catch what the agent is there to catch; that is the strongest evidence this flow ever gets that an agent needs a line.
 - **Knowledge.** `knowledge.stage` is set and the debate produced a non-obvious "why" worth keeping (a reviewer-surfaced constraint, an integration gotcha, a decision that reversed the design) → `knowledge.stage` for this branch (silence by default; only on a clear signal). Consolidated at `knowledge.save` time.
 - **Count the round in the artifact, not in your head.** Increment `respond_rounds` for this MR/PR in `meta.json` (its `mrs[]` entry; work-level when there are no `mrs`) in the same write that appends the round to `08-feedback.md` — the §1 ceiling is worth exactly as much as this counter. Lightweight mode: nothing to write, no ceiling to enforce; say so once and carry on.
 - **Re-post the performance comment when this round changed a measured path.** A push that touches a query or an entry point already benchmarked (`/flow:feat:ship` §4.3) makes the standing comment wrong — and a wrong number is worse than none. Re-run those rows against the same base and post a new comment; never edit the old one. Nothing measured changed → post nothing.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5). Not in lightweight mode.
 - **A repeated answer spends the budget and buys nothing.** A reply this round that says what an earlier round said — same position, same reasoning, no new evidence → stop **now**, before the ceiling, and escalate that thread by name: your position, the reviewer's counter, the fact that neither has moved.
-- **Loop / close.** Threads open awaiting the reviewer → tell the user the ball is in their court; a later `/flow:work:respond` picks up the next round. All threads answered and code pushed → summarize: threads addressed, code changes made, threads **ready for the user to resolve**, follow-up tickets proposed. Once approved and merged, the normal `/flow:feat:ship §6` / `/flow:bug:ship` close applies (and `/flow:work:watch` for the post-deploy).
+- **Loop / close.** Threads open awaiting the reviewer → tell the user the ball is in their court; a later `/flow:work:respond` picks up the next round. All threads answered and code pushed → **offer the agent lessons first** — `/flow:feat:ship §5.2`, in full and unchanged, over the rows still pending (this round's and any earlier ship left as `later`) — then summarize: threads addressed, code changes made, threads **ready for the user to resolve**, follow-up tickets proposed. Once approved and merged, the normal `/flow:feat:ship §6` / `/flow:bug:ship` close applies (and `/flow:work:watch` for the post-deploy).
 
 ## Notes
 

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.79.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,124 @@ 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.
+
+### 6.7 — An agent that missed something learns it, once
+
+A reviewer that let a defect through will let the same one through next time: nothing it is given
+changes between works. The fix is to its definition, and the evidence that it needs one arrives
+here, in the flow, where somebody else caught what it did not. So a phase that holds that evidence
+records it, and the work's close offers to write it into the agent.
+
+**Only evidence from outside the agent counts.** An agent judging its own performance almost
+always finds it good, and a lesson learned from that is a transient failure written down as a
+permanent rule. Three signals, and nothing else:
+
+- **Missed** — a finding that survived (§6 verification, or the user's acceptance) falls squarely in
+  the category a panel member or a named `agents.<role>` owns, and **that agent did not report it**
+  while another source did: the built-in review, another pass, a reinforcement, a human.
+- **Produced** — a surviving finding sits in code a delegated agent wrote (a `build` piece, the
+  testing agent's suite): the lesson goes to the agent that wrote it.
+- **Human caught** — a reviewer's thread in `/flow-work-respond` that ended in a code change, in a
+  category a panel member owns: the whole panel missed it, and the owner is the one to learn.
+
+**The same test as a convention (§8), aimed at the agent.** Would this lesson help that agent on an
+unrelated work in its domain? No → it belongs to this ticket, record nothing. Yes, but it is a fact
+about the **repo** rather than the agent's craft (*"the test command is `make test-unit`"*) → it is a
+`conventions_candidates[]` row, not a lesson. Yes, and it is about the craft (*"check that every
+state change inside a loop is flushed once, not per iteration"*) → a lesson.
+
+Record it in `meta.json.agent_lessons[]`, asking nothing:
+
+`{ "agent": "query-reviewer", "signal": "missed" | "produced" | "human", "phase":
+"review", "evidence": "<finding or thread, one line, with file:line or URL>", "lesson": "<one
+imperative line, general, no ticket id>", "status": null }`
+
+**What is never edited**, and the lesson stays recorded in `meta.json` for you to read:
+
+- an agent installed from a plugin or a marketplace — it is someone else's file, and the next
+  update would overwrite the edit anyway;
+- a skill (`quality.review_skill`) — it orchestrates agents rather than being one;
+- `general-purpose` and the improvised specialists of §6.6 that were not saved — no file to edit.
+
+**Writing it — only at the work's close** (`/flow-feat-ship` §5.2, `/flow-work-respond` §8), with
+`agents.learn` (empty → `offer`; `off` → nothing is recorded or offered):
+
+- **Your agents** (written by hand, or shared through the repo) → shown as a diff and written only
+  on an explicit yes, **in every mode**: it is your configuration, and in the repo it is your team's.
+- **Agents flow created** (§6.6 saved with `created_by: flow` in their frontmatter) → the same
+  question in `manual`; in `guided`/`auto` written directly and reported in one line.
+
+**How it is kept small** — without this, the file grows one line per incident until the rules
+nobody reads crowd out the ones that matter:
+
+1. Lessons live in one section at the end of the file, `## Lessons from past work`, one line each.
+   The rest of the file is never rewritten.
+2. **Already there, in any wording → the lesson is not added.** The agent had the rule and missed
+   anyway, which says the rule is weak, not absent: offer instead to move it out of the lessons
+   into the body of the brief, rewritten as a check the agent must perform.
+3. **At `agents.lessons_max` lines (empty → 10), adding one means consolidating first**: merge
+   lines that say the same thing, generalise two narrow ones into the rule they share, drop one a
+   later lesson supersedes. Show the section before and after in the same question.
+4. **Before any edit, copy the file** to `.claude/work/<work>/agent-backups/<name>.md` and record
+   the path in the lesson's entry. Undoing is copying it back. A file is never deleted.
+
+Then `status`: `"written"` (with the path) · `"declined"` (never offered again) · `"later"` ·
+`"not-editable"` (one of the three cases above, with which).
+
 ## 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-review/SKILL.md

@@ -234,6 +234,7 @@ Cost line: count every subagent this command launched — reviewers = §2.1 buil
 - Without blockers: `phase = "review"`, add to `phases_done`. Suggest `/flow-bug-postmortem` (M/L) or `/flow-bug-ship` (XS/S).
 - **Record *what* you reviewed, and separately what you changed after reading it** — `/flow-feat-review` §9, unchanged: `reviewed_sha` = the **candidate** of §1.5 (the revision the reviewers read, never `git rev-parse HEAD`, which by now holds this round's own fixes), and `fixed_sha` = `git rev-parse HEAD` after those fixes, empty when the round applied none. `phases_done` says a review happened; these two say on which tree and what moved afterwards, and `/flow-bug-ship §0` reads both against what is being pushed. Only when the phase advances: a review that ended in blockers reviewed nothing that stands.
 - **Record which pass found what** — `/flow-feat-review §9`, unchanged: one `meta.json.review_findings[]` entry per finding **per source** (`{ round, origin, severity, file, discarded_by_skeptic }`, no finding text), written by `flow review --record` when the CLI ran the panel and by this Close when the agentic panel did. `flow cost` reads them back per origin, and the retirement rule is the same: a pass with no exclusive surviving finding across twenty reviews comes out of the command.
+- **Record what the agents missed** — `/flow-feat-review §9`, unchanged: surviving findings in a category a panel member or named `agents.<role>` owns and did not report → `meta.json.agent_lessons[]` rows (flow-core §6.7), asking nothing. A fix is where this pays most: the defect already reached production once, and the reviewer that owns its category let it.
 - **Stage what the review taught** (`knowledge.stage` set; silence by default). Review is where a project teaches the most and, until now, the one phase that never staged — a work with three review rounds and seventeen blockers produced zero knowledge cards because nothing asked for them while they were in context. Candidates are findings about the **domain or the codebase's real behaviour**, not about this diff: a library that does other than its name says, a test disguise that kept the suite green over a live defect, a module rule the reviewers had to cite from its own prose, a measurement. A blocker fixed here is not knowledge; *why it was written wrong* may be. Same evidence rule as `/flow-feat-design` §8 — one line of evidence per finding or it is not staged. One call per finding, one line to the user («Staged N finding(s) for `postmortem`/`ship`»). Never `knowledge.save` here.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
 - Stop body (after the flow-core §3 header): the findings that survived and what you did with each, plus the same Cost line as the Summary: "- Cost: <n>/<budget_max> subagents launched (<k> reviewers · <m> reinforcements · <s> skeptics), tier <light|proportional|full>".

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

@@ -186,6 +186,8 @@ 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.
+- **What the agents missed — `/flow-feat-ship` §5.2, in full and unchanged.** Read `meta.json.agent_lessons[]` (flow-core §6.7); `agents.learn: off` or nothing pending → skip silently. Otherwise one question per agent with the resulting lessons section, backup first, your agents asked in every mode.
 - **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-review/SKILL.md

@@ -386,6 +386,7 @@ Write `.claude/work/<TICKET>/06-review.md`. The `Cost:` line of `## Summary` is
   **The retirement rule, written down before the data arrives** so it cannot be argued backwards later: a pass that contributes **no exclusive surviving finding across twenty reviews** is removed from this command. Zero is zero, and the decision is made against the number rather than against whoever is most attached to the pass.
 - **Stage what the review taught** (`knowledge.stage` set; silence by default). Review is where a project teaches the most and, until now, the one phase that never staged — a work with three review rounds and seventeen blockers produced zero knowledge cards because nothing asked for them while they were in context. Candidates are findings about the **domain or the codebase's real behaviour**, not about this diff: a library that does other than its name says, a test disguise that kept the suite green over a live defect, a module rule the reviewers had to cite from its own prose, a measurement. A blocker fixed here is not knowledge; *why it was written wrong* may be. Same evidence rule as `/flow-feat-design` §8 — one line of evidence per finding or it is not staged. One call per finding, one line to the user («Staged N finding(s) for `ship`»). Never `knowledge.save` here.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
-- **Configuration this phase earned the right to ask about** (flow-core §0, `manual` only, at most one key per work, as an extra option on this same stop — never a question of its own): a role the panel had to improvise on an M/L or sensitive diff → `agents.<role>`; a `Cost:` line that went over `agents.budget_max` → `quality.review_depth`. In `guided`/`auto` neither is asked: the default is taken and recorded in `meta.json.defaults_used[]`.
+- **Record what the agents missed** (flow-core §6.7, `agents.learn` not `off`; asking nothing): for each finding that survived, the panel member or named `agents.<role>` whose category it falls in and who did not report it, and the delegated `build` agent whose code it sits in → one `meta.json.agent_lessons[]` row each, only when the lesson passes the §6.7 test. The origins §2.1 carried are what make this possible — a finding with no origin teaches nobody.
+- **Configuration this phase earned the right to ask about** (flow-core §0, `manual` only, at most one key per work, as an extra option on this same stop — never a question of its own): a `Cost:` line that went over `agents.budget_max` → `quality.review_depth`. In `guided`/`auto` neither is asked: the default is taken and recorded in `meta.json.defaults_used[]`.
 - Report findings and next step **following the stop header** (flow-core §3) **when this is a stop**; in `guided`/`auto` with a clean gate the next command runs in this same turn, so this goes to `06-review.md` and the turn opens with the call that chains — the `Cost:` line then travels to the stop the run does reach, added to that phase's own. Include it once. Body: the findings that **survived** verification and what you did with each — a blocker, an applied fix, a rejection with its reason. Corrections to the reviewers' own reports go to `06-review.md`, not here.
 - **Autonomy handoff.** Only when there are **no blockers and no unresolved high-severity findings** — with any of those, stop in every mode (hard gate). Clean: in `manual`, propose `/flow-feat-validate` with a single `AskUserQuestion` and invoke it on confirmation; in `guided`/`auto`, **chain into `/flow-feat-validate` automatically** in this same turn. Never chain into `/flow-feat-ship` from here — ship is reached through `validate`.

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

@@ -234,6 +234,54 @@ 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`, a one-line `description` of when to
+   use it and `created_by: flow` (flow-core §6.7 reads 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.2 What the agents missed (offer)
+
+Read `meta.json.agent_lessons[]` (flow-core §6.7). `agents.learn: off`, or no entry with `status`
+unset or `"later"` → skip this section and say nothing. Last of the three offers on purpose: the
+MR/PR is open, the knowledge is saved, the specialists have their files — now the agents that
+exist get what this work showed they lacked.
+
+1. **Group by agent**, and resolve each agent's file (`~/.claude/agents`, the repo's agent folder,
+   the overlay's harness equivalent). Plugin- or marketplace-installed, a skill, or no file →
+   `status: "not-editable"` with which, and one line on screen; the lesson stays readable in
+   `meta.json`.
+2. **Apply the size rules of §6.7 before asking** — drop what the file already says (and turn it
+   into the "promote to a check" option instead), consolidate when the section is at
+   `agents.lessons_max` — so the question shows the section as it would end up, not a line to append.
+3. **One `AskUserQuestion`**, one entry per agent (at most 4, most lessons first): the agent, the
+   evidence in one line per lesson, and the resulting `## Lessons from past work` section. Options:
+   **Write it** · **No** · **Later**. Your agents are asked **in every mode**; agents with
+   `created_by: flow` are asked in `manual` and written directly in `guided`/`auto`.
+4. **Write it** → back up the file (§6.7), replace only that section, record the path and the
+   backup in each entry, `status: "written"`. A file tracked by the repo is left modified in the
+   tree, uncommitted, and said so in one line: it is the team's file and the team's commit.
+   **No** → `"declined"`. **Later** → `"later"`, offered again by the re-run of this close or by
+   `/flow-work-respond`.
+5. **One line on screen**: how many agents learned something, and where the backups are.
+
 ## 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,19 @@ 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 }
+  ],
+  "agent_lessons": [
+    { "agent": "query-reviewer", "signal": "missed" | "produced" | "human",
+      "phase": "review", "evidence": "finding or thread, one line, file:line or URL",
+      "lesson": "one imperative line, general, no ticket id",
+      "status": null | "written" | "declined" | "later" | "not-editable",
+      "path": null, "backup": null }
+  ],
   "origin": { "work": "{PREFIX}XXXXX", "followup": "F1" },
   "started_at": "2026-05-11T10:00:00Z",
   "updated_at": "2026-05-11T11:30:00Z",
@@ -152,6 +165,8 @@ 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.
+- **`agent_lessons`**: what an agent was shown to lack **by evidence from outside it** — a surviving finding in its category that it did not report, a finding in code it wrote, a human review thread in its category that ended in a change (flow-core §6.7). Written by `review` and `respond` asking nothing; offered for the agent's file by `/flow-feat-ship` §5.2 and at `respond`'s close, with a backup under `agent-backups/`, never on plugin-installed agents or skills.
 - **`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/skills/flow-work-respond/SKILL.md

@@ -165,12 +165,13 @@ After the push (or immediately, for reply-only threads), post the agreed respons
 ## 8. Log, loop, and domain knowledge
 
 - **Artifact.** Append this round to `.claude/work/<TICKET>/08-feedback.md` (create it the first round). Per round: the date, and per thread — location, category, decision (reply-only / code-change / defer / held / handled-by-user), the reply posted, and the commit/edit if any. **For a `G` thread, the measurement table goes in whole** — variants, plans, timings, keys served, how the data set was built — plus what stayed unresolved. A later round reads it to avoid re-litigating settled threads.
+- **What the panel missed.** Each thread this round that ended in a code change and falls in a category a `quality.reviewers` member or a named `agents.<role>` owns → one `meta.json.agent_lessons[]` row, `signal: "human"` (flow-core §6.7), when the lesson passes that section's test. A human had to catch what the agent is there to catch; that is the strongest evidence this flow ever gets that an agent needs a line.
 - **Knowledge.** `knowledge.stage` is set and the debate produced a non-obvious "why" worth keeping (a reviewer-surfaced constraint, an integration gotcha, a decision that reversed the design) → `knowledge.stage` for this branch (silence by default; only on a clear signal). Consolidated at `knowledge.save` time.
 - **Count the round in the artifact, not in your head.** Increment `respond_rounds` for this MR/PR in `meta.json` (its `mrs[]` entry; work-level when there are no `mrs`) in the same write that appends the round to `08-feedback.md` — the §1 ceiling is worth exactly as much as this counter. Lightweight mode: nothing to write, no ceiling to enforce; say so once and carry on.
 - **Re-post the performance comment when this round changed a measured path.** A push that touches a query or an entry point already benchmarked (`/flow-feat-ship` §4.3) makes the standing comment wrong — and a wrong number is worse than none. Re-run those rows against the same base and post a new comment; never edit the old one. Nothing measured changed → post nothing.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5). Not in lightweight mode.
 - **A repeated answer spends the budget and buys nothing.** A reply this round that says what an earlier round said — same position, same reasoning, no new evidence → stop **now**, before the ceiling, and escalate that thread by name: your position, the reviewer's counter, the fact that neither has moved.
-- **Loop / close.** Threads open awaiting the reviewer → tell the user the ball is in their court; a later `/flow-work-respond` picks up the next round. All threads answered and code pushed → summarize: threads addressed, code changes made, threads **ready for the user to resolve**, follow-up tickets proposed. Once approved and merged, the normal `/flow-feat-ship §6` / `/flow-bug-ship` close applies (and `/flow-work-watch` for the post-deploy).
+- **Loop / close.** Threads open awaiting the reviewer → tell the user the ball is in their court; a later `/flow-work-respond` picks up the next round. All threads answered and code pushed → **offer the agent lessons first** — `/flow-feat-ship §5.2`, in full and unchanged, over the rows still pending (this round's and any earlier ship left as `later`) — then summarize: threads addressed, code changes made, threads **ready for the user to resolve**, follow-up tickets proposed. Once approved and merged, the normal `/flow-feat-ship §6` / `/flow-bug-ship` close applies (and `/flow-work-watch` for the post-deploy).
 
 ## Notes