claude-mcp-workflow 0.1.8 → 0.1.10

package/templates/bug-fix.yaml

@@ -13,16 +13,28 @@ states:
       - Does it include a screenshot or describe a VISUAL problem (layout, overlap, wrong color, missing element)?
       - Or is it a LOGIC problem (wrong data, crash, incorrect calculation, serialization error)?
 
+      Persist the classification for verify_route:
+      `context_set({ key: "bug_type", value: "visual" })` (or `"logic"`)
+
       Choose:
       - `visual` → UI/layout bug — requires debug bridge, screenshots, visual reproduction
       - `logic` → data/logic bug — reproducible via unit tests or logs
     transitions:
       visual: load_skills_visual
-      logic: reproduce_logic
+      logic: load_skills_logic
+
+  load_skills_logic:
+    skills:
+      - coding-skill-selector
+      - "?debugging"
+      - ?project-skill-selector
+    transitions:
+      continue: reproduce_logic
 
   load_skills_visual:
     skills:
       - coding-skill-selector
+      - "?debugging"
       - ?debug-bridge
       - ?project-skill-selector
     transitions:
@@ -34,7 +46,7 @@ states:
       Reproduce the bug VISUALLY before proceeding — reading code is NOT reproduction.
 
       DO NOT fix the bug here. You may add trace/log statements to help reproduce,
-      but do NOT modify production logic. The fix belongs in the `fix` state.
+      but do NOT modify production logic. The fix comes later, after diagnosis.
 
       REPRODUCTION TOOLING — find the right tool:
       1. Check available MCP tools for browser/screenshot/debug-bridge capabilities.
@@ -64,9 +76,8 @@ states:
       `cant_reproduce` = you tried but can't see it. This leads to asking the user for help.
       NEVER use `reproduced` when you haven't seen the bug yourself.
 
-      If the bug requires simulated input or file operations, use the chosen tool's
-      recipes: Playwright `browser_evaluate` / `browser_press_key` for web,
-      tm-interactive-debug for native.
+      If the bug requires simulated input or file operations, use the chosen
+      tool's input-simulation capabilities.
     transitions:
       reproduced: diagnose
       cant_reproduce: clarify
@@ -76,8 +87,9 @@ states:
     prompt: |
       Reproduce the bug by EXECUTING code — reading source is NOT reproduction.
 
-      DO NOT fix the bug here. You may add trace/log statements or write test code
-      to help reproduce, but do NOT modify production logic. The fix belongs in the `fix` state.
+      DO NOT fix the bug here, and do NOT touch production code at all — not even
+      trace/log statements. Write test code to reproduce. The fix comes later,
+      after diagnosis.
 
       FILE RESTRICTION: You may ONLY create or edit test files.
       Any edit to production code is a workflow violation.
@@ -88,18 +100,35 @@ states:
       3. BUILD and RUN the test — show the actual output
       4. Describe: EXPECTED vs ACTUAL — what should happen vs what does happen
 
+      Delegate the build+run to a flat `general-purpose` subagent
+      (build/run/report — no workflow, no skills) to keep build output
+      out of main context.
+      A flat subagent inherits none of this project's skills or env
+      rules — it only knows what YOU put in its spawn prompt. So include
+      VERBATIM in that prompt: (a) any tooling/hook constraints that
+      apply in this project (required CLIs, blocked commands), and
+      (b) "Strip noise, but quote every error, failing assertion, and
+      number VERBATIM — don't paraphrase the signal or replace it with
+      a verdict; the parent judges.", and (c) "Bash: run commands
+      FOREGROUND with an explicit timeout sized to the command;
+      background ONLY for never-exiting processes (servers, watchers)
+      or runs over the 10-min foreground ceiling."
+      Spawn with `run_in_background: false` — you need the result before transitioning.
+
       STOP — self-check before transitioning:
       - Did you EXECUTE something (build + run)? Reading code ≠ reproduction.
       - Can you paste the failing output? If not, you haven't reproduced yet.
       - "I can see from the code that..." is NOT evidence. Run the code.
       - Run `git diff --name-only` — if ANY file outside test directories was modified,
