maxsimcli 4.8.0 → 4.9.0

package/dist/assets/templates/commands/maxsim/batch.md

@@ -1,42 +0,0 @@
----
-name: maxsim:batch
-description: Decompose a large task into independent units and execute each in an isolated git worktree with its own PR
-argument-hint: "<task description>"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
-  - Bash
-  - Task
-  - AskUserQuestion
----
-<objective>
-Decompose a large task into independent units, execute each in an isolated git worktree, and produce one PR per unit.
-
-Batch mode uses the full MAXSIM system with worktree isolation:
-- Spawns maxsim-planner (batch mode) to decompose the task into independent units
-- Validates file independence across all units (no overlap allowed)
-- Spawns one worktree agent per unit, each with its own branch and PR
-- Tracks progress and handles failures with automatic retries
-- Records batch metadata in `.planning/batch/`
-
-**Use when:** Task has 3+ independent units that can be implemented in parallel.
-**Do not use when:** Fewer than 3 units (use `/maxsim:quick` instead) or units have sequential dependencies.
-</objective>
-
-<execution_context>
-@./workflows/batch.md
-</execution_context>
-
-<context>
-$ARGUMENTS
-
-Context files are resolved inside the workflow (`init quick`) and delegated via `<files_to_read>` blocks.
-</context>
-
-<process>
-Execute the batch workflow from @./workflows/batch.md end-to-end.
-Preserve all workflow gates (validation, decomposition, independence check, agent spawning, tracking, state updates).
-</process>

package/dist/assets/templates/commands/maxsim/check-drift.md

@@ -1,56 +0,0 @@
----
-name: maxsim:check-drift
-description: Compare .planning/ spec against codebase to detect drift and produce DRIFT-REPORT.md
-argument-hint: "[optional: phase number to check, e.g., '4']"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Task
----
-
-<objective>
-Compare the `.planning/` specification against the actual codebase using a drift-checker agent to produce a structured DRIFT-REPORT.md with severity-tiered findings.
-
-The drift checker performs a fresh codebase scan every run, comparing all requirements, no-gos, conventions, and phase summaries against actual implementation. It reports both directions: spec ahead of code (missing implementations) and code ahead of spec (undocumented features).
-
-Output: `.planning/DRIFT-REPORT.md` with YAML frontmatter, full inventory of findings, evidence per mismatch, and fix recommendations.
-</objective>
-
-<execution_context>
-@./workflows/check-drift.md
-</execution_context>
-
-<context>
-Phase filter: $ARGUMENTS (optional)
-- If provided: Focus analysis on specific phase (e.g., "4")
-- If not provided: Full .planning/ sweep across all phases and milestones
-
-**Requirements:**
-- `.planning/` directory must exist
-- At least REQUIREMENTS.md or ROADMAP.md must be present
-- If partial spec (some files missing), analysis runs on what exists with a warning
-</context>
-
-<process>
-Execute the check-drift workflow from @./workflows/check-drift.md end-to-end.
-
-After the workflow completes and DRIFT-REPORT.md is generated:
-
-**If drift detected:** Offer realignment options:
-- `/maxsim:realign to-code` -- Update `.planning/` to match codebase
-- `/maxsim:realign to-spec` -- Create new phases to close implementation gaps
-- Done -- No action needed, drift acknowledged
-
-**If aligned:** Confirm alignment and offer next steps.
-</process>
-
-<success_criteria>
-- [ ] .planning/DRIFT-REPORT.md created with YAML frontmatter
-- [ ] Report includes severity-tiered findings (critical/warning/info)
-- [ ] Report includes evidence per mismatch (spec line + code location)
-- [ ] Report covers both directions (spec ahead of code + code ahead of spec)
-- [ ] User presented with realignment options if drift detected
-</success_criteria>

package/dist/assets/templates/commands/maxsim/check-todos.md

@@ -1,46 +0,0 @@
----
-name: maxsim:check-todos
-description: List pending todos and select one to work on
-argument-hint: [area filter]
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - AskUserQuestion
----
-
-<objective>
-List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
-
-Routes to the check-todos workflow which handles:
-- Todo counting and listing with area filtering
-- Interactive selection with full context loading
-- Roadmap correlation checking
-- Action routing (work now, add to phase, brainstorm, create phase)
-- STATE.md updates and git commits
-</objective>
-
-<execution_context>
-@./workflows/check-todos.md
-@./references/thinking-partner.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (optional area filter)
-
-Todo state and roadmap correlation are loaded in-workflow using `init todos` and targeted reads.
-</context>
-
-<process>
-**Follow the check-todos workflow** from `@./workflows/check-todos.md`.
-
-The workflow handles all logic including:
-1. Todo existence checking
-2. Area filtering
-3. Interactive listing and selection
-4. Full context loading with file summaries
-5. Roadmap correlation checking
-6. Action offering and execution
-7. STATE.md updates
-8. Git commits
-</process>

