maxsimcli 3.12.0 → 4.0.1

package/dist/assets/templates/skills/roadmap-writing/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: roadmap-writing
+description: Use when creating or restructuring a project roadmap — requires phased planning with dependencies, success criteria, and MAXSIM-compatible format
+---
+
+# Roadmap Writing
+
+A roadmap without success criteria is a wish list. Define what done looks like for every phase.
+
+**If a phase does not have measurable success criteria, it is not a plan — it is a hope.**
+
+## The Iron Law
+
+<HARD-GATE>
+NO PHASE WITHOUT SUCCESS CRITERIA AND DEPENDENCIES.
+Every phase MUST have: a number, a name, a goal, success criteria (testable statements), and explicit dependencies.
+"We'll figure it out as we go" is not planning — it is drifting.
+Violating this rule is a violation — not flexibility.
+</HARD-GATE>
+
+## The Gate Function
+
+Follow these steps IN ORDER when creating or restructuring a roadmap.
+
+### 1. SCOPE — Understand the Project
+
+Before writing phases, understand what you are planning:
+
+- Read PROJECT.md for vision and constraints
+- Read REQUIREMENTS.md for v1/v2/out-of-scope boundaries
+- Check existing STATE.md for decisions and blockers
+- Identify the delivery target (MVP, v1, v2, etc.)
+
+```bash
+# Load project context
+node ~/.claude/maxsim/bin/maxsim-tools.cjs state read --raw
+
+# Check existing roadmap (if any)
+node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap read --raw
+```
+
+### 2. DECOMPOSE — Break Into Phases
+
+Each phase should be:
+
+| Property | Requirement |
+|----------|------------|
+| **Independently deliverable** | The phase produces a working increment — not a half-built feature |
+| **1-3 days of work** | Larger phases should be split; smaller ones should be merged |
+| **Clear boundary** | You can tell when the phase is done without ambiguity |
+| **Ordered by dependency** | No phase depends on a later phase |
+
+**Phase numbering convention:**
+
+| Format | When to Use |
+|--------|------------|
+| `01`, `02`, `03` | Standard sequential phases |
+| `01A`, `01B` | Parallel sub-phases that can execute concurrently |
+| `01.1`, `01.2` | Sequential sub-phases within a parent phase |
+
+Sort order: `01 < 01A < 01B < 01.1 < 01.2 < 02`
+
+### 3. DEFINE — Write Each Phase
+
+Every phase MUST include all of these fields:
+
+```markdown
+### Phase {number}: {name}
+**Goal**: {one sentence — what this phase achieves}
+**Depends on**: {phase numbers, or "Nothing" for the first phase}
+**Requirements**: {requirement IDs from REQUIREMENTS.md, if applicable}
+**Success Criteria** (what must be TRUE):
+  1. {Testable statement — can be verified with a command, test, or inspection}
+  2. {Testable statement}
+  3. {Testable statement}
+**Plans**: TBD
+```
+
+**Success criteria rules:**
+- Each criterion must be testable — "code is clean" is not testable; "no lint warnings" is testable
+- Include at least 2 criteria per phase
+- At least one criterion should be verifiable by running a command (test, build, lint)
+- Criteria describe the END STATE, not the process ("tests pass" not "write tests")
+
+### 4. CONNECT — Map Dependencies
+
+Draw the dependency graph:
+- Which phases can run in parallel? (Use letter suffixes: `03A`, `03B`)
+- Which phases are strictly sequential? (Use number suffixes: `03.1`, `03.2`)
+- Are there any circular dependencies? (This is a design error — restructure)
+
+**Rule: Every phase except the first must declare at least one dependency.**
+
+### 5. MILESTONE — Group Into Milestones
+
+Group phases into milestones that represent user-visible releases:
+
+```markdown
+## Milestones
+
+- **v1.0 MVP** — Phases 1-4
+- **v1.1 Polish** — Phases 5-7
+- **v2.0 Scale** — Phases 8-10
+```
+
+Each milestone should be a coherent deliverable that could ship independently.
+
+### 6. WRITE — Produce the Roadmap
+
+Assemble the complete ROADMAP.md:
+
+```markdown
+# Roadmap: {project name}
+
+## Overview
+
+{2-3 sentences: what the project is, what this roadmap covers, delivery strategy}
+
+## Milestones
+
+- {emoji} **{milestone name}** — Phases {range} ({status})
+
+## Phases
+
+- [ ] **Phase {N}: {name}** - {one-line summary}
+
+## Phase Details
+
+### Phase {N}: {name}
+**Goal**: ...
+**Depends on**: ...
+**Requirements**: ...
+**Success Criteria** (what must be TRUE):
+  1. ...
+**Plans**: TBD
+```
+
+### 7. VALIDATE — Check the Roadmap
+
+Before finalizing, verify:
+
+```bash
+# Write the roadmap (creates or overwrites .planning/ROADMAP.md)
+# Then verify phase structure
+node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap read --raw
+```
+
+| Check | How to Verify |
+|-------|--------------|
+| Every phase has success criteria | Read each phase detail section |
+| Dependencies are acyclic | Trace the dependency chain — no loops |
+| Phase numbering is sequential | Numbers increase, no gaps larger than 1 |
+| Milestones cover all phases | Every phase appears in exactly one milestone |
+| Success criteria are testable | Each criterion can be verified by command, test, or inspection |
+
+## Common Rationalizations — REJECT THESE
+
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "We don't know enough to plan" | Plan what you know. Unknown phases get a research spike first. |
+| "The roadmap will change anyway" | Plans change — that is expected. No plan guarantees drift. |
+| "Success criteria are too rigid" | Vague criteria are useless. Rigid criteria are adjustable. |
+| "One big phase is simpler" | Big phases hide complexity and delay feedback. Split them. |
+| "Dependencies are obvious" | Obvious to you now. Not obvious to the agent running phase 5 next week. |
+| "We'll add details later" | Later never comes. Write the details now while context is fresh. |
+
+## Red Flags — STOP If You Catch Yourself:
+
+- Writing a phase without success criteria
+- Creating phases longer than 3 days of work
+- Skipping dependency declarations
+- Writing vague criteria like "code is good" or "feature works"
+- Creating circular dependencies between phases
+- Putting all work in one or two massive phases
+
+**If any red flag triggers: STOP. Review the phase structure and fix it.**
+
+## Verification Checklist
+
+Before finalizing a roadmap, confirm:
+
+- [ ] Every phase has a number, name, goal, dependencies, and success criteria
+- [ ] Success criteria are testable (verifiable by command, test, or inspection)
+- [ ] Dependencies form a DAG (no circular dependencies)
+- [ ] Phase numbering follows MAXSIM convention (01, 01A, 01B, 01.1, etc.)
+- [ ] Phases are 1-3 days of work each
+- [ ] Milestones group phases into coherent deliverables
+- [ ] ROADMAP.md matches the expected format for MAXSIM CLI parsing
+- [ ] Overview section summarizes the project and delivery strategy
+
+## In MAXSIM Plan Execution
+
+Roadmap writing integrates with the MAXSIM lifecycle:
+- Use during project initialization (`/maxsim:plan-phase`) to create the initial roadmap
+- Use when restructuring after a significant scope change or pivot
+- The roadmap is read by MAXSIM agents via `roadmap read` — format compliance is mandatory
+- Phase numbering must be parseable by `normalizePhaseName()` and `comparePhaseNum()` in core
+- Config `model_profile` in `.planning/config.json` affects agent assignment per phase

