maxsimcli 4.8.0 → 4.9.0

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

@@ -1,6 +1,6 @@
 <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:new-project` first.
+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.
 </sanity_check>
@@ -27,7 +27,7 @@ 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:new-project` first.
+**If `roadmap_exists` is false:** Error — Batch mode requires an active project with ROADMAP.md. Run `/maxsim:init` first.
 
 Verify git is available:
 ```bash
@@ -69,7 +69,7 @@ Display banner:
 </step>
 
 <step name="decompose">
-Spawn maxsim-planner with batch-specific prompt to produce a decomposition:
+Spawn planner with batch-specific prompt to produce a decomposition:
 
 ```
 Task(
@@ -132,7 +132,7 @@ status: pending
 Return: ## PLANNING COMPLETE with unit count and decomposition path
 </output>
 ",
-  subagent_type="maxsim-planner",
+  subagent_type="planner",
   model="{planner_model}",
   description="Batch decomposition: ${DESCRIPTION}"
 )
@@ -187,7 +187,7 @@ Options:
 Revise DECOMPOSITION.md to resolve all overlaps.
 </revision_context>
 ",
-  subagent_type="maxsim-planner",
+  subagent_type="planner",
   model="{planner_model}",
   description="Revise batch decomposition: fix overlaps"
 )

package/dist/assets/templates/workflows/diagnose-issues.md

@@ -79,8 +79,8 @@ For each gap, fill the debug-subagent-prompt template and spawn:
 
 ```
 Task(
-  prompt=filled_debug_subagent_prompt + "\n\n<files_to_read>\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n</files_to_read>",
-  subagent_type="general-purpose",
+  prompt="## Task: Diagnose root cause of test failure\n\n## Suggested Skills: systematic-debugging\n\n" + filled_debug_subagent_prompt + "\n\n<files_to_read>\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n</files_to_read>",
+  subagent_type="verifier",
   description="Debug: {truth_short}"
 )
 ```

package/dist/assets/templates/workflows/discovery-phase.md

@@ -4,7 +4,7 @@ Produces DISCOVERY.md (for Level 2-3) that informs PLAN.md creation.
 
 Called from plan-phase.md's mandatory_discovery step with a depth parameter.
 
-NOTE: For comprehensive ecosystem research ("how do experts build this"), use /maxsim:research-phase instead, which produces RESEARCH.md.
+NOTE: For comprehensive ecosystem research ("how do experts build this"), use /maxsim:plan --research instead, which produces RESEARCH.md.
 </purpose>
 
 <required_reading>
@@ -256,8 +256,8 @@ Confidence: [level]
 
 What's next?
 
-1. Discuss phase context (/maxsim:discuss-phase [current-phase])
-2. Create phase plan (/maxsim:plan-phase [current-phase])
+1. Discuss phase context (/maxsim:plan (discussion stage) [current-phase])
+2. Create phase plan (/maxsim:plan [current-phase])
 3. Refine discovery (dig deeper)
 4. Review discovery
 

package/dist/assets/templates/workflows/discuss-phase.md