package/dist/assets/templates/commands/maxsim/cleanup.md

@@ -1,18 +0,0 @@
----
-name: maxsim:cleanup
-description: Archive accumulated phase directories from completed milestones
----
-<objective>
-Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`.
-
-Use when `.planning/phases/` has accumulated directories from past milestones.
-</objective>
-
-<execution_context>
-@./workflows/cleanup.md
-</execution_context>
-
-<process>
-Follow the cleanup workflow at @./workflows/cleanup.md.
-Identify completed milestones, show a dry-run summary, and archive on confirmation.
-</process>

package/dist/assets/templates/commands/maxsim/complete-milestone.md

@@ -1,136 +0,0 @@
----
-type: prompt
-name: maxsim:complete-milestone
-description: Archive completed milestone and prepare for next version
-argument-hint: <version>
-allowed-tools:
-  - Read
-  - Write
-  - Bash
----
-
-<objective>
-Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.
-
-Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone.
-Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.
-</objective>
-
-<execution_context>
-**Load these files NOW (before proceeding):**
-
-- @./workflows/complete-milestone.md (main workflow)
-- @./templates/milestone-archive.md (archive template)
-  </execution_context>
-
-<context>
-**Project files:**
-- `.planning/ROADMAP.md`
-- `.planning/REQUIREMENTS.md`
-- `.planning/STATE.md`
-- `.planning/PROJECT.md`
-
-**User input:**
-
-- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
-  </context>
-
-<process>
-
-**Follow complete-milestone.md workflow:**
-
-0. **Check for audit:**
-
-   - Look for `.planning/v{{version}}-MILESTONE-AUDIT.md`
-   - If missing or stale: recommend `/maxsim:audit-milestone` first
-   - If audit status is `gaps_found`: recommend `/maxsim:plan-milestone-gaps` first
-   - If audit status is `passed`: proceed to step 1
-
-   ```markdown
-   ## Pre-flight Check
-
-   {If no v{{version}}-MILESTONE-AUDIT.md:}
-   ⚠ No milestone audit found. Run `/maxsim:audit-milestone` first to verify
-   requirements coverage, cross-phase integration, and E2E flows.
-
-   {If audit has gaps:}
-   ⚠ Milestone audit found gaps. Run `/maxsim:plan-milestone-gaps` to create
-   phases that close the gaps, or proceed anyway to accept as tech debt.
-
-   {If audit passed:}
-   ✓ Milestone audit passed. Proceeding with completion.
-   ```
-
-1. **Verify readiness:**
-
-   - Check all phases in milestone have completed plans (SUMMARY.md exists)
-   - Present milestone scope and stats
-   - Wait for confirmation
-
-2. **Gather stats:**
-
-   - Count phases, plans, tasks
-   - Calculate git range, file changes, LOC
-   - Extract timeline from git log
-   - Present summary, confirm
-
-3. **Extract accomplishments:**
-
-   - Read all phase SUMMARY.md files in milestone range
-   - Extract 4-6 key accomplishments
-   - Present for approval
-
-4. **Archive milestone:**
-
-   - Create `.planning/milestones/v{{version}}-ROADMAP.md`
-   - Extract full phase details from ROADMAP.md
-   - Fill milestone-archive.md template
-   - Update ROADMAP.md to one-line summary with link
-
-5. **Archive requirements:**
-
-   - Create `.planning/milestones/v{{version}}-REQUIREMENTS.md`
-   - Mark all v1 requirements as complete (checkboxes checked)
-   - Note requirement outcomes (validated, adjusted, dropped)
-   - Delete `.planning/REQUIREMENTS.md` (fresh one created for next milestone)
-
-6. **Update PROJECT.md:**
-
-   - Add "Current State" section with shipped version
-   - Add "Next Milestone Goals" section
-   - Archive previous content in `<details>` (if v1.1+)
-
-7. **Commit and tag:**
-
-   - Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
-   - Commit: `chore: archive v{{version}} milestone`
-   - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
-   - Ask about pushing tag
-
-8. **Offer next steps:**
-   - `/maxsim:new-milestone` — start next milestone (questioning → research → requirements → roadmap)
-
-</process>
-
-<success_criteria>
-
-- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
-- Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md`
-- `.planning/REQUIREMENTS.md` deleted (fresh for next milestone)
-- ROADMAP.md collapsed to one-line entry
-- PROJECT.md updated with current state
-- Git tag v{{version}} created
-- Commit successful
-- User knows next steps (including need for fresh requirements)
-  </success_criteria>
-
-<critical_rules>
-
-- **Load workflow first:** Read complete-milestone.md before executing
-- **Verify completion:** All phases must have SUMMARY.md files
-- **User confirmation:** Wait for approval at verification gates
-- **Archive before deleting:** Always create archive files before updating/deleting originals
-- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
-- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
-- **Fresh requirements:** Next milestone starts with `/maxsim:new-milestone` which includes requirements definition
-  </critical_rules>

