claude-mcp-workflow 0.1.8 → 0.1.9

package/hooks/workflow-start.sh

@@ -21,77 +21,105 @@ if [ -d "$SKILLS_SRC" ]; then
   done
 fi
 
+ZED_SUFFIX=""
+if [[ -n "$ZED_ENVIRONMENT" ]]; then
+  ZED_SUFFIX=" Then load skill ide-zed (Skill tool)."
+fi
+
+# Everything below requires jq — without it, still emit the fresh-start prompt.
+command -v jq >/dev/null 2>&1 || { echo "STOP. Call mcp__plugin_workflow_wf__start (no args) first.$ZED_SUFFIX"; exit 0; }
+
 read -t 1 -r INPUT
+SOURCE=$(echo "$INPUT" | jq -r '.source // empty')
 TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty')
+HOOK_CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+# Physical path (pwd -P) so a symlinked cwd (e.g. /tmp → /private/tmp)
+# compares equal to the engine's getcwd()-resolved context.cwd.
+HOOK_CWD=$(cd "${HOOK_CWD:-$PWD}" 2>/dev/null && pwd -P || echo "$PWD")
 STATE_DIR="${STATE_DIR:-$HOME/.claude/workflow-state}"
 PLANS_DIR="$HOME/.claude/plans"
 
