maxsimcli 4.8.0 → 4.9.0

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

@@ -1,90 +1,86 @@
 ---
 name: maxsim-batch
 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
-  3-30 independent units or orchestrating worktree-based parallel execution. Not
-  for sequential dependencies or fewer than 3 units.
+  Parallel worktree execution for independent work units. Isolates agents in
+  separate git worktrees for conflict-free parallel implementation. Use when
+  executing multiple independent plans, batch processing, or parallelizable
+  tasks.
 ---
 
-# Batch Worktree
+# Batch Worktree Execution
 
-Decompose large tasks into independent units, execute each in an isolated worktree, and produce one PR per unit.
+Decompose large tasks into independent units and execute each in an isolated git worktree.
 
-**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.**
+## When to Use
+
+- 3 or more independent work units with no shared file modifications
+- Tasks that can be verified independently (each unit's tests pass without the others)
+- Parallelizable implementation where speed matters
+
+**Do not use for:** Fewer than 3 units (overhead not worth it), sequential dependencies, tasks that modify the same files.
 
 ## Process
 
-### 1. Research -- Analyze and Decompose
+### 1. DECOMPOSE -- Analyze 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.
+List all units with a one-line description each. For each unit, list the files it will create or modify. Verify:
 
-For each pair of units, confirm:
-- No shared file modifications
+- No file appears in more than one unit
 - No runtime dependency (unit A output is not unit B input)
-- Each unit's tests pass without the other unit's changes
+- Each unit's tests pass without the other units' changes
+
+If overlap exists, merge overlapping units or extract shared code into a prerequisite unit that runs first.
 
-If validation fails, redesign the decomposition before proceeding.
+### 2. PLAN -- Define Unit Specifications
 
-### 2. Plan -- Define Unit Specifications
+For each unit, prepare:
 
-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
-
-Record the decomposition decision:
-
-```
-node .claude/maxsim/bin/maxsim-tools.cjs state-add-decision "Batch decomposition: N units identified, no file overlap confirmed"
-```
+- Instructions: implement, test, commit, push, create PR
 
-### 3. Spawn -- Create Worktree Per Unit
+### 3. SPAWN -- Create Worktree Per Unit
 
-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.
+For each unit, create an isolated worktree and spawn an agent. Each agent works independently: read source, implement changes, run tests, commit, push, create PR.
 
-### 4. Track -- Monitor Progress
+### 4. TRACK -- Monitor Progress
 
-Maintain a status table and update it as agents report back:
+Maintain a status table:
 
 | # | Unit | Status | PR |
 |---|------|--------|----|
 | 1 | description | done | #123 |
 | 2 | description | in-progress | -- |
-| 3 | description | failed | -- |
 
-Statuses: `pending`, `in-progress`, `done`, `failed`, `needs-review`
+Statuses: `pending`, `in-progress`, `done`, `failed`
+
+### 5. MERGE -- Collect Results
+
+When all units complete, list all created PRs. Handle 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
+- Merge conflict: decomposition was wrong -- fix overlap and re-run unit
+- 3+ failures on same unit: stop and escalate
+
+## Limits
 
-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.
+- Up to 30 parallel agents, but typically 3-10 for manageable coordination
+- Fast-forward merge preferred, rebase if needed
+- Each unit must be independently mergeable
 
 ## Common Pitfalls
 
 - "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.
+- "Only 2 units, let's still use worktrees" -- Worktree overhead is not worth it for fewer than 3 units.
 
 ## Verification
 
-Before reporting completion, confirm:
+Before reporting completion:
 
-- [ ] All units were verified to touch non-overlapping files
+- [ ] All units touch non-overlapping files
 - [ ] Each unit was implemented in an isolated worktree
 - [ ] Each unit's tests pass independently
 - [ ] Each unit has its own PR
 - [ ] No PR depends on another PR being merged first
-- [ ] Status table is complete with all PR links
-
-## MAXSIM Integration
-
-When a plan specifies `skill: "maxsim-batch"`:
-- The orchestrator decomposes the plan's tasks into independent units
-- Each unit becomes a worktree agent with its own branch and PR
-- The orchestrator tracks progress and reports the final PR list in SUMMARY.md
-- Failed units are retried once before escalating

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

@@ -1,55 +1,38 @@
 ---
 name: maxsim-simplify
 description: >-
-  Maintainability optimization pass: finds duplication, dead code, and
-  unnecessary complexity. Answers "Is this code as simple as it can be?"
-  Use when reviewing code before committing, cleaning up implementations,
-  or preparing changes for review. Not a correctness gate — that is
-  code-review's job.
+  Maintainability optimization covering duplication, dead code, complexity, and
+  naming. Produces structured findings with before/after metrics. Use when
+  reviewing code for simplification, during refactoring passes, or when
+  codebase complexity is increasing.
 ---
 
 # Simplify
 
 Every line of code is a liability. Remove what does not earn its place.
 
-**HARD GATE**: No code ships without a simplification pass. If you have not checked for duplication, dead code, and unnecessary complexity, the change is not ready. "It works" is the starting point, not the finish line.
+## Scope
 
-## When to Use
+Only simplify touched files unless explicitly asked for broader refactoring. The goal is incremental maintainability improvement, not a codebase-wide rewrite.
 
-- After implementing a feature or fix, before committing
-- When preparing changes for code review
-- When cleaning up code that has grown organically over multiple iterations
-- When onboarding to a file and noticing accumulated complexity
+## Dimensions
 
-Do NOT use this skill when:
-- Making a hotfix where speed matters more than polish (file a follow-up instead)
-- The changes are purely mechanical (renames, formatting, dependency bumps)
-
-## Process
-
-### 1. DIFF — Identify What Changed
-
-- Collect the set of modified and added files
-- Read each file in full, not just the changed hunks
-- Note files that interact with the changes (callers, consumers, shared modules)
-
-### 2. DUPLICATION — Eliminate Repeated Logic
+### 1. DUPLICATION -- Eliminate Repeated Logic
 
 - Are there patterns repeated across files that should be a shared helper?
 - Does new code duplicate existing utilities or library functions?
 - Could two similar implementations be merged behind a single interface?
-- Is there copy-paste that should be refactored?
 
-**Rule of three**: If the same pattern appears three times, extract it.
+**Rule of three:** If the same pattern appears three times, extract it.
 
-### 3. DEAD CODE — Remove What Is Not Called
+### 2. DEAD CODE -- Remove What Is Not Called
 
 - Delete unused imports, variables, functions, and parameters
 - Remove commented-out code blocks (version control is the archive)
 - Strip unreachable branches and impossible conditions
-- Drop feature flags and configuration for features that no longer exist
+- Drop feature flags for features that no longer exist
 
-### 4. COMPLEXITY — Question Every Abstraction
+### 3. COMPLEXITY -- Question Every Abstraction
 
 - Does every wrapper, adapter, or indirection layer justify its existence?
 - Are there generics or parametrization that serve only one concrete case?
@@ -58,86 +41,50 @@ Do NOT use this skill when:
 
 **If removing it does not break anything, it should not be there.**
 
-### 5. CLARITY — Tighten Naming and Structure
+### 4. NAMING -- Tighten Clarity
 
 - Are names self-documenting? Rename anything that needs a comment to explain.
 - Could nested logic be flattened with early returns?
 - Is control flow straightforward, or does it require tracing to understand?
-- Are there layers of indirection that obscure the data path?
-
-### 6. REVIEW — Final Sanity Check
-
-- Re-read the simplified code end to end
-- Confirm all tests still pass
-- Verify no behavioral changes were introduced (simplify, do not alter)
-
-## Parallel 3-Reviewer Pattern
-
-When invoked as part of the execute-phase cycle, simplification runs as three parallel review agents, each focused on one dimension.
 
-### Reviewer 1: Code Reuse
-
-- Scan all changed files for duplicated patterns
-- Cross-reference against existing shared utilities and helpers
-- Flag any logic that appears three or more times without extraction
-- **Output**: List of reuse opportunities with file paths and line ranges
-
-### Reviewer 2: Code Quality
-
-- Check for dead code: unused imports, unreachable branches, commented blocks
-- Verify naming consistency with codebase conventions
-- Flag unnecessary abstractions, wrappers, and indirection
-- **Output**: List of quality issues categorized by severity
-
-### Reviewer 3: Efficiency
+## Process
 
-- Identify over-engineered solutions (parametrization serving one case, generic interfaces with one implementor)
-- Flag defensive programming that guards impossible conditions
-- Check for configuration and feature flags that serve no current purpose
-- **Output**: List of efficiency issues with suggested removals
+1. **DIFF** -- Collect the set of modified and added files. Read each file in full, not just changed hunks.
+2. **SCAN** -- Check each dimension (duplication, dead code, complexity, naming) against each file.
+3. **RECORD** -- Document findings with file path, line range, dimension, and suggested fix.
+4. **FIX** -- Apply fixes for all actionable items. Blocker and High priority first.
+5. **VERIFY** -- Re-run tests to confirm nothing broke. Simplify, do not alter behavior.
 
-### Consolidation
+## Output Format
 
-After all three reviewers complete:
-1. Merge findings into a deduplicated list
-2. Apply fixes for all actionable items (BLOCKER and HIGH priority first)
-3. Re-run tests to confirm nothing broke
-4. Report status: CLEAN (nothing found), FIXED (issues resolved), or BLOCKED (cannot simplify without architectural changes)
+```
+DIMENSION: [Duplication | Dead Code | Complexity | Naming]
+FILE: [path]
+FINDING: [description]
+SEVERITY: [Blocker | High | Medium]
+FIX: [what was done or recommended]
+```
 
-## Common Rationalizations — REJECT THESE
+## Common Rationalizations -- Reject These
 
-| Excuse | Why It Violates the Rule |
-|--------|--------------------------|
+| Excuse | Why It Fails |
+|--------|-------------|
 | "It might be needed later" | Delete it. Re-adding is cheaper than maintaining unused code. |
-| "The abstraction makes it extensible" | Extensibility that serves no current requirement is dead weight. |
+| "The abstraction makes it extensible" | Extensibility serving no current requirement is dead weight. |
 | "Refactoring is risky" | Small, tested simplifications reduce risk. Accumulated complexity increases it. |
 | "I'll clean it up later" | Later never comes. Simplify now while context is fresh. |
 
-## Red Flags — STOP If You Catch Yourself:
-
-- Skipping the simplification pass because the diff is small
-- Keeping dead code "just in case"
-- Adding complexity during a simplification pass
-- Merging without having read the full file (not just changed lines)
+Stop if you catch yourself skipping the simplification pass because the diff is small, keeping dead code "just in case", or adding complexity during a simplification pass.
 
-**If any red flag triggers: STOP. Complete the simplification cycle before proceeding.**
+## Verification
 
-## Verification Checklist
+Before reporting completion:
 
-Before reporting completion, confirm:
-
-- [ ] All changed files were reviewed in full (not just diffs)
+- [ ] All changed files reviewed in full (not just diffs)
 - [ ] No duplicated logic remains that appears three or more times
 - [ ] No dead code: unused imports, commented blocks, unreachable branches
 - [ ] No unnecessary abstractions, wrappers, or indirection layers
 - [ ] All tests pass after simplification
-- [ ] No behavioral changes were introduced (simplify only, do not alter)
-
-## MAXSIM Integration
+- [ ] No behavioral changes introduced (simplify only, do not alter)
 
-When a plan specifies `skill: "maxsim-simplify"`:
-- The orchestrator collects changed files from the implementation step
-- Three parallel reviewers (Reuse, Quality, Efficiency) are spawned
-- Findings are consolidated and fixes applied
-- Progress is tracked in STATE.md via decision entries
-- Final results are recorded in SUMMARY.md
+See also: `/code-review` for correctness review (security, interfaces, error handling, test coverage).

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

@@ -1,19 +1,17 @@
 ---
 name: memory-management
-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."
+description: >-
+  Pattern and error persistence across sessions. Defines what to persist, where
+  to store it, and when to capture. Use when encountering recurring patterns,
+  solving non-trivial problems, making architectural decisions, or discovering
+  environment-specific behaviors.
 ---
 
 # Memory Management
 
 Context dies with each session. Patterns discovered but not saved are patterns lost.
 
-**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.
-
-## Process
-
-### 1. Detect -- Recognize Save Triggers
-
-Save immediately when any of these occur:
+## What to Persist
 
 | Trigger | Threshold | What to Save |
 |---------|-----------|-------------|
@@ -24,87 +22,54 @@ Save immediately when any of these occur:
 | 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, information already in CLAUDE.md, speculative conclusions, temporary workarounds, or obvious patterns.
-
-### 2. Check -- Avoid Duplicates
+**Do NOT save:** Session-specific context, information already in CLAUDE.md, speculative conclusions, temporary workarounds, or obvious patterns.
 
-- 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
+## Where to Store
 
-### 3. Write -- Persist the Memory
+| Location | Content | When Loaded |
+|----------|---------|-------------|
+| STATE.md | Project-level decisions, blockers, metrics | Every MAXSIM session |
+| CLAUDE.md | Project conventions, build commands, architecture | Every Claude Code session |
+| LESSONS.md | Cross-session codebase-specific lessons | MAXSIM execution startup |
 
-Add to the appropriate topic file using this entry format:
+### Entry Format
 
 ```markdown
-## [Short descriptive title]
-
-**Context:** When this applies
-**Pattern/Error:** What was observed
-**Solution/Decision:** What to do about it
-**Evidence:** How this was confirmed (dates, occurrences, test results)
+- [YYYY-MM-DD] [{phase}-{plan}] {actionable lesson}
 ```
 
-### 4. Verify -- Confirm the Save
+For LESSONS.md entries. For STATE.md decisions, use the `state add-decision` tool.
 
-- Re-read the file to confirm the entry was written correctly
-- Ensure the entry is actionable (someone reading it can act on it immediately)
+## When to Persist
 
-## File Organization
+Persist at natural breakpoints:
 
-Memory files live in `.claude/memory/` (or the equivalent runtime memory directory).
-
-```
-.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
-```
-
-- **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
+- After resolving a non-trivial bug (save error pattern + fix)
+- After making an architectural decision (save decision + rationale)
+- After discovering a recurring pattern (save pattern + when to apply)
+- At checkpoints (save current understanding before context resets)
+- At session end (review what was learned, save anything missed)
 
 ## Error Escalation
 
 ```
 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
+Error seen twice    -- Save to LESSONS.md with pattern and fix
+Error seen 3+ times -- Save AND add to CLAUDE.md for immediate visibility
 ```
 
+## Process
+
+1. **DETECT** -- Recognize a save trigger from the table above
+2. **CHECK** -- Read existing memory files before writing to avoid duplicates
+3. **WRITE** -- Add the entry to the appropriate file
+4. **VERIFY** -- Re-read the file to confirm the entry was written correctly and is actionable
+
 ## Common Pitfalls
 
 - 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 of these occur: stop, write the memory entry now, then continue.
-
-## Verification
-
-Before ending a work session:
-
-- [ ] All errors encountered 2+ times are saved to `errors.md`
-- [ ] All significant decisions are saved to `architecture.md`
-- [ ] All discovered patterns are saved to `patterns.md`
-- [ ] MEMORY.md index is up to date
-- [ ] No duplicate entries were created
-- [ ] All entries follow the format (Context, Pattern, Solution, Evidence)
-
-## MAXSIM Integration
-
-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
-
-Memory persistence happens at natural breakpoints:
-- After resolving a bug (save to errors.md)
-- After completing a phase (save patterns discovered)
-- After making an architectural decision (save to architecture.md)
-- At checkpoints (save current understanding before context resets)

package/dist/assets/templates/skills/research-methodology/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: research-methodology
+description: >-
+  Research process with tool priorities, confidence levels, and source evaluation.
+  Defines how to investigate technical domains, evaluate sources, and structure
+  findings with confidence tags. Use when researching libraries, APIs, architecture
+  patterns, or any domain requiring external knowledge gathering.
+user-invocable: false
+---
+
+# Research Methodology
+
+Systematic process for investigating technical domains and producing structured findings with confidence levels.
+
+## Research Process
+
+### 1. Define Questions
+
+Before researching, write explicit questions:
+
+- What specific information do I need?
+- What decisions will this research inform?
+- What would change my approach if I learned X vs Y?
+
+Avoid open-ended exploration. Each question should have a clear "answered" state.
+
+### 2. Identify Sources
+
+Use this priority order for source selection:
+
+| Priority | Source Type | Tool | Best For |
+|----------|-----------|------|----------|
+| 1 | Official documentation | WebFetch | API specs, config options, platform features |
+| 2 | Codebase (existing code) | Grep, Glob, Read | Current patterns, conventions, dependencies |
+| 3 | CLI tool help | Bash (`--help`, `--version`) | Tool capabilities, available flags |
+| 4 | Package registries | WebFetch (npm, PyPI) | Version info, dependency trees |
+| 5 | Reputable technical blogs | WebFetch | Architecture patterns, best practices |
+| 6 | Community forums | WebFetch | Edge cases, workarounds, known issues |
+
+### 3. Evaluate Sources
+
+Not all sources are equal. Tag each finding with a confidence level:
+
+| Level | Criteria | Examples |
+|-------|----------|---------|
+| **HIGH** | Official docs, verified by tool output, multiple primary sources agree | Platform docs, API reference, confirmed by running code |
+| **MEDIUM** | Reputable blogs, community consensus, single primary source | Well-known tech blogs, Stack Overflow accepted answers, conference talks |
+| **LOW** | Single non-official source, outdated (>1 year), unverified claims | Personal blogs, forum posts, AI-generated content without verification |
+
+**Source evaluation checklist:**
+- Is this a primary source (official docs) or secondary (blog post)?
+- When was it published or last updated?
+- Does it match what I see in the actual codebase/tool?
+- Do multiple independent sources agree?
+
+### 4. Cross-Reference Claims
+
+For any finding that influences architecture or design:
+
+- Find at least 2 independent sources
+- Verify against actual tool behavior (run a command, read a config)
+- Note when sources disagree and which you trust more
+- Mark single-source findings as LOW confidence
+
+### 5. Structure Output
+
+Research findings follow this format:
+
+```markdown
+## Finding: [Title]
+
+**Confidence:** HIGH | MEDIUM | LOW
+**Sources:** [list of sources with links]
+
+[Finding description -- what was learned]
+
+**Implications:** [How this affects our decisions]
+**Open questions:** [What remains unclear]
+```
+
+## Research Output Template
+
+```markdown
+# [Domain] Research
+
+**Researched:** [date]
+**Confidence:** [overall confidence level]
+
+## Key Findings
+- [Finding 1] (HIGH confidence)
+- [Finding 2] (MEDIUM confidence)
+
+## Standard Stack
+| Component | Choice | Why |
+|-----------|--------|-----|
+| [area] | [choice] | [reason] |
+
+## Don't Hand-Roll
+| Problem | Don't Build | Use Instead |
+|---------|-------------|-------------|
+| [problem] | [custom solution] | [existing solution] |
+
+## Common Pitfalls
+### Pitfall 1: [name]
+**What goes wrong:** [description]
+**How to avoid:** [recommendation]
+
+## Open Questions
+- [Unanswered questions for future investigation]
+
+## Sources
+### Primary (HIGH confidence)
+- [source with link]
+### Secondary (MEDIUM confidence)
+- [source with link]
+```
+
+## Common Research Mistakes
+
+| Mistake | Why It's Wrong | Do Instead |
+|---------|---------------|------------|
+| Using only AI knowledge | May be outdated or hallucinated | Fetch actual docs with WebFetch |
+| Trusting a single blog post | Could be wrong, outdated, or opinionated | Cross-reference with official docs |
+| Skipping version checks | APIs change between versions | Verify against the actual version in use |
+| Assuming current codebase is correct | Code may have bugs or outdated patterns | Verify patterns against official docs |
+| Not recording sources | Cannot verify or update findings later | Always include links and dates |
+| Research without questions | Leads to unfocused exploration | Define questions first, research to answer them |
+
+## Time Boxing
+
+Research is a means to an end, not the end itself:
+
+- **Quick lookup** (5 min): Single question, check official docs, done
+- **Standard research** (30 min): Multiple questions, cross-reference, structured output
+- **Deep investigation** (60 min): Architecture decision, multiple domains, full template
+
+If you cannot answer a question within the time box, document it as an open question and move on.