package/dist/assets/templates/commands/maxsim/discuss-phase.md

@@ -1,87 +0,0 @@
----
-name: maxsim:discuss-phase
-description: Gather phase context through adaptive questioning before planning
-argument-hint: "<phase> [--auto]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
-  - Task
----
-
-<objective>
-Extract implementation decisions that downstream agents need — researcher and planner will use CONTEXT.md to know what to investigate and what choices are locked.
-
-**How it works:**
-1. Analyze the phase to identify gray areas (UI, UX, behavior, etc.)
-2. Present gray areas — user selects which to discuss
-3. Deep-dive each selected area until satisfied
-4. Create CONTEXT.md with decisions that guide research and planning
-
-**Output:** `{phase_num}-CONTEXT.md` — decisions clear enough that downstream agents can act without asking the user again
-
-**CRITICAL — AskUserQuestion tool mandate:**
-Every single question to the user MUST use the `AskUserQuestion` tool. NEVER ask questions as plain text in your response. This includes gray area selection, deep-dive questions, continuation prompts, and any other user interaction. If you need the user's input, use `AskUserQuestion`. No exceptions.
-</objective>
-
-<execution_context>
-@./workflows/discuss-phase.md
-@./references/thinking-partner.md
-@./templates/context.md
-</execution_context>
-
-<context>
-Phase number: $ARGUMENTS (required)
-
-Context files are resolved in-workflow using `init phase-op` and roadmap/state tool calls.
-</context>
-
-<process>
-1. Validate phase number (error if missing or not in roadmap)
-2. Check if CONTEXT.md exists (offer update/view/skip if yes)
-3. **Analyze phase** — Identify domain and generate phase-specific gray areas
-4. **Present gray areas** — Multi-select: which to discuss? (NO skip option)
-5. **Deep-dive each area** — 4 questions per area, then offer more/next
-6. **Write CONTEXT.md** — Sections match areas discussed
-7. Offer next steps (research or plan)
-
-**CRITICAL: Scope guardrail**
-- Phase boundary from ROADMAP.md is FIXED
-- Discussion clarifies HOW to implement, not WHETHER to add more
-- If user suggests new capabilities: "That's its own phase. I'll note it for later."
-- Capture deferred ideas — don't lose them, don't act on them
-
-**Domain-aware gray areas:**
-Gray areas depend on what's being built. Analyze the phase goal:
-- Something users SEE → layout, density, interactions, states
-- Something users CALL → responses, errors, auth, versioning
-- Something users RUN → output format, flags, modes, error handling
-- Something users READ → structure, tone, depth, flow
-- Something being ORGANIZED → criteria, grouping, naming, exceptions
-
-Generate 3-4 **phase-specific** gray areas, not generic categories.
-
-**Probing depth:**
-- Ask 4 questions per area before checking
-- "More questions about [area], or move to next?"
-- If more → ask 4 more, check again
-- After all areas → "Ready to create context?"
-
-**Do NOT ask about (Claude handles these):**
-- Technical implementation
-- Architecture choices
-- Performance concerns
-- Scope expansion
-</process>
-
-<success_criteria>
-- Gray areas identified through intelligent analysis
-- User chose which areas to discuss
-- Each selected area explored until satisfied
-- Scope creep redirected to deferred ideas
-- CONTEXT.md captures decisions, not vague vision
-- User knows next steps
-</success_criteria>