package/dist/assets/templates/skills/sdd/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: sdd
+description: Dispatch fresh subagent per task with 2-stage review between tasks
+---
+
+# Spec-Driven Dispatch (SDD)
+
+Execute tasks sequentially, each in a fresh subagent with clean context. Review every task before moving to the next.
+
+**If the previous task did not pass review, you do not start the next task.**
+
+## When to Use
+
+- Tasks are sequential and each builds on the previous
+- Context rot is a concern (long plans, many files, complex logic)
+- Each task benefits from starting with a clean context window
+- You want enforced quality gates between tasks
+
+Do NOT use this skill when:
+- Tasks are independent and can run in parallel (use batch-worktree instead)
+- The plan has only 1-2 small tasks (overhead is not worth it)
+- All tasks modify the same small set of files (single-agent execution is simpler)
+
+## The Iron Law
+
+<HARD-GATE>
+NO TASK STARTS UNTIL THE PREVIOUS TASK PASSES 2-STAGE REVIEW.
+If the review found issues, they must be fixed before the next task begins.
+No "we'll fix it later." No "it's close enough." No skipping review for simple tasks.
+Violating this rule ships unreviewed code — the exact problem SDD prevents.
+</HARD-GATE>
+
+## Process
+
+### 1. LOAD — Read the Plan
+
+- Read the plan file (PLAN.md) to get the ordered task list
+- For each task, identify: description, acceptance criteria, relevant files
+- Confirm task order makes sense (later tasks may depend on earlier ones)
+
+```bash
+# Load plan context
+INIT=$(node .claude/maxsim/bin/maxsim-tools.cjs init execute-phase "${PHASE}")
+```
+
+### 2. DISPATCH — Spawn Fresh Agent Per Task
+
+For each task in order:
+
+1. Assemble the task context:
+   - Task description and acceptance criteria from the plan
+   - Only the files relevant to this specific task
+   - Results from previous tasks (commit hashes, created files) — NOT the full previous context
+2. Spawn a fresh `general-purpose` agent with this minimal context
+3. The agent implements the task, runs tests, and commits
+
+```bash
+# Record task dispatch
+node .claude/maxsim/bin/maxsim-tools.cjs state-add-decision "SDD: dispatching task N — [description]"
+```
+
+### 3. REVIEW — 2-Stage Quality Gate
+
+After each task completes, run two review stages before proceeding:
+
+#### Stage 1: Spec Compliance
+
+- Does the implementation match the task description?
+- Are all acceptance criteria met?
+- Were only the specified files modified (no scope creep)?
+- Do the changes align with the plan's intent?
+
+**Verdict:** PASS or FAIL with specific issues.
+
+#### Stage 2: Code Quality
+
+- Are there obvious bugs, edge cases, or error handling gaps?
+- Is the code readable and consistent with codebase conventions?
+- Are there unnecessary complications or dead code?
+- Do all tests pass?
+
+```bash
+# Run tests to verify
+npx vitest run
+```
+
+**Verdict:** PASS or FAIL with specific issues.
+
+### 4. FIX — Address Review Failures
+
+If either review stage fails:
+
+1. Spawn a NEW fresh agent with:
+   - The original task description
+   - The review feedback (specific issues found)
+   - The current state of the files
+2. The fix agent addresses ONLY the review issues — no new features
+3. Re-run both review stages on the fixed code
+4. If 3 fix attempts fail: STOP and escalate to the user
+
+### 5. ADVANCE — Move to Next Task
+
+Only after both review stages pass:
+- Record the task as complete
+- Note the commit hash and any files created/modified
+- Pass this minimal summary (not full context) to the next task's agent
+
+```bash
+# Record task completion
+node .claude/maxsim/bin/maxsim-tools.cjs state-add-decision "SDD: task N complete — [summary]"
+```
+
+### 6. REPORT — Final Summary
+
+After all tasks complete:
+- List each task with its status and commit hash
+- Note any tasks that required fix iterations
+- Summarize the total changes made
+
+## Context Management Rules
+
+Each agent receives ONLY what it needs:
+
+| Context Item | Included? |
+|-------------|-----------|
+| Task description + acceptance criteria | Always |
+| Files relevant to this task | Always |
+| Previous task commit hashes | Always |
+| Previous task full diff | Never |
+| Previous task agent conversation | Never |
+| PROJECT.md / REQUIREMENTS.md | Only if task references project-level concerns |
+| Full codebase | Never — only specified files |
+
+**The point of SDD is fresh context. Loading the previous agent's full context defeats the purpose.**
+
+## Common Rationalizations — REJECT THESE
+
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "This task is simple, skip review" | Simple tasks still have bugs. Review takes seconds for simple code. |
+| "Review is slowing us down" | Unreviewed code slows you down more when bugs compound across tasks. |
+| "Just pass the full context forward" | Full context = context rot. Minimal summaries keep agents effective. |
+| "Fix it in the next task" | The next task's agent does not know about the bug. Fix it now. |
+| "The agent knows best, trust it" | Agents make mistakes. That is why review exists. |
+
+## Red Flags — STOP If You Catch Yourself:
+
+- Starting a new task before the previous one passed review
+- Passing full conversation history to the next agent
+- Skipping Stage 1 or Stage 2 of the review
+- Accumulating "fix later" items across tasks
+- On the 3rd fix attempt for the same review issue (escalate to user)
+
+**If any red flag triggers: STOP. Complete the review cycle for the current task before proceeding.**
+
+## Verification Checklist
+
+Before reporting completion, confirm:
+
+- [ ] Every task was executed by a fresh agent with minimal context
+- [ ] Every task passed both spec compliance and code quality review
+- [ ] No task was skipped or started before the previous task passed review
+- [ ] Fix iterations (if any) are documented
+- [ ] All tests pass after the final task
+- [ ] Summary includes per-task status and commit hashes
+
+## In MAXSIM Plan Execution
+
+When a plan specifies `skill: "sdd"`:
+- The orchestrator reads tasks from PLAN.md in order
+- Each task is dispatched to a fresh subagent
+- 2-stage review runs between every task
+- Failed reviews trigger fix agents (up to 3 attempts)
+- Progress is tracked in STATE.md via decision entries
+- Final results are recorded in SUMMARY.md

