maxsimcli 3.10.3 → 3.12.0

package/dist/assets/templates/skills/using-maxsim/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: using-maxsim
+description: Entry skill that establishes MAXSIM workflow rules — triggers before any action to route work through the correct MAXSIM commands, skills, and agents
+---
+
+# Using MAXSIM
+
+MAXSIM is a spec-driven development system. Work flows through phases, plans, and tasks — not ad-hoc coding.
+
+**If you are about to write code without a plan, STOP. Route through MAXSIM first.**
+
+## The Iron Law
+
+<HARD-GATE>
+NO IMPLEMENTATION WITHOUT A PLAN.
+If there is no .planning/ directory, run `/maxsim:init` first.
+If there is no current phase, run `/maxsim:plan-phase` first.
+If there is no PLAN.md for the current phase, run `/maxsim:plan-phase` first.
+If there IS a plan, run `/maxsim:execute-phase` to execute it.
+Skipping the workflow is a violation — not a shortcut.
+</HARD-GATE>
+
+## When This Skill Triggers
+
+This skill applies to ALL work sessions. Before starting any task:
+
+1. **Check for `.planning/` directory** — if missing, initialize with `/maxsim:init`
+2. **Check STATE.md** — resume from last checkpoint if one exists
+3. **Check current phase** — determine what phase is active in ROADMAP.md
+4. **Route to the correct command** based on the situation (see routing table below)
+
+## Routing Table
+
+| Situation | Route To |
+|-----------|----------|
+| No `.planning/` directory | `/maxsim:init` |
+| No ROADMAP.md or empty roadmap | `/maxsim:plan-roadmap` |
+| Active phase has no PLAN.md | `/maxsim:plan-phase` |
+| Active phase has PLAN.md, not started | `/maxsim:execute-phase` |
+| Checkpoint exists in STATE.md | `/maxsim:resume-work` |
+| Bug found during execution | `/maxsim:debug` (triggers systematic-debugging skill) |
+| Phase complete, needs verification | `/maxsim:verify-phase` (triggers verification-before-completion skill) |
+| Quick standalone task | `/maxsim:quick` |
+| User asks for help | `/maxsim:help` |
+
+## Available Skills
+
+Skills are behavioral rules that activate automatically based on context:
+
+| Skill | Triggers When |
+|-------|---------------|
+| `systematic-debugging` | Any bug, test failure, or unexpected behavior encountered |
+| `tdd` | Implementing any feature or bug fix (write test first) |
+| `verification-before-completion` | Before claiming any work is complete or passing |
+| `memory-management` | Recurring patterns, errors, or decisions worth persisting |
+| `using-maxsim` | Always — entry point for all MAXSIM work |
+
+## Available Agents
+
+Agents are specialized subagent prompts spawned by MAXSIM commands:
+
+| Agent | Purpose | Triggered By |
+|-------|---------|-------------|
+| `maxsim-executor` | Executes plans with atomic commits | `/maxsim:execute-phase` |
+| `maxsim-planner` | Creates structured PLAN.md files | `/maxsim:plan-phase` |
+| `maxsim-debugger` | Investigates bugs systematically | `/maxsim:debug` |
+| `maxsim-verifier` | Verifies phase goal achievement | `/maxsim:verify-phase` |
+| `maxsim-roadmapper` | Creates project roadmaps | `/maxsim:plan-roadmap` |
+| `maxsim-phase-researcher` | Researches phase requirements | `/maxsim:plan-phase` |
+| `maxsim-code-reviewer` | Reviews code changes | `/maxsim:review` |
+| `maxsim-spec-reviewer` | Reviews specifications | `/maxsim:plan-roadmap` |
+| `maxsim-plan-checker` | Validates plan completeness | `/maxsim:plan-phase` |
+| `maxsim-project-researcher` | Researches project context | `/maxsim:init` |
+| `maxsim-research-synthesizer` | Synthesizes research findings | `/maxsim:plan-phase` |
+| `maxsim-codebase-mapper` | Maps codebase structure | `/maxsim:init` |
+| `maxsim-integration-checker` | Checks integration points | `/maxsim:verify-phase` |
+
+## Common Rationalizations — REJECT THESE
+
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "It's just a small fix" | Small fixes have context and consequences. Use `/maxsim:quick`. |
+| "I know what to do, I don't need a plan" | Plans catch what you miss. The plan is the checkpoint. |
+| "MAXSIM overhead is too much for this" | `/maxsim:quick` exists for lightweight tasks. Use it. |
+| "I'll plan it in my head" | Plans in your head die with context. Write them down. |
+| "The user said 'just do it'" | Route through `/maxsim:quick` — it is fast and still tracked. |
+
+## Red Flags — STOP If You Catch Yourself:
+
+- Writing implementation code without a PLAN.md
+- Skipping `/maxsim:init` because "the project is simple"
+- Ignoring STATE.md checkpoints from previous sessions
+- Working outside the current phase without explicit user approval
+- Making architectural decisions without documenting them in STATE.md
+- Finishing work without running verification
+
+**If any red flag triggers: STOP. Check the routing table. Follow the workflow.**
+
+## Verification Checklist
+
+Before ending any work session:
+
+- [ ] All work was routed through MAXSIM commands (not ad-hoc)
+- [ ] STATE.md reflects current progress and decisions
+- [ ] Any bugs encountered were debugged systematically (not guessed)
+- [ ] Tests were written before implementation (TDD)
+- [ ] Completion claims have verification evidence
+- [ ] Recurring patterns or errors were saved to memory
+
+## Integration with CLAUDE.md
+
+When a project has a `CLAUDE.md`, both apply:
+- `CLAUDE.md` defines project-specific conventions (language, tools, style)
+- MAXSIM skills define workflow rules (how work is structured and verified)
+- If they conflict, `CLAUDE.md` project conventions take priority for code style; MAXSIM takes priority for workflow structure

