maxsimcli 4.8.0 → 4.9.0

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

@@ -0,0 +1,421 @@
+<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. `.planning/ROADMAP.md` exists -- if not, stop and tell the user to initialize the project.
+</sanity_check>
+
+<purpose>
+Thin orchestrator for the /maxsim:execute state machine. Detects the current state of a phase (already done, needs verification, needs execution), delegates per-plan execution to execute-plan.md subagents, runs auto-verification, and handles retry with gap closure.
+
+This file is the ORCHESTRATOR ONLY. Per-plan execution logic lives in:
+- @./workflows/execute-plan.md (per-plan subagent execution)
+
+Verification is handled inline (spawning verifier agent) since it is a stage of this workflow, not a separate command.
+</purpose>
+
+<process>
+
+## 1. Initialize
+
+Load phase state in one call:
+
+```bash
+INIT=$(node .claude/maxsim/bin/maxsim-tools.cjs init execute-phase "$PHASE")
+```
+
+Parse `$ARGUMENTS` for: phase number (required), `--worktrees` (force worktree mode), `--no-worktrees` (force standard mode), `--auto` (auto-advance), `--gaps-only` (gap plans only).
+
+Parse JSON for: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `has_verification`, `commit_docs`, `executor_model`, `verifier_model`, `parallelization`, `state_path`, `roadmap_path`, `requirements_path`, `phase_req_ids`.
+
+All flags from `$ARGUMENTS` are passed through to the execute-phase workflow steps so they are available for execution mode decision and auto-advance detection.
+
+**If `phase_found` is false:**
+```
+Phase [X] not found in roadmap.
+
+Use /maxsim:progress to see available phases.
+```
+Exit workflow.
+
+**If `plan_count` is 0:**
+```
+No plans found for Phase {phase_number}.
+
+Run /maxsim:plan {phase_number} first to create execution plans.
+```
+Exit workflow.
+
+## 2. Detect State
+
+Determine where to start based on phase artifacts:
+
+| Condition | State | Action |
+|-----------|-------|--------|
+| `incomplete_count == 0` AND `has_verification == true` | Already done | Go to **Re-entry flow** (step 3) |
+| `incomplete_count == 0` AND `has_verification == false` | Needs verification | Start at **Auto-Verify** (step 5) |
+| `incomplete_count > 0` | Needs execution | Start at **Execute Plans** (step 4) |
+
+Display detected state:
+```
+Phase {phase_number}: {phase_name}
+Current state: {Already executed | Needs verification | Ready to execute}
+Plans: {plan_count} total, {incomplete_count} incomplete
+```
+
+## 3. Re-entry Flow (Already Executed and Verified)
+
+When all plans are complete and verification has passed, show status and offer options.
+
+Display:
+```
+## Phase {phase_number} Already Executed
+
+**Plans:** {plan_count} plan(s) -- all complete
+**Verification:** Passed
+**Phase directory:** {phase_dir}
+
+**Options:**
+1. View results -- show SUMMARY.md files and verification report
+2. Re-execute from scratch -- delete SUMMARYs, restart execution
+3. View verification -- show VERIFICATION.md
+4. Done (exit)
+```
+
+Wait for user choice via natural conversation.
+
+- **View results:** Display contents of each SUMMARY.md file, then re-show options.
+- **Re-execute:** Delete existing SUMMARY.md files, restart from Execute Plans (step 4).
+- **View verification:** Display VERIFICATION.md contents, then re-show options.
+- **Done:** Exit workflow.
+
+## 4. Execute Plans
+
+Execute all plans in wave order, delegating each plan to a subagent via execute-plan.md.
+
+### 4.1 Discover and Group Plans
+
+Load plan inventory with wave grouping:
+
+```bash
+PLAN_INDEX=$(node .claude/maxsim/bin/maxsim-tools.cjs phase-plan-index "${PHASE_NUMBER}")
+```
+
+Parse JSON for: `plans[]` (each with `id`, `wave`, `autonomous`, `objective`, `has_summary`), `waves` (map of wave number to plan IDs), `incomplete`.
+
+Skip plans where `has_summary: true` (already complete -- supports resume).
+
+If all plans already have summaries: skip to Auto-Verify (step 5).
+
+Report:
+```
+## Execution Plan
+
+**Phase {phase_number}: {phase_name}** -- {total_plans} plans across {wave_count} waves
+
+| Wave | Plans | What it builds |
+|------|-------|----------------|
+| 1 | 03-01, 03-02 | {from plan objectives, 3-8 words} |
+| 2 | 03-03 | ... |
+```
+
+### 4.2 Execute Waves
+
+Execute each wave in sequence. Within a wave: parallel if `parallelization` is true, sequential if false.
+
+**For each wave:**
+
+1. **Describe what is being built (BEFORE spawning):**
+
+   Read each plan's `<objective>`. Extract what is being built and why.
+
+   ```
+   ---
+   ## Wave {N}
+
+   **{Plan ID}: {Plan Name}**
+   {2-3 sentences: what this builds, technical approach, why it matters}
+
+   Spawning {count} agent(s)...
+   ---
+   ```
+
+2. **Spawn executor agents:**
+
+   Pass paths only -- executors read files themselves with their fresh 200k context.
+
+   ```
+   Task(
+     subagent_type="executor",
+     model="{executor_model}",
+     prompt="
+       <objective>
+       Execute plan {plan_number} of phase {phase_number}-{phase_name}.
+       Commit each task atomically. Create SUMMARY.md. Update STATE.md and ROADMAP.md.
+       </objective>
+
+       <execution_context>
+       @./workflows/execute-plan.md
+       @./templates/summary.md
+       @./references/checkpoints.md
+       @./references/tdd.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)
+       - .planning/config.json (Config, if exists)
+       - ./CLAUDE.md (Project instructions, if exists)
+       </files_to_read>
+
+       <success_criteria>
+       - [ ] All tasks executed
+       - [ ] Each task committed individually
+       - [ ] SUMMARY.md created in plan directory
+       - [ ] STATE.md updated with position and decisions
+       - [ ] ROADMAP.md updated with plan progress
+       </success_criteria>
+     "
+   )
+   ```
+
+3. **Wait for all agents in wave to complete.**
+
+4. **Spot-check results:**
+
+   For each completed plan's SUMMARY.md:
+   - Verify first 2 files from key-files exist on disk
+   - Check `git log --oneline --all --grep="{phase}-{plan}"` returns at least 1 commit
+   - Check for `## Self-Check: FAILED` marker
+   - Check for `## Review Cycle` section -- verify both Spec and Code stages show PASS
+
+   If ANY spot-check fails: report which plan failed, ask "Retry plan?" or "Continue with remaining waves?"
+
+5. **Report wave completion:**
+
+   ```
+   ---
+   ## Wave {N} Complete
+
+   **{Plan ID}: {Plan Name}**
+   {What was built -- from SUMMARY.md}
+   {Notable deviations, if any}
+
+   {If more waves: what this enables for next wave}
+   ---
+   ```
+
+6. **Handle checkpoint plans:** Plans with `autonomous: false` may return checkpoints. Present checkpoint to user, spawn continuation agent after user responds, wait for completion before proceeding.
+
+7. **Proceed to next wave.**
+
+### 4.3 Execution Summary Gate
+
+After all waves complete:
+
+```
+## Gate: Execution Complete
+
+**Plans executed:** {completed}/{total}
+**Waves:** {wave_count}
+**Commits:** {list of commit summaries from SUMMARY.md files}
+
+Proceeding to verification...
+```
+
+Wait for user confirmation before proceeding to verification.
+
+## 5. Auto-Verify
+
+Verify that the phase achieved its GOAL, not just that tasks completed.
+
+### 5.1 Spawn Verifier
+
+Resolve verifier model and spawn the verifier agent:
+
+```bash
+VERIFIER_MODEL=$(node .claude/maxsim/bin/maxsim-tools.cjs resolve-model verifier --raw)
+```
+
+```
+Task(
+  prompt="Verify phase {phase_number} goal achievement.
+Phase directory: {phase_dir}
+Phase goal: {goal from ROADMAP.md}
+Phase requirement IDs: {phase_req_ids}
+Check must_haves against actual codebase.
+Cross-reference requirement IDs from PLAN frontmatter against REQUIREMENTS.md.
+Create VERIFICATION.md.",
+  subagent_type="verifier",
+  model="{verifier_model}"
+)
+```
+
+### 5.2 Parse Verifier Result
+
+Read verification status:
+```bash
+grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
+```
+
+**If `passed`:** Show verification gate and proceed to completion.
+
+```
+## Gate: Verification Passed
+
+**Status:** All must-haves verified
+**Evidence:** {summary from VERIFICATION.md}
+
+Phase {phase_number} complete!
+```
+
+Mark phase complete:
+```bash
+COMPLETION=$(node .claude/maxsim/bin/maxsim-tools.cjs phase complete "${PHASE_NUMBER}")
+```
+
+Update tracking files:
+```bash
+node .claude/maxsim/bin/maxsim-tools.cjs commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md
+```
+
+**If `gaps_found`:** Proceed to Retry Loop (step 6).
+
+**If `human_needed`:** Present items for human testing, get approval or feedback. If approved, treat as passed. If issues reported, proceed to Retry Loop.
+
+## 6. Retry Loop (Max 2 Retries)
+
+If verification failed, attempt gap closure. Maximum 2 retries (3 total attempts including the initial execution).
+
+Initialize: `attempt_count = 1`
+
+### 6.1 Check Attempt Budget
+
+If `attempt_count > 2`:
+```
+## Verification Failed After 3 Attempts
+
+**Status:** Could not resolve all gaps
+**Attempts:** 3 (initial + 2 retries)
+
+### What Failed
+{List of unresolved gaps from VERIFICATION.md with evidence}
+
+### Options
+1. Fix manually and re-run `/maxsim:execute {phase_number}`
+2. Run `/maxsim:debug` to investigate failing items
+3. Accept as-is and continue to next phase
+```
+
+Wait for user decision. Exit workflow.
+
+### 6.2 Plan Gap Closure
+
+Display: "Verification failed. Retrying... (attempt {attempt_count + 1}/3)"
+
+Spawn planner in gap-closure mode to create fix plans:
+
+```
+Task(
+  prompt="
+<planning_context>
+**Phase:** {phase_number}
+**Mode:** gap_closure
+
+<files_to_read>
+- {phase_dir}/{phase_num}-VERIFICATION.md (Verification with gaps)
+- .planning/STATE.md (Project State)
+- .planning/ROADMAP.md (Roadmap)
+</files_to_read>
+</planning_context>
+
+<downstream_consumer>
+Output consumed by /maxsim:execute.
+Plans must be executable prompts.
+</downstream_consumer>
+",
+  subagent_type="planner",
+  model="{planner_model}"
+)
+```
+
+### 6.3 Execute Gap Plans
+
+Execute the newly created gap-closure plans using the same wave execution logic from step 4. Only execute plans with `gap_closure: true` in frontmatter.
+
+### 6.4 Re-verify
+
+Spawn verifier again (back to step 5). Increment `attempt_count`.
+
+If verification passes: proceed to completion.
+If verification fails and attempts remain: loop back to 6.1.
+
+## 7. Checkpoint Before /clear
+
+At any point during the workflow, if context is getting full (conversation is long, many tool calls made), recommend checkpointing before `/clear`.
+
+**Checkpoint protocol:**
+1. Post a checkpoint comment to the phase's GitHub Issue (if issue tracking is active):
+```bash
+# Use MCP tool to post checkpoint
+mcp_post_plan_comment(
+  phase_issue_number={issue_number},
+  plan_number="checkpoint",
+  plan_content="## MAXSIM Checkpoint\n\n**Command:** /maxsim:execute\n**Stage:** {current_stage}\n**Plans completed:** {completed_count}/{total_count}\n**Verification attempts:** {attempt_count}/3\n**Resume from:** {next_action}\n**Timestamp:** {ISO timestamp}"
+)
+```
+
+2. Display checkpoint recommendation:
+```
+Context is filling up. Recommended: save progress and /clear.
+
+Your progress has been checkpointed. Re-run `/maxsim:execute {phase_number}` after /clear -- it will detect completed plans and resume from where it left off.
+```
+
+The state detection in step 2 handles resume automatically -- completed plans have SUMMARY.md files that are detected on re-entry.
+
+## 8. Update State
+
+After verification passes, update STATE.md:
+
+```bash
+node .claude/maxsim/bin/maxsim-tools.cjs state record-session \
+  --stopped-at "Phase ${PHASE} executed and verified" \
+  --resume-file "${phase_dir}"
+```
+
+## 9. Completion
+
+Display final results:
+
+```
+## Phase {phase_number}: {phase_name} -- Execution Complete
+
+**Plans:** {completed}/{total} complete
+**Waves:** {wave_count}
+**Verification:** Passed (attempt {attempt_count}/3)
+
+### Plan Details
+1. **{plan_id}**: {one-liner from SUMMARY.md}
+2. **{plan_id}**: {one-liner from SUMMARY.md}
+
+### Next Steps
+- `/maxsim:plan {next_phase}` -- Plan next phase
+- `/maxsim:progress` -- View overall progress
+```
+
+</process>
+
+<success_criteria>
+- [ ] Phase validated against roadmap
+- [ ] Current state correctly detected from artifacts
+- [ ] Re-entry flow works for already-executed phases
+- [ ] Plans discovered and grouped by wave
+- [ ] Per-plan execution delegates to execute-plan.md sub-workflow via Task
+- [ ] Spot-check of SUMMARY.md after each wave
+- [ ] Gate confirmation shown after execution completes
+- [ ] Auto-verification spawns verifier agent
+- [ ] Retry loop with gap closure (max 2 retries, 3 total attempts)
+- [ ] Checkpoint-before-clear pattern available
+- [ ] No references to old commands (execute-phase, verify-work)
+</success_criteria>

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