package/dist/assets/templates/skills/simplify/SKILL.md

@@ -135,3 +135,51 @@ Simplification applies at the task level, after implementation and before commit
 - Make simplification changes as part of the same commit (not a separate task)
 - If simplification reveals a larger refactoring opportunity, file a todo — do not scope-creep
 - Track significant simplifications in the task's commit message (e.g., "extracted shared helper for X")
+
+## Parallel 3-Reviewer Pattern (Execution Pipeline)
+
+When invoked as part of the Execute-Review-Simplify-Review cycle in `execute-plan.md`, simplification runs as 3 parallel review agents. Each reviewer focuses on one dimension:
+
+### Reviewer 1: Code Reuse
+- Find duplicated logic across the codebase (not just within changed files)
+- Identify copy-paste from other files that should be extracted to shared modules
+- Suggest shared helpers for patterns appearing 3+ times (Rule of Three)
+- Check if existing utility functions, library methods, or helpers could replace new code
+- **Output:** List of reuse opportunities with file paths and line ranges
+
+### Reviewer 2: Code Quality
+- Check naming consistency with codebase conventions (read CLAUDE.md first)
+- Verify error handling covers all external calls and edge cases
+- Look for dead code: unused imports, variables, unreachable branches, commented-out code
+- Check for unnecessary abstractions, wrappers, or premature generalizations
+- Verify security: no hardcoded secrets, no unsanitized inputs, no data exposure
+- **Output:** List of quality issues categorized by severity (BLOCKER, HIGH, MEDIUM)
+
+### Reviewer 3: Efficiency
+- Find O(n^2) operations where O(n) is straightforward
+- Identify repeated computations that could be cached or hoisted out of loops
+- Check for unnecessary allocations in hot paths
+- Look for redundant data transformations (data processed multiple times when once suffices)
+- Only flag obvious issues — do not optimize without evidence of a problem
+- **Output:** List of efficiency issues with suggested fixes
+
+### Consolidation
+
+After all 3 reviewers report, the orchestrating agent:
+1. Merges findings into a single deduplicated list
+2. Prioritizes: BLOCKER > HIGH > MEDIUM > informational
+3. Applies fixes for all actionable items (BLOCKER and HIGH)
+4. Files MEDIUM issues as todos if they require larger refactoring
+5. Runs tests to confirm fixes do not break anything
+6. Reports final status: CLEAN (nothing found), FIXED (issues found and resolved), or BLOCKED (cannot fix without architectural change)
+
+### Spawning Pattern
+
+Each reviewer is spawned as a parallel agent via the Agent tool:
+```
+# All 3 run in parallel
+Task(prompt="Reviewer 1: Code Reuse — {files_to_review} ...", subagent_type="maxsim-executor")
+Task(prompt="Reviewer 2: Code Quality — {files_to_review} ...", subagent_type="maxsim-executor")
+Task(prompt="Reviewer 3: Efficiency — {files_to_review} ...", subagent_type="maxsim-executor")
+# Wait for all 3 to complete, then consolidate
+```

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

