flow-workflows 0.78.0 → 0.79.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.78.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
@@ -610,6 +610,69 @@ Record what you picked where a default would be recorded (§0): *"`agents.fronte
 `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/codex/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/codex/skills/flow-bug-ship/SKILL.md

@@ -187,6 +187,7 @@ nothing was measured. A slowness bug is the case where this comment *is* the pro
 - **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/codex/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/codex/skills/flow-feat-ship/SKILL.md

@@ -248,8 +248,8 @@ the knowledge is saved, and what is left is whether an agent this work improvise
 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,
+   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.
@@ -257,6 +257,31 @@ the knowledge is saved, and what is left is whether an agent this work improvise
    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/codex/skills/flow-work-README/SKILL.md

@@ -142,6 +142,13 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
       "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",
@@ -159,6 +166,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **`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/codex/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
 

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.78.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
@@ -609,6 +609,69 @@ Record what you picked where a default would be recorded (§0): *"`agents.fronte
 `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/gemini/commands/flow/bug/review.toml

@@ -230,6 +230,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/gemini/commands/flow/bug/ship.toml

@@ -183,6 +183,7 @@ nothing was measured. A slowness bug is the case where this comment *is* the pro
 - **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/gemini/commands/flow/feat/review.toml

@@ -382,7 +382,8 @@ 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/gemini/commands/flow/feat/ship.toml

@@ -244,8 +244,8 @@ the knowledge is saved, and what is left is whether an agent this work improvise
 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,
+   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.
@@ -253,6 +253,31 @@ the knowledge is saved, and what is left is whether an agent this work improvise
    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

@@ -138,6 +138,13 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
       "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",
@@ -155,6 +162,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **`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.78.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
@@ -610,6 +610,69 @@ Record what you picked where a default would be recorded (§0): *"`agents.fronte
 `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

@@ -187,6 +187,7 @@ nothing was measured. A slowness bug is the case where this comment *is* the pro
 - **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-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

@@ -248,8 +248,8 @@ the knowledge is saved, and what is left is whether an agent this work improvise
 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,
+   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.
@@ -257,6 +257,31 @@ the knowledge is saved, and what is left is whether an agent this work improvise
    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

@@ -142,6 +142,13 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
       "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",
@@ -159,6 +166,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **`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
 

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.78.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
@@ -609,6 +609,69 @@ Record what you picked where a default would be recorded (§0): *"`agents.fronte
 `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/opencode/commands/flow-bug-review.md

@@ -232,6 +232,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/opencode/commands/flow-bug-ship.md

@@ -185,6 +185,7 @@ nothing was measured. A slowness bug is the case where this comment *is* the pro
 - **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/opencode/commands/flow-feat-review.md

@@ -384,6 +384,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/opencode/commands/flow-feat-ship.md

@@ -246,8 +246,8 @@ the knowledge is saved, and what is left is whether an agent this work improvise
 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,
+   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.
@@ -255,6 +255,31 @@ the knowledge is saved, and what is left is whether an agent this work improvise
    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/opencode/commands/flow-work-README.md

@@ -140,6 +140,13 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
       "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",
@@ -157,6 +164,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **`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/opencode/commands/flow-work-respond.md

@@ -163,12 +163,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-workflows",
-  "version": "0.78.0",
+  "version": "0.79.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.78.0",
+  "version": "0.79.0",
   "author": {
     "name": "Alberto Vioque",
     "email": "mashware@gmail.com"

package/plugins/flow/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.79.0 — The reviewer that missed it was never told  ·  2026-09-23
+
+**In short**
+- **An agent that let something through gets a one-line lesson in its own file.** A panel reviewer
+  that missed a finding in its category, a delegated agent whose code a finding landed in, a
+  reviewer whose category a colleague's MR comment exposed — recorded as the flow sees it, offered
+  when the work closes.
+- **Only outside evidence counts.** Another pass, the built-in review or a human caught it; an agent
+  grading itself is never the source.
+- **It stays small**: one section per agent, no repeats (a rule the agent already had becomes an
+  offer to turn it into a check), and a consolidation once it reaches `agents.lessons_max` (10).
+- **Your agents are asked in every mode, with a backup first**; agents flow created itself are
+  written directly in `guided`/`auto`. Plugin-installed agents and skills are never edited.
+- **The review stops offering to fill agent roles**, finishing what v0.78.0 started.
+
+Idea taken from Hermes Agent, which patches the skills it wrote and curates them so they do not
+pile up. What flow does differently is the signal: Hermes reviews its own transcript and admits it
+tends to think it did well; flow only learns when something outside the agent caught what it did
+not. `agents.learn: off` turns it off.
+
 ## v0.78.0 — The specialist was installed; the flow asked for a generalist  ·  2026-09-23
 
 **In short**

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

@@ -180,6 +180,9 @@ the step if it was optional** (flow-core §6.6).
                     #   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`
+- `learn:`          # agents learn from what they missed (flow-core §6.7). Empty = `offer`: when a reviewer or a delegated agent let
+                    #   through something another source caught, `ship` offers a one-line lesson for its file, with a backup. `off` = never
+- `lessons_max:`    # lines the lessons section of one agent may hold before a new lesson forces a consolidation. Empty = 10
 
 - `architecture:`   # design/layers/architecture
 - `persistence:`    # DB/ORM/mappings/migrations/queries