maxsimcli 4.0.0 → 4.0.2

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

package/dist/assets/templates/skills/memory-management/SKILL.md

@@ -1,28 +1,19 @@
 ---
 name: memory-management
-description: Use when encountering recurring patterns, errors, or decisions that should persist across sessions — defines when and how to save to project memory
+description: "Persists recurring patterns, error solutions, and architectural decisions to project memory files for cross-session continuity. Use when encountering the same error twice, making significant decisions, or discovering non-obvious conventions."
 ---
 
 # Memory Management
 
 Context dies with each session. Patterns discovered but not saved are patterns lost.
 
-**If you encountered it twice, save it. You will encounter it again.**
+**HARD GATE** -- If you encountered it twice, save it. You will encounter it again. "I'll remember" is a lie -- your context resets. Write it down. Violating this rule guarantees repeated mistakes across sessions.
 
-## The Iron Law
+## Process
 
-<HARD-GATE>
-RECURRING PATTERNS MUST BE PERSISTED.
-If you have seen the same error, pattern, or decision twice in this session or across sessions, you MUST save it.
-"I'll remember" is a lie — your context resets. Write it down.
-Violating this rule guarantees repeated mistakes across sessions.
-</HARD-GATE>
+### 1. Detect -- Recognize Save Triggers
 
-## When to Save
-
-### Auto-Save Triggers (MUST save)
-
-These situations require immediate memory persistence:
+Save immediately when any of these occur:
 
 | Trigger | Threshold | What to Save |
 |---------|-----------|-------------|
@@ -33,36 +24,17 @@ These situations require immediate memory persistence:
 | Workaround for tooling/framework quirk | Once | The quirk and the workaround |
 | Project-specific pattern confirmed | 2+ uses | The pattern and when to apply it |
 
-### Do NOT Save
-
-- Session-specific context (current task details, in-progress work)
-- Information already in CLAUDE.md or project documentation
-- Speculative conclusions from reading a single file
-- Temporary workarounds that will be removed
-- Obvious patterns that any developer would know
-
-## Where to Save
-
-Memory files live in `.claude/memory/` (for Claude Code) or the equivalent runtime memory directory.
+Do NOT save: session-specific context, information already in CLAUDE.md, speculative conclusions, temporary workarounds, or obvious patterns.
 
-### File Organization
-
-```
-.claude/memory/
-  MEMORY.md          # Index file — always loaded into context
-  patterns.md        # Code patterns and conventions
-  errors.md          # Error patterns and solutions
-  architecture.md    # Architectural decisions and rationale
-  tooling.md         # Tool quirks and workarounds
-```
+### 2. Check -- Avoid Duplicates
 
-- **MEMORY.md** is the index: keep it under 200 lines, link to topic files for details
-- Topic files hold detailed notes organized by subject
-- Use headers and bullet points for scannability
+- Read existing memory files before writing
+- If the pattern is already documented, update it (do not duplicate)
+- If it contradicts existing memory, investigate which is correct
 
-### Memory Entry Format
+### 3. Write -- Persist the Memory
 
-Each entry should follow this structure:
+Add to the appropriate topic file using this entry format:
 
 ```markdown
 ## [Short descriptive title]
@@ -73,83 +45,47 @@ Each entry should follow this structure:
 **Evidence:** How this was confirmed (dates, occurrences, test results)
 ```
 
