maxsimcli 4.0.1 → 4.0.2

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

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

@@ -1,118 +1,79 @@
 ---
 name: sdd
-description: Dispatch fresh subagent per task with 2-stage review between tasks
+description: >-
+  Executes plan tasks sequentially, each in a fresh subagent with minimal context,
+  with mandatory two-stage review between tasks. Use when executing sequential
+  tasks where context rot is a concern or running spec-driven dispatch.
 ---
 
 # 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>
+**HARD GATE** -- No task starts until the previous task passes two-stage review. If the review found issues, they must be fixed before the next task begins. No exceptions, no deferral, no skipping review for simple tasks.
 
 ## Process
 
-### 1. LOAD — Read the Plan
+### 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
+### 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
+   - Results from previous tasks (commit hashes, created files) -- NOT the full previous context
+2. Spawn a fresh 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
+### 3. REVIEW -- Two-Stage Quality Gate
 
 After each task completes, run two review stages before proceeding:
 
-#### Stage 1: Spec Compliance
+**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.
+Verdict: PASS or FAIL with specific issues.
 
-#### Stage 2: Code Quality
+**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.
+Verdict: PASS or FAIL with specific issues.
 
-### 4. FIX — Address Review Failures
+### 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
+1. Spawn a NEW fresh agent with the original task description, the review feedback, and the current file state
+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
+### 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
+- Note the commit hash and any files created or 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
+### 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
@@ -122,38 +83,27 @@ After all tasks complete:
 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.**
+| Full codebase | Never -- only specified files |
 
-## Common Rationalizations — REJECT THESE
+The point of SDD is fresh context. Loading the previous agent's full context defeats the purpose.
 
-| 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. |
+## Common Pitfalls
 
-## Red Flags — STOP If You Catch Yourself:
+| Pitfall | Why it matters |
+|---|---|
+| Skipping review for simple tasks | Simple tasks still have bugs. Review takes seconds for simple code. |
+| Passing full context forward | Full context causes context rot. Minimal summaries keep agents effective. |
+| Deferring fixes to the next task | The next task's agent does not know about the bug. Fix it now. |
+| Accumulating fix-later items across tasks | Each task must be clean before the next starts. |
 
-- 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
+## Verification
 
 Before reporting completion, confirm:
 
@@ -164,12 +114,13 @@ Before reporting completion, confirm:
 - [ ] All tests pass after the final task
 - [ ] Summary includes per-task status and commit hashes
 
-## In MAXSIM Plan Execution
+## MAXSIM Integration
 
 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
+- Two-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