package/dist/assets/templates/commands/maxsim/discuss.md

@@ -1,70 +0,0 @@
----
-name: maxsim:discuss
-description: Triage a problem, idea, or bug into the right size -- todo, quick task, or phase
-argument-hint: "[description or todo reference]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-<objective>
-Triage an unknown problem, idea, or bug into the right size -- quick todo, quick task, or new phase -- through collaborative discussion.
-
-**How it works:**
-1. User describes a problem, idea, or bug (or references an existing todo)
-2. System asks 2-3 adaptive clarifying questions to understand scope
-3. System proposes routing (todo vs phase) with explanation -- user confirms via AskUserQuestion before any filing
-4. System files the item (todo or phase) using existing tools
-5. System offers next action choices (work now, save for later, plan phase)
-
-**Modes:**
-- **No-arg mode:** User describes the problem interactively after invocation
-- **With-arg mode:** User provides a description or existing todo reference inline (e.g., `/maxsim:discuss auth tokens expire too fast` or `/maxsim:discuss fix-login-redirect`)
-
-**Key distinction from `/maxsim:discuss-phase`:**
-- `/maxsim:discuss` triages an UNKNOWN problem into the right size. It answers: "Is this a todo or a phase?"
-- `/maxsim:discuss-phase` gathers implementation decisions for a KNOWN phase. It answers: "How should we build this phase?"
-- These are complementary, not overlapping. After `/maxsim:discuss` creates a phase, the natural next step is `/maxsim:discuss-phase` to gather context for it.
-
-**CRITICAL -- AskUserQuestion tool mandate:**
-Every single question to the user MUST use the `AskUserQuestion` tool. NEVER ask questions as plain text in your response. This includes clarifying questions, triage proposals, confirmation prompts, and next-action offers. If you need the user's input, use `AskUserQuestion`. No exceptions.
-
-**Thinking-partner behaviors:**
-Apply collaborative discussion behaviors -- challenge vague descriptions, surface unstated assumptions, propose alternatives with trade-offs. The user should feel like they are working through a problem with a collaborator, not filling out a form.
-</objective>
-
-<execution_context>
-@./workflows/discuss.md
-@./references/thinking-partner.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (optional description or todo reference)
-
-State is resolved in-workflow via `init todos` and targeted reads.
-</context>
-
-<process>
-**Follow the discuss workflow** from `@./workflows/discuss.md`.
-
-The workflow handles all logic including:
-1. Project state loading and todo initialization
-2. Existing todo detection (if argument matches a pending todo)
-3. Adaptive clarifying questions (2-3 minimum, more if complex)
-4. Size classification triage with user confirmation
-5. Filing as todo (using existing maxsim-tools.cjs commands) or phase (using phase add)
-6. Post-filing next action offer
-7. Git commits
-</process>
-
-<success_criteria>
-- User's problem/idea/bug is understood through collaborative discussion
-- Routing decision confirmed by user before any filing
-- Item filed as todo or phase using existing tools
-- Next action offered after filing
-- Git commit created for the filed item
-</success_criteria>

package/dist/assets/templates/commands/maxsim/execute-phase.md