@@ -1,6 +1,6 @@
 <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:new-project` first.
+1. The current directory contains a `.planning/` folder — if not, stop and tell the user to run `/maxsim:init` first.
 2. `.planning/ROADMAP.md` exists — if not, stop and tell the user to initialize the project.
 </sanity_check>
 
@@ -39,11 +39,11 @@ Every question directed at the user MUST use a structured tool. NEVER write a qu
 <downstream_awareness>
 **CONTEXT.md feeds into:**
 
-1. **maxsim-phase-researcher** — Reads CONTEXT.md to know WHAT to research
+1. **researcher** — Reads CONTEXT.md to know WHAT to research
    - "User wants card-based layout" → researcher investigates card component patterns
    - "Infinite scroll decided" → researcher looks into virtualization libraries
 
-2. **maxsim-planner** — Reads CONTEXT.md to know WHAT decisions are locked
+2. **planner** — Reads CONTEXT.md to know WHAT decisions are locked
    - "Pull-to-refresh on mobile" → planner includes that in task specs
    - "Claude's Discretion: loading skeleton" → planner can decide approach
 
@@ -199,7 +199,7 @@ Use AskUserQuestion:
 - header: "Plans exist"
 - question: "Phase [X] already has {plan_count} plan(s) created without user context. Your decisions here won't affect existing plans unless you replan."
 - options:
-  - "Continue and replan after" — Capture context, then run /maxsim:plan-phase {X} to replan
+  - "Continue and replan after" — Capture context, then run /maxsim:plan {X} to replan
   - "View existing plans" — Show plans before deciding
   - "Cancel" — Skip discuss-phase
 
@@ -541,14 +541,14 @@ Created: .planning/phases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
 
 **Phase ${PHASE}: [Name]** — [Goal from ROADMAP.md]
 
-`/maxsim:plan-phase ${PHASE}`
+`/maxsim:plan ${PHASE}`
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- `/maxsim:plan-phase ${PHASE} --skip-research` — plan without research
+- `/maxsim:plan ${PHASE} --skip-research` — plan without research
 - Review/edit CONTEXT.md before continuing
 
 ---
@@ -628,7 +628,7 @@ Task(
     <instructions>
     1. Read plan-phase.md from execution_context for your complete workflow
     2. Follow ALL steps: initialize, validate, load context, research, plan, verify, auto-advance
-    3. When spawning agents (maxsim-phase-researcher, maxsim-planner, maxsim-plan-checker), use Task with specified subagent_type and model
+    3. When spawning agents (researcher, planner), use Task with specified subagent_type and model
     4. For step 14 (auto-advance to execute): spawn execute-phase as a Task with DIRECT file reference — tell it to read execute-phase.md. Include @file refs to execute-phase.md, checkpoints.md, tdd.md, model-profile-resolution.md. Pass --no-transition flag so execute-phase returns results instead of chaining further.
     5. Do NOT use the Skill tool or /maxsim: commands. Read workflow .md files directly.
     6. Return: PHASE COMPLETE (full pipeline success), PLANNING COMPLETE (planning done but execute failed/skipped), PLANNING INCONCLUSIVE, or GAPS FOUND
@@ -648,23 +648,23 @@ Task(
 
   Auto-advance pipeline finished: discuss → plan → execute
 
-  Next: /maxsim:discuss-phase ${NEXT_PHASE} --auto
+  Next: /maxsim:plan ${NEXT_PHASE} --auto
   <sub>/clear first → fresh context window</sub>
   ```
 - **PLANNING COMPLETE** → Planning done, execution didn't complete:
   ```
   Auto-advance partial: Planning complete, execution did not finish.
-  Continue: /maxsim:execute-phase ${PHASE}
+  Continue: /maxsim:execute ${PHASE}
   ```
 - **PLANNING INCONCLUSIVE / CHECKPOINT** → Stop chain:
   ```
   Auto-advance stopped: Planning needs input.
-  Continue: /maxsim:plan-phase ${PHASE}
+  Continue: /maxsim:plan ${PHASE}
   ```
 - **GAPS FOUND** → Stop chain:
   ```
   Auto-advance stopped: Gaps found during execution.
-  Continue: /maxsim:plan-phase ${PHASE} --gaps
+  Continue: /maxsim:plan ${PHASE} --gaps
   ```
 
 **If neither `--auto` nor config enabled:**

package/dist/assets/templates/workflows/execute-phase.md

@@ -1,6 +1,6 @@
 <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:new-project` first.
+1. The current directory contains a `.planning/` folder — if not, stop and tell the user to run `/maxsim:init` first.
 2. `.planning/ROADMAP.md` exists — if not, stop and tell the user to initialize the project.
 </sanity_check>
 
@@ -12,6 +12,16 @@ Execute all plans in a phase using wave-based parallel execution. Orchestrator s
 Orchestrator coordinates, not executes. Each subagent loads the full execute-plan context. Orchestrator: discover plans → analyze deps → group waves → spawn agents → handle checkpoints → collect results.
 </core_principle>
 
+<agent_teams>
+**Agent Teams Model:** MAXSIM uses Agent Teams for grouping parallel agents, NOT for peer-to-peer communication.
+
+- `team_name` groups agents in a wave so Claude Code can track them as a unit
+- All coordination routes through the orchestrator (this workflow)
+- Subagents CANNOT spawn other subagents — only the orchestrator spawns agents
+- Inter-wave handoff: orchestrator passes wave N results as context to wave N+1 agents
+- Status tracking: orchestrator maintains a progress table per wave
+</agent_teams>
+
 <required_reading>
 Read STATE.md before any operation to load project context.
 
@@ -29,6 +39,13 @@ INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init execute-phase "${PHASE_AR
 
 Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`.
 