@@ -0,0 +1,250 @@
+<purpose>
+Auto-detect project state through deep context gathering, surface problems proactively, and dispatch to the appropriate MAXSIM command. Uses the Show + Act pattern: display detection reasoning first, then act immediately.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="immediate_feedback">
+**Show immediate feedback while gathering context:**
+
+```
+Analyzing project state...
+```
+
+This ensures the user sees something immediately while context gathering runs.
+</step>
+
+<step name="deep_context_gathering">
+**Phase 1: Deep Context Gathering**
+
+Gather all project signals in parallel for speed. Run these checks simultaneously:
+
+**1. Project existence check:**
+```bash
+PLANNING_EXISTS=$(test -d .planning && echo "true" || echo "false")
+```
+
+If `.planning/` does not exist, skip all other checks and go directly to the decision tree (Rule 1: No project found).
+
+**2. Load project state (if .planning/ exists):**
+```bash
+# State snapshot
+STATE=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs state-snapshot 2>/dev/null || echo "{}")
+
+# Roadmap analysis
+ROADMAP=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap analyze 2>/dev/null || echo "{}")
+```
+
+**3. Read key files (if they exist):**
+- `.planning/PROJECT.md` -- project name and vision
+- `.planning/STATE.md` -- blockers, decisions, session continuity
+- `.planning/ROADMAP.md` -- phase structure and progress
+
+**4. Git context:**
+```bash
+# Uncommitted changes
+GIT_STATUS=$(git status --porcelain 2>/dev/null | head -20)
+
+# Recent commits
+RECENT_COMMITS=$(git log --oneline -5 2>/dev/null)
+```
+
+**5. Phase directory scan:**
+```bash
+# List phase directories and their contents
+ls -1 .planning/phases/ 2>/dev/null
+```
+
+For each phase directory, check for PLAN.md, SUMMARY.md, CONTEXT.md, RESEARCH.md files to determine phase state.
+</step>
+
+<step name="problem_detection">
+**Phase 2: Problem Detection**
+
+Check for problems BEFORE suggesting any action. All problems are blocking -- no severity tiers.
+
+**Check each of these in order:**
+
+**1. Uncommitted changes in .planning/**
+```bash
+git status --porcelain .planning/ 2>/dev/null | head -10
+```
+If uncommitted changes exist in `.planning/`:
+```
+## Problem Detected
+
+**Issue:** Uncommitted changes in .planning/ directory
+**Impact:** State drift -- local planning files may diverge from team or lose work
+**Resolution:** Commit planning changes to preserve state
+
+**Files with changes:**
+{list of changed files}
+
+Resolve this before continuing. Options:
+1. Commit now (recommended)
+2. Investigate changes first
+3. Skip and continue anyway
+```
+
+Block until user responds.
+
+**2. Blockers in STATE.md**
+Extract blockers from state snapshot. If any exist:
+```
+## Problem Detected
+
+**Issue:** Active blocker recorded in project state
+**Blocker:** {blocker text}
+**Impact:** Execution cannot proceed safely until this is resolved
+**Resolution:** Address the blocker or remove it if no longer relevant
+
+Resolve this before continuing. Options:
+1. Investigate and resolve
+2. Remove blocker (if no longer relevant)
+3. Skip and continue anyway
+```
+
+Block until user responds.
+
+**3. Failed verification**
+Check for VERIFICATION.md in the current/latest phase with FAIL status:
+```bash
+grep -l "FAIL\|status: failed" .planning/phases/*/VERIFICATION.md 2>/dev/null | tail -1
+```
+If found:
+```
+## Problem Detected
+
+**Issue:** Phase verification failed
+**Phase:** {phase number and name}
+**Impact:** Phase is not verified as complete -- may have gaps
+**Resolution:** Re-run verification or fix identified issues
+
+Resolve this before continuing. Options:
+1. View verification results
+2. Re-execute to fix issues
+3. Skip and continue anyway
+```
+
+Block until user responds.
+
+**If any problem is found:** Surface it and wait for user resolution. Do NOT proceed to the decision tree until all problems are cleared or explicitly skipped.
+
+**If no problems found:** Proceed to the decision tree.
+</step>
+
+<step name="decision_tree">
+**Phase 3: Decision Tree**
+
+Apply rules in strict precedence order. The FIRST matching rule determines the action.
+
+```
+Rule 1: No .planning/ directory?
+  -> Action: /maxsim:init
+  -> Reasoning: "No MAXSIM project found in this directory."
+
+Rule 2: Has blockers in STATE.md? (not cleared in problem detection)
+  -> Action: Surface blocker, suggest resolution
+  -> Reasoning: "BLOCKED: {blocker text}"
+
+Rule 3: Active phase has plans but not all executed?
+  -> Check: summaries < plans in current phase directory
+  -> Action: /maxsim:execute {N}
+  -> Reasoning: "Phase {N} ({name}) has {X} plans, {Y} executed. Ready to continue."
+
+Rule 4: Active phase needs planning? (no PLAN.md files)
+  -> Check: no PLAN.md files in current phase directory
+  -> Action: /maxsim:plan {N}
+  -> Reasoning: "Phase {N} ({name}) needs planning."
+
+  Sub-check: Does CONTEXT.md exist?
+  -> If yes: "Discussion complete, ready for research + planning."
+  -> If no: "Starting from discussion stage."
+
+Rule 5: Current phase complete, next phase exists?
+  -> Check: all plans have summaries AND next phase exists in roadmap
+  -> Action: /maxsim:plan {N+1}
+  -> Reasoning: "Phase {N} complete. Next: Phase {N+1} ({name})."
+
+Rule 6: All phases complete?
+  -> Check: all phases in roadmap have all plans executed
+  -> Action: /maxsim:progress
+  -> Reasoning: "All phases complete. Milestone ready for review."
+
+Rule 7: None of the above?
+  -> Action: Show interactive menu
+  -> Reasoning: "Project state is ambiguous. Here are your options."
+```
+</step>
+
+<step name="show_and_act">
+**Phase 4: Show + Act**
+
+Once a rule matches, display detection reasoning FIRST, then act immediately.
+
+**Format for auto-dispatch (Rules 1-6):**
+
+```
+## Detected: {summary of what was found}
+
+**Project:** {project name from PROJECT.md, or "New project"}
+**Milestone:** {milestone from ROADMAP.md, or "Not started"}
+**Current phase:** {phase N - name, or "None"}
+**Status:** {description of current state}
+
+**Action:** Running /maxsim:{command} {args}...
+```
+
+Then immediately dispatch the command using the SlashCommand tool. The user can Ctrl+C if the detection is wrong.
+
+**Important:** Show the detection block, then dispatch. Do not ask for confirmation -- this is Show + Act, not Show + Ask.
+</step>
+
+<step name="interactive_menu">
+**Phase 5: Interactive Menu (Rule 7 -- no obvious action)**
+
+When no clear action is detected, show a contextual menu. The menu items are NOT static -- filter based on what makes sense for the current project state.
+
+```
+## Project Status
+
+**Project:** {project name}
+**Milestone:** {milestone}
+**Progress:** {X}/{Y} phases complete
+
+What would you like to do?
+
+1. /maxsim:plan {next_phase} -- Plan next phase
+2. /maxsim:quick -- Quick ad-hoc task
+3. /maxsim:progress -- View detailed progress
+4. /maxsim:debug -- Debug an issue
+
+Or describe what you'd like to do:
+```
+
+**Contextual filtering rules:**
+- If phases are planned but not executed: show execute options prominently
+- If all phases are done: show `/maxsim:progress` (offers milestone completion)
+- If recent git activity suggests debugging: show `/maxsim:debug` prominently
+- If no phases exist: show `/maxsim:plan` prominently
+- Always include `/maxsim:quick` as it is always relevant
+- Always include an open-ended fallback ("Or describe what you'd like to do")
+
+Wait for user selection, then dispatch the chosen command.
+</step>
+
+</process>
+
+<constraints>
+- Never ask for confirmation before dispatching (Show + Act, not Show + Ask)
+- Always surface problems BEFORE suggesting actions
+- All problems block -- no severity tiers, no "warnings"
+- No arguments accepted -- this is pure auto-detection
+- No mention of old commands (plan-phase, execute-phase, etc.)
+- Keep initial feedback fast -- show "Analyzing..." before heavy operations
+- If context gathering fails (tools not available, etc.), fall back to the interactive menu
+</constraints>

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

@@ -62,10 +62,10 @@ Errors: N | Warnings: N | Info: N
 ## Errors
 
 - [E001] config.json: JSON parse error at line 5
-  Fix: Run /maxsim:health --repair to reset to defaults
+  Fix: Run /maxsim:progress (health check) --repair to reset to defaults
 
 - [E002] PROJECT.md not found
-  Fix: Run /maxsim:new-project to create
+  Fix: Run /maxsim:init to create
 ```
 
 **If warnings exist:**
@@ -73,7 +73,7 @@ Errors: N | Warnings: N | Info: N
 ## Warnings
 
 - [W001] STATE.md references phase 5, but only phases 1-3 exist
-  Fix: Run /maxsim:health --repair to regenerate
+  Fix: Run /maxsim:progress (health check) --repair to regenerate
 
 - [W005] Phase directory "1-setup" doesn't follow NN-name format
   Fix: Rename to match pattern (e.g., 01-setup)
@@ -90,7 +90,7 @@ Errors: N | Warnings: N | Info: N
 **Footer (if repairable issues exist and --repair was NOT used):**
 ```
 ---
-N issues can be auto-repaired. Run: /maxsim:health --repair
+N issues can be auto-repaired. Run: /maxsim:progress (health check) --repair
 ```
 </step>
 
@@ -100,7 +100,7 @@ N issues can be auto-repaired. Run: /maxsim:health --repair
 Ask user if they want to run repairs:
 
 ```
-Would you like to run /maxsim:health --repair to fix N issues automatically?
+Would you like to run /maxsim:progress (health check) --repair to fix N issues automatically?
 ```
 
 If yes, re-run with --repair flag and display results.