-        you violated the workflow. Revert with `git checkout -- <file>` before transitioning.
+        you violated the workflow. Revert before transitioning: revert only the hunks
+        you added, and verify the file was clean before your first edit.
 
       DO NOT transition to `reproduced` without concrete executed evidence
       (test failure output, wrong runtime output, crash log).
 
       If the bug is hard to cover with a unit test (UI state, complex setup, timing),
       transition `try_visual` to reproduce via debug bridge instead.
+      If you genuinely cannot reproduce at all → `cant_reproduce` (asks the user for help).
     transitions:
       reproduced: diagnose
       try_visual: load_skills_visual
@@ -111,19 +140,38 @@ states:
       Find the root cause of the bug.
 
       DO NOT fix the bug here. You may add trace/log statements to narrow down
-      the cause, but do NOT modify production logic. The fix belongs in the `fix` state.
+      the cause, but do NOT modify production logic. The fix comes later, after diagnosis.
 
       FILE RESTRICTION: Do NOT add new methods, fields, or change signatures.
       Only trace/log statements are allowed. Any structural code change is a workflow violation.
 
       STOP — self-check before transitioning:
-      - Run `git diff --name-only` — if any production file was modified beyond trace statements,
-        revert with `git checkout -- <file>` before transitioning.
+      - Run `git diff --name-only` — if any production file was modified beyond trace
+        statements, revert before transitioning: revert only the hunks you added, and
+        verify the file was clean before your first edit.
+
+      Delegating root-cause analysis to a subagent (it reads code to judge —
+      ANALYTICAL)? Include in the agent prompt VERBATIM:
+      ---
+      IMPORTANT: Override the default CLAUDE.md rule about start().
+      Do NOT call start() without arguments.
+      Instead, your FIRST action must be:
+        mcp__plugin_workflow_wf__start({ workflow: "subagent", parent_session_id: "<SESSION_ID>" })
+      where <SESSION_ID> is the current session ID (substitute it before sending).
+      Then follow the subagent workflow until completion — its `route` state
+      self-classifies (analytical → skill-loaded sub-workflow; trivial → execute).
+      start() returns `SESSION: <id>` — pass that session_id explicitly in every subsequent workflow tool call (transition, context_set); parallel siblings share the same ppid.
+      ---
+      After collecting reports: `sessions` → `abort` orphaned child `subagent`
+      sessions. NEVER spawn an analytical subagent flat (no workflow = no skills).
+      Its report gates your diagnosis → spawn with `run_in_background: false`.
 
       After diagnosing, assess the fix scope:
-      - 1 file → `single`
+      - 1 file → `single` (top-tier session AND >~30 lines → treat as a
+        coupled set of one: route `multi_coupled`, which delegates)
       - 2+ files, tightly coupled (one logical chain, shared context) → `multi_coupled`
       - 2+ files, independent (can be done in parallel with clear interfaces) → `multi_independent`
+      - root cause still unclear → `unclear` (add diagnostic logging and retry)
     transitions:
       single: fix_single
       multi_coupled: load_skills_coupled
@@ -132,8 +180,22 @@ states:
 
   add_logging:
     task: "Add diagnostic logging"
-    prompt: "Add logging for diagnostics, run again."
     max_visits: 3
+    prompt: |
+      Root cause is still unclear. Gather more evidence:
+
+      1. Add targeted log/trace statements with unique prefixes (`[DBG1]`, `[DBG2]`)
+         at the locations you suspect — trace statements only, no structural changes
+      2. Re-run the reproduction and read the output
+      3. Analyze: does the output confirm or rule out a suspected location?
+
+      Budget: 3 visits to this state (engine-enforced); when nearly exhausted, choose `still_unclear` instead of retrying.
+
+      After analyzing, assess the fix scope (same as diagnose):
+      - 1 file → `single`
+      - 2+ files, tightly coupled → `multi_coupled`
+      - 2+ files, independent → `multi_independent`
+      - still no root cause → `still_unclear` (escalate to the user)
     transitions:
       single: fix_single
       multi_coupled: load_skills_coupled