-## The Gate Function
-
-When you encounter something worth remembering:
-
-### 1. DETECT — Recognize the Pattern
-
-- Is this the same error/pattern you saw before?
-- Is this a decision that will affect future work?
-- Is this a non-obvious convention or quirk?
-
-### 2. CHECK — Avoid Duplicates
-
-- Read the existing memory files first
-- If the pattern is already documented, update it (don't duplicate)
-- If it contradicts existing memory, investigate which is correct
-
-### 3. WRITE — Persist the Memory
-
-- Add to the appropriate topic file
-- Update MEMORY.md index if adding a new topic
-- Keep entries concise — future you needs the answer, not the journey
-
-### 4. VERIFY — Confirm the Save
+### 4. Verify -- Confirm the Save
 
 - Re-read the file to confirm the entry was written correctly
-- Ensure the entry is actionable (someone reading it can act on it)
+- Ensure the entry is actionable (someone reading it can act on it immediately)
 
-## Error Pattern Detection
+## File Organization
 
-When debugging, track errors in a mental tally:
+Memory files live in `.claude/memory/` (or the equivalent runtime memory directory).
 
 ```
-Error seen once → Note it, move on
-Error seen twice → Save to errors.md with pattern and fix
-Error seen 3+ times → Save AND add to MEMORY.md index for immediate visibility
+.claude/memory/
+  MEMORY.md          # Index file -- always loaded into context
+  patterns.md        # Code patterns and conventions
+  errors.md          # Error patterns and solutions
+  architecture.md    # Architectural decisions and rationale
+  tooling.md         # Tool quirks and workarounds
 ```
 
-### What Makes a Good Error Memory
+- **MEMORY.md** is the index: keep it under 200 lines, link to topic files for details
+- Topic files hold detailed notes organized by subject
+- Use headers and bullet points for scannability
 
-Good:
-```markdown
-## Vitest "cannot find module" for path aliases
+## Error Escalation
 
-**Context:** When running tests that import from `@maxsim/core`
-**Error:** `Cannot find module '@maxsim/core/types'`
-**Fix:** Add `resolve.alias` to `vitest.config.ts` matching tsconfig paths
-**Evidence:** Hit 3 times across phases 01-03 (Feb 2026)
 ```
-
-Bad:
-```markdown
-## Test error
-There was an error with tests. Fixed it by changing config.
+Error seen once     -- Note it, move on
+Error seen twice    -- Save to errors.md with pattern and fix
+Error seen 3+ times -- Save AND add to MEMORY.md index for immediate visibility
 ```
 
-## Common Rationalizations — REJECT THESE
-
-| Excuse | Why It Violates the Rule |
-|--------|--------------------------|
-| "I'll remember this" | No you won't. Context resets. Write it down. |
-| "It's too specific to save" | Specific is good. Generic memories are useless. |
-| "Memory files are messy" | Organize them. Messy files > lost knowledge. |
-| "This only applies to this project" | Project memory IS project-scoped. Save it. |
-| "Someone else documented this" | If it's not in your memory files, you won't find it next session. |
-| "I'll save it later" | You'll forget to. Save it now. |
-
-## Red Flags — STOP If You Catch Yourself:
+## Common Pitfalls
 
-- Encountering the same error for the second time without saving it
+- Encountering the same error a second time without saving it
 - Making the same architectural decision you made in a previous session
 - Debugging a problem you already solved before
 - Saying "I think we fixed this before" without finding the memory entry
 - Leaving a session without updating memory for patterns discovered
 
-**If any red flag triggers: STOP. Write the memory entry NOW, before continuing.**
+If any of these occur: stop, write the memory entry now, then continue.
 
-## Verification Checklist
+## Verification
 
 Before ending a work session:
 
@@ -160,12 +96,12 @@ Before ending a work session:
 - [ ] No duplicate entries were created
 - [ ] All entries follow the format (Context, Pattern, Solution, Evidence)
 
-## Integration with MAXSIM
+## MAXSIM Integration
 
-During plan execution, the executor and researcher agents load memory files at startup:
+During plan execution, agents load memory files at startup:
 - **Executor:** Reads MEMORY.md to avoid known pitfalls before implementing
 - **Researcher:** Saves findings to memory for future phases
-- **Debugger:** Checks error memories before starting investigation — the fix may already be known
+- **Debugger:** Checks error memories before starting investigation -- the fix may already be known
 
 Memory persistence happens at natural breakpoints:
 - After resolving a bug (save to errors.md)

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

@@ -1,28 +1,20 @@
 ---
 name: roadmap-writing
-description: Use when creating or restructuring a project roadmap — requires phased planning with dependencies, success criteria, and MAXSIM-compatible format
+description: >-
+  Creates structured project roadmaps with phased planning, dependency graphs,
+  and testable success criteria in MAXSIM-compatible format. Use when creating a
+  new roadmap, restructuring project phases, or planning milestones.
 ---
 
 # 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.**
+**HARD GATE: No phase without success criteria and dependencies. Every phase must have a number, name, goal, testable success criteria, and explicit dependencies. Violating this rule is a violation, not flexibility.**
 
-## The Iron Law
+## Process
 
-<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
+### 1. SCOPE -- Understand the Project
 
 Before writing phases, understand what you are planning:
 
@@ -31,26 +23,18 @@ Before writing phases, understand what you are planning:
 - 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
+### 2. DECOMPOSE -- Break Into Phases
 
 Each phase should be:
 
 | Property | Requirement |
 |----------|------------|
-| **Independently deliverable** | The phase produces a working increment — not a half-built feature |
+| **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:**
+Phase numbering convention:
 
 | Format | When to Use |
 |--------|------------|
@@ -58,54 +42,51 @@ Each phase should be:
 | `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`
+Sort order: `01` then `01A` then `01B` then `01.1` then `01.2` then `02`.
 
-### 3. DEFINE — Write Each Phase
+### 3. DEFINE -- Write Each Phase
 
-Every phase MUST include all of these fields:
+Every phase must include all of these fields:
 
 ```markdown
 ### Phase {number}: {name}
-**Goal**: {one sentence — what this phase achieves}
+**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}
+  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
+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")
+- Criteria describe the end state, not the process ("tests pass" not "write tests")
 
-### 4. CONNECT — Map Dependencies
+### 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)
+- Are there any circular dependencies? (This is a design error -- restructure)
 
-**Rule: Every phase except the first must declare at least one dependency.**
+Every phase except the first must declare at least one dependency.
 
-### 5. MILESTONE — Group Into Milestones
+### 5. MILESTONE -- Group Into Milestones
 
-Group phases into milestones that represent user-visible releases:
+Group phases into milestones that represent user-visible releases. Each milestone should be a coherent deliverable that could ship independently.
 
 ```markdown
 ## Milestones
 
-- **v1.0 MVP** — Phases 1-4
-- **v1.1 Polish** — Phases 5-7
-- **v2.0 Scale** — Phases 8-10
+- **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
+### 6. WRITE -- Produce the Roadmap
 
 Assemble the complete ROADMAP.md:
 
@@ -118,7 +99,7 @@ Assemble the complete ROADMAP.md:
 
 ## Milestones
 
-- {emoji} **{milestone name}** — Phases {range} ({status})
+- **{milestone name}** -- Phases {range} ({status})
 
 ## Phases
 
@@ -135,47 +116,32 @@ Assemble the complete ROADMAP.md:
 **Plans**: TBD
 ```
 
-### 7. VALIDATE — Check the Roadmap
+### 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 |
+| 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
+## Common Pitfalls
 
-| Excuse | Why It Violates the Rule |
-|--------|--------------------------|
+| Pitfall | Why It Fails |
+|---------|-------------|
 | "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. |
+| "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.**
+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", creating circular dependencies, or putting all work in one or two massive phases.
 
-## Verification Checklist
+## Verification
 
 Before finalizing a roadmap, confirm:
 
@@ -188,11 +154,11 @@ Before finalizing a roadmap, confirm:
 - [ ] ROADMAP.md matches the expected format for MAXSIM CLI parsing
 - [ ] Overview section summarizes the project and delivery strategy
 
-## In MAXSIM Plan Execution
+## MAXSIM Integration
 
 Roadmap writing integrates with the MAXSIM lifecycle:
-- Use during project initialization (`/maxsim:plan-phase`) to create the initial roadmap
+- Use during project initialization 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
+- 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