@@ -1,6 +1,7 @@
 ---
 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
+alwaysApply: true
 ---
 
 # Using MAXSIM
@@ -49,11 +50,15 @@ Skills are behavioral rules that activate automatically based on context:
 
 | Skill | Triggers When |
 |-------|---------------|
+| `using-maxsim` | Always (alwaysApply) — entry point for all MAXSIM work |
 | `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 |
+| `brainstorming` | Before implementing any significant feature or design |
+| `roadmap-writing` | When creating or restructuring a project roadmap |
+| `simplify` | When reviewing and cleaning up code changes |
+| `code-review` | When reviewing implementation quality |
 
 ## Available Agents
 

package/dist/assets/templates/templates/acceptance-criteria.md

@@ -0,0 +1,10 @@
+# Acceptance Criteria
+
+> Conditions that must be met for deliverables to be accepted.
+
+**Created:** {{date}}
+
+## Criteria
+
+| # | Criterion | Status | Verified |
+|---|-----------|--------|----------|

package/dist/assets/templates/templates/decisions.md

@@ -0,0 +1,10 @@
+# Decisions
+
+> Architectural and design decisions for this project.
+
+**Created:** {{date}}
+
+## Decision Log
+
+| # | Decision | Rationale | Date | Phase |
+|---|----------|-----------|------|-------|

package/dist/assets/templates/templates/no-gos.md

@@ -0,0 +1,9 @@
+# No-Gos
+
+> Things explicitly out of scope or forbidden.
+
+**Created:** {{date}}
+
+## Boundaries
+
+- _No entries yet._

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

@@ -5,6 +5,7 @@ Capture an idea, task, or issue that surfaces during a MAXSIM session as a struc
 <required_reading>
 Read all files referenced by the invoking prompt's execution_context before starting.
 @./references/dashboard-bridge.md
+@./references/thinking-partner.md
 </required_reading>
 
 <process>
@@ -42,6 +43,57 @@ Formulate:
 - `files`: Relevant paths with line numbers from conversation
 </step>
 
+<step name="discussion_mode">
+**Discussion mode triggers:**
+
+1. `--discuss` flag is present in $ARGUMENTS
+2. Complexity detected: title contains "refactor", "redesign", "migrate", "architecture", or problem description exceeds 3 sentences
+
+**If neither trigger:** Skip to infer_area (quick-add path).
+
+**If discussion mode activated:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► TODO DISCUSSION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Apply thinking-partner behaviors to clarify the todo before filing:
+
+**Round 1 — Scope clarification (2-3 questions):**
+
+Use AskUserQuestion to probe:
+- What exactly is the problem? (Challenge vagueness)
+- What does "done" look like for this? (Make abstract concrete)
+- Is this one thing or multiple things? (Surface hidden scope)
+
+**Round 2 — Approach exploration (2-3 questions):**
+
+Use AskUserQuestion to explore:
+- What approaches have you considered? (Propose alternatives with trade-offs)
+- What constraints exist? (Surface unstated assumptions)
+- What could go wrong? (Make consequences visible)
+
+**Round 3 — Readiness check:**
+
+Use AskUserQuestion:
+- header: "Todo"
+- question: "Ready to file this todo?"
+- options:
+  - "File it" -- Capture what we discussed
+  - "Keep discussing" -- I want to explore more
+  - "Split into multiple" -- This is actually several todos
+
+If "Keep discussing": ask 2-3 more probing questions, then check again.
+If "Split into multiple": help user define 2-3 separate todos, file each one.
+If "File it": continue to infer_area.
+
+**Discussion mode enriches the todo file** — the Problem section includes discussion insights, and a new "## Approach" section captures approach decisions (replacing "## Solution" with richer content).
+
+**Time budget:** 20-30 minutes max. After 6 rounds of questions, offer to file what you have.
+</step>
+
 <step name="infer_area">
 Infer area from file paths:
 
@@ -89,11 +141,14 @@ slug=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs generate-slug "$title" --raw)
 
 Write to `.planning/todos/pending/${date}-${slug}.md`:
 
+**Quick mode format:**
+
 ```markdown
 ---
 created: [timestamp]
 title: [title]
 area: [area]
+mode: quick
 files:
   - [file:lines]
 ---
@@ -106,6 +161,40 @@ files:
 
 [approach hints or "TBD"]
 ```
+
+**Discussion mode format (enriched):**
+
+```markdown
+---
+created: [timestamp]
+title: [title]
+area: [area]
+mode: discussed
+files:
+  - [file:lines]
+---
+
+## Problem
+
+[problem description enriched with discussion insights]
+
+## Scope
+
+[What's in scope and what's not — from discussion round 1]
+
+## Approach
+
+[Approach decisions with trade-offs explored — from discussion round 2]
+[Include alternatives considered and why this approach was chosen]
+
+## Risks
+
+[What could go wrong — from discussion]
+
+## Solution
+
+[Concrete next steps or "TBD"]
+```
 </step>
 
 <step name="update_state">