@@ -1,41 +0,0 @@
----
-name: maxsim:execute-phase
-description: Execute all plans in a phase with wave-based parallelization
-argument-hint: "<phase-number> [--gaps-only]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
-  - Bash
-  - Task
-  - TodoWrite
-  - AskUserQuestion
----
-<objective>
-Execute all plans in a phase using wave-based parallel execution.
-
-Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.
-
-Context budget: ~15% orchestrator, 100% fresh per subagent.
-</objective>
-
-<execution_context>
-@./workflows/execute-phase.md
-@./references/ui-brand.md
-</execution_context>
-
-<context>
-Phase: $ARGUMENTS
-
-**Flags:**
-- `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
-
-Context files are resolved inside the workflow via `maxsim-tools init execute-phase` and per-subagent `<files_to_read>` blocks.
-</context>
-
-<process>
-Execute the execute-phase workflow from @./workflows/execute-phase.md end-to-end.
-Preserve all workflow gates (wave execution, checkpoint handling, verification, state updates, routing).
-</process>

package/dist/assets/templates/commands/maxsim/health.md

@@ -1,22 +0,0 @@
----
-name: maxsim:health
-description: Diagnose planning directory health and optionally repair issues
-argument-hint: [--repair]
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - AskUserQuestion
----
-<objective>
-Validate `.planning/` directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans.
-</objective>
-
-<execution_context>
-@./workflows/health.md
-</execution_context>
-
-<process>
-Execute the health workflow from @./workflows/health.md end-to-end.
-Parse --repair flag from arguments and pass to workflow.
-</process>

package/dist/assets/templates/commands/maxsim/init-existing.md

@@ -1,46 +0,0 @@
----
-name: maxsim:init-existing
-description: Initialize MAXSIM in an existing project with codebase scanning and smart defaults
-argument-hint: "[--auto]"
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - Task
-  - AskUserQuestion
----
-<context>
-**Flags:**
-- `--auto` — Automatic mode. Runs full codebase scan, infers everything from code, creates all docs without interaction. Review recommended after auto mode.
-</context>
-
-<objective>
-Initialize MAXSIM in an existing codebase through scan-first flow: codebase analysis, conflict resolution, scan-informed questioning, stage-aware document generation.
-
-**Creates:**
-- `.planning/codebase/` — full codebase analysis (4 mapper agents)
-- `.planning/PROJECT.md` — project context with current state summary
-- `.planning/config.json` — workflow preferences
-- `.planning/REQUIREMENTS.md` — stage-aware requirements
-- `.planning/ROADMAP.md` — milestone + suggested phases
-- `.planning/STATE.md` — pre-populated project memory
-- `.planning/DECISIONS.md` — key decisions with rationale (artefakte)
-- `.planning/ACCEPTANCE-CRITERIA.md` — measurable success criteria (artefakte)
-- `.planning/NO-GOS.md` — explicit exclusions and anti-patterns (artefakte)
-
-**After this command:** Run `/maxsim:plan-phase 1` to start execution.
-</objective>
-
-<execution_context>
-@./workflows/init-existing.md
-@./references/questioning.md
-@./references/thinking-partner.md
-@./references/ui-brand.md
-@./templates/project.md
-@./templates/requirements.md
-</execution_context>
-
-<process>
-Execute the init-existing workflow from @./workflows/init-existing.md end-to-end.
-Preserve all workflow gates (conflict resolution, scan completion, validation, approvals, commits).
-</process>

package/dist/assets/templates/commands/maxsim/insert-phase.md

@@ -1,32 +0,0 @@
----
-name: maxsim:insert-phase
-description: Insert urgent work as decimal phase (e.g., 72.1) between existing phases
-argument-hint: <after> <description>
-allowed-tools:
-  - Read
-  - Write
-  - Bash
----
-
-<objective>
-Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases.
-
-Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.
-
-Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.
-</objective>
-
-<execution_context>
-@./workflows/insert-phase.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (format: <after-phase-number> <description>)
-
-Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
-</context>
-
-<process>
-Execute the insert-phase workflow from @./workflows/insert-phase.md end-to-end.
-Preserve all validation gates (argument parsing, phase verification, decimal calculation, roadmap updates).
-</process>

package/dist/assets/templates/commands/maxsim/list-phase-assumptions.md

@@ -1,46 +0,0 @@
----
-name: maxsim:list-phase-assumptions
-description: Surface Claude's assumptions about a phase approach before planning
-argument-hint: "[phase]"
-allowed-tools:
-  - Read
-  - Bash
-  - Grep
-  - Glob
----
-
-<objective>
-Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
-
-Purpose: Help users see what Claude thinks BEFORE planning begins - enabling course correction early when assumptions are wrong.
-Output: Conversational output only (no file creation) - ends with "What do you think?" prompt
-</objective>
-
-<execution_context>
-@./workflows/list-phase-assumptions.md
-</execution_context>
-
-<context>
-Phase number: $ARGUMENTS (required)
-
-Project state and roadmap are loaded in-workflow using targeted reads.
-</context>
-
-<process>
-1. Validate phase number argument (error if missing or invalid)
-2. Check if phase exists in roadmap
-3. Follow list-phase-assumptions.md workflow:
-   - Analyze roadmap description
-   - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
-   - Present assumptions clearly
-   - Prompt "What do you think?"
-4. Gather feedback and offer next steps
-</process>
-
-<success_criteria>
-
-- Phase validated against roadmap
-- Assumptions surfaced across five areas
-- User prompted for feedback
-- User knows next steps (discuss context, plan phase, or correct assumptions)
-  </success_criteria>