package/dist/assets/templates/templates/config.json

@@ -3,7 +3,7 @@
   "depth": "standard",
   "workflow": {
     "research": true,
-    "plan_check": true,
+    "plan_checker": true,
     "verifier": true,
     "auto_advance": false,
     "nyquist_validation": false

package/dist/assets/templates/workflows/add-tests.md

@@ -141,10 +141,10 @@ If user selects "Cancel": exit gracefully.
 Before generating the test plan, discover the project's existing test structure:
 
 ```bash
-# Find existing test directories
-find . -type d -name "*test*" -o -name "*spec*" -o -name "*__tests__*" 2>/dev/null | head -20
+# Find existing test directories and files (cross-platform)
+git ls-files --others --cached --exclude-standard | grep -E "(test|spec|__tests__)" | head -20
 # Find existing test files for convention matching
-find . -type f \( -name "*.test.*" -o -name "*.spec.*" -o -name "*Tests.fs" -o -name "*Test.fs" \) 2>/dev/null | head -20
+git ls-files --others --cached --exclude-standard | grep -E "\.(test|spec)\.|Tests\.(fs|cs)|Test\.(fs|cs)" | head -20
 # Check for test runners
 ls package.json *.sln 2>/dev/null
 ```

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

@@ -128,7 +128,7 @@ Calculate milestone statistics:
 ```bash
 git log --oneline --grep="feat(" | head -20
 git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
-find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
+git ls-files --cached --exclude-standard -- "*.swift" "*.ts" "*.py" | xargs wc -l 2>/dev/null
 git log --format="%ai" FIRST_COMMIT | tail -1
 git log --format="%ai" LAST_COMMIT | head -1
 ```

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

@@ -36,20 +36,8 @@ Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelizat
 When `parallelization` is false, plans within a wave execute sequentially.
 </step>
 
-<step name="launch_dashboard">
-Launch the live project dashboard (if not already running):
-
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs dashboard 2>/dev/null || true
-```
-
-This is idempotent: if the dashboard is already running, it prints the URL. If not, it spawns a detached subprocess that survives the execute-phase session.
-
-The dashboard provides a real-time visual companion showing phase progress, plan tasks, and blockers as execution proceeds.
-
-**Best-effort:** If the dashboard fails to start (e.g., not installed, build missing), execution continues without it. Do NOT gate phase execution on dashboard availability.
-
-**Dashboard MCP probe:** After the dashboard launch attempt, probe for MCP availability (see @dashboard-bridge). If `DASHBOARD_ACTIVE`, emit:
+<step name="probe_dashboard">
+Probe for MCP dashboard availability (see @dashboard-bridge). If `DASHBOARD_ACTIVE`, emit:
 ```
 mcp__maxsim-dashboard__submit_lifecycle_event(
   event_type: "phase-started",
@@ -57,6 +45,8 @@ mcp__maxsim-dashboard__submit_lifecycle_event(
   phase_number: PHASE_NUMBER
 )
 ```
+
+**Note:** The dashboard is NOT auto-launched. Users start it explicitly via `maxsim dashboard`. This step only checks if a running dashboard is reachable via MCP.
 </step>
 
 <step name="handle_branching">

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

@@ -10,6 +10,16 @@ Read config.json for planning behavior settings.
 @./references/dashboard-bridge.md
 </required_reading>
 
+## MCP Server Fallback
+
+MAXSIM provides MCP tools (mcp_create_phase, mcp_list_phases, etc.) for structured operations.
+If MCP tools are available in your tool list, prefer them for phase, todo, and state operations.
+
+**If MCP tools are NOT available** (server not running, .mcp.json not configured, or non-Claude runtime):
+- Log a warning: "MCP server not available -- using Bash tools router fallback"
+- Fall back to the Bash tools router: `node .claude/maxsim/bin/maxsim-tools.cjs <command>`
+- All operations work identically via either path -- MCP is preferred but not required
+
 <process>
 
 <step name="init_context" priority="first">

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

@@ -9,6 +9,10 @@ Read all files referenced by the invoking prompt's execution_context before star
 @./references/dashboard-bridge.md
 </required_reading>
 
+<tool_mandate>
+**Question routing:** At workflow start, probe for the dashboard (see @dashboard-bridge). If `DASHBOARD_ACTIVE = true`, route ALL `AskUserQuestion` calls through `mcp__maxsim-dashboard__ask_question` using the schema translation rules from @dashboard-bridge. If `DASHBOARD_ACTIVE = false`, use `AskUserQuestion` as normal.
+</tool_mandate>
+
 <auto_mode>
 ## Auto Mode Detection
 
@@ -258,7 +262,7 @@ Print per-agent completion status:
 After all agents complete, also create a file tree overview:
 
 ```bash
-find . -type f | grep -v node_modules | grep -v .git | grep -v .planning | grep -v __pycache__ | grep -v .next | grep -v dist/ | grep -v build/ | head -200 > .planning/codebase/STRUCTURE.md
+git ls-files --others --cached --exclude-standard | grep -v node_modules | grep -v __pycache__ | grep -v .next | grep -v dist/ | grep -v build/ | head -200 > .planning/codebase/STRUCTURE.md
 ```
 
 Then wrap it with a header:
@@ -321,7 +325,7 @@ Store discrepancy notes in a variable for use in Steps 6 and 9.
   "model_profile": "balanced",
   "workflow": {
     "research": true,
-    "plan_check": true,
+    "plan_checker": true,
     "verifier": true
   }
 }
@@ -461,7 +465,7 @@ AskUserQuestion([
   "model_profile": "[quality|balanced|budget]",
   "workflow": {
     "research": [true|false],
-    "plan_check": [true|false],
+    "plan_checker": [true|false],
     "verifier": [true|false]
   }
 }

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

@@ -11,6 +11,10 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 </required_reading>
 
+<tool_mandate>
+**Question routing:** At workflow start, probe for the dashboard (see @dashboard-bridge). If `DASHBOARD_ACTIVE = true`, route ALL `AskUserQuestion` calls through `mcp__maxsim-dashboard__ask_question` using the schema translation rules from @dashboard-bridge. If `DASHBOARD_ACTIVE = false`, use `AskUserQuestion` as normal.
+</tool_mandate>
+
 <process>
 
 ## 1. Load Context

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

@@ -7,6 +7,10 @@ Read all files referenced by the invoking prompt's execution_context before star
 @./references/dashboard-bridge.md
 </required_reading>
 
+<tool_mandate>
+**Question routing:** At workflow start, probe for the dashboard (see @dashboard-bridge). If `DASHBOARD_ACTIVE = true`, route ALL `AskUserQuestion` calls through `mcp__maxsim-dashboard__ask_question` using the schema translation rules from @dashboard-bridge. If `DASHBOARD_ACTIVE = false`, use `AskUserQuestion` as normal.
+</tool_mandate>
+
 <auto_mode>
 ## Auto Mode Detection
 
@@ -176,7 +180,7 @@ Create `.planning/config.json` with mode set to "yolo":
   "model_profile": "quality|balanced|budget",
   "workflow": {
     "research": true|false,
-    "plan_check": true|false,
+    "plan_checker": true|false,
     "verifier": true|false,
     "auto_advance": true
   }
@@ -475,7 +479,7 @@ Create `.planning/config.json` with all settings:
   "model_profile": "quality|balanced|budget",
   "workflow": {
     "research": true|false,
-    "plan_check": true|false,
+    "plan_checker": true|false,
     "verifier": true|false
   }
 }

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

@@ -25,7 +25,7 @@ Load all context in one call (paths only to minimize orchestrator context):
 INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init plan-phase "$PHASE")
 ```
 
-Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `plan_count`, `planning_exists`, `roadmap_exists`, `phase_req_ids`.
+Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `plan_count`, `planning_exists`, `roadmap_exists`, `phase_req_ids`.
 
 **File paths (for <files_to_read> blocks):** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `verification_path`, `uat_path`. These are null if files don't exist.
 
@@ -136,7 +136,7 @@ Task(
 
 ## 5.5. Create Validation Strategy (if Nyquist enabled)
 
-**Skip if:** `nyquist_validation_enabled` is false from INIT JSON.
+**Skip if:** `workflow.nyquist_validation` is false in `.planning/config.json`.
 
 After researcher completes, check if RESEARCH.md contains a Validation Architecture section:
 

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

@@ -1,5 +1,5 @@
 <purpose>
-Interactive configuration of MAXSIM workflow agents (research, plan_check, verifier) and model profile selection via multi-question prompt. Updates .planning/config.json with user preferences. Optionally saves settings as global defaults (~/.maxsim/defaults.json) for future projects.
+Interactive configuration of MAXSIM workflow agents (research, plan_checker, verifier) and model profile selection via multi-question prompt. Updates .planning/config.json with user preferences. Optionally saves settings as global defaults (~/.maxsim/defaults.json) for future projects.
 </purpose>
 
 <required_reading>
@@ -7,6 +7,10 @@ Read all files referenced by the invoking prompt's execution_context before star
 @./references/dashboard-bridge.md
 </required_reading>
 
+<tool_mandate>
+**Question routing:** At workflow start, probe for the dashboard (see @dashboard-bridge). If `DASHBOARD_ACTIVE = true`, route ALL `AskUserQuestion` calls through `mcp__maxsim-dashboard__ask_question` using the schema translation rules from @dashboard-bridge. If `DASHBOARD_ACTIVE = false`, use `AskUserQuestion` as normal.
+</tool_mandate>
+
 <process>
 
 <step name="ensure_and_load_config">
@@ -27,7 +31,7 @@ cat .planning/config.json
 
 Parse current values (default to `true` if not present):
 - `workflow.research` — spawn researcher during plan-phase
-- `workflow.plan_check` — spawn plan checker during plan-phase
+- `workflow.plan_checker` — spawn plan checker during plan-phase
 - `workflow.verifier` — spawn verifier during execute-phase
 - `workflow.nyquist_validation` — validation architecture research during plan-phase
 - `model_profile` — which model each agent uses (default: `balanced`)
@@ -117,7 +121,7 @@ Merge new settings into existing config.json:
   "model_profile": "quality" | "balanced" | "budget",
   "workflow": {
     "research": true/false,
-    "plan_check": true/false,
+    "plan_checker": true/false,
     "verifier": true/false,
     "auto_advance": true/false,
     "nyquist_validation": true/false
@@ -165,7 +169,7 @@ Write `~/.maxsim/defaults.json` with:
   "branching_strategy": <current>,
   "workflow": {
     "research": <current>,
-    "plan_check": <current>,
+    "plan_checker": <current>,
     "verifier": <current>,
     "auto_advance": <current>,
     "nyquist_validation": <current>

package/dist/assets/templates/workflows/verify-work.md

@@ -38,7 +38,7 @@ Parse JSON for: `planner_model`, `checker_model`, `commit_docs`, `phase_found`,
 **First: Check for active UAT sessions**
 
 ```bash
-find .planning/phases -name "*-UAT.md" -type f 2>/dev/null | head -5
+ls .planning/phases/*/*-UAT.md 2>/dev/null | head -5
 ```
 
 **If active sessions exist AND no $ARGUMENTS provided:**