maxsimcli 5.0.6 → 5.1.0

package/dist/assets/templates/workflows/batch.md

@@ -1,341 +1,318 @@
 <sanity_check>
 Before executing any step in this workflow, verify:
 1. The current directory contains a `.planning/` folder — if not, stop and tell the user to run `/maxsim:init` first.
-2. Git is initialized (`git rev-parse --git-dir` succeeds) — worktrees require a git repository.
-3. `.planning/ROADMAP.md` exists — if not, stop and tell the user to initialize the project.
+2. `.planning/ROADMAP.md` exists — if not, stop and tell the user to initialize the project.
+3. Git is initialized (`git rev-parse --git-dir` succeeds) — worktrees require a git repository.
 </sanity_check>
 
 <purpose>
-Decompose a large task into independent units, execute each in an isolated git worktree, and produce one PR per unit. Each unit gets its own branch, worktree, and PR — enabling parallel implementation with zero merge conflicts.
+Execute multiple independent tasks in parallel using the Agent tool. Each unit gets its own isolated git worktree, branch, and PR. Based on Anthropic's own /batch pattern: decompose → validate independence → spawn ALL agents in ONE message block → track → report.
 
-Follows the batch-worktree skill process: Research (decompose) -> Plan (validate independence) -> Spawn (worktree agents) -> Track (progress and failures).
+Use this when you have 3+ tasks that share no files and have no runtime dependencies between them.
 </purpose>
 
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
 <process>
 
-<step name="initialize" priority="first">
-Load context in one call:
+## Step 1 — Initialize
 
 ```bash
+EXECUTOR_MODEL=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs resolve-model executor --raw)
+PLANNER_MODEL=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs resolve-model planner --raw)
 INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init quick "$DESCRIPTION")
 ```
 
-Parse JSON for: `planner_model`, `executor_model`, `slug`, `date`, `timestamp`, `roadmap_exists`, `planning_exists`.
-
-**If `roadmap_exists` is false:** Error — Batch mode requires an active project with ROADMAP.md. Run `/maxsim:init` first.
+Parse JSON: `planner_model`, `executor_model`, `slug`, `date`, `timestamp`, `roadmap_exists`.
 
-Verify git is available:
-```bash
-git rev-parse --git-dir > /dev/null 2>&1 || echo "ERROR: Not a git repository"
-```
+If `roadmap_exists` is false: error — batch mode requires an active project. Run `/maxsim:init` first.
 
-Store `BASE_BRANCH`:
+Store base branch:
 ```bash
 BASE_BRANCH=$(git rev-parse --abbrev-ref HEAD)
 ```
-</step>
-
-<step name="gather_task">
-Parse `$ARGUMENTS` for the task description.
-
-If `$ARGUMENTS` is empty, prompt user interactively:
-
-```
-AskUserQuestion(
-  header: "Batch Task",
-  question: "Describe the large task to decompose into independent worktree units.",
-  followUp: null
-)
-```
-
-Store response as `$DESCRIPTION`.
-
-If still empty, re-prompt: "Please provide a task description."
 
 Display banner:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM > BATCH WORKTREE EXECUTION