+Also extract parallel execution fields:
+```
+WORKTREE_MODE (from init JSON worktree_mode — "auto", "always", or "never")
+MAX_PARALLEL_AGENTS (from init JSON max_parallel_agents — default 10)
+REVIEW_CONFIG (from init JSON review_config — spec_review, code_review, simplify_review, retry_limit)
+```
+
 **If `phase_found` is false:** Error — phase directory not found.
 **If `plan_count` is 0:** Error — no plans found in phase.
 **If `state_exists` is false but `.planning/` exists:** Offer reconstruct or continue.
@@ -92,8 +109,167 @@ Report:
 ```
 </step>
 
+<step name="decide_execution_mode">
+After discovering plans and grouping by wave, determine whether to use batch (worktree) or standard execution.
+
+```bash
+# Parse --worktrees / --no-worktrees flags from $ARGUMENTS
+FLAG_OVERRIDE=""
+if echo "$ARGUMENTS" | grep -q "\-\-worktrees"; then FLAG_OVERRIDE="worktrees"; fi
+if echo "$ARGUMENTS" | grep -q "\-\-no-worktrees"; then FLAG_OVERRIDE="no-worktrees"; fi
+
+# Call CLI decision function
+MODE_RESULT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs decide-execution-mode \
+  "${INCOMPLETE_PLAN_COUNT}" "${WAVE_COUNT}" \
+  --worktree-mode "${WORKTREE_MODE}" \
+  ${FLAG_OVERRIDE:+--flag-override "$FLAG_OVERRIDE"})
+EXECUTION_MODE=$(echo "$MODE_RESULT" | node -e "process.stdin.on('data',d=>console.log(JSON.parse(d).mode))")
+```
+
+Display decision:
+```
+**Execution Mode:** {Batch (worktree isolation) | Standard}
+{If batch: "Will create {N} worktrees for parallel plan execution"}
+{If standard and parallelization true: "Parallel within waves, sequential across waves"}
+{If standard and parallelization false: "Sequential execution"}
+```
+
+**If batch mode, validate plan independence:**
+```bash
+# Build plans JSON from PLAN_INDEX data
+VALID=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs validate-plan-independence "$PLANS_JSON")
+```
+If conflicts found: report conflicts, fall back to standard mode with warning.
+</step>
+
 <step name="execute_waves">
-Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`, sequential if `false`.
+Execute each wave in sequence. The execution path depends on `EXECUTION_MODE` from the decide_execution_mode step.
+
+**BATCH PATH (when EXECUTION_MODE == "batch"):**
+
+For each wave:
+
+1. **Create worktrees for all plans in the wave:**
+   ```bash
+   for PLAN_ID in $WAVE_PLANS; do
+     WT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs worktree-create "${PHASE_NUMBER}" "$PLAN_ID" "$WAVE_NUM")
+     # Parse WT JSON for path and branch
+   done
+   ```
+
+2. **Describe what is being built (BEFORE spawning):**
+
+   Read each plan's `<objective>`. Extract what is being built and why.
+
+   ```
+   ---
+   ## Wave {N} (Batch Mode)
+
+   **{Plan ID}: {Plan Name}**
+   {2-3 sentences: what this builds, technical approach, why it matters}
+
+   Spawning {count} isolated agent(s) in worktrees...
+   ---
+   ```
+
+3. **Spawn executor agents with worktree isolation:**
+
+   ```
+   Task(
+     subagent_type="executor",
+     model="{executor_model}",
+     isolation="worktree",
+     team_name="maxsim-phase-{PHASE_NUMBER}-wave-{WAVE_NUM}",
+     prompt="
+       <objective>
+       Execute plan {plan_number} of phase {phase_number}-{phase_name}.
+       Commit each task atomically. Create SUMMARY.md.
+       IMPORTANT: Do NOT update STATE.md or ROADMAP.md — the orchestrator handles metadata.
+       </objective>
+
+       <execution_context>
+       @./workflows/execute-plan.md
+       @./templates/summary.md
+       @./references/checkpoints.md
+       </execution_context>
+
+       <files_to_read>
+       Read these files at execution start using the Read tool:
+       - {phase_dir}/{plan_file} (Plan)
+       - .planning/STATE.md (State — READ ONLY, do not modify)
+       - .planning/config.json (Config, if exists)
+       - ./CLAUDE.md (Project instructions, if exists)
+       </files_to_read>
+
+       <constraints>
+       - You are running in a worktree. Do NOT modify .planning/STATE.md or .planning/ROADMAP.md.
+       - Only create SUMMARY.md and commit task code.
+       - The orchestrator will handle metadata updates after all agents complete.
+       </constraints>
+
+       <success_criteria>
+       - [ ] All tasks executed
+       - [ ] Each task committed individually
+       - [ ] SUMMARY.md created in plan directory
+       </success_criteria>
+     ",
+     run_in_background=true
+   )
+   ```
+
+4. **Track progress with status table** (update as agents complete):
+   ```
+   | Plan | Agent | Status | Duration |
+   |------|-------|--------|----------|
+   | 05-01 | agent-abc | Running... | 2m |
+   | 05-02 | agent-def | Complete | 5m |
+   ```
+
+5. **After all agents in wave complete, collect results:**
+   - Read each SUMMARY.md from the worktree paths
+   - Run spot-checks (same as standard path: files exist, commits present, review cycle check)
+   - Orchestrator performs batch metadata updates:
+     ```bash
+     for PLAN_ID in $COMPLETED_PLANS; do
+       node ~/.claude/maxsim/bin/maxsim-tools.cjs state advance-plan
+       node ~/.claude/maxsim/bin/maxsim-tools.cjs state update-progress
+     done
+     node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap update-plan-progress "${PHASE_NUMBER}"
+     ```
+   - Report:
+     ```
+     ---
+     ## Wave {N} Complete (Batch)
+
+     **{Plan ID}: {Plan Name}**
+     {What was built — from SUMMARY.md}
+     {Notable deviations, if any}
+
+     {If more waves: what this enables for next wave}
+     ---
+     ```
+
+6. **Cleanup worktrees after wave completes:**
+   ```bash
+   node ~/.claude/maxsim/bin/maxsim-tools.cjs worktree-cleanup --all
+   ```
+
+7. **Prepare inter-wave handoff context (for waves after Wave 1):**
+
+   When spawning agents for the next wave, include a brief context block so they can reference prior wave outputs without reading full SUMMARYs:
+
+   ```
+   <prior_wave_results>
+   Wave {N-1} completed:
+   {For each plan in prior wave: plan ID, one-liner from SUMMARY.md, key files created/modified}
+   </prior_wave_results>
+   ```
+
+   Add this block to the `<objective>` section of the next wave's Task() prompts.
+
+8. **Proceed to next wave.**
+
+**STANDARD PATH (when EXECUTION_MODE == "standard"):**
 
 **For each wave:**
 