@@ -156,7 +218,14 @@ states:
     task: "Fix tightly coupled multi-file changes"
     prompt: |
       The fix spans multiple tightly coupled files (one logical chain, shared context).
-      Do it yourself sequentially — delegation overhead exceeds benefit here.
+
+      Top-tier session AND >~30 changed lines expected → do NOT write inline:
+      write the fix plan + interface contracts here, spawn ONE implementer
+      agent carrying the whole plan (model per task-delegation: sonnet for a
+      detailed plan + linter/tests net, opus otherwise — never per-file
+      fan-out of a coupled set), collect its report, verify integration.
+      Otherwise (small fix, or non-top-tier session) do it yourself
+      sequentially — delegation overhead exceeds benefit:
 
       1. Plan the order: start from the innermost change, work outward to callers
       2. For each file: read → edit → self-review against loaded skills
@@ -178,7 +247,10 @@ states:
     prompt: |
       The fix spans multiple files. Produce a per-file plan with interface contracts,
       then spawn one Agent per file for parallel implementation.
-      Use `subagent_type="general-purpose"`.
+      Use `subagent_type="general-purpose"`. ALWAYS pass an explicit `model`
+      (task-delegation's model table): `opus` for non-trivial fix logic,
+      `sonnet` for mechanical edits from the plan. Never haiku, never silent
+      session-model inheritance.
 
       For each file, include in the agent prompt VERBATIM:
       ---
@@ -188,6 +260,7 @@ states:
         mcp__plugin_workflow_wf__start({ workflow: "file-code", parent_session_id: "<SESSION_ID>" })
       where <SESSION_ID> is the current session ID (substitute it before sending).
       Then follow the file-code workflow states until completion.
+      start() returns `SESSION: <id>` — pass that session_id explicitly in every subsequent workflow tool call (transition, context_set); parallel siblings share the same ppid.
       ---
       Also include:
       - The file path
@@ -195,7 +268,10 @@ states:
       - The per-file fix plan
       - Interface contracts with other files
 
-      Launch ALL file agents in parallel. Wait for all to complete. Collect reports.
+      Launch ALL file agents in ONE message, each with `run_in_background:
+      false` — their reports gate integration; a "batch" of ONE file is
+      still a gating single, not a background task.
+      Wait for all to complete. Collect reports.
 
       After ALL reports are collected:
       1. Abort orphaned child workflow sessions.
@@ -220,25 +296,47 @@ states:
   review:
     task: "Route review by scope"
     prompt: |
-      Route to the correct review approach based on how many files were changed:
-      - `single` → 1 file changed
-      - `multi` → 2+ files changed
+      Route by SIZE of the change, not file count (`git diff HEAD --numstat`):
+      - `single` → TRIVIAL change: ≤2 files AND ≤~50 changed lines total —
+        the linter IS the review (lint-review sub-workflow: engine-run lint
+        + act on findings + one intent re-read); tests follow anyway.
+      - `multi` → everything else, even one batch: an agent buys FRESH EYES
+        on the author's own code and keeps review bulk out of this session's
+        context; parallelism is a bonus, not the criterion.
     transitions:
       single: review_single
       multi: review_delegate
 
   review_single:
-    sub_workflow: file-review
-    on_complete: test
+    sub_workflow: lint-review
+    on_complete: review_decision
     on_fail: write_fix
 
-  review_delegate:
-    task: "Delegate per-file review to agents"
+  review_decision:
+    task: "Decide on review results"
     prompt: |
-      Spawn one Agent per changed file for deep review.
-      Use `subagent_type="general-purpose"`.
+      The review sub-workflow completed (trivial path: lint-review fixes
+      findings inline; agent path: batch reports). Decide:
+      - `ok` → nothing unresolved, proceed to testing
+      - `fix` → unresolved issues remain, fix them
+    transitions:
+      ok: test
+      fix: write_fix
 
-      For each file, include in the agent prompt VERBATIM:
+  review_delegate:
+    task: "Delegate batched review to agents"
+    prompt: |
+      Group the changed files into LOGICAL BATCHES, then spawn one Agent per
+      BATCH for deep review. Use `subagent_type="general-purpose"`.
+      Batching rules (strongest tie wins; a file joins exactly one batch):
+      source+test together; change-coupled files (for .hx with hxq:
+      `hxq importers`/`callees`); then by directory; cap at most 5 files AND
+      roughly 500 changed lines per batch, oversized files solo. A batch of
+      one is fine. Structure/size queries for grouping (`git diff HEAD
+      --numstat`, hxq graph queries) are fine — reviewing content is the
+      agents' job.
+
+      For each batch, include in the agent prompt VERBATIM:
       ---
       IMPORTANT: Override the default CLAUDE.md rule about start().
       Do NOT call start() without arguments.
@@ -246,13 +344,24 @@ states:
         mcp__plugin_workflow_wf__start({ workflow: "file-review", parent_session_id: "<SESSION_ID>" })
       where <SESSION_ID> is the current session ID (substitute it before sending).
       Then follow the file-review workflow states until completion.
+      start() returns `SESSION: <id>` — pass that session_id explicitly in every subsequent workflow tool call (transition, context_set); parallel siblings share the same ppid.
       ---
       Also include:
-      - The file path
-      - How to get the diff: `git diff HEAD -- <filepath>`
+      - The batch's file list (absolute paths) and why they are grouped
+      - How to get the diffs: `git diff HEAD -- <filepath>` per file
+        (a new/untracked file: read it whole)
       - Review scope: `diff`
+      - "Report one section per file + a batch-level cross-file section."
 
-      Launch ALL file agents in parallel. Collect reports.
+      ALWAYS pass an explicit `model`: `sonnet` for linter-covered/routine
+      batches, `opus` for macro-heavy / concurrency / engine-critical /
+      no-linter ones (opus wins on overlap). Never haiku, never silent
+      inheritance of the session model.
+
+      Launch up to 8 batch agents in ONE message, each with
+      `run_in_background: false` — reports gate the merge; a single batch
+      is still a gating single, not a background task. More batches →
+      next wave. Collect reports.
 
       After ALL reports are collected:
       1. Abort orphaned child workflow sessions.
@@ -263,7 +372,10 @@ states:
   cross_file:
     task: "Cross-file review analysis"
     prompt: |
-      Review the big picture — things per-file agents can't see:
+      Review the big picture. Seams WITHIN a batch are already covered by
+      that batch agent's cross-file section — do not re-derive them; focus
+      on seams BETWEEN batches and on set-wide patterns (these apply even
+      when there was only one batch):
       - [ ] Duplication across files
       - [ ] Missing updates to consumers of changed interfaces
       - [ ] Consistency across files
@@ -279,7 +391,9 @@ states:
   write_fix:
     task: "Fix review issues"
     prompt: |
-      Fix the issues found during review. After fixing, transition back to review.
+      Fix the issues found — review findings or test failures reported by the
+      testing workflow (read the failure report for what broke).
+      After fixing → transition `done` (returns to review for re-verification).
     transitions:
       done: review
 
@@ -291,7 +405,10 @@ states:
   verify_route:
     task: "Route to correct verification"
     prompt: |
-      Check the bug type classified at the start:
+      Bug type classified at the start: {{context.bug_type}}
+      (If empty — context was lost. Re-classify now: was the original report a
+      visual problem or a logic problem?)
+
       - Visual bug → `visual` (needs screenshot verification)
       - Logic bug → `logic` (tests already passed in testing workflow)
     transitions:
@@ -324,20 +441,37 @@ states:
       5. Compare before/after — describe the visual difference
 
       DO NOT transition to `confirmed` without a screenshot proving the fix works.
+
+      Choose transition:
+      - `confirmed` → your screenshot proves the bug is gone
+      - `still_broken` → bug still visible, back to diagnosis
     transitions:
       confirmed: done
       still_broken: diagnose
 
   clarify:
     task: "Clarify bug details"
-    prompt: "Ask the user for more details about the bug."
+    prompt: |
+      You could not reproduce the bug. Ask the user for more details:
+      - Exact steps to reproduce
+      - Error messages, logs, or screenshots
+      - Environment (platform, version, configuration)
+
+      If there is no interactive user (you are running as a subagent), do NOT ask — state your assumptions and continue, or take the failure path.
+
+      Choose transition:
+      - `got_info_visual` → new details point to a visual reproduction attempt
+      - `got_info_logic` → new details point to a test/log reproduction attempt
+      - `escalate` → no way to get more information; give up
     transitions:
       got_info_visual: load_skills_visual
       got_info_logic: reproduce_logic
+      escalate: escalate
 
   escalate:
-    prompt: "Could not diagnose. Report to the user."
+    prompt: "Could not reproduce or diagnose the bug. Report to the user: what was tried, what was ruled out, what information would help."
     terminal: true
+    outcome: fail
 
   done:
     prompt: "Bug fixed and verified."

package/templates/code-review.yaml

@@ -14,7 +14,7 @@ states:
       1. **User specified files** — user named concrete file paths → use those.
          Do NOT touch git.
       2. **User specified directories** — user named directories or patterns
-         (e.g. "src/api/", "src/ без editor", "src/*.hx, src/api/, src/drill/").
+         (e.g. "src/api/", "src/ without editor", "src/*.hx, src/api/, src/drill/").
          Parse the request in natural language:
          - `"src/"` → all source files recursively, auto-group by first-level subdirectories
          - `"src/api/, src/drill/"` → only these dirs recursively, each = one package
@@ -34,17 +34,21 @@ states:
       **Step 2 — Determine review depth:**
       - Coming from testing/coding / "check changes" / "review diff" / default
         → `scope: diff` (only review changed lines)
-      - "review file" / "целиком" / "check whole file" / "bring to order" / "привести в порядок"
-        → `scope: full` (review entire file)
+      - "review file" / "check whole file" / "bring to order" (or equivalent
+        phrases in the user's language) → `scope: full` (review entire file)
       - Directory mode → always `scope: full`
       Save the scope via `context_set(key: "review_scope", value: "diff" or "full")`.
 
       **Step 3 — Get file names:**
       - If source is user-specified files or directories → already have the list.
       - If source is git → get ALL changed file names (modified AND new/untracked):
-        - Modified/staged: `git diff HEAD --name-only`
+        - Modified/staged: `git diff HEAD --name-only --diff-filter=d`
+          (lowercase `d` excludes deleted files)
         - New untracked: `git ls-files --others --exclude-standard`
         Combine both lists. Do NOT read full diffs yet — names only.
+        Deleted files (`git diff HEAD --name-only --diff-filter=D`) get NO
+        per-file review — note them for the cross-file step instead
+        (their callers/imports may break).
         **Git pathspec gotcha (zsh):** to exclude paths, use `-- . ':(exclude)path'`,
         NOT `-- ':!path'` — the latter silently returns empty results in zsh.
 
@@ -65,16 +69,23 @@ states:
       Check context key `review_mode`:
       - If `review_mode` is `"directory"` → `directory`
 
-      Otherwise route based on how many files:
-      - `single` → 1 file — review via file-review sub-workflow (yourself)
-      - `multi` → 2+ files — spawn file-review agents in parallel
+      Otherwise route by SIZE of what will actually be REVIEWED:
+      - `diff` scope → size = changed lines (`git diff HEAD --numstat`);
+        `full` scope → size = the whole file (`wc -l`), since that is what
+        gets read.
+      - `single` → TRIVIAL: ≤2 files AND ≤~50 lines to review — the linter
+        IS the review (lint-review sub-workflow: engine-run lint + act on
+        findings + one intent re-read).
+      - `multi` → everything else, EVEN a single batch: an agent buys fresh
+        eyes and keeps review bulk out of this session's context;
+        parallelism is a bonus, not the criterion.
     transitions:
       single: review_single
       multi: review_delegate
       directory: package_review
 
   review_single:
-    sub_workflow: file-review
+    sub_workflow: lint-review
     on_complete: cross_file
     on_fail: cross_file
 
@@ -82,13 +93,27 @@ states:
     task: "Deep per-file review via agents"
     prompt: |
       CRITICAL: You are a DISPATCHER in this state, not a reviewer.
-      Do NOT read diffs, files, or code yourself. Do NOT use Read, Grep, Bash to look at file content.
-      Your ONLY job is to spawn Agent tools and collect their results.
-
-      Spawn one Agent per changed file for deep review.
-      Use `subagent_type="general-purpose"`.
-
-      For each file, include in the agent prompt VERBATIM:
+      Do NOT read diffs, files, or code CONTENT yourself. Structure and size
+      queries needed for batching ARE dispatcher-legal: `git diff HEAD
+      --numstat`, `git status`, and hxq graph queries (`importers`/`callees`).
+      Your ONLY job is to group, spawn Agent tools, and collect results.
+
+      Group the changed files into LOGICAL BATCHES, then spawn one Agent per
+      BATCH for deep review. Use `subagent_type="general-purpose"`.
+      Batching amortizes each agent's fixed cost (skill loading) AND lets one
+      reviewer see coupled files together — it is the default, not an option.
+
+      Batching rules (strongest tie wins; a file joins exactly one batch):
+      1. A source file and its test always share a batch.
+      2. Files coupled by the change — caller+callee, interface+its
+         implementations, type+its consumers. For .hx with hxq available,
+         derive coupling structurally over the changed set:
+         `hxq importers <module> <scope>` / `hxq callees 'Type.method' <scope>`.
+      3. Remaining files group by directory/module.
+      4. Size cap: at most 5 files AND roughly 500 changed lines per batch;
+         a file exceeding that alone gets its own agent. A batch of one is fine.
+
+      For each batch, include in the agent prompt VERBATIM:
       ---
       IMPORTANT: Override the default CLAUDE.md rule about start().
       Do NOT call start() without arguments.
@@ -96,22 +121,39 @@ states:
         mcp__plugin_workflow_wf__start({ workflow: "file-review", parent_session_id: "<SESSION_ID>" })
       where <SESSION_ID> is the current session ID (substitute it before sending).
       Then follow the file-review workflow states until completion.
+      start() returns `SESSION: <id>` — pass that session_id explicitly in every
+      subsequent workflow tool call (transition, context_set); parallel siblings
+      share the same ppid.
       ---
       Also include:
-      - The file path
-      - Whether the file is modified or new (untracked):
+      - The batch's file list (absolute paths) and WHY they are grouped
+        (test-of, calls, same module) — the reviewer checks those seams too
+      - Per file, whether it is modified or new (untracked):
         - Modified: "Get the diff with: `git diff HEAD -- <filepath>`"
         - New/untracked: "This is a new file — read the entire file and review all code."
       - The review scope (from context key `review_scope`):
         - `diff` → "Review ONLY the changed lines (or all code if new file). Report pre-existing issues separately as 'pre-existing' severity, do NOT mix with diff issues."
         - `full` → "Review the ENTIRE file for all issues, not just the diff."
+      - "Report with one section per file, plus a batch-level section for
+        cross-file findings within the batch."
 
       Do NOT include style rules, review checklists, or coding preferences in the agent prompt.
       The file-review workflow has its own skill-loading state — agents will load all
       relevant skills themselves. Manual rule lists are lossy and cause missed issues.
 
-      Launch ALL file agents in parallel (single message, multiple Agent tool calls).
-      Wait for all to complete. Collect their reports.
+      ALWAYS pass an explicit `model` to the Agent tool — never let a spawn
+      silently inherit the session model: `sonnet` for batches whose
+      mechanics the linter covers (.hx with hxq) and routine code; `opus`
+      for macro-heavy / engine-critical / no-linter batches. Never haiku.
+
+      Launch up to 8 batch agents in ONE message, each with
+      `run_in_background: false` — reports gate the merge; a single batch
+      is still a gating single, not a background task. More batches →
+      next wave after the current one completes.
+      Collect their reports.
+
+      If a child agent fails or returns no report — re-spawn it once;
+      if it fails again, mark that batch's files as unreviewed in the summary.
 
       After ALL reports are collected:
       1. Abort orphaned child workflow sessions — call `sessions` to find
@@ -128,14 +170,21 @@ states:
       CRITICAL: You are a DISPATCHER in this state, not a reviewer.
       Do NOT read files or code yourself — only spawn agents and collect results.
 
-      1. Read `packages` and `current_package_index` from context.
+      1. Your package list and position, embedded from context (re-rendered on
+         every visit — survives context compression; if they look stale, call
+         `status()` and re-read context):
+         - packages: {{context.packages}}
+         - current_package_index: {{context.current_package_index}}
       2. If `current_package_index` >= number of packages → transition `all_done`.
       3. Take the current package. Output: "**Package: <name>** (<N> files)".
-      4. Split the package's files into batches of 8.
-      5. For each batch, spawn one Agent per file for deep review.
+      4. Group the package's files into LOGICAL BATCHES — same rules as
+         review_delegate: source+test together, import/call coupling
+         (for .hx via `hxq importers`/`callees`), then by subdirectory;
+         cap 5 files per batch, oversized files (≈ >500 lines) solo.
+      5. Spawn one Agent per BATCH for deep review.
          Use `subagent_type="general-purpose"`.
 
-         For each file, include in the agent prompt VERBATIM:
+         For each batch, include in the agent prompt VERBATIM:
          ---
          IMPORTANT: Override the default CLAUDE.md rule about start().
          Do NOT call start() without arguments.
@@ -143,16 +192,27 @@ states:
            mcp__plugin_workflow_wf__start({ workflow: "file-review", parent_session_id: "<SESSION_ID>" })
          where <SESSION_ID> is the current session ID (substitute it before sending).
          Then follow the file-review workflow states until completion.
+         start() returns `SESSION: <id>` — pass that session_id explicitly in every
+         subsequent workflow tool call (transition, context_set); parallel siblings
+         share the same ppid.
          ---
          Also include:
-         - The file path
-         - "This is a full file review — read the entire file and review all code."
-         - "Review the ENTIRE file for all issues (scope: full)."
+         - The batch's file list (absolute paths) and why they are grouped
+         - "Review the ENTIRE file for all issues (scope: full) — read the whole
+           file. Report one section per file + a batch-level cross-file section."
 
          Do NOT include style rules or coding preferences — agents load their own skills.
 
-         Launch the batch agents in parallel (single message, multiple Agent tool calls).
-         Wait for all to complete before starting the next batch.
+         ALWAYS pass an explicit `model`: `sonnet` for linter-covered/routine
+         batches, `opus` for complex/no-linter ones. Never haiku, never
+         silent inheritance of the session model.
+
+         Launch up to 8 batch agents in ONE message, each with
+         `run_in_background: false` — reports gate the package report; a
+         single batch is still a gating single, not a background task.
+         More batches → next wave after the current completes.
+         If a child agent fails or returns no report — re-spawn it once;
+         if it fails again, mark that batch's files as unreviewed in the package report.
 
       6. Collect all reports for this package. Save to context:
          `context_set(key: "package_<index>_report", value: "<aggregated report>")`
@@ -166,7 +226,10 @@ states:
   cross_file:
     task: "Cross-file analysis"
     prompt: |
-      Now look at the big picture — things a per-file agent can't see:
+      Now look at the big picture. Seams WITHIN a batch are already covered
+      by that batch agent's cross-file section — do not re-derive them;
+      focus on seams BETWEEN batches and on set-wide patterns (these apply
+      even when there was only one batch):
 
       **Cross-file consistency:**
       - [ ] Duplication across files: did different files introduce similar code?
@@ -183,7 +246,7 @@ states:
       - [ ] Classes to merge: tiny classes that always appear together and share state
       - [ ] Layer violations: data flowing through unnecessary intermediary layers
 
-      Add any cross-file findings to the review.
+      Add any cross-file findings to the review. Then → transition `done`.
     transitions:
       done: summarize
 
@@ -301,8 +364,7 @@ states:
          consumers of what changed.
 
       After verification, transition `complete`. The coding sub-workflow already
-      reviewed the files it modified. Planning produces a plan only — review
-      happens later when the plan is executed via the coding workflow.
+      reviewed the files it modified.
     transitions:
       complete: done