maxsimcli 4.8.0 → 4.9.0

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

@@ -5,521 +5,251 @@ Display the complete MAXSIM command reference. Output ONLY the reference content
 <reference>
 # MAXSIM Command Reference
 
-**MAXSIM** creates hierarchical project plans optimized for solo agentic development with Claude Code.
+MAXSIM is a spec-driven development system for Claude Code. It structures work into milestones, phases, plans, and tasks -- each backed by state-machine logic that tracks progress and resumes automatically.
 
-## Quick Start
+## Table of Contents
 
-1. `/maxsim:new-project` - Initialize project (includes research, requirements, roadmap)
-2. `/maxsim:plan-phase 1` - Create detailed plan for first phase
-3. `/maxsim:execute-phase 1` - Execute the phase
+1. [Getting Started](#getting-started)
+2. [Commands](#commands)
+3. [Plan Flow](#plan-flow)
+4. [Execute Flow](#execute-flow)
+5. [Project Structure](#project-structure)
+6. [Quick Reference](#quick-reference)
 
-## Staying Updated
+---
 
-MAXSIM evolves fast. Update periodically:
+## Getting Started
 
-```bash
-npx maxsimcli@latest
-```
+**First time?** Run `/maxsim:init` to initialize your project.
 
-## Core Workflow
+**Returning?** Run `/maxsim:go` to auto-detect where you left off.
 
+**Core loop:**
 ```
-/maxsim:new-project → /maxsim:plan-phase → /maxsim:execute-phase → repeat
+/maxsim:init --> /maxsim:plan 1 --> /maxsim:execute 1 --> /maxsim:plan 2 --> ...
 ```
 
-### Project Initialization
-
-**`/maxsim:new-project`**
-Initialize new project through unified flow.
-
-One command takes you from idea to ready-for-planning:
-- Deep questioning to understand what you're building
-- Optional domain research (spawns 4 parallel researcher agents)
-- Requirements definition with v1/v2/out-of-scope scoping
-- Roadmap creation with phase breakdown and success criteria
-
-Creates all `.planning/` artifacts:
-- `PROJECT.md` — vision and requirements
-- `config.json` — workflow mode (interactive/yolo)
-- `research/` — domain research (if selected)
-- `REQUIREMENTS.md` — scoped requirements with REQ-IDs
-- `ROADMAP.md` — phases mapped to requirements
-- `STATE.md` — project memory
-
-Usage: `/maxsim:new-project`
-
-**`/maxsim:map-codebase`**
-Map an existing codebase for brownfield projects.
-
-- Analyzes codebase with parallel Explore agents
-- Creates `.planning/codebase/` with 7 focused documents
-- Covers stack, architecture, structure, conventions, testing, integrations, concerns
-- Use before `/maxsim:new-project` on existing codebases
-
-Usage: `/maxsim:map-codebase`
-
-### Phase Planning
-
-**`/maxsim:discuss-phase <number>`**
-Help articulate your vision for a phase before planning.
-
-- Captures how you imagine this phase working
-- Creates CONTEXT.md with your vision, essentials, and boundaries
-- Use when you have ideas about how something should look/feel
-
-Usage: `/maxsim:discuss-phase 2`
-
-**`/maxsim:research-phase <number>`**
-Comprehensive ecosystem research for niche/complex domains.
-
-- Discovers standard stack, architecture patterns, pitfalls
-- Creates RESEARCH.md with "how experts build this" knowledge
-- Use for 3D, games, audio, shaders, ML, and other specialized domains
-- Goes beyond "which library" to ecosystem knowledge
-
-Usage: `/maxsim:research-phase 3`
-
-**`/maxsim:list-phase-assumptions <number>`**
-See what Claude is planning to do before it starts.
-
-- Shows Claude's intended approach for a phase
-- Lets you course-correct if Claude misunderstood your vision
-- No files created - conversational output only
-
-Usage: `/maxsim:list-phase-assumptions 3`
-
-**`/maxsim:plan-phase <number>`**
-Create detailed execution plan for a specific phase.
-
-- Generates `.planning/phases/XX-phase-name/XX-YY-PLAN.md`
-- Breaks phase into concrete, actionable tasks
-- Includes verification criteria and success measures
-- Multiple plans per phase supported (XX-01, XX-02, etc.)
-
-Usage: `/maxsim:plan-phase 1`
-Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
+---
 
-### Execution
+## Commands
 
-**`/maxsim:execute-phase <phase-number>`**
-Execute all plans in a phase.
+### /maxsim:init
 
-- Groups plans by wave (from frontmatter), executes waves sequentially
-- Plans within each wave run in parallel via Task tool
-- Verifies phase goal after all plans complete
-- Updates REQUIREMENTS.md, ROADMAP.md, STATE.md
+Initialize a new project or manage milestone lifecycle.
 
-Usage: `/maxsim:execute-phase 5`
+- **New project:** Deep questioning, optional domain research, requirements definition, roadmap creation
+- **Existing project:** Scans codebase, creates planning docs from existing code
+- **Active project:** Detects current state, offers milestone lifecycle options (complete, start new)
 
-**`/maxsim:sdd <phase-number>`**
-Execute a phase using Spec-Driven Dispatch — fresh agent per task with 2-stage review.
+Usage: `/maxsim:init` or `/maxsim:init --auto`
 
-- Each task dispatched to a fresh subagent with minimal context
-- Mandatory two-stage review (spec compliance + code quality) between every task
-- No task starts until the previous passes both review stages
-- Fix agents spawned for failed reviews (up to 3 attempts)
+---
 
-Use when context rot is a concern or for sequential tasks requiring strict quality gates.
+### /maxsim:plan [N]
 
-Usage: `/maxsim:sdd 3`
+Plan a phase through three stages: Discussion, Research, Planning.
 
-**`/maxsim:batch <task description>`**
-Decompose a large task into independent units and execute each in an isolated git worktree.
+- **Discussion:** Gather implementation decisions via conversation, creates CONTEXT.md
+- **Research:** Spawn researcher agent for domain analysis, creates RESEARCH.md
+- **Planning:** Spawn planner agent to create executable PLAN.md files
+- Auto-detects current stage and resumes from there
+- Gate confirmation between each stage
 
-- Spawns planner to decompose task into 5-30 independent units
-- Validates no file overlap between units
-- Each unit runs in its own worktree with its own branch and PR
-- Tracks progress via status table, handles failures with retries
+Usage: `/maxsim:plan 3` or `/maxsim:plan` (auto-detects next unplanned phase)
 
-Use for large parallelizable changes where each unit can be independently merged.
+Flags: `--force-research` (re-run research), `--skip-verify` (skip plan verification)
 
-Usage: `/maxsim:batch "Migrate all API endpoints to new auth middleware"`
+---
 
-### Quick Mode
+### /maxsim:execute [N]
 
-**`/maxsim:quick`**
-Execute small, ad-hoc tasks with MAXSIM guarantees but skip optional agents.
+Execute all plans in a phase with auto-verification.
 
-Quick mode uses the same system with a shorter path:
-- Spawns planner + executor (skips researcher, checker, verifier)
-- Quick tasks live in `.planning/quick/` separate from planned phases
-- Updates STATE.md tracking (not ROADMAP.md)
+- Runs plans in wave order (parallel within waves)
+- Auto-verifies after execution completes
+- Retries failed verification (max 2 retries, 3 total attempts)
+- On final failure, reports what failed and lets you decide
 
-Use when you know exactly what to do and the task is small enough to not need research or verification.
+Usage: `/maxsim:execute 3`
 
-Usage: `/maxsim:quick`
-Result: Creates `.planning/quick/NNN-slug/PLAN.md`, `.planning/quick/NNN-slug/SUMMARY.md`
+---
 
-### Roadmap Management
+### /maxsim:go
 
-**`/maxsim:add-phase <description>`**
-Add new phase to end of current milestone.
+Auto-detect project state and dispatch to the right command.
 
-- Appends to ROADMAP.md
-- Uses next sequential number
-- Updates phase directory structure
+- Deep context analysis: project state, git status, recent commits
+- Surfaces problems proactively before suggesting actions
+- Show + Act pattern: displays what was detected, then acts immediately
+- No arguments -- pure auto-detection
 
-Usage: `/maxsim:add-phase "Add admin dashboard"`
+Usage: `/maxsim:go`
 
-**`/maxsim:insert-phase <after> <description>`**
-Insert urgent work as decimal phase between existing phases.
+---
 
-- Creates intermediate phase (e.g., 7.1 between 7 and 8)
-- Useful for discovered work that must happen mid-milestone
-- Maintains phase ordering
+### /maxsim:progress
 
-Usage: `/maxsim:insert-phase 7 "Fix critical auth bug"`
-Result: Creates Phase 7.1
+View project progress and milestone status.
 
-**`/maxsim:remove-phase <number>`**
-Remove a future phase and renumber subsequent phases.
-
-- Deletes phase directory and all references
-- Renumbers all subsequent phases to close the gap
-- Only works on future (unstarted) phases
-- Git commit preserves historical record
-
-Usage: `/maxsim:remove-phase 17`
-Result: Phase 17 deleted, phases 18-20 become 17-19
-
-### Milestone Management
-
-**`/maxsim:new-milestone <name>`**
-Start a new milestone through unified flow.
-
-- Deep questioning to understand what you're building next
-- Optional domain research (spawns 4 parallel researcher agents)
-- Requirements definition with scoping
-- Roadmap creation with phase breakdown
-
-Mirrors `/maxsim:new-project` flow for brownfield projects (existing PROJECT.md).
-
-Usage: `/maxsim:new-milestone "v2.0 Features"`
-
-**`/maxsim:complete-milestone <version>`**
-Archive completed milestone and prepare for next version.
-
-- Creates MILESTONES.md entry with stats
-- Archives full details to milestones/ directory
-- Creates git tag for the release
-- Prepares workspace for next version
-
-Usage: `/maxsim:complete-milestone 1.0.0`
-
-### Progress Tracking
-
-**`/maxsim:progress`**
-Check project status and intelligently route to next action.
-
-- Shows visual progress bar and completion percentage
-- Summarizes recent work from SUMMARY files
-- Displays current position and what's next
-- Lists key decisions and open issues
-- Offers to execute next plan or create it if missing
-- Detects 100% milestone completion
+- Phase completion overview with visual progress
+- Recent activity summary from SUMMARY files
+- Current position and what comes next
+- Offers milestone completion when all phases are done
 
 Usage: `/maxsim:progress`
 
-### Session Management
-
-**`/maxsim:resume-work`**
-Resume work from previous session with full context restoration.
-
-- Reads STATE.md for project context
-- Shows current position and recent progress
-- Offers next actions based on project state
-
-Usage: `/maxsim:resume-work`
-
-**`/maxsim:pause-work`**
-Create context handoff when pausing work mid-phase.
-
-- Creates .continue-here file with current state
-- Updates STATE.md session continuity section
-- Captures in-progress work context
+---
 
-Usage: `/maxsim:pause-work`
+### /maxsim:debug [description]
 
-### Debugging
-
-**`/maxsim:debug [issue description]`**
 Systematic debugging with persistent state across context resets.
 
-- Gathers symptoms through adaptive questioning
-- Creates `.planning/debug/[slug].md` to track investigation
-- Investigates using scientific method (evidence → hypothesis → test)
-- Survives `/clear` — run `/maxsim:debug` with no args to resume
-- Archives resolved issues to `.planning/debug/resolved/`
-
-Usage: `/maxsim:debug "login button doesn't work"`
-Usage: `/maxsim:debug` (resume active session)
-
-### Todo Management
-
-**`/maxsim:add-todo [description]`**
-Capture idea or task as todo from current conversation.
-
-- Extracts context from conversation (or uses provided description)
-- Creates structured todo file in `.planning/todos/pending/`
-- Infers area from file paths for grouping
-- Checks for duplicates before creating
-- Updates STATE.md todo count
-
-Usage: `/maxsim:add-todo` (infers from conversation)
-Usage: `/maxsim:add-todo Add auth token refresh`
-Usage: `/maxsim:add-todo --discuss Refactor auth module` (collaborative discussion before filing)
+- Scientific method: gather symptoms, hypothesize, test, verify
+- Persistent debug sessions in `.planning/debug/` -- survives `/clear`
+- Spawns isolated debugger agent (fresh 200K context per investigation)
+- Run with no args to resume an active session
 
-**`/maxsim:check-todos [area]`**
-List pending todos and select one to work on.
+Usage: `/maxsim:debug login form returns 500` or `/maxsim:debug` (resume)
 
-- Lists all pending todos with title, area, age
-- Optional area filter (e.g., `/maxsim:check-todos api`)
-- Loads full context for selected todo
-- Routes to appropriate action (work now, add to phase, brainstorm)
-- Moves todo to done/ when work begins
+---
 
-Usage: `/maxsim:check-todos`
-Usage: `/maxsim:check-todos api`
+### /maxsim:quick [--full]
 
-### Artefakte Management
+Ad-hoc tasks with MAXSIM guarantees.
 
-**`/maxsim:artefakte [type] [--phase <N>]`**
-View and manage project decisions, acceptance criteria, and no-gos.
+- Atomic commits, state tracking, todo capture
+- `--full` flag enables plan-checking and verification agents
+- "Save for later" captures ideas as todos for future work
 
-- No arguments: lists all artefakte documents with status
-- With type (`decisions`, `acceptance-criteria`, `no-gos`): view specific document
-- With `--phase N`: scope to phase-level artefakte
-- Interactive: add entries, view documents, switch between types
+Usage: `/maxsim:quick` or `/maxsim:quick --full`
 
-Artefakte documents:
-- `DECISIONS.md` — Architectural and design decisions with rationale
-- `ACCEPTANCE-CRITERIA.md` — Conditions that must be met for deliverables
-- `NO-GOS.md` — Things explicitly out of scope or forbidden
+---
 
-Usage: `/maxsim:artefakte`
-Usage: `/maxsim:artefakte decisions`
-Usage: `/maxsim:artefakte no-gos --phase 3`
+### /maxsim:settings
 
-### User Acceptance Testing
+Configure MAXSIM workflow and model profile.
 
-**`/maxsim:verify-work [phase]`**
-Validate built features through conversational UAT.
-
-- Extracts testable deliverables from SUMMARY.md files
-- Presents tests one at a time (yes/no responses)
-- Automatically diagnoses failures and creates fix plans
-- Ready for re-execution if issues found
-
-Usage: `/maxsim:verify-work 3`
-
-### Milestone Auditing
-
-**`/maxsim:audit-milestone [version]`**
-Audit milestone completion against original intent.
-
-- Reads all phase VERIFICATION.md files
-- Checks requirements coverage
-- Spawns integration checker for cross-phase wiring
-- Creates MILESTONE-AUDIT.md with gaps and tech debt
-
-Usage: `/maxsim:audit-milestone`
-
-**`/maxsim:plan-milestone-gaps`**
-Create phases to close gaps identified by audit.
-
-- Reads MILESTONE-AUDIT.md and groups gaps into phases
-- Prioritizes by requirement priority (must/should/nice)
-- Adds gap closure phases to ROADMAP.md
-- Ready for `/maxsim:plan-phase` on new phases
-
-Usage: `/maxsim:plan-milestone-gaps`
-
-### Configuration
-
-**`/maxsim:settings`**
-Configure workflow toggles and model profile interactively.
-
-- Toggle researcher, plan checker, verifier agents
-- Select model profile (quality/balanced/budget)
+- Model profile: quality, balanced, or budget
+- Toggle agents: researcher, plan checker, verifier
+- Branching strategy configuration
 - Updates `.planning/config.json`
 
 Usage: `/maxsim:settings`
 
-**`/maxsim:set-profile <profile>`**
-Quick switch model profile for MAXSIM agents.
+---
 
-- `quality` — Opus everywhere except verification
-- `balanced` — Opus for planning, Sonnet for execution (default)
-- `budget` — Sonnet for writing, Haiku for research/verification
+### /maxsim:help
 
-Usage: `/maxsim:set-profile budget`
-
-### Utility Commands
-
-**`/maxsim:cleanup`**
-Archive accumulated phase directories from completed milestones.
-
-- Identifies phases from completed milestones still in `.planning/phases/`
-- Shows dry-run summary before moving anything
-- Moves phase dirs to `.planning/milestones/v{X.Y}-phases/`
-- Use after multiple milestones to reduce `.planning/phases/` clutter
-
-Usage: `/maxsim:cleanup`
-
-**`/maxsim:help`**
 Show this command reference.
 
-**`/maxsim:update`**
-Update MAXSIM to latest version with changelog preview.
-
-- Shows installed vs latest version comparison
-- Displays changelog entries for versions you've missed
-- Highlights breaking changes
-- Confirms before running install
-- Better than raw `npx maxsimcli`
+Usage: `/maxsim:help`
 
-Usage: `/maxsim:update`
+---
 
-## Files & Structure
+## Plan Flow
 
 ```
-.planning/
-├── PROJECT.md            # Project vision
-├── ROADMAP.md            # Current phase breakdown
-├── STATE.md              # Project memory & context
-├── DECISIONS.md          # Architectural decisions with rationale
-├── ACCEPTANCE-CRITERIA.md # Success conditions for deliverables
-├── NO-GOS.md             # Explicit exclusions and boundaries
-├── config.json           # Workflow mode & gates
-├── todos/                # Captured ideas and tasks
-│   ├── pending/          # Todos waiting to be worked on
-│   └── done/             # Completed todos
-├── debug/                # Active debug sessions
-│   └── resolved/         # Archived resolved issues
-├── milestones/
-│   ├── v1.0-ROADMAP.md       # Archived roadmap snapshot
-│   ├── v1.0-REQUIREMENTS.md  # Archived requirements
-│   └── v1.0-phases/          # Archived phase dirs (via /maxsim:cleanup or --archive-phases)
-│       ├── 01-foundation/
-│       └── 02-core-features/
-├── codebase/             # Codebase map (brownfield projects)
-│   ├── STACK.md          # Languages, frameworks, dependencies
-│   ├── ARCHITECTURE.md   # Patterns, layers, data flow
-│   ├── STRUCTURE.md      # Directory layout, key files
-│   ├── CONVENTIONS.md    # Coding standards, naming
-│   ├── TESTING.md        # Test setup, patterns
-│   ├── INTEGRATIONS.md   # External services, APIs
-│   └── CONCERNS.md       # Tech debt, known issues
-└── phases/
-    ├── 01-foundation/
-    │   ├── 01-01-PLAN.md
-    │   └── 01-01-SUMMARY.md
-    └── 02-core-features/
-        ├── 02-01-PLAN.md
-        └── 02-01-SUMMARY.md
+/maxsim:plan N
+     |
+     v
+ Discussion -- gather decisions via conversation
+     |
+     | Gate: "N decisions captured. Continue?"
+     v
+  Research -- spawn researcher agent
+     |
+     | Gate: "Research complete. Continue?"
+     v
+  Planning -- spawn planner agent
+     |
+     | Gate: "N plans in M waves. Ready?"
+     v
+   Done -- CONTEXT.md + RESEARCH.md + PLAN.md files created
 ```
 
-## Workflow Modes
-
-Set during `/maxsim:new-project`:
-
-**Interactive Mode**
-
-- Confirms each major decision
-- Pauses at checkpoints for approval
-- More guidance throughout
-
-**YOLO Mode**
-
-- Auto-approves most decisions
-- Executes plans without confirmation
-- Only stops for critical checkpoints
+**Artifacts produced at each stage:**
 
-Change anytime by editing `.planning/config.json`
+| Stage | Artifact | Contains |
+|-------|----------|----------|
+| Discussion | CONTEXT.md | Locked decisions, constraints, boundaries |
+| Research | RESEARCH.md | Domain findings, patterns, recommendations |
+| Planning | PLAN.md (1+) | Executable tasks with verification criteria |
 
-## Planning Configuration
+**Re-entry:** Running `/maxsim:plan` on an already-planned phase shows status and offers options (view plans, re-plan, execute).
 
-Configure how planning artifacts are managed in `.planning/config.json`:
+---
 
-**`planning.commit_docs`** (default: `true`)
-- `true`: Planning artifacts committed to git (standard workflow)
-- `false`: Planning artifacts kept local-only, not committed
-
-When `commit_docs: false`:
-- Add `.planning/` to your `.gitignore`
-- Useful for OSS contributions, client projects, or keeping planning private
-- All planning files still work normally, just not tracked in git
-
-**`planning.search_gitignored`** (default: `false`)
-- `true`: Add `--no-ignore` to broad ripgrep searches
-- Only needed when `.planning/` is gitignored and you want project-wide searches to include it
-
-Example config:
-```json
-{
-  "planning": {
-    "commit_docs": false,
-    "search_gitignored": true
-  }
-}
-```
-
-## Common Workflows
-
-**Starting a new project:**
+## Execute Flow
 
 ```
-/maxsim:new-project        # Unified flow: questioning → research → requirements → roadmap
-/clear
-/maxsim:plan-phase 1       # Create plans for first phase
-/clear
-/maxsim:execute-phase 1    # Execute all plans in phase
+/maxsim:execute N
+     |
+     v
+  Execute -- run plans in wave order
+     |      (parallel within waves)
+     v
+  Verify -- spawn verifier agent
+     |
+     +--> PASS --> Phase complete!
+     |
+     +--> FAIL --> Retry (max 2)
+               |
+               v
+           Fix --> Re-verify
+               |
+               +--> PASS --> Done
+               +--> FAIL --> Report to user
 ```
 
-**Resuming work after a break:**
+**Wave execution:** Plans declare wave numbers in their frontmatter. All plans in wave 1 run first (in parallel), then wave 2, etc. This respects dependencies between plans.
 
-```
-/maxsim:progress  # See where you left off and continue
-```
-
-**Adding urgent mid-milestone work:**
-
-```
-/maxsim:insert-phase 5 "Critical security fix"
-/maxsim:plan-phase 5.1
-/maxsim:execute-phase 5.1
-```
+---
 
-**Completing a milestone:**
+## Project Structure
 
 ```
-/maxsim:complete-milestone 1.0.0
-/clear
-/maxsim:new-milestone  # Start next milestone (questioning → research → requirements → roadmap)
-```
-
-**Capturing ideas during work:**
+.planning/
+  PROJECT.md           # Project vision and context
+  REQUIREMENTS.md      # Scoped requirements with IDs
+  ROADMAP.md           # Phase structure and progress
+  STATE.md             # Project memory: decisions, blockers, metrics
+  config.json          # Workflow preferences
+  phases/
+    01-foundation/
+      01-CONTEXT.md    # Discussion decisions
+      01-RESEARCH.md   # Domain research
+      01-01-PLAN.md    # Execution plan
+      01-01-SUMMARY.md # Completion record
+    02-features/
+      ...
+  debug/               # Active debug sessions
+  quick/               # Quick task plans and summaries
+```
+
+---
+
+## Quick Reference
+
+| Want to... | Run |
+|------------|-----|
+| Start a new project | `/maxsim:init` |
+| Resume where you left off | `/maxsim:go` |
+| Plan next phase | `/maxsim:plan` |
+| Plan a specific phase | `/maxsim:plan N` |
+| Execute a phase | `/maxsim:execute N` |
+| Check progress | `/maxsim:progress` |
+| Debug an issue | `/maxsim:debug description` |
+| Quick ad-hoc task | `/maxsim:quick` |
+| Change settings | `/maxsim:settings` |
+| See this help | `/maxsim:help` |
+
+---
 
-```
-/maxsim:add-todo                    # Capture from conversation context
-/maxsim:add-todo Fix modal z-index  # Capture with explicit description
-/maxsim:check-todos                 # Review and work on todos
-/maxsim:check-todos api             # Filter by area
-```
+## Staying Updated
 
-**Debugging an issue:**
+Update MAXSIM to the latest version:
 
+```bash
+npx maxsimcli@latest
 ```
-/maxsim:debug "form submission fails silently"  # Start debug session
-# ... investigation happens, context fills up ...
-/clear
-/maxsim:debug                                    # Resume from where you left off
-```
-
-## Getting Help
-
-- Read `.planning/PROJECT.md` for project vision
-- Read `.planning/STATE.md` for current context
-- Check `.planning/ROADMAP.md` for phase status
-- Run `/maxsim:progress` to check where you're up to
 </reference>