-ZED_SUFFIX=""
-if [[ -n "$ZED_ENVIRONMENT" ]]; then
-  ZED_SUFFIX=" Then load skill ide-zed (Skill tool)."
-fi
+# Session IDs are 8 hex chars; the {7,} length filter skips shorter incidental hex words.
+SID_RE='[a-f0-9]{7,}'
+
+# --- Helper: apply a jq filter to a file in place (atomic tmp+rename) ---
+# $$ makes the temp name unique per hook instance, so concurrent hooks
+# cannot clobber each other's half-written temp files.
+jq_inplace() {
+  local filter="$1" f="$2" tmp="$2.tmp.$$"
+  jq "$filter" "$f" 2>/dev/null > "$tmp" && mv "$tmp" "$f" || rm -f "$tmp"
+}
+
+# --- Helper: check <sid> refers to a live planning session ---
+# Live = state file exists + top stack frame is "planning" + not abandoned.
+validate_planning_session() {
+  local sf="$STATE_DIR/$1.json"
+  [ -f "$sf" ] || return 1
+  jq -e '.outcome != "abandoned" and (.stack | length > 0) and .stack[-1].workflow == "planning"' "$sf" >/dev/null 2>&1
+}
 
 # --- Helper: increment skill_epoch in a session JSON by ID ---
 bump_skill_epoch_by_id() {
-  local sid="$1"
-  local sf="$STATE_DIR/${sid}.json"
+  local sf="$STATE_DIR/$1.json"
   [ -f "$sf" ] || return
-  jq '.skill_epoch = ((.skill_epoch // 0) + 1)' "$sf" 2>/dev/null > "${sf}.tmp" && mv "${sf}.tmp" "$sf" || rm -f "${sf}.tmp"
+  jq_inplace '.skill_epoch = ((.skill_epoch // 0) + 1)' "$sf"
 }
 
 # --- Helper: increment skill_epoch in active sessions for current PID ---
 bump_skill_epoch_by_pid() {
   [ -d "$STATE_DIR" ] || return
+  # $PPID is the Claude Code process: hook commands run as single-command
+  # `bash -c` invocations, which bash exec-optimizes (the shell replaces
+  # itself), so no intermediate shell sits between this script and Claude Code.
   local cc_pid=$PPID
   for sf in "$STATE_DIR"/*.json; do
     [ -f "$sf" ] || continue
     local pid
     pid=$(jq -r '.context.claude_code_pid // empty' "$sf" 2>/dev/null)
     [ "$pid" = "$cc_pid" ] || continue
-    jq 'if .stack | length > 0 then .skill_epoch = ((.skill_epoch // 0) + 1) else . end' "$sf" 2>/dev/null > "${sf}.tmp" && mv "${sf}.tmp" "$sf" || rm -f "${sf}.tmp"
+    jq_inplace 'if .stack | length > 0 then .skill_epoch = ((.skill_epoch // 0) + 1) else . end' "$sf"
   done
 }
 
-# --- Helper: find active planning session from plan files ---
+# --- Helper: find a live planning session for this project from plan files ---
+# Only plans whose session context.cwd matches the hook's cwd are considered;
+# candidates are checked newest-first by plan file mtime.
 find_plan_session() {
   [ -d "$PLANS_DIR" ] || return
-  for plan in "$PLANS_DIR"/*.md; do
+  local plan sid
+  while IFS= read -r plan; do
     [ -f "$plan" ] || continue
-    # Extract session ID from ## Workflow section (Session line: `<hex>`)
-    local sid
-    sid=$(grep -A5 '^## Workflow' "$plan" | grep 'Session' | grep -oE '[a-f0-9]{7,}' | head -1)
+    # Session ID from the ## Workflow section. -A5: the section contract is
+    # 5 list lines after the heading (Session / Current state / After approve /
+    # Execution workflow / Resume) — Session is always within that window.
+    sid=$(grep -A5 '^## Workflow' "$plan" | grep 'Session' | grep -oE "$SID_RE" | head -1)
     [ -n "$sid" ] || continue
-    # Check if this session is active and in planning state
-    local state_file="$STATE_DIR/${sid}.json"
-    [ -f "$state_file" ] || continue
-    local wf
-    wf=$(jq -r 'select(.stack | length > 0) | .stack[-1].workflow // empty' "$state_file" 2>/dev/null)
-    if [ "$wf" = "planning" ]; then
-      echo "$sid"
-      return
-    fi
-  done
+    validate_planning_session "$sid" || continue
+    [ "$(jq -r '.context.cwd // empty' "$STATE_DIR/${sid}.json" 2>/dev/null)" = "$HOOK_CWD" ] || continue
+    echo "$sid"
+    return
+  done < <(ls -t "$PLANS_DIR"/*.md 2>/dev/null)
 }
 
-# --- 1. Transcript exists and has content → same process ---
-if [ -n "$TRANSCRIPT" ] && [ -s "$TRANSCRIPT" ]; then
-  # Check for ExitPlanMode → plan resume after context clear
-  if grep -q 'ExitPlanMode' "$TRANSCRIPT" 2>/dev/null; then
-    PLAN_SID=$(grep -oE 'transition\(\\"[a-f0-9]+\\"' "$TRANSCRIPT" | tail -1 | grep -oE '[a-f0-9]{7,}')
-    if [ -n "$PLAN_SID" ]; then
+# --- 1. clear/compact → same process, context lost ---
+if [ "$SOURCE" = "clear" ] || [ "$SOURCE" = "compact" ]; then
+  # Transcript grep is only used to recover the planning session hex;
+  # validity is checked against the state file, not the transcript.
+  if [ -n "$TRANSCRIPT" ] && grep -q 'ExitPlanMode' "$TRANSCRIPT" 2>/dev/null; then
+    PLAN_SID=$(grep -oE 'transition\(\\"[a-f0-9]+\\"' "$TRANSCRIPT" | tail -1 | grep -oE "$SID_RE")
+    if [ -n "$PLAN_SID" ] && validate_planning_session "$PLAN_SID"; then
       bump_skill_epoch_by_id "$PLAN_SID"
       echo "PLAN RESUME (same process): call transition(\"$PLAN_SID\", \"planned\") to resume planning session.$ZED_SUFFIX"
       exit 0
     fi
   fi
-  # Has content but no plan → context clear
   bump_skill_epoch_by_pid
   echo "Context was cleared. Call status() to check for active session and restore context.$ZED_SUFFIX"
   exit 0
 fi
 
-# --- 2. Transcript empty or missing → new process ---
-# Check plans/ for active planning sessions (cross-process plan resume)
+# --- 2. startup/resume → new process ---
+# Check plans/ for live planning sessions (cross-process plan resume)
 PLAN_SID=$(find_plan_session)
 if [ -n "$PLAN_SID" ]; then
   bump_skill_epoch_by_id "$PLAN_SID"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mcp-workflow",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Structured workflow orchestration for AI agents via finite-state machines",
   "author": "AxGord <axgord@gmail.com> (https://github.com/AxGord)",
   "license": "MIT",

package/templates/bug-fix.yaml

@@ -13,6 +13,9 @@ 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
@@ -34,7 +37,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 +67,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 +78,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 +91,32 @@ 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."
+      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 +128,36 @@ 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).
 
       After diagnosing, assess the fix scope:
       - 1 file → `single`
       - 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 +166,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
@@ -188,6 +236,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
@@ -229,9 +278,19 @@ states:
 
   review_single:
     sub_workflow: file-review
-    on_complete: test
+    on_complete: review_decision
     on_fail: write_fix
 
+  review_decision:
+    task: "Decide on review results"
+    prompt: |
+      The file-review sub-workflow completed. Read its report and decide:
+      - `ok` → no issues (or notes only), proceed to testing
+      - `fix` → found issues that need fixing
+    transitions:
+      ok: test
+      fix: write_fix
+
   review_delegate:
     task: "Delegate per-file review to agents"
     prompt: |
@@ -246,6 +305,7 @@ 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
@@ -279,7 +339,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 +353,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 +389,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.
 
@@ -96,6 +100,9 @@ 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
@@ -110,8 +117,12 @@ states:
       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.
+      Split the files into batches of 8. Launch each batch's agents in parallel
+      (single message, multiple Agent tool calls). Wait for the whole batch to
+      complete before starting the next batch. Collect their reports.
+
+      If a child agent fails or returns no report — re-spawn it once;
+      if it fails again, mark that file as unreviewed in the summary.
 
       After ALL reports are collected:
       1. Abort orphaned child workflow sessions — call `sessions` to find
@@ -128,7 +139,11 @@ 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.
@@ -143,16 +158,20 @@ 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)."
+         - "Review the ENTIRE file for all issues (scope: full) — read the whole file."
 
          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.
+         If a child agent fails or returns no report — re-spawn it once;
+         if it fails again, mark that file 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>")`
@@ -183,7 +202,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 +320,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
 

package/templates/coding.yaml

@@ -27,8 +27,24 @@ states:
          that must match across file boundaries
       7. Identify dependencies between files — which must be written first
 
+      Delegating analysis to a subagent (blast-radius / recon / deep code
+      investigation — correctness depends on project skills, or it returns
+      a judgement)? 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).
+
       Route based on scope:
-      - `single` → 1 file to change (or tightly coupled changes best done together)
+      - `single` → 1 file to change
       - `multi` → 2+ independent files to change in parallel via agents
       - `multi_self` → 2+ files but high coupling / detailed plan already exists → write yourself
     transitions:
@@ -47,6 +63,22 @@ states:
       Write changes across multiple files yourself (high coupling or detailed plan).
       Implement layer by layer respecting dependencies.
 
+      Delegating a pre-code check to a subagent (blast-radius / impact
+      analysis — correctness depends on project skills, or it returns
+      a judgement)? 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).
+
       Do NOT build or verify compilation here — testing workflow handles that.
       Just write code and transition `done`.
     transitions:
@@ -66,6 +98,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
@@ -114,9 +147,19 @@ states:
 
   review_single:
     sub_workflow: file-review
-    on_complete: verify
+    on_complete: review_decision
     on_fail: write_fix
 
+  review_decision:
+    task: "Decide on review results"
+    prompt: |
+      The file-review sub-workflow completed. Read its report and decide:
+      - `ok` → no issues (or notes only), proceed to testing
+      - `fix` → found issues that need fixing
+    transitions:
+      ok: verify
+      fix: write_fix
+
   review_delegate:
     task: "Delegate per-file review to agents"
     prompt: |
@@ -131,6 +174,7 @@ 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
@@ -169,8 +213,9 @@ states:
   write_fix:
     task: "Fix review issues"
     prompt: |
-      Fix the issues found during review. After fixing, transition back to review
-      for re-verification.
+      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