maxsimcli 4.0.1 → 4.0.2

package/dist/assets/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [4.0.1](https://github.com/maystudios/maxsimcli/compare/v4.0.0...v4.0.1) (2026-03-02)
+
+
+### Bug Fixes
+
+* **mcp:** bundle MCP server dependencies and update README with skills/MCP docs ([7724966](https://github.com/maystudios/maxsimcli/commit/772496696167d8723873b6645826327472824560))
+
 # [4.0.0](https://github.com/maystudios/maxsimcli/compare/v3.12.0...v4.0.0) (2026-03-02)
 
 

package/dist/assets/templates/skills/batch-worktree/SKILL.md

@@ -1,123 +1,76 @@
 ---
 name: batch-worktree
-description: Orchestrate parallel work across isolated git worktrees with independent PRs
+description: >-
+  Decomposes large tasks into independent units and executes each in an isolated
+  git worktree with its own branch and PR. Use when parallelizing work across
+  5-30 independent units or orchestrating worktree-based parallel execution. Not
+  for sequential dependencies or fewer than 3 units.
 ---
 
 # Batch Worktree
 
 Decompose large tasks into independent units, execute each in an isolated worktree, and produce one PR per unit.
 
-**If units share overlapping files, you cannot parallelize them. Serialize or redesign.**
-
-## When to Use
-
-- The task is decomposable into 5-30 independent units
-- Each unit can be implemented, tested, and merged independently
-- Units touch non-overlapping files (no merge conflicts between units)
-- You want parallel execution with isolated git state per unit
-
-Do NOT use this skill when:
-- Units have sequential dependencies (use SDD instead)
-- The task has fewer than 3 units (overhead is not worth it)
-- Units modify the same files (merge conflicts will block you)
-
-## The Iron Law
-
-<HARD-GATE>
-EVERY UNIT MUST BE INDEPENDENTLY MERGEABLE.
-If merging unit A would break the build without unit B, they are not independent — combine them or serialize them.
-No exceptions. No "we'll merge them in order." No "it'll probably be fine."
-Violating this rule produces unmergeable PRs — wasted work.
-</HARD-GATE>
+**HARD GATE: Every unit must be independently mergeable. If merging unit A would break the build without unit B, they are not independent. Combine them or serialize them. No exceptions.**
 
 ## Process
 
-### 1. DECOMPOSE — Split Task into Independent Units
-
-- List all units with a clear one-line description each
-- For each unit, list the files it will create or modify
-- Verify NO file appears in more than one unit
-- If overlap exists: merge the overlapping units into one, or extract shared code into a prerequisite unit that runs first
-
-```bash
-# Document the decomposition
-node .claude/maxsim/bin/maxsim-tools.cjs state-add-decision "Batch decomposition: N units identified, no file overlap confirmed"
-```
+### 1. Research -- Analyze and Decompose
 
-### 2. VALIDATE — Confirm Independence
+List all units with a one-line description each. For each unit, list the files it will create or modify. Verify no file appears in more than one unit. If overlap exists, merge the overlapping units into one or extract shared code into a prerequisite unit that runs first.
 
-For each pair of units, verify:
+For each pair of units, confirm:
 - No shared file modifications
-- No runtime dependency (unit A's output is not unit B's input)
+- No runtime dependency (unit A output is not unit B input)
 - Each unit's tests pass without the other unit's changes
 
-If validation fails: redesign the decomposition. Do not proceed with overlapping units.
+If validation fails, redesign the decomposition before proceeding.
 
-### 3. SPAWN — Create Worktree Per Unit
+### 2. Plan -- Define Unit Specifications
 
-For each unit, create an isolated worktree and spawn an agent:
+For each unit, prepare a specification containing:
+- Unit description and acceptance criteria
+- The list of files it owns (and only those files)
+- The base branch to branch from
+- Instructions to implement, test, commit, push, and create a PR
 
-```bash
-# Create worktree branch for each unit
-git worktree add .claude/worktrees/unit-NN unit/NN-description -b unit/NN-description
-```
+Record the decomposition decision:
 
-Spawn one agent per unit with `isolation: "worktree"`. Each agent receives:
-- The unit description and acceptance criteria
-- The list of files it owns (and ONLY those files)
-- The base branch to branch from
-- Instructions to: implement, test, commit, push, create PR
+```
+node .claude/maxsim/bin/maxsim-tools.cjs state-add-decision "Batch decomposition: N units identified, no file overlap confirmed"
+```
 
-### 4. EXECUTE — Each Agent Works Independently
+### 3. Spawn -- Create Worktree Per Unit
 
-Each spawned agent follows this sequence:
-1. Read the unit description and relevant source files
-2. Implement the changes (apply TDD or simplify skills as configured)
-3. Run tests — all must pass
-4. Commit with a descriptive message referencing the unit
-5. Push the branch
-6. Create a PR with unit description as the body
+For each unit, create an isolated worktree and spawn an agent with `isolation: "worktree"`. Each agent receives its unit specification and works independently through: read relevant source, implement changes, run tests, commit, push, create PR.
 
-### 5. TRACK — Monitor Progress
+### 4. Track -- Monitor Progress
 
 Maintain a status table and update it as agents report back:
 
-```markdown
 | # | Unit | Status | PR |
 |---|------|--------|----|
 | 1 | description | done | #123 |
-| 2 | description | in-progress | — |
-| 3 | description | failed | — |
-```
+| 2 | description | in-progress | -- |
+| 3 | description | failed | -- |
 
 Statuses: `pending`, `in-progress`, `done`, `failed`, `needs-review`
 
-### 6. REPORT — Collect Results
-
-When all units complete:
-- List all created PRs
-- Flag any failed units with error summaries
-- If any unit failed: spawn a fix agent for that unit only
-
-## Handling Failures
+Failure handling:
+- Unit fails tests: spawn a fix agent in the same worktree
+- Merge conflict: decomposition was wrong, fix overlap and re-run unit
+- Agent times out: re-spawn with the same unit description
+- 3+ failures on same unit: stop and escalate to user
 
-| Situation | Action |
-|-----------|--------|
-| Unit fails tests | Spawn a fix agent in the same worktree |
-| Unit has merge conflict | The decomposition was wrong — fix overlap, re-run unit |
-| Agent times out | Re-spawn with the same unit description |
-| 3+ failures on same unit | Stop and escalate to user — likely an architectural issue |
+When all units complete, list all created PRs and flag any failed units with error summaries. If any unit failed, spawn a fix agent for that unit only.
 
-## Common Rationalizations — REJECT THESE
+## Common Pitfalls
 
-| Excuse | Why It Violates the Rule |
-|--------|--------------------------|
-| "The overlap is minor" | Minor overlap = merge conflicts. Split the shared code into a prerequisite unit. |
-| "We'll merge in the right order" | Order-dependent merges are not independent. Serialize those units. |
-| "It's faster to do them all in one branch" | One branch means one context window. Worktrees give each unit fresh context. |
-| "Only 2 units, let's still use worktrees" | Worktree overhead is not worth it for <3 units. Use sequential execution. |
+- "The overlap is minor" -- Minor overlap causes merge conflicts. Split shared code into a prerequisite unit.
+- "We'll merge in the right order" -- Order-dependent merges are not independent. Serialize those units.
+- "Only 2 units, let's still use worktrees" -- Worktree overhead is not worth it for fewer than 3 units. Use sequential execution.
 
-## Verification Checklist
+## Verification
 
 Before reporting completion, confirm:
 
@@ -128,7 +81,7 @@ Before reporting completion, confirm:
 - [ ] No PR depends on another PR being merged first
 - [ ] Status table is complete with all PR links
 
-## In MAXSIM Plan Execution
+## MAXSIM Integration
 
 When a plan specifies `skill: "batch-worktree"`:
 - The orchestrator decomposes the plan's tasks into independent units

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

@@ -1,159 +1,89 @@
 ---
 name: brainstorming
-description: Use before implementing any significant feature or design — requires exploring multiple approaches and getting explicit design approval before writing code
+description: >-
+  Explores multiple implementation approaches with trade-off analysis before
+  committing to a design direction. Use when starting a significant feature,
+  making architectural decisions, or choosing between design alternatives.
 ---
 
 # Brainstorming
 
 The first idea is rarely the best idea. Explore the space before committing to a direction.
 
-**If you have not considered alternatives, you are building the first thing that came to mind.**
+**HARD GATE** -- No implementation without design approval. If you have not presented approaches, discussed trade-offs, and received explicit user approval, you cannot write implementation code. This is not a judgment call.
 
-## The Iron Law
+## Process
 
-<HARD-GATE>
-NO IMPLEMENTATION WITHOUT DESIGN APPROVAL.
-If you have not presented approaches, discussed trade-offs, and received explicit approval, you CANNOT write implementation code.
-"I already know the best approach" is an assumption, not a conclusion.
-Violating this rule is a violation — not a judgment call.
-</HARD-GATE>
+### 1. Frame the Problem
 
-## The Gate Function
-
-Follow these steps IN ORDER before implementing any significant feature, architecture change, or design decision.
-
-### 1. FRAME — Define the Problem
-
-Ask the user ONE question at a time to understand the problem space. Do not bundle multiple questions — each response informs the next question.
+Ask the user ONE question at a time to understand the problem space. Each answer informs the next question.
 
 - What is the goal? What does success look like?
 - What are the constraints (performance, compatibility, timeline)?
-- What has already been tried or considered?
+- What has been tried or considered already?
 - What are the non-negotiables vs. nice-to-haves?
 
-**Rule: ONE question at a time. Wait for the answer before asking the next.**
-
-### 2. RESEARCH — Understand the Context
-
-Before proposing solutions, gather evidence:
+### 2. Research Context
 
-- Read the relevant code and understand current architecture
-- Check `.planning/` for existing decisions and constraints
-- Review ROADMAP.md for phase dependencies and scope
-- Identify related patterns already in the codebase
+Before proposing solutions, gather evidence from the codebase and any existing planning artifacts. Read relevant code, check for prior decisions, and identify patterns already in use.
 
-```bash
-# Check existing decisions
-node ~/.claude/maxsim/bin/maxsim-tools.cjs state read --raw
-
-# Check current roadmap context
-node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap read --raw
-```
-
-### 3. PROPOSE — Present 2-3 Approaches
+### 3. Present 2-3 Approaches
 
 For each approach, provide:
 
-| Aspect | What to Include |
-|--------|----------------|
-| **Summary** | One-sentence description of the approach |
-| **How it works** | Key implementation steps (3-5 bullets) |
-| **Pros** | Concrete advantages — not vague ("simpler" is vague, "200 fewer lines" is concrete) |
-| **Cons** | Honest drawbacks — do not hide weaknesses to sell a preferred option |
-| **Effort** | Relative complexity (low / medium / high) |
-| **Risk** | What could go wrong and how recoverable is it |
-
-**Present exactly 2-3 approaches.** One option is not brainstorming. Four or more creates decision paralysis.
-
-If one approach is clearly superior, say so — but still present alternatives so the user can validate your reasoning.
+| Aspect | Content |
+|--------|---------|
+| **Summary** | One sentence |
+| **How it works** | 3-5 implementation bullets |
+| **Pros** | Concrete advantages (not vague -- "200 fewer lines" beats "simpler") |
+| **Cons** | Honest drawbacks -- do not hide weaknesses |
+| **Effort** | Low / Medium / High |
+| **Risk** | What could go wrong and how recoverable |
 
-### 4. DISCUSS — Refine with the User
+Present exactly 2-3 approaches. If one is clearly superior, say so -- but still present alternatives so the user can validate your reasoning.
 
-- Ask the user which approach they prefer (or if they want a hybrid)
-- Answer follow-up questions honestly — do not advocate for a single approach
-- If the user raises concerns, address them specifically
-- If no approach fits, propose new ones informed by the discussion
+### 4. Discuss and Refine
 
-**Continue ONE question at a time. Do not assume consensus until stated.**
+Ask the user which approach they prefer or whether they want a hybrid. Answer follow-up questions honestly. If no approach fits, propose new ones informed by the discussion. Continue one question at a time -- do not assume consensus.
 
-### 5. DECIDE — Get Explicit Approval
+### 5. Get Explicit Approval
 
-The user must explicitly approve the chosen approach. Acceptable approvals:
+The user must explicitly approve one approach (e.g., "Go with A", "Approved", "Ship it"). Vague responses like "Sounds good" or "Interesting" are not approval. If ambiguous, ask: "To confirm -- should I proceed with [specific approach]?"
 
-- "Go with approach A"
-- "Let's do option 2"
-- "Approved" / "LGTM" / "Ship it"
+### 6. Document the Decision
 
-Not acceptable as approval:
+Record the chosen approach, rejected alternatives with reasons, key implementation decisions, and risks. Use MAXSIM state tooling if available.
 
-- "Sounds good" (too vague — clarify which approach)
-- "Interesting" (not a decision)
-- Silence (not consent)
+### 7. Implement the Approved Design
 
-**If approval is ambiguous, ask: "To confirm — should I proceed with [specific approach]?"**
+Only after steps 1-6. Follow the approved design. If implementation reveals a design flaw, stop and return to step 4.
 
-### 6. DOCUMENT — Record the Decision
+## Common Pitfalls
 
-After approval, write a design doc and record the decision:
-
-```bash
-# Record the decision in STATE.md
-node ~/.claude/maxsim/bin/maxsim-tools.cjs add-decision \
-  --phase "current-phase" \
-  --summary "Chose approach X for [feature] because [reason]" \
-  --rationale "Evaluated 3 approaches: A (rejected — too complex), B (rejected — performance risk), C (approved — best trade-off of simplicity and extensibility)"
-```
-
-The design doc should include:
-- **Chosen approach** and why
-- **Rejected alternatives** and why they were rejected
-- **Key implementation decisions** that flow from the choice
-- **Risks** and mitigation strategies
-
-### 7. IMPLEMENT — Build the Approved Design
-
-Only after steps 1-6 are complete:
-- Follow the approved design — do not deviate without re-discussion
-- If implementation reveals a flaw in the design, STOP and return to step 4
-- Reference the design doc in commit messages
-
-## Common Rationalizations — REJECT THESE
-
-| Excuse | Why It Violates the Rule |
-|--------|--------------------------|
-| "I already know the best approach" | You know YOUR preferred approach. Alternatives may be better. |
-| "There's only one way to do this" | There is almost never only one way. You have not looked hard enough. |
-| "The user won't care about the design" | Users care about the outcome. Bad design leads to bad outcomes. |
+| Excuse | Reality |
+|--------|---------|
+| "I already know the best approach" | You know your preferred approach. Alternatives may be better. |
+| "There's only one way to do this" | There is almost never only one way. |
 | "Brainstorming slows us down" | Building the wrong thing is slower. 30 minutes of design saves days of rework. |
-| "I'll refactor if the first approach is wrong" | Refactoring is expensive. Choosing well upfront is cheaper. |
-| "The scope is too small for brainstorming" | If it touches architecture, it needs brainstorming regardless of size. |
-
-## Red Flags — STOP If You Catch Yourself:
 
-- Writing implementation code before presenting approaches to the user
-- Presenting only one approach and calling it "brainstorming"
-- Asking multiple questions at once instead of one at a time
-- Assuming approval without an explicit statement
-- Skipping the documentation step because "we'll remember"
-- Deviating from the approved design without discussion
+Stop immediately if you catch yourself: writing code before presenting approaches, presenting only one option, asking multiple questions at once, assuming approval without explicit confirmation, or skipping documentation.
 
-**If any red flag triggers: STOP. Return to the appropriate step.**
-
-## Verification Checklist
+## Verification
 
 Before starting implementation, confirm:
 
 - [ ] Problem has been framed with user input (not assumptions)
 - [ ] Relevant code and context have been researched
-- [ ] 2-3 approaches have been presented with concrete trade-offs
+- [ ] 2-3 approaches presented with concrete trade-offs
 - [ ] User has explicitly approved one specific approach
-- [ ] Decision has been recorded in STATE.md
+- [ ] Decision has been recorded
 - [ ] Design doc captures chosen approach, rejected alternatives, and risks
 
-## In MAXSIM Plan Execution
+## MAXSIM Integration
+
+Brainstorming applies before significant implementation work within MAXSIM workflows:
 
-Brainstorming applies before significant implementation work:
 - Use during phase planning when design choices affect multiple tasks
-- Use before any task that introduces new architecture, patterns, or external dependencies
-- The decision record in STATE.md persists across sessions — future agents inherit context
-- If a brainstorming session spans multiple interactions, record partial progress in STATE.md blockers
+- Use before any task introducing new architecture, patterns, or external dependencies
+- Decision records in STATE.md persist across sessions -- future agents inherit context
+- If a session spans multiple interactions, record partial progress in STATE.md blockers

package/dist/assets/templates/skills/code-review/SKILL.md

@@ -1,40 +1,28 @@
 ---
 name: code-review
-description: Use after completing a phase or significant implementation — requires reviewing all changed code for critical issues before sign-off
+description: >-
+  Reviews all changed code for security vulnerabilities, interface correctness,
+  error handling, test coverage, and quality before sign-off. Use when completing
+  a phase, reviewing implementation, or before approving changes for merge.
 ---
 
 # Code Review
 
 Shipping unreviewed code is shipping unknown risk. Review before sign-off.
 
-**If you have not reviewed every changed file, you cannot approve the phase.**
+**HARD GATE: NO PHASE SIGN-OFF WITHOUT REVIEWING ALL CHANGED CODE.** If every diff introduced in this phase has not been read, the phase cannot be marked complete. Passing tests do not prove code quality.
 
-## The Iron Law
+## Process
 
-<HARD-GATE>
-NO PHASE SIGN-OFF WITHOUT REVIEWING ALL CHANGED CODE.
-If you have not read every diff introduced in this phase, you CANNOT mark it complete.
-"It works" is not "it's correct." Passing tests do not prove code quality.
-Violating this rule is a violation — not a shortcut.
-</HARD-GATE>
+Follow these steps in order before approving any phase or significant implementation.
 
-## The Gate Function
+### 1. SCOPE -- Identify All Changes
 
-Follow these steps IN ORDER before approving any phase or significant implementation.
+- Diff against the phase starting point to see every changed file
+- List all new, modified, and deleted files
+- Do not skip generated files, config changes, or minor edits
 
-### 1. SCOPE — Identify All Changes
-
-- Run `git diff` against the phase's starting point to see every changed file
-- List all new files, modified files, and deleted files
-- Do NOT skip generated files, config changes, or "minor" edits
-
-```bash
-# Example: see all changes since phase branch point
-git diff --stat main...HEAD
-git diff main...HEAD
-```
-
-### 2. SECURITY — Check for Vulnerabilities
+### 2. SECURITY -- Check for Vulnerabilities
 
 Review every changed file for:
 
@@ -48,75 +36,47 @@ Review every changed file for:
 
 **Any security issue is a blocking finding. No exceptions.**
 
-### 3. INTERFACES — Verify API Contracts
+### 3. INTERFACES -- Verify API Contracts
 
 - Do public function signatures match their documentation?
 - Are return types accurate and complete?
 - Do error types cover all failure modes?
 - Are breaking changes documented and intentional?
-- Do exported interfaces maintain backward compatibility (or is the break intentional)?
+- Do exported interfaces maintain backward compatibility?
 
-### 4. ERROR HANDLING — Check Failure Paths
+### 4. ERROR HANDLING -- Check Failure Paths
 
-- Are all external calls (I/O, network, user input) wrapped in error handling?
+- Are all external calls wrapped in error handling?
 - Do error messages provide enough context to diagnose the issue?
 - Are errors propagated correctly (not swallowed silently)?
 - Are edge cases handled (empty input, null values, boundary conditions)?
 
-### 5. TESTS — Evaluate Coverage
+### 5. TESTS -- Evaluate Coverage
 
 - Does every new public function have corresponding tests?
 - Do tests cover both success and failure paths?
-- Are edge cases tested (empty, null, boundary, error conditions)?
+- Are edge cases tested?
 - Do tests verify behavior, not implementation details?
 
-### 6. QUALITY — Assess Maintainability
+### 6. QUALITY -- Assess Maintainability
 
-- Is naming consistent with the existing codebase conventions?
-- Are there code duplication opportunities that should be extracted?
+- Is naming consistent with existing codebase conventions?
+- Are there duplication opportunities that should be extracted?
 - Is the complexity justified by the requirements?
-- Are comments present where logic is non-obvious (and absent where code is self-evident)?
-
-## Critical Issues — Block Phase Sign-Off
-
-These categories MUST be resolved before the phase can be marked complete:
-
-| Severity | Category | Example |
-|----------|----------|---------|
-| **Blocker** | Security vulnerability | SQL injection, XSS, hardcoded secrets |
-| **Blocker** | Broken interface | Public API returns wrong type, missing required field |
-| **Blocker** | Missing error handling | Unhandled promise rejection, swallowed exceptions on I/O |
-| **Blocker** | Data loss risk | Destructive operation without confirmation, missing transaction |
-| **High** | Performance regression | O(n^2) where O(n) is trivial, unbounded memory allocation |
-| **High** | Missing critical tests | No tests for error paths, no tests for new public API |
-| **Medium** | Naming inconsistency | Convention mismatch with existing codebase |
-| **Medium** | Dead code | Unreachable branches, unused imports, commented-out code |
-
-**Blocker and High severity issues block sign-off. Medium issues should be filed for follow-up.**
+- Are comments present where logic is non-obvious?
 
-## Common Rationalizations — REJECT THESE
+## Common Pitfalls
 
-| Excuse | Why It Violates the Rule |
-|--------|--------------------------|
+| Issue | Reality |
+|-------|---------|
 | "Tests pass, so the code is fine" | Tests verify behavior, not code quality. Review is separate. |
 | "I wrote it, so I know it's correct" | Author bias is real. Review as if someone else wrote it. |
-| "It's just a small change" | Small changes cause large outages. Review proportional effort, not zero effort. |
-| "We'll clean it up later" | "Later" accumulates. Fix blockers now, file medium issues. |
-| "The deadline is tight" | Shipping broken code costs more time than reviewing. |
+| "It's just a small change" | Small changes cause large outages. |
 | "Generated code doesn't need review" | Generated code has the same bugs. Review it. |
 
-## Red Flags — STOP If You Catch Yourself:
-
-- Skipping files because they "look fine" from the diff stat
-- Approving without reading the actual code changes
-- Ignoring a gut feeling that something is wrong
-- Rushing through review to meet a deadline
-- Assuming tests cover everything without checking
-- Skipping error handling review because "the happy path works"
-
-**If any red flag triggers: STOP. Go back to step 1 (SCOPE) and review properly.**
+Stop if you catch yourself skipping files because they "look fine," approving without reading actual code, or rushing through review to meet a deadline.
 
-## Verification Checklist
+## Verification
 
 Before signing off on a phase, confirm:
 
@@ -128,9 +88,21 @@ Before signing off on a phase, confirm:
 - [ ] Naming and style are consistent with codebase conventions
 - [ ] No blocker or high severity issues remain open
 
-## Review Output Format
+### Severity Reference
+
+| Severity | Category | Example |
+|----------|----------|---------|
+| Blocker | Security vulnerability | SQL injection, XSS, hardcoded secrets |
+| Blocker | Broken interface | Public API returns wrong type |
+| Blocker | Data loss risk | Destructive operation without confirmation |
+| High | Performance regression | O(n^2) where O(n) is trivial |
+| High | Missing critical tests | No tests for error paths or new public API |
+| Medium | Naming inconsistency | Convention mismatch with existing codebase |
+| Medium | Dead code | Unreachable branches, unused imports |
+
+Blocker and High severity issues block sign-off. Medium issues should be filed for follow-up.
 
-Produce a review summary for phase documentation:
+### Review Output Format
 
 ```
 REVIEW SCOPE: [number] files changed, [number] additions, [number] deletions
@@ -142,7 +114,7 @@ QUALITY: PASS | ISSUES FOUND (list)
 VERDICT: APPROVED | BLOCKED (list blocking issues)
 ```
 
-## In MAXSIM Plan Execution
+## MAXSIM Integration
 
 Code review applies at phase boundaries:
 - After all tasks in a phase are complete, run this review before marking the phase done