maxsimcli 4.8.0 → 4.10.0

package/dist/assets/templates/workflows/init-existing.md

@@ -27,7 +27,7 @@ Check if `--auto` flag is present in $ARGUMENTS.
 - Auto mode does NOT require an idea document (unlike new-project's --auto)
 - Default config: stage=MVP, branching_strategy=none, model_profile=balanced, mode=yolo, depth=standard
 - After scan: generate all documents with smart inferences
-- Add `<!-- Auto-generated by /maxsim:init-existing --auto. Review recommended. -->` comment at top of each generated document
+- Add `<!-- Auto-generated by /maxsim:init --auto. Review recommended. -->` comment at top of each generated document
 - Auto mode still creates all documents: config.json, PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md
 - If `.planning/` exists: auto mode defaults to merge behavior (keep existing, fill gaps, re-scan)
 - If `.planning/` does not exist: create fresh
@@ -53,7 +53,7 @@ Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `ma
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 No source code or package manifest detected in this directory.
-For greenfield projects, use /maxsim:new-project instead.
+For greenfield projects, use /maxsim:init instead.
 ```
 
 Use AskUserQuestion:
@@ -61,9 +61,9 @@ Use AskUserQuestion:
 - question: "No code detected. Continue with init-existing anyway, or switch to new-project?"
 - options:
   - "Continue anyway" -- I know there's code here (maybe in subdirectories)
-  - "Switch to /maxsim:new-project" -- This is a greenfield project
+  - "Switch to /maxsim:init" -- This is a greenfield project
 
-**If "Switch":** Print "Run `/maxsim:new-project` to start a greenfield project." and exit.
+**If "Switch":** Print "Run `/maxsim:init` to start a greenfield project." and exit.
 **If "Continue":** Proceed to Step 2.
 
 **In auto mode:** If no code detected, proceed anyway (scan will find what it can).
@@ -108,7 +108,7 @@ Use AskUserQuestion:
 - options:
   - "Merge (Recommended)" -- Keep existing files, fill gaps, re-scan codebase
   - "Overwrite" -- Delete existing .planning/ and start fresh
-  - "Cancel" -- Exit (run /maxsim:health to diagnose)
+  - "Cancel" -- Exit (run /maxsim:progress (health check) to diagnose)
 
 **On Merge:**
 - Note which core files exist: config.json, PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md
@@ -142,7 +142,7 @@ mkdir -p .planning
 Proceed to Step 3.
 
 **On Cancel:**
-Print: "Cancelled. Run `/maxsim:health` to diagnose your .planning/ state."
+Print: "Cancelled. Run `/maxsim:progress (health check)` to diagnose your .planning/ state."
 Exit workflow.
 
 ## Step 3: Codebase Scan
@@ -171,13 +171,13 @@ mkdir -p .planning/codebase/
 
 Spawn 4 mapper agents using the Task tool. Follow the EXACT pattern from `templates/workflows/map-codebase.md`.
 
-**CRITICAL:** Spawn mapper agents directly using the Task tool. Do NOT invoke `/maxsim:map-codebase` command (that would exit the current workflow context).
+**CRITICAL:** Spawn mapper agents directly using the Task tool. Do NOT invoke `/maxsim:init (codebase mapping stage)` command (that would exit the current workflow context).
 
 **Agent 1: Tech Focus**
 
 ```
 Task(
-  subagent_type="maxsim-codebase-mapper",
+  subagent_type="researcher",
   model="{mapper_model}",
   run_in_background=true,
   description="Map codebase tech stack",
@@ -196,7 +196,7 @@ Explore thoroughly. Write documents directly using templates. Return confirmatio
 
 ```
 Task(
-  subagent_type="maxsim-codebase-mapper",
+  subagent_type="researcher",
   model="{mapper_model}",
   run_in_background=true,
   description="Map codebase architecture",
@@ -215,7 +215,7 @@ Explore thoroughly. Write documents directly using templates. Return confirmatio
 
 ```
 Task(
-  subagent_type="maxsim-codebase-mapper",
+  subagent_type="researcher",
   model="{mapper_model}",
   run_in_background=true,
   description="Map codebase conventions",
@@ -234,7 +234,7 @@ Explore thoroughly. Write documents directly using templates. Return confirmatio
 
 ```
 Task(
-  subagent_type="maxsim-codebase-mapper",
+  subagent_type="researcher",
   model="{mapper_model}",
   run_in_background=true,
   description="Map codebase concerns",
@@ -856,7 +856,7 @@ If no discrepancies, omit this section.
 
 **If auto mode:** Add at top of file:
 ```markdown
-<!-- Auto-generated by /maxsim:init-existing --auto. Review recommended. -->
+<!-- Auto-generated by /maxsim:init --auto. Review recommended. -->
 ```
 
 ### 9b: REQUIREMENTS.md
@@ -1006,7 +1006,7 @@ These are MUST NOT requirements derived from production constraints:
 
 **If auto mode:** Add at top of file:
 ```markdown
-<!-- Auto-generated by /maxsim:init-existing --auto. Review recommended. -->
+<!-- Auto-generated by /maxsim:init --auto. Review recommended. -->
 ```
 
 ### 9c: ROADMAP.md
@@ -1023,7 +1023,7 @@ Use template from `templates/roadmap.md`.
 ◆ Spawning roadmapper...
 ```
 
-Spawn the `maxsim-roadmapper` agent via Task tool to generate the roadmap:
+Spawn the planner (roadmap mode) via Task tool to generate the roadmap:
 
 ```
 Task(prompt="
@@ -1068,7 +1068,7 @@ not generic setup phases. The codebase already exists.
 
 Write files first, then return. This ensures artifacts persist even if context is lost.
 </instructions>
-", subagent_type="maxsim-roadmapper", model="{roadmapper_model}", description="Create roadmap for existing project")
+", subagent_type="planner", model="{roadmapper_model}", description="Create roadmap for existing project")
 ```
 
 **Handle roadmapper return:**
@@ -1124,7 +1124,7 @@ Pre-populate:
 
 **If auto mode:** Add at top of file:
 ```markdown
-<!-- Auto-generated by /maxsim:init-existing --auto. Review recommended. -->
+<!-- Auto-generated by /maxsim:init --auto. Review recommended. -->
 ```
 
 ### 9e: config.json
@@ -1156,7 +1156,7 @@ Write content:
 | 3 | [Any constraint decisions from Step 7] | [Why] | [Alternatives] | Locked |
 
 ---
-*Decisions captured during /maxsim:init-existing initialization*
+*Decisions captured during /maxsim:init initialization*
 ```
 
 **ACCEPTANCE-CRITERIA.md:**
@@ -1181,7 +1181,7 @@ Write content:
 
 ## Phase-Level Criteria
 
-Populated per-phase during /maxsim:discuss-phase.
+Populated per-phase during /maxsim:plan (discussion stage).
 
 ---
 *Criteria derived from init-existing initialization*
@@ -1218,7 +1218,7 @@ Write content:
 - [What this milestone is NOT trying to achieve]
 
 ---
-*No-gos captured during /maxsim:init-existing initialization*
+*No-gos captured during /maxsim:init initialization*
 ```
 
 **If auto mode:** Generate artefakte from scan findings with reasonable inferences. Mark uncertain entries with `(inferred)`.
@@ -1293,7 +1293,7 @@ git add .planning/
 
 If `commit_docs` is true:
 ```bash
-git commit -m "docs: initialize MAXSIM in existing project via /maxsim:init-existing"
+git commit -m "docs: initialize MAXSIM in existing project via /maxsim:init"
 ```
 
 Print structured summary:
@@ -1327,14 +1327,14 @@ Print next steps:
 
 **Phase 1: [Phase Name]** -- [Goal from ROADMAP.md]
 
-/maxsim:plan-phase 1 -- plan the first phase
+/maxsim:plan 1 -- plan the first phase
 
 <sub>/clear first → fresh context window</sub>
 
 ───────────────────────────────────────────────────────────────
 
 **Also available:**
-- /maxsim:roadmap -- review the generated roadmap
+- /maxsim:progress -- review the generated roadmap
 - /maxsim:progress -- see project status
 
 ───────────────────────────────────────────────────────────────
@@ -1388,7 +1388,7 @@ Print next steps:
 - [ ] CONCERNS.md findings presented as candidate no-gos
 - [ ] Agent dry-run validation passed (Quality Score >= 7)
 - [ ] Structured summary printed
-- [ ] Next steps suggested: /maxsim:roadmap then /maxsim:plan-phase 1
+- [ ] Next steps suggested: /maxsim:progress then /maxsim:plan 1
 
 **Auto mode criteria:**
 - [ ] All questions skipped

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

@@ -0,0 +1,205 @@
+<purpose>
+
+Unified initialization router. Detects the current project state and delegates to the appropriate sub-workflow:
+- **New project** (no .planning/) -> delegates to @./workflows/new-project.md
+- **Existing project** (.planning/ exists, no ROADMAP.md) -> delegates to @./workflows/init-existing.md
+- **Active milestone** (.planning/ + ROADMAP.md, phases in progress) -> shows status, offers options
+- **Milestone complete** (all phases done) -> offers completion or new milestone via @./workflows/new-milestone.md
+
+This file is a THIN ROUTER. All heavy logic lives in the sub-workflows.
+
+</purpose>
+
+<required_reading>
+
+Read all files referenced by the invoking prompt's execution_context before starting.
+
+</required_reading>
+
+<process>
+
+## 1. Parse Flags
+
+Check if `--auto` was passed in $ARGUMENTS. If present, set `AUTO_MODE=true` and pass through to sub-workflows.
+
+## 2. Detect Scenario
+
+Run filesystem checks to determine which flow applies:
+
+```bash
+# Check project state
+PLANNING_EXISTS=$(test -d .planning && echo "true" || echo "false")
+
+if [ "$PLANNING_EXISTS" = "true" ]; then
+  ROADMAP_EXISTS=$(test -f .planning/ROADMAP.md && echo "true" || echo "false")
+  STATE_EXISTS=$(test -f .planning/STATE.md && echo "true" || echo "false")
+else
+  ROADMAP_EXISTS="false"
+  STATE_EXISTS="false"
+fi
+
+echo "PLANNING=$PLANNING_EXISTS ROADMAP=$ROADMAP_EXISTS STATE=$STATE_EXISTS"
+```
+
+Use the results to route:
+
+| PLANNING | ROADMAP | Route |
+|----------|---------|-------|
+| false | - | Scenario A: New Project |
+| true | false | Scenario B: Existing Project |
+| true | true | Scenario C or D: check phase completion |
+
+For Scenario C vs D, check phase progress:
+
+```bash
+node .claude/maxsim/bin/maxsim-tools.cjs roadmap analyze 2>/dev/null || echo "NO_ANALYSIS"
+```
+
+If all phases show status "complete" -> Scenario D (Milestone Complete).
+Otherwise -> Scenario C (Active Milestone).
+
+## 3. Route to Scenario
+
+### Scenario A: New Project
+
+No `.planning/` directory found. This is a fresh project initialization.
+
+Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► INITIALIZING NEW PROJECT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Delegate to @./workflows/new-project.md -- execute the full new-project workflow end-to-end.
+
+Pass through:
+- `--auto` flag if set
+- All $ARGUMENTS for idea document references
+
+After the new-project workflow completes, display:
+
+```
+Project initialized. Run /maxsim:plan 1 to start phase planning.
+```
+
+### Scenario B: Existing Project
+
+`.planning/` exists but no `ROADMAP.md`. This is an existing codebase that needs MAXSIM initialization.
+
+Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► INITIALIZING EXISTING PROJECT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Delegate to @./workflows/init-existing.md -- execute the full init-existing workflow end-to-end.
+
+Pass through:
+- `--auto` flag if set
+
+After the init-existing workflow completes, display:
+
+```
+Project initialized. Run /maxsim:plan 1 to start phase planning.
+```
+
+### Scenario C: Active Milestone
+
+`.planning/` and `ROADMAP.md` exist with phases still in progress. The project is actively being worked on.
+
+Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► PROJECT STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Load current state:
+
+```bash
+node .claude/maxsim/bin/maxsim-tools.cjs state load 2>/dev/null
+```
+
+Read `.planning/ROADMAP.md` and `.planning/STATE.md` to display:
+- Current milestone name and version
+- Phase progress (completed/total)
+- Current phase and plan being executed
+- Recent activity from session continuity
+
+Then present options conversationally (natural language, not AskUserQuestion):
+
+**Options:**
+
+1. **Continue working** -- Based on the current state, suggest the next logical action:
+   - If a plan is in progress: "Continue executing Plan {N} with `/maxsim:execute {phase}`"
+   - If a phase needs planning: "Plan the next phase with `/maxsim:plan {phase}`"
+   - If verification is pending: "Verify the current phase"
+
+2. **Start a new milestone** -- If the user wants to pivot or start fresh:
+   - Delegate to @./workflows/new-milestone.md for the milestone creation flow
+
+3. **View detailed progress** -- Direct to `/maxsim:progress` for full status
+
+4. **Exit** -- No action needed
+
+Wait for the user's choice and route accordingly.
+
+### Scenario D: Milestone Complete
+
+`.planning/` and `ROADMAP.md` exist with all phases marked complete. The current milestone is finished.
+
+Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► MILESTONE COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Load state and display completion summary:
+- Milestone name and version
+- Total phases completed
+- Key metrics (plans executed, decisions made)
+
+Then present options conversationally:
+
+**Options:**
+
+1. **Complete and archive this milestone** -- Run the milestone completion flow:
+   - Delegate to @./workflows/new-milestone.md with completion mode
+   - Archives current milestone data
+   - Updates MILESTONES.md with summary
+
+2. **Start a new milestone** -- Begin the next cycle:
+   - Delegate to @./workflows/new-milestone.md for creation flow
+   - Gathers new milestone goals
+   - Creates fresh REQUIREMENTS.md and ROADMAP.md
+
+3. **View final progress** -- Direct to `/maxsim:progress` for the full report
+
+Wait for the user's choice and route accordingly.
+
+## 4. Context Management
+
+For long-running flows (Scenarios A and B especially), the sub-workflows handle their own context management including checkpoint-before-clear patterns. The router does not need to manage context beyond the initial detection and delegation.
+
+If context is filling up during Scenario C or D interactive options:
+- Recommend the user run `/clear` and then the specific command for their chosen action
+- Example: "Context is getting large. Run `/clear`, then `/maxsim:plan 3` to continue planning phase 3."
+
+</process>
+
+<constraints>
+
+- This workflow is a ROUTER only. All project initialization logic lives in the sub-workflows.
+- Do NOT inline or duplicate logic from new-project.md, init-existing.md, or new-milestone.md.
+- Do NOT reference removed command names in user-facing output. The old per-scenario commands no longer exist as user-facing commands.
+- The sub-workflows may still reference removed command names internally -- that is expected and will be cleaned up in a later plan.
+- For Scenarios C and D, use natural conversational flow for options. Do not use AskUserQuestion for the menu -- just present options and let the user respond naturally.
+
+</constraints>

package/dist/assets/templates/workflows/new-milestone.md

@@ -93,7 +93,7 @@ AskUserQuestion: "Research the domain ecosystem for new features before defining
 - "Research first (Recommended)" — Discover patterns, features, architecture for NEW capabilities
 - "Skip research" — Go straight to requirements
 
-**Persist choice to config** (so future `/maxsim:plan-phase` honors it):
+**Persist choice to config** (so future `/maxsim:plan` honors it):
 
 ```bash
 # If "Research first": persist true
@@ -118,7 +118,7 @@ node ~/.claude/maxsim/bin/maxsim-tools.cjs config-set workflow.research false
 mkdir -p .planning/research
 ```
 
-Spawn 4 parallel maxsim-project-researcher agents. Each uses this template with dimension-specific fields:
+Spawn 4 parallel researcher agents. Each uses this template with dimension-specific fields:
 
 **Common structure for all 4 researchers:**
 ```
@@ -145,7 +145,7 @@ Focus ONLY on what's needed for the NEW features.
 Write to: .planning/research/{FILE}
 Use template: ~/.claude/maxsim/templates/research-project/{FILE}
 </output>
-", subagent_type="maxsim-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
+", subagent_type="researcher", model="{researcher_model}", description="{DIMENSION} research")
 ```
 
 **Dimension-specific fields:**
@@ -174,7 +174,7 @@ Synthesize research outputs into SUMMARY.md.
 Write to: .planning/research/SUMMARY.md
 Use template: ~/.claude/maxsim/templates/research-project/SUMMARY.md
 Commit after writing.
-", subagent_type="maxsim-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
+", subagent_type="researcher", model="{synthesizer_model}", description="Synthesize research")
 ```
 
 Display key findings from SUMMARY.md:
@@ -297,7 +297,7 @@ Create roadmap for milestone v[X.Y]:
 
 Write files first, then return.
 </instructions>
-", subagent_type="maxsim-roadmapper", model="{roadmapper_model}", description="Create roadmap")
+", subagent_type="planner", model="{roadmapper_model}", description="Create roadmap")
 ```
 
 **Handle return:**
@@ -360,11 +360,11 @@ node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: create milestone v[X.Y]
 
 **Phase [N]: [Phase Name]** — [Goal]
 
-`/maxsim:discuss-phase [N]` — gather context and clarify approach
+`/maxsim:plan [N]` — gather context and clarify approach
 
 <sub>`/clear` first → fresh context window</sub>
 
-Also: `/maxsim:plan-phase [N]` — skip discussion, plan directly
+Also: `/maxsim:plan [N]` — skip discussion, plan directly
 ```
 
 </process>
@@ -376,12 +376,12 @@ Also: `/maxsim:plan-phase [N]` — skip discussion, plan directly
 - [ ] Research completed (if selected) — 4 parallel agents, milestone-aware
 - [ ] Requirements gathered and scoped per category
 - [ ] REQUIREMENTS.md created with REQ-IDs
-- [ ] maxsim-roadmapper spawned with phase numbering context
+- [ ] planner (roadmap mode) spawned with phase numbering context
 - [ ] Roadmap files written immediately (not draft)
 - [ ] User feedback incorporated (if any)
 - [ ] ROADMAP.md phases continue from previous milestone
 - [ ] All commits made (if planning docs committed)
-- [ ] User knows next step: `/maxsim:discuss-phase [N]`
+- [ ] User knows next step: `/maxsim:plan [N]`
 
 **Atomic commits:** Each phase commits its artifacts immediately.
 </success_criteria>

package/dist/assets/templates/workflows/new-project.md

@@ -30,7 +30,7 @@ Check if `--auto` flag is present in $ARGUMENTS.
 
 **Document requirement:**
 Auto mode requires an idea document — either:
-- File reference: `/maxsim:new-project --auto @prd.md`
+- File reference: `/maxsim:init --auto @prd.md`
 - Pasted/written text in the prompt
 
 If no document content provided, error:
@@ -39,8 +39,8 @@ If no document content provided, error:
 Error: --auto requires an idea document.
 
 Usage:
-  /maxsim:new-project --auto @your-idea.md
-  /maxsim:new-project --auto [paste or write your idea here]
+  /maxsim:init --auto @your-idea.md
+  /maxsim:init --auto [paste or write your idea here]
 
 The document should describe what you want to build.
 ```
@@ -75,12 +75,12 @@ Use AskUserQuestion:
 - header: "Codebase"
 - question: "I detected existing code in this directory. Would you like to map the codebase first?"
 - options:
-  - "Map codebase first" — Run /maxsim:map-codebase to understand existing architecture (Recommended)
+  - "Map codebase first" — Run /maxsim:init (codebase mapping stage) to understand existing architecture (Recommended)
   - "Skip mapping" — Proceed with project initialization
 
 **If "Map codebase first":**
 ```
-Run `/maxsim:map-codebase` first, then return to `/maxsim:new-project`
+Run `/maxsim:init (codebase mapping stage)` first, then return to `/maxsim:init`
 ```
 Exit command.
 
@@ -440,7 +440,7 @@ Write content:
 | 2 | [Choice from questioning] | [Why this was chosen] | [What else was discussed] | Locked |
 
 ---
-*Decisions captured during /maxsim:new-project initialization*
+*Decisions captured during /maxsim:init initialization*
 ```
 
 **ACCEPTANCE-CRITERIA.md** — Measurable success criteria derived from user's vision:
@@ -467,7 +467,7 @@ These define what "done" looks like for the entire project:
 
 ## Phase-Level Criteria
 
-Populated per-phase during /maxsim:discuss-phase.
+Populated per-phase during /maxsim:plan.
 
 ---
 *Criteria derived from project initialization*
@@ -500,7 +500,7 @@ Write content:
 - [What this project is NOT]
 
 ---
-*No-gos captured during /maxsim:new-project initialization*
+*No-gos captured during /maxsim:init initialization*
 ```
 
 **CONVENTIONS.md** — Coding conventions for agents to follow:
@@ -739,10 +739,10 @@ Display spawning indicator:
   → Pitfalls research
 ```
 
-Spawn 4 parallel maxsim-project-researcher agents with path references:
+Spawn 4 parallel researcher agents with path references:
 
 ```
-Task(prompt="First, read ~/.claude/agents/maxsim-project-researcher.md for your role and instructions.
+Task(prompt="
 
 <research_type>
 Project Research — Stack dimension for [domain].
@@ -780,9 +780,9 @@ Your STACK.md feeds into roadmap creation. Be prescriptive:
 Write to: .planning/research/STACK.md
 Use template: ~/.claude/maxsim/templates/research-project/STACK.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Stack research")
+", subagent_type="researcher", model="{researcher_model}", description="Stack research")
 
-Task(prompt="First, read ~/.claude/agents/maxsim-project-researcher.md for your role and instructions.
+Task(prompt="
 
 <research_type>
 Project Research — Features dimension for [domain].
@@ -820,9 +820,9 @@ Your FEATURES.md feeds into requirements definition. Categorize clearly:
 Write to: .planning/research/FEATURES.md
 Use template: ~/.claude/maxsim/templates/research-project/FEATURES.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Features research")
+", subagent_type="researcher", model="{researcher_model}", description="Features research")
 
-Task(prompt="First, read ~/.claude/agents/maxsim-project-researcher.md for your role and instructions.
+Task(prompt="
 
 <research_type>
 Project Research — Architecture dimension for [domain].
@@ -860,9 +860,9 @@ Your ARCHITECTURE.md informs phase structure in roadmap. Include:
 Write to: .planning/research/ARCHITECTURE.md
 Use template: ~/.claude/maxsim/templates/research-project/ARCHITECTURE.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Architecture research")
+", subagent_type="researcher", model="{researcher_model}", description="Architecture research")
 
-Task(prompt="First, read ~/.claude/agents/maxsim-project-researcher.md for your role and instructions.
+Task(prompt="
 
 <research_type>
 Project Research — Pitfalls dimension for [domain].
@@ -900,7 +900,7 @@ Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
 Write to: .planning/research/PITFALLS.md
 Use template: ~/.claude/maxsim/templates/research-project/PITFALLS.md
 </output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Pitfalls research")
+", subagent_type="researcher", model="{researcher_model}", description="Pitfalls research")
 ```
 
 After all 4 agents complete, spawn synthesizer to create SUMMARY.md:
@@ -923,7 +923,7 @@ Write to: .planning/research/SUMMARY.md
 Use template: ~/.claude/maxsim/templates/research-project/SUMMARY.md
 Commit after writing.
 </output>
-", subagent_type="maxsim-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
+", subagent_type="researcher", model="{synthesizer_model}", description="Synthesize research")
 ```
 
 **Locked Decisions Approval Gate:**
@@ -1135,7 +1135,7 @@ Display stage banner:
 ◆ Spawning roadmapper...
 ```
 
-Spawn maxsim-roadmapper agent with path references:
+Spawn planner (roadmap mode) with path references:
 
 ```
 Task(prompt="
@@ -1161,7 +1161,7 @@ Create roadmap:
 
 Write files first, then return. This ensures artifacts persist even if context is lost.
 </instructions>
-", subagent_type="maxsim-roadmapper", model="{roadmapper_model}", description="Create roadmap")
+", subagent_type="planner", model="{roadmapper_model}", description="Create roadmap")
 ```
 
 **Handle roadmapper return:**
@@ -1241,7 +1241,7 @@ Use AskUserQuestion:
   Update the roadmap based on feedback. Edit files in place.
   Return ROADMAP REVISED with changes made.
   </revision>
-  ", subagent_type="maxsim-roadmapper", model="{roadmapper_model}", description="Revise roadmap")
+  ", subagent_type="planner", model="{roadmapper_model}", description="Revise roadmap")
   ```
 - Present revised roadmap
 - Loop until user approves
@@ -1340,7 +1340,7 @@ Present completion summary:
 ╚══════════════════════════════════════════╝
 ```
 
-Exit skill and invoke SlashCommand("/maxsim:discuss-phase 1 --auto")
+Exit skill and invoke SlashCommand("/maxsim:plan 1 --auto")
 
 **If interactive mode:**
 
@@ -1351,14 +1351,14 @@ Exit skill and invoke SlashCommand("/maxsim:discuss-phase 1 --auto")
 
 **Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
 
-/maxsim:discuss-phase 1 — gather context and clarify approach
+/maxsim:plan 1 — gather context and clarify approach
 
 <sub>/clear first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- /maxsim:plan-phase 1 — skip discussion, plan directly
+- /maxsim:plan 1 — skip discussion, plan directly
 
 ───────────────────────────────────────────────────────────────
 ```
@@ -1397,7 +1397,7 @@ Exit skill and invoke SlashCommand("/maxsim:discuss-phase 1 --auto")
 - [ ] Requirements gathered (from research or conversation)
 - [ ] User scoped each category (v1/v2/out of scope)
 - [ ] REQUIREMENTS.md created with REQ-IDs → **committed**
-- [ ] maxsim-roadmapper spawned with context
+- [ ] planner (roadmap mode) spawned with context
 - [ ] Roadmap files written immediately (not draft)
 - [ ] User feedback incorporated (if any)
 - [ ] ROADMAP.md created with phases, requirement mappings, success criteria
@@ -1406,7 +1406,7 @@ Exit skill and invoke SlashCommand("/maxsim:discuss-phase 1 --auto")
 - [ ] CONVENTIONS.md generated with 4 must-have sections (Tech Stack, File Layout, Error Handling, Testing)
 - [ ] NO-GOS.md populated from confirmed no-gos during questioning
 - [ ] Agent dry-run validation passed (Quality Score >= 7)
-- [ ] User knows next step is `/maxsim:discuss-phase 1`
+- [ ] User knows next step is `/maxsim:plan 1`
 
 **Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.