flow-workflows 0.78.0 → 0.80.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.80.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-design/SKILL.md

@@ -42,7 +42,7 @@ read.)*
 **No code, and no design yet.** The output of this section is a ranked set of options and one chosen
 approach; §3 onwards designs *that* approach.
 
-### 1.5.1 Focused knowledge query
+### 1.5.1 Focused knowledge query, then the inventory
 
 `knowledge.search` set → 2-3 parallel queries on the **concept or pattern** the feature covers, not
 its title (`$flow-feat-start` already queried that): tracking → `"tracking deduplication"`,
@@ -50,6 +50,11 @@ its title (`$flow-feat-start` already queried that): tracking → `"tracking ded
 `"attachment handler"`, `"tax rules integration"`. Two seconds, then continue regardless. Hits go
 under "Additional domain context" in §5's template.
 
+**Then the inventory.** Run §3's prior inventory **now**, before any approach is proposed, and keep
+its result for `03-design.md`'s "## What already exists". An approach proposed without it reinvents
+what the repository already has, and a lens whose only job was to go and look for it spends an
+agent on what one search answers for every advisor at once. §3 is then already done.
+
 ### 1.5.2 Panel or single agent?
 
 - **M or L**, in `manual`: offer the **parallel approach panel** with `AskUserQuestion` ("Generate
@@ -58,11 +63,14 @@ under "Additional domain context" in §5's template.
   panel, note it in one line of `03-design.md`, go to §1.5.3.
 - Declined, or the user insisted on running this on S → §1.5.4.
 
-### 1.5.3 Approach panel (parallel fan-out — LLM-council pattern)
+### 1.5.3 Approach panel (parallel fan-out, one round)
 
-**Launch the advisors as parallel subagents** — one per lens, single round, each blind to the others
-(LLM-council: independent advisors, then a chairman synthesises; a **cross-critique** round in
-between for **L** only).
+**Launch the advisors as parallel subagents** — one per lens, a single round, each blind to the
+others; then you synthesise. **There is no debate round.** Advisors that share one base model share
+its blind spots: a round in which they read and attack each other tends to converge on the most
+confident answer rather than surface a new one, and it costs as many agents as the first round. The
+diversity is in what each lens is asked to *optimise*, and the adversarial pass is §6's challenger,
+which attacks the design that was actually chosen.
 
 **How wide the fan-out goes** — `agents.fanout_max` from `FLOW.md` (empty → **4**): never more than
 that in one round, and never more than `agents.budget_max` (empty → **12**) across this whole
@@ -70,22 +78,16 @@ command run (flow-core §6); a round that does not fit is truncated and the trun
 (`3/4`). With `models.workers` and `models.agents` empty, a round of 4 or more inherits this thread's
 model — say so in one line before launching, naming the key and never a model (flow-core §1).
 
-| Size | Rounds |
-|---|---|
-| M | Advisors → you synthesise |
-| L | Advisors → cross-critique → you synthesise |
-
-**You are the chairman.** Round 1 (and round 2 on L) are subagents; the synthesis and the ranking are
-yours, never a subagent's — you hold the work's context and you write `03-design.md`.
+**You are the chairman.** The advisors are subagents; the synthesis and the ranking are yours, never
+a subagent's — you hold the work's context and you write `03-design.md`.
 
-**Round 1 — advisors (parallel, blind to each other).** One subagent per lens, up to `fanout_max`.
-M → the first three lenses; L → add `operations`, and also on a sensitive surface (authentication or
+**Advisors (parallel, blind to each other).** One subagent per lens, up to `fanout_max`. M → the
+first two lenses; L → add `operations`, and also on a sensitive surface (authentication or
 authorization, payments, personal data, a public contract, a migration):
 
 | Lens | Brief |
 |---|---|
-| `minimum` | The **smallest** approach that solves the declared use case, nothing more (strict MVP) |
-| `reuse` | The approach that **most reuses** existing pieces in the affected module or its neighbours |
+| `minimum` | The **smallest** approach that solves the declared use case, built on what the inventory found before anything new (strict MVP) |
 | `reframe` | **Challenge the premise**: what if the problem is solved without building what was asked, or somewhere else? |
 | `operations` | The most production-solid approach (observability, integration failure, data at scale) |
 
@@ -93,31 +95,22 @@ Each advisor gets this brief, with its lens substituted:
 
 > Propose ONE approach to solve ticket `<TICKET>`, from this lens: `<lens brief>`. Read
 > `.claude/work/<TICKET>/01-context.md` for context and the effective FLOW configuration (base plus
-> active harness overlay) for project conventions. Do not
+> active harness overlay) for project conventions. What already exists in the repository:
+> `<the §1.5.1 inventory>` — propose a new piece only where nothing there fits. Do not
 > write code. Be specific about real modules and layers of this project. Report: name, what it is
 > (one sentence), modules/layers affected, main risk, and why it could be a bad idea. Under 250 words.
 > **Write that same answer to `.claude/work/<TICKET>/approaches/<lens>.md` before you reply** — the
 > file is the deliverable and the reply is a copy of it.
 
-**Round 2 — cross-critique (L only, parallel).** Each advisor receives the full set and attacks the
-*others* from its own lens:
-
-> You are the "`<lens>`" advisor. The approaches proposed for `<TICKET>` are in
-> `.claude/work/<TICKET>/approaches/` — read them all, plus `.claude/work/<TICKET>/01-context.md`.
-> From your lens (`<lens brief>`), critique the
-> OTHER approaches — not your own. For each one name its single biggest flaw for THIS project, or
-> "none". Then say which is strongest and which weakest, and why. Be concrete and grounded in the
-> project; do not invent flaws to fill space. **Write your critique to
-> `.claude/work/<TICKET>/approaches/critique-<lens>.md` before you reply.**
-
-**Round 3 — you synthesise.** A reply that arrived is already in your context and its file adds
+**Then you synthesise.** A reply that arrived is already in your context and its file adds
 nothing — **open only the files of the lenses that did not answer**, and only then. Rank the
-approaches best to worst *for this case* (project fit and
-simplicity, not generic merit), weighing the fatal flaws the critique surfaced. State explicitly
-where the advisors **agreed** and where they **disagreed** — the disagreement is the useful part.
+approaches best to worst *for this case* (project fit and simplicity, not generic merit), weighing
+each one's own "why it could be a bad idea" against the others' — rank on substance, not on which
+advisor wrote best. State explicitly where the advisors **agreed** and where they **disagreed** —
+the disagreement is the useful part.
 
-`agents.fanout_tool` set → run the rounds through that tool instead of plain parallel subagents; the
-rounds, the briefs and the ceiling do not change.
+`agents.fanout_tool` set → run the round through that tool instead of plain parallel subagents; the
+lenses, the briefs and the ceiling do not change.
 
 **A round that answers nothing is read off disk before it is written off** (flow-core §6). The
 advisors write their files first and reply second, so `ls .claude/work/<TICKET>/approaches/` settles
@@ -125,15 +118,15 @@ what actually happened: a file there is an answer that got lost in transit, and
 it without spending a single agent. Only a lens with no file is empty — **it is asked once for its
 answer and then dropped, never relaunched**, because an empty result is as often a truncated report
 as an advisor with nothing to say, and a relaunched round is paid for twice out of one
-`agents.budget_max`. Synthesise from those that answered and record `N/M`. An empty critique round
-→ rank from the approaches alone.
+`agents.budget_max`. Synthesise from those that answered and record `N/M`.
 
 ### 1.5.4 Single agent (the S case, or a declined panel)
 
 Launch a `general-purpose` subagent with this short, self-contained brief:
 
 > Generate 3-5 distinct approaches to solve `<title>` following the project conventions (see
-> the effective FLOW configuration and `.claude/work/<TICKET>/01-context.md`). For each: a
+> the effective FLOW configuration and `.claude/work/<TICKET>/01-context.md`), building on what
+> already exists: `<the §1.5.1 inventory>`. For each: a
 > one-sentence description,
 > modules/layers affected, main risk, and why it could be a bad idea. Do not write code. Report in
 > markdown, under 400 words.
@@ -166,7 +159,7 @@ A sensitive domain (payments, authentication, tracking) → launch **in parallel
 
 ## 3. Prior inventory (reuse before creating)
 
-**Before** launching the design subagents, list what the feature needs that **already exists** in code or DB. Launch an `Agent` with `subagent_type: Explore`:
+**M/L already ran this in §1.5.1** — reuse that result and skip to §4. XS/S: **before** launching the design subagents, list what the feature needs that **already exists** in code or DB. Launch an `Agent` with `subagent_type: Explore`:
 
 > For feature `<title>` (see `.claude/work/<TICKET>/01-context.md`), search the repo for related pieces that already exist and could be reused: domain entities, value objects, repositories, services, events, columns or tables, CQRS commands/queries, and similar endpoints. Do not propose design — only list what is found with one line each and its location. If the feature mentions concepts like `<concept1>`, `<concept2>`, search for those specifically.
 

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

@@ -72,7 +72,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **Code review is mandatory**: `$flow-feat-ship` is not run and `$flow-bug-postmortem` is not closed without passing through `/*:review`.
 - **Existing sub-agents**: commands delegate to the project's agents and skills; work is never duplicated.
 - **The subagents' model is the repo's call, never the plugin's (`models` in FLOW.md)**: `agents` (every subagent a command improvises) · `workers` (the fan-out rounds, falling back to `agents`). Empty = **inherit**. There is no key for what the main agent does itself: **an agent cannot switch its own model** (say it, **continue**); **a named agent keeps its own** (`agents.<role>`) — flow-core §1. `$flow-doctor` prints both resolved; `quality.review_skill` owns the review panel.
-- **Parallel multi-agent fan-out (optional, only where it pays)**: plain subagents. (1) `$flow-feat-design` §1.5.3: one agent per lens (minimum / reuse / reframe, + operations for L or a sensitive surface), cross-critique for L only. (2) `$flow-bug-investigate` §3.A: one agent per root cause, evidence **for and against**. (3) `$flow-feat-review` §6 and `$flow-bug-review` §5: one skeptic per **ambiguous** finding, refute-by-default. (4) `$flow-feat-build` §2.1bis and `$flow-bug-fix` §2.2: **one** skeptic on a premise the change depends on and nothing verifies — at **any size, XS included**, once per MR/PR, a category and not a depth tier, like the query duel. Other phases **do not** fan out. `manual`: offered with `AskUserQuestion`; `guided`/`auto`: runs, noted in the artifact. **The fan-out has two ceilings, and the synthesis is not a subagent**: `agents.fanout_max` (empty → **4**) per round and `agents.budget_max` (empty → **12**) for everything one command run launches, with what either cap drops **said** and the phase each command gives up first declared in it; both count agents, not findings, so grouping is intended and one-agent-per-finding past the cap is a breach; the review tier scales to the **diff under review**, not the size of the feature, and the verification gate also needs a **diff over 150 changed lines**; delegate the **gathering**, keep the **deciding**. **A heavier orchestrator is opt-in, per repo**: `agents.fanout_tool` (e.g. Claude Code's `Workflow`), rounds and ceiling unchanged; empty is the default and the portable path.
+- **Parallel multi-agent fan-out (optional, only where it pays)**: plain subagents. (1) `$flow-feat-design` §1.5.3: one agent per lens (minimum / reframe, + operations for L or a sensitive surface), one round, no debate. (2) `$flow-bug-investigate` §3.A: one agent per root cause, evidence **for and against**. (3) `$flow-feat-review` §6 and `$flow-bug-review` §5: one skeptic per **ambiguous** finding, refute-by-default. (4) `$flow-feat-build` §2.1bis and `$flow-bug-fix` §2.2: **one** skeptic on a premise the change depends on and nothing verifies — at **any size, XS included**, once per MR/PR, a category and not a depth tier, like the query duel. Other phases **do not** fan out. `manual`: offered with `AskUserQuestion`; `guided`/`auto`: runs, noted in the artifact. **The fan-out has two ceilings, and the synthesis is not a subagent**: `agents.fanout_max` (empty → **4**) per round and `agents.budget_max` (empty → **12**) for everything one command run launches, with what either cap drops **said** and the phase each command gives up first declared in it; both count agents, not findings, so grouping is intended and one-agent-per-finding past the cap is a breach; the review tier scales to the **diff under review**, not the size of the feature, and the verification gate also needs a **diff over 150 changed lines**; delegate the **gathering**, keep the **deciding**. **A heavier orchestrator is opt-in, per repo**: `agents.fanout_tool` (e.g. Claude Code's `Workflow`), rounds and ceiling unchanged; empty is the default and the portable path.
 - **Knowledge sources (full cycle)**: the `knowledge` section names a tool per **role** — `search`, `stage`, `read_staging`, `save` — any MCP (domain-memory, codegraph…), CLI or skill; a role that is empty degrades (no lookup / finding stays in the artifact / artifacts are the staging / `KNOWLEDGE.md`); `knowledge.timeout_s` (2 s) or any failure → continue silently. **`knowledge.search`**: `$flow-feat-start`, `$flow-bug-start` (ticket keywords), `$flow-feat-design` (approaches, module + integrations), `$flow-bug-investigate` (component in §1.5, cause in §2). **`knowledge.stage`**: closing `$flow-feat-design` and `$flow-bug-investigate`, offer to stage non-obvious domain decisions (silence by default; per-branch). **`knowledge.read_staging`** then **`knowledge.save`** at `$flow-feat-ship` and `$flow-bug-postmortem`: offer to consolidate the "why" only.
 
 ## `meta.json` schema
@@ -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.80.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.