@@ -129,10 +305,13 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
    Pass paths only — executors read files themselves with their fresh 200k context.
    This keeps orchestrator context lean (~10-15%).
 
+   When the wave has multiple plans (parallel execution), add `team_name` to group agents:
+
    ```
    Task(
-     subagent_type="maxsim-executor",
+     subagent_type="executor",
      model="{executor_model}",
+     team_name="maxsim-phase-{PHASE_NUMBER}-wave-{WAVE_NUM}",  // only for multi-plan waves
      prompt="
        <objective>
        Execute plan {plan_number} of phase {phase_number}-{phase_name}.
@@ -217,7 +396,20 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
 6. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
 
-7. **Proceed to next wave.**
+7. **Prepare inter-wave handoff context (for waves after Wave 1):**
+
+   When spawning agents for the next wave, include a brief context block so they can reference prior wave outputs without reading full SUMMARYs:
+
+   ```
+   <prior_wave_results>
+   Wave {N-1} completed:
+   {For each plan in prior wave: plan ID, one-liner from SUMMARY.md, key files created/modified}
+   </prior_wave_results>
+   ```
+
+   Add this block to the `<objective>` section of the next wave's Task() prompts.
+
+8. **Proceed to next wave.**
 </step>
 
 <step name="checkpoint_handling">
@@ -270,6 +462,8 @@ After all waves:
 ```markdown
 ## Phase {X}: {Name} Execution Complete
 