+ MAXSIM > BATCH PARALLEL EXECUTION
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
- Task: ${DESCRIPTION}
- Base branch: ${BASE_BRANCH}
+Task: {description from $ARGUMENTS}
+Base branch: {BASE_BRANCH}
 ```
-</step>
 
-<step name="decompose">
-Spawn planner with batch-specific prompt to produce a decomposition:
+If `$ARGUMENTS` is empty, prompt: "Describe the large task to decompose into independent units."
 
-```
-Task(
-  prompt="
-<planning_context>
+## Step 2 — Decompose into Independent Units
 
-**Mode:** batch
-**Description:** ${DESCRIPTION}
-**Base branch:** ${BASE_BRANCH}
+Spawn planner to produce a decomposition:
 
-<files_to_read>
-- .planning/STATE.md (Project State)
-- .planning/ROADMAP.md (Phase structure)
-- ./CLAUDE.md (if exists — follow project-specific guidelines)
-- .skills/maxsim-batch/SKILL.md (if exists — maxsim-batch constraints)
-</files_to_read>
-
-**Project skills:** Check .skills/ directory (if exists) — read SKILL.md files, plans should account for project skill rules
-
-</planning_context>
-
-<constraints>
-- Decompose into 3-30 independent units
-- Each unit MUST be independently mergeable (hard gate from batch-worktree skill)
-- If fewer than 3 units are identified, STOP and recommend /maxsim:quick instead
-- No file may appear in more than one unit
-- No runtime dependency between units (unit A output must not be unit B input)
-- Each unit must have: title, description, files owned, acceptance criteria
-</constraints>
-
-<output>
-Write decomposition to: .planning/batch/${slug}/DECOMPOSITION.md
-
-Format:
----
-task: ${DESCRIPTION}
-date: ${date}
-base_branch: ${BASE_BRANCH}
-unit_count: N
-status: pending
----
-
-## Units
-
-### Unit 1: [Title]
-**Description:** ...
-**Files owned:**
-- path/to/file1.ts
-- path/to/file2.ts
-**Acceptance criteria:**
-- [ ] Criterion 1
-- [ ] Criterion 2
-
-### Unit 2: [Title]
-...
-
-## Independence Matrix
-[For each pair of units, confirm no file overlap and no runtime dependency]
-
-Return: ## PLANNING COMPLETE with unit count and decomposition path
-</output>
-",
+```
+Agent(
   subagent_type="planner",
   model="{planner_model}",
-  description="Batch decomposition: ${DESCRIPTION}"
+  prompt="
+    <planning_context>
+    Mode: batch
+    Description: {description}
+    Base branch: {BASE_BRANCH}
+
+    Read these files:
+    - .planning/STATE.md
+    - .planning/ROADMAP.md
+    - ./CLAUDE.md (if exists — follow project guidelines)
+    </planning_context>
+
+    <constraints>
+    Decompose into 3–30 independent units. Hard rules:
+    - Each unit MUST be independently mergeable — no unit depends on another unit's output
+    - No file may appear in more than one unit
+    - No runtime dependency between units (unit A output must not be unit B input)
+    - If fewer than 3 independent units can be identified, output: INSUFFICIENT UNITS — recommend /maxsim:quick instead
+    - Each unit must have: title, description, files owned (exhaustive list), acceptance criteria
+    </constraints>
+
+    <output>
+    Write decomposition to: .planning/batch/{slug}/DECOMPOSITION.md
+
+    Format:
+    ---
+    task: {description}
+    date: {date}
+    base_branch: {BASE_BRANCH}
+    unit_count: N
+    status: pending
+    ---
+
+    ## Units
+
+    ### Unit 1: {Title}
+    **Description:** ...
+    **Files owned:**
+    - path/to/file1.ts
+    **Acceptance criteria:**
+    - [ ] Criterion 1
+
+    ### Unit 2: {Title}
+    ...
+
+    ## Independence Matrix
+    [For each pair of units: confirm no file overlap and no runtime dependency]
+
+    Return: ## PLANNING COMPLETE — {N} units
+    </output>
+  "
 )
 ```
 
 After planner returns:
-1. Verify decomposition exists at `.planning/batch/${slug}/DECOMPOSITION.md`
+1. Verify `.planning/batch/{slug}/DECOMPOSITION.md` exists
 2. Extract unit count
-3. If unit count < 3: warn user and suggest `/maxsim:quick` instead. Ask: "Continue with batch (${unit_count} units) or switch to quick mode?"
-4. Report: "Decomposition complete: ${unit_count} units identified"
+3. If `INSUFFICIENT UNITS`: warn and suggest `/maxsim:quick`. Ask: "Continue with batch ({N} units) or switch to quick?"
+4. Report: "Decomposition complete: {N} units identified"
 
-If decomposition not found, error: "Planner failed to create DECOMPOSITION.md"
-</step>
+## Step 3 — Validate Independence
 
-<step name="validate_independence">
-Read the DECOMPOSITION.md and validate file independence across all units.
+Read `DECOMPOSITION.md` and check file independence across all unit pairs.
 
-For each pair of units:
-1. Extract the files owned by each unit
-2. Compute the intersection
-3. If any file appears in more than one unit, the validation fails
+For each pair (Unit A, Unit B): compute intersection of their file lists.
 
-**If validation fails:**
+**If any overlap found:**
 
-Report the overlapping files and which units conflict:
 ```
 ## Independence Validation Failed
 
 | File | Unit A | Unit B |
 |------|--------|--------|
-| path/to/file.ts | Unit 1: Title | Unit 3: Title |
+| {path} | {Unit N: title} | {Unit M: title} |
 ```
 
-Return to planner with revision prompt:
+Return to planner with revision prompt. Re-validate after revision. If validation fails a second time, stop and escalate to user.
+
+**If validation passes:**
+```
+Independence validated: {N} units, no file overlap confirmed
 ```
-Task(
-  prompt="
-<revision_context>
 
-<files_to_read>
-- .planning/batch/${slug}/DECOMPOSITION.md (Existing decomposition)
-</files_to_read>
+Record decision:
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs state add-decision \
+  --phase "batch" \
+  --summary "Batch decomposition: {N} units, independence validated"
+```
 
-**Independence validation failed.** The following files appear in multiple units:
-${overlap_table}
+## Step 4 — Plan Mode — Confirm Before Spawning
 
-Options:
-1. Merge overlapping units into one
-2. Extract shared files into a prerequisite unit that runs first
-3. Redesign the split so each file belongs to exactly one unit
+**Enter Plan Mode.** Display the full execution plan:
 
-Revise DECOMPOSITION.md to resolve all overlaps.
-</revision_context>
-",
-  subagent_type="planner",
-  model="{planner_model}",
-  description="Revise batch decomposition: fix overlaps"
-)
 ```
+## Batch Execution Plan
 
-Re-validate after revision. If validation fails a second time, stop and escalate to user.
+Task: {description}
+Units: {N} independent worktree agents
+Base branch: {BASE_BRANCH}
 
-**If validation passes:**
+| # | Unit | Files | Acceptance Criteria |
+|---|------|-------|---------------------|
+| 1 | {title} | {file count} | {criteria count} |
+| 2 | {title} | {file count} | {criteria count} |
 
+Each unit runs in isolation: own branch, own worktree, own PR.
+
+Confirm to spawn all {N} agents? (yes/no)
 ```
-Independence validated: ${unit_count} units, no file overlap
-```
-</step>
 
-<step name="record_decision">
-Record the decomposition decision in STATE.md:
+Wait for user confirmation. **Exit Plan Mode after user confirms.**
 
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs state add-decision --phase "batch" --summary "Batch decomposition: ${unit_count} units, no file overlap confirmed"
-```
-</step>
+## Step 5 — Spawn All Agents in ONE Message Block
 
-<step name="spawn_worktree_agents">
-For each unit in the decomposition, spawn a worktree agent.
+All Agent calls are issued simultaneously in a single message. Every agent gets `isolation="worktree"` and `run_in_background=true`.
 
-Display progress table header:
+Display header:
 ```
-## Spawning Worktree Agents
+## Spawning {N} Worktree Agents
 
-| # | Unit | Status | PR |
-|---|------|--------|----|
+| # | Unit | Status | Branch | PR |
+|---|------|--------|--------|----|
 ```
 
-For each unit (spawn all with `run_in_background: true` for parallel execution):
+For EACH unit (all in one message block):
 
 ```
-Task(
+Agent(
   subagent_type="executor",
   model="{executor_model}",
   isolation="worktree",
   run_in_background=true,
   prompt="
-You are implementing Unit ${unit_number} of a batch worktree execution.
-
-<unit_spec>
-**Title:** ${unit_title}
-**Description:** ${unit_description}
-**Base branch:** ${BASE_BRANCH}
-**Branch name:** batch/${slug}/unit-${unit_number}
-**Files owned (ONLY touch these files):**
-${unit_files}
-**Acceptance criteria:**
-${unit_criteria}
-</unit_spec>
-
-<files_to_read>
-- ./CLAUDE.md (if exists — follow project-specific guidelines)
-- .planning/STATE.md (Project state)
-- .skills/ (if exists — list skills, read SKILL.md for each, follow relevant rules)
-</files_to_read>
-
-<instructions>
-1. Create branch: git checkout -b batch/${slug}/unit-${unit_number}
-2. Implement the changes described in the unit spec
-3. ONLY modify files listed in 'Files owned' — do not touch any other files
-4. Run tests relevant to your changes
-5. Commit atomically with message: feat(batch): ${unit_title}
-6. Push branch: git push -u origin batch/${slug}/unit-${unit_number}
-7. Create PR: gh pr create --title 'batch(${slug}): ${unit_title}' --body '## Unit ${unit_number}: ${unit_title}\n\n${unit_description}\n\nPart of batch: ${DESCRIPTION}'
-8. Return the PR URL
-
-If tests fail, fix and retry. If you cannot fix after 2 attempts, report failure with error details.
-</instructions>
-
-<output>
-Return one of:
-- ## UNIT COMPLETE\nPR: <url>
-- ## UNIT FAILED\nError: <details>
-</output>
-",
-  description="Batch unit ${unit_number}: ${unit_title}"
+    You are implementing Unit {unit_number} of a batch parallel execution.
+    You are running in an isolated git worktree with your own branch.
+
+    <unit_spec>
+    Title: {unit_title}
+    Description: {unit_description}
+    Base branch: {BASE_BRANCH}
+    Branch name: batch/{slug}/unit-{unit_number}
+    Files owned (ONLY touch these files — do not modify any others):
+    {unit_files_list}
+    Acceptance criteria:
+    {unit_acceptance_criteria}
+    </unit_spec>
+
+    <files_to_read>
+    - ./CLAUDE.md (if exists — follow project coding conventions)
+    - .planning/STATE.md
+    </files_to_read>
+
+    <instructions>
+    1. Create branch:
+       git checkout -b batch/{slug}/unit-{unit_number}
+    2. Read each file listed in Files owned to understand current state
+    3. Implement the changes described in unit_description
+    4. ONLY modify files listed in Files owned
+    5. Run tests relevant to your changed files
+    6. If tests fail: diagnose and fix. Retry up to 2 times.
+    7. Commit with conventional commit message:
+       git add {specific_files_only}
+       git commit -m 'feat(batch/{slug}): {unit_title}'
+    8. Push branch:
+       git push -u origin batch/{slug}/unit-{unit_number}
+    9. Create PR:
+       gh pr create \\
+         --title 'batch({slug}): {unit_title}' \\
+         --body 'Unit {unit_number}: {unit_description}\n\nPart of batch: {description}\n\nAcceptance criteria:\n{unit_acceptance_criteria}'
+    10. Return the PR URL
+    </instructions>
+
+    <codebase_conventions>
+    - Follow existing code style and patterns in the files you modify
+    - No dead code, TODOs, stubs, or placeholder comments
+    - Handle errors explicitly
+    - Stage specific files only — never git add . or git add -A
+    </codebase_conventions>
+
+    <output>
+    Final output must be exactly one of:
+    ## UNIT COMPLETE
+    PR: {pr_url}
+
+    ## UNIT FAILED
+    Error: {specific error details}
+    </output>
+  ",
+  description="Batch unit {unit_number}: {unit_title}"
 )
 ```
-</step>
 
-<step name="track_progress">
+## Step 6 — Track Progress
+
 As agents complete, update the status table:
 
-| # | Unit | Status | PR |
-|---|------|--------|----|
-| 1 | title | done | #123 |
-| 2 | title | in-progress | -- |
-| 3 | title | failed | -- |
+| # | Unit | Status | Branch | PR |
+|---|------|--------|--------|----|
+| 1 | {title} | done | batch/{slug}/unit-1 | #{pr_number} |
+| 2 | {title} | in-progress | batch/{slug}/unit-2 | — |
+| 3 | {title} | failed | batch/{slug}/unit-3 | — |
 
-Statuses: `pending`, `in-progress`, `done`, `failed`
+Statuses: `pending` → `in-progress` → `done` | `failed`
 
 After each agent returns:
 1. Parse output for `## UNIT COMPLETE` or `## UNIT FAILED`
 2. Extract PR URL if complete
-3. Update status table
-4. Report progress: "${completed}/${unit_count} units complete"
+3. Update status table row
+4. Print progress: "{done}/{total} units complete"
+
+Wait for ALL agents to finish before proceeding.
 
-Wait for all agents to finish before proceeding.
-</step>
+## Step 7 — Handle Failures
 
-<step name="handle_failures">
-For each failed unit:
+For each failed unit, spawn a fix agent:
 
-**Attempt 1 — spawn fix agent:**
 ```
-Task(
+Agent(
   subagent_type="executor",
   model="{executor_model}",
   isolation="worktree",
   prompt="
-Unit ${unit_number} failed with error:
-${error_details}
+    Unit {unit_number} ({unit_title}) failed with this error:
+    {error_details}
+
+    The worktree and branch may already exist. Check:
+    git worktree list
+    git checkout batch/{slug}/unit-{unit_number} 2>/dev/null || git checkout -b batch/{slug}/unit-{unit_number}
 
-<unit_spec>
-${original_unit_spec}
-</unit_spec>
+    Original unit spec:
+    {unit_spec}
 
-Fix the failing unit. The worktree and branch already exist.
-Check out the existing branch, diagnose the failure, fix it, test, commit, push, create PR.
-",
-  description="Fix batch unit ${unit_number}: ${unit_title}"
+    Fix the failure. Diagnose the root cause before attempting changes.
+    After fixing: test, commit, push, create PR.
+    Return: ## UNIT COMPLETE\nPR: {url} or ## UNIT FAILED\nError: {details}
+  ",
+  description="Fix batch unit {unit_number}: {unit_title}"
 )
 ```
 
-**Merge conflict detected:** Flag to user — decomposition had hidden overlap.
+**Merge conflict detected:** Decomposition had hidden overlap. Escalate to user:
 ```
-AskUserQuestion(
-  header: "Merge Conflict in Unit ${unit_number}",
-  question: "Unit ${unit_number} (${unit_title}) has a merge conflict. This suggests the decomposition missed a dependency. Options:\n1. Fix manually\n2. Skip this unit\n3. Abort remaining units",
-  followUp: null
-)
+Merge conflict in Unit {unit_number} ({unit_title}).
+This suggests the decomposition missed a dependency.
+Options:
+1. Fix manually on branch batch/{slug}/unit-{unit_number}
+2. Skip this unit
+3. Abort remaining fix attempts
 ```
 
-**3+ failures on same unit:** Stop retrying and escalate:
+**3+ failures on same unit:** Stop retrying. Escalate:
 ```
-## Unit ${unit_number} Escalated
+## Unit {unit_number} Escalated
 
-Unit "${unit_title}" failed 3+ times. Manual intervention required.
-Error history: ${error_summaries}
-Branch: batch/${slug}/unit-${unit_number}
+Unit "{unit_title}" failed 3+ times. Manual intervention required.
+Branch: batch/{slug}/unit-{unit_number}
+Error history:
+{error_summaries}
 ```
-</step>
 
-<step name="report">
+## Step 8 — Final Report
+
 After all units are resolved (complete or escalated):
 
 ```
@@ -343,77 +320,81 @@ After all units are resolved (complete or escalated):
  MAXSIM > BATCH EXECUTION COMPLETE
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Task: ${DESCRIPTION}
-Units: ${completed_count}/${unit_count} complete
+Task: {description}
+Units: {completed}/{total} complete
 
 | # | Unit | Status | PR |
 |---|------|--------|----|
-${final_status_table}
+{final_status_table}
 
-${failed_count > 0 ? "Failed units require manual attention." : "All units completed successfully."}
+{failed_count > 0 ? "Failed units require manual attention." : "All units completed."}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Update STATE.md with batch completion:
+Update STATE.md:
 ```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs state add-decision --phase "batch" --summary "Batch complete: ${completed_count}/${unit_count} units done. PRs: ${pr_list}"
+node ~/.claude/maxsim/bin/maxsim-tools.cjs state add-decision \
+  --phase "batch" \
+  --summary "Batch complete: {completed}/{total} units done. PRs: {pr_list}"
 ```
-</step>
 
-<step name="commit_metadata">
-Store batch record in `.planning/batch/` directory.
+## Step 9 — Commit Batch Metadata
 
-Update DECOMPOSITION.md frontmatter status:
-- All units done: `status: complete`
+Update `DECOMPOSITION.md` status:
+- All done: `status: complete`
 - Some failed: `status: partial`
 
-Create `.planning/batch/${slug}/RESULTS.md`:
+Write `.planning/batch/{slug}/RESULTS.md`:
 ```markdown
 ---
-task: ${DESCRIPTION}
-date: ${date}
-status: ${all_done ? "complete" : "partial"}
-units_total: ${unit_count}
-units_complete: ${completed_count}
-units_failed: ${failed_count}
+task: {description}
+date: {date}
+status: {complete | partial}
+units_total: {N}
+units_complete: {completed}
+units_failed: {failed}
 ---
 
 ## Results
 
 | # | Unit | Status | PR | Branch |
 |---|------|--------|----|--------|
-${results_table}
+{results_table}
 
 ## Failed Units
-${failed_summaries or "None"}
+{failed_summaries or "None."}
 ```
 
 Commit metadata:
 ```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs(batch): ${DESCRIPTION}" --files .planning/batch/${slug}/DECOMPOSITION.md .planning/batch/${slug}/RESULTS.md .planning/STATE.md
+node ~/.claude/maxsim/bin/maxsim-tools.cjs commit \
+  "docs(batch): {description}" \
+  --files .planning/batch/{slug}/DECOMPOSITION.md \
+          .planning/batch/{slug}/RESULTS.md \
+          .planning/STATE.md
 ```
-</step>
 
 </process>
 
 <success_criteria>
-- [ ] `.planning/` and git repository verified
-- [ ] User provides task description
-- [ ] Decomposition produces 3+ independent units
-- [ ] File independence validated across all unit pairs
-- [ ] Decision recorded in STATE.md
-- [ ] One worktree agent spawned per unit
+- [ ] .planning/ and git repository verified
+- [ ] Decomposition produces 3+ independent units (or user confirms fewer)
+- [ ] File independence validated across all unit pairs before spawning
+- [ ] Plan Mode shown and confirmed before any agents spawned
+- [ ] All agents spawned in a SINGLE message block using Agent tool (not Task)
+- [ ] Every agent has isolation="worktree" and run_in_background=true
 - [ ] Each agent creates its own branch and PR
-- [ ] Progress tracked with status table
-- [ ] Failed units retried once before escalation
+- [ ] Progress tracked with live status table
+- [ ] Failed units retried with fix agent (max 2 retries before escalation)
+- [ ] Merge conflicts escalated to user immediately
 - [ ] Final report lists all PRs and flags failures
-- [ ] Batch metadata committed to `.planning/batch/`
+- [ ] Batch metadata committed to .planning/batch/
 </success_criteria>
 
 <failure_handling>
-- **classifyHandoffIfNeeded false failure:** Agent reports "failed" with `classifyHandoffIfNeeded is not defined` error — Claude Code bug, not MAXSIM. Check if branch exists and has commits. If so, treat as success.
-- **Independence validation fails twice:** Stop, present overlaps to user, ask for manual decomposition guidance.
-- **Agent fails to create PR:** Check if `gh` CLI is authenticated. If not, report branch name for manual PR creation.
-- **All agents fail:** Likely systemic issue (git config, permissions). Stop and report for investigation.
-- **Fewer than 3 units identified:** Suggest `/maxsim:quick` instead. Do not force worktree overhead for small tasks.
+- **Independence validation fails twice:** Present overlaps to user. Ask for manual decomposition guidance.
+- **Agent fails to create PR:** Check `gh` CLI auth. If not authenticated, report branch name for manual PR creation.
+- **All agents fail:** Likely systemic issue (git config, permissions, worktree limit). Stop and report for investigation.
+- **Fewer than 3 independent units:** Suggest `/maxsim:quick`. Do not force worktree overhead for small tasks.
+- **classifyHandoffIfNeeded error:** Claude Code runtime bug (not MAXSIM). Check if branch has commits. If commits exist, treat as success and extract PR URL from branch.
 </failure_handling>