+**Execution Mode:** {Batch (worktree) | Standard}
+**Worktrees Used:** {N} (batch only — omit for standard mode)
 **Waves:** {N} | **Plans:** {M}/{total} complete
 
 | Wave | Plans | Status |
@@ -366,7 +560,7 @@ Phase requirement IDs: {phase_req_ids}
 Check must_haves against actual codebase.
 Cross-reference requirement IDs from PLAN frontmatter against REQUIREMENTS.md — every ID MUST be accounted for.
 Create VERIFICATION.md.",
-  subagent_type="maxsim-verifier",
+  subagent_type="verifier",
   model="{verifier_model}"
 )
 ```
@@ -380,7 +574,7 @@ grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
 |--------|--------|
 | `passed` | → update_roadmap |
 | `human_needed` | Present items for human testing, get approval or feedback |
-| `gaps_found` | Present gap summary, offer `/maxsim:plan-phase {phase} --gaps` |
+| `gaps_found` | Present gap summary, offer `/maxsim:plan {phase} --gaps` |
 
 **If human_needed:**
 ```
@@ -406,15 +600,15 @@ All automated checks passed. {N} items need human testing:
 ---
 ## ▶ Next Up
 
-`/maxsim:plan-phase {X} --gaps`
+`/maxsim:plan {X} --gaps`
 
 <sub>`/clear` first → fresh context window</sub>
 
 Also: `cat {phase_dir}/{phase_num}-VERIFICATION.md` — full report
-Also: `/maxsim:verify-work {X}` — manual testing first
+Also: `/maxsim:execute {X}` (includes verification) — manual testing first
 ```
 
-Gap closure cycle: `/maxsim:plan-phase {X} --gaps` reads VERIFICATION.md → creates gap plans with `gap_closure: true` → user runs `/maxsim:execute-phase {X} --gaps-only` → verifier re-runs.
+Gap closure cycle: `/maxsim:plan {X} --gaps` reads VERIFICATION.md → creates gap plans with `gap_closure: true` → user runs `/maxsim:execute {X} --gaps-only` → verifier re-runs.
 </step>
 
 <step name="update_roadmap">
@@ -449,7 +643,7 @@ mcp__maxsim-dashboard__submit_lifecycle_event(
 
 <step name="offer_next">
 
-**Exception:** If `gaps_found`, the `verify_phase_goal` step already presents the gap-closure path (`/maxsim:plan-phase {X} --gaps`). No additional routing needed — skip auto-advance.
+**Exception:** If `gaps_found`, the `verify_phase_goal` step already presents the gap-closure path (`/maxsim:plan {X} --gaps`). No additional routing needed — skip auto-advance.
 
 **No-transition check (spawned by auto-advance chain):**
 
@@ -515,7 +709,7 @@ Orchestrator: ~10-15% context. Subagents: fresh 200k each. No polling (Task bloc
 </failure_handling>
 
 <resumption>
-Re-run `/maxsim:execute-phase {phase}` → discover_plans finds completed SUMMARYs → skips them → resumes from first incomplete plan → continues wave execution.
+Re-run `/maxsim:execute {phase}` → discover_plans finds completed SUMMARYs → skips them → resumes from first incomplete plan → continues wave execution.
 
 STATE.md tracks: last completed plan, current wave, pending checkpoints.
 </resumption>