maxsimcli 5.0.6 → 5.1.0

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

@@ -1,10 +1,6 @@
 ---
 name: maxsim-simplify
-description: >-
-  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.
+description: Reviews changed code for reuse opportunities, quality issues, and efficiency improvements, then fixes actionable items. Use after implementing features or when code feels over-engineered.
 ---
 
 # Simplify
@@ -15,57 +11,83 @@ Every line of code is a liability. Remove what does not earn its place.
 
 Only simplify touched files unless explicitly asked for broader refactoring. The goal is incremental maintainability improvement, not a codebase-wide rewrite.
 
-## Dimensions
+---
+
+## 3-Pass Review
+
+### Pass 1 — Reuse
 
-### 1. DUPLICATION -- Eliminate Repeated Logic
+Identify duplication and missed opportunities to use existing code.
 
-- Are there patterns repeated across files that should be a shared helper?
+- Are there patterns repeated across files that belong in a shared helper?
 - Does new code duplicate existing utilities or library functions?
 - Could two similar implementations be merged behind a single interface?
+- Are there inline blocks that match patterns already extracted elsewhere?
 
-**Rule of three:** If the same pattern appears three times, extract it.
+**Rule of three:** If the same pattern appears three or more times, extract it.
 
-### 2. DEAD CODE -- Remove What Is Not Called
+### Pass 2 — Quality
 
-- 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 for features that no longer exist
+Identify naming, complexity, and error handling problems.
 
-### 3. COMPLEXITY -- Question Every Abstraction
+- Are names self-documenting? Rename anything that requires a comment to explain.
+- Does every abstraction, wrapper, or indirection layer justify its existence?
+- Is there dead code: unused imports, commented-out blocks, unreachable branches?
+- Are feature flags still needed, or do they guard features that no longer exist?
+- Is error handling present and consistent, or are errors silently swallowed?
+- Could nested logic be flattened with early returns?
 
-- Does every wrapper, adapter, or indirection layer justify its existence?
-- Are there generics or parametrization that serve only one concrete case?
-- Could a 20-line class be replaced by a 3-line function?
-- Is there defensive programming that guards against conditions that cannot occur?
+**If removing something does not break anything, it should not be there.**
 
-**If removing it does not break anything, it should not be there.**
+### Pass 3 — Efficiency
 
-### 4. NAMING -- Tighten Clarity
+Identify unnecessary work, missing caching, and query patterns that scale poorly.
 
-- 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 operations repeated in a loop that could run once outside it?
+- Is data fetched that is never used?
+- Are there N+1 query patterns (fetching inside a loop that iterates over results)?
+- Could expensive computations be memoized or cached?
+- Are synchronous operations blocking where async would suffice?
+
+---
+
+## Priority Levels
+
+| Priority | Description | Action |
+|----------|-------------|--------|
+| Blocker | Incorrect behavior, data loss risk, or broken error handling introduced by the change | Fix immediately |
+| High | Significant duplication, N+1 queries, or complexity that will compound | Fix in this pass |
+| Medium | Naming issues, minor inefficiencies, single-use abstractions | File as follow-up issue |
+| Low | Style preferences, marginal improvements | Note only, do not act |
+
+Apply fixes for Blocker and High priority items in the current pass. File Medium and Low items as GitHub Issues for follow-up, labelled `maxsim:simplify`.
+
+---
 
 ## Process
 
-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.
+1. **Diff** — Collect the set of modified and added files. Read each file in full, not just the changed hunks.
+2. **Scan** — Run all three passes (Reuse, Quality, Efficiency) against each file.
+3. **Record** — Document each finding using the output format below.
+4. **Fix** — Apply all Blocker and High fixes. Do not alter behavior — simplify only.
+5. **Verify** — Re-run tests. Confirm all tests pass before reporting completion.
+
+---
 
 ## Output Format
 
 ```
-DIMENSION: [Duplication | Dead Code | Complexity | Naming]
-FILE: [path]
-FINDING: [description]
-SEVERITY: [Blocker | High | Medium]
-FIX: [what was done or recommended]
+PASS: [Reuse | Quality | Efficiency]
+FILE: <path>
+LINE: <range>
+FINDING: <description>
+PRIORITY: [Blocker | High | Medium | Low]
+FIX: <what was applied or recommended>
 ```
 
-## Common Rationalizations -- Reject These
+---
+
+## Common Rationalizations — Reject These
 
 | Excuse | Why It Fails |
 |--------|-------------|
@@ -73,18 +95,21 @@ FIX: [what was done or recommended]
 | "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. |
+| "The diff is small, not worth reviewing" | Small diffs introduce the most insidious problems. |
 
-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.
+---
 
-## Verification
+## Verification Checklist
 
 Before reporting completion:
 
 - [ ] All changed files reviewed in full (not just diffs)
-- [ ] No duplicated logic remains that appears three or more times
+- [ ] No duplicated logic that appears three or more times
 - [ ] No dead code: unused imports, commented blocks, unreachable branches
 - [ ] No unnecessary abstractions, wrappers, or indirection layers
+- [ ] Error handling present and consistent in all changed paths
+- [ ] No N+1 queries or repeated expensive operations in loops
 - [ ] All tests pass after simplification
-- [ ] No behavioral changes introduced (simplify only, do not alter)
+- [ ] No behavioral changes introduced
 
-See also: `/code-review` for correctness review (security, interfaces, error handling, test coverage).
+See also: `/code-review` for correctness review covering security, interfaces, and test coverage.

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

@@ -0,0 +1,121 @@
+---
+name: project-memory
+description: GitHub-native persistence for project learnings, decisions, and patterns using issue labels and structured comments. Use when recording what worked, what failed, or architectural decisions that should persist across sessions.
+---
+
+# Project Memory Skill
+
+Claude Code sessions are stateless. This skill uses GitHub Issues as a persistent, searchable memory store so that learnings, decisions, and patterns survive across sessions and agents.
+
+---
+
+## What to Persist
+
+Not everything is worth recording. Persist only information that would change behaviour in a future session.
+
+**Persist:**
+- Successful patterns discovered during implementation (things that worked and why)
+- Failed approaches and the reason they failed (prevents re-trying dead ends)
+- Performance insights with measured baselines (e.g., "query X takes 800ms without index Y")
+- Architectural decisions and the trade-offs considered
+- Non-obvious constraints (environment limits, API quirks, team conventions not in docs)
+
+**Do not persist:**
+- Transient debug output
+- Work-in-progress notes
+- Information already captured in code comments or documentation
+
+---
+
+## Storage: GitHub Issues
+
+All project memory lives as GitHub Issues in the project repository. Two labels are used:
+
+| Label | Purpose |
+|-------|---------|
+| `maxsim:lesson` | Something learned — what worked or what failed |
+| `maxsim:decision` | An architectural or design decision and its rationale |
+
+Create issues with `gh issue create`. Query them with `gh issue list --label maxsim:lesson`.
+
+---
+
+## Lesson Issue Format
+
+```
+Title: LESSON: <short description of what was learned>
+
+## What Happened
+<1–3 sentences describing the situation>
+
+## What Worked / What Failed
+<specific outcome>
+
+## Why
+<root cause or reason, if known>
+
+## Applies To
+<file paths, modules, or domains this lesson is relevant to>
+
+## Confidence
+[HIGH|MEDIUM|LOW]
+```
+
+---
+
+## Decision Issue Format
+
+```
+Title: DECISION: <short description of the decision>
+
+## Context
+<what problem prompted this decision>
+
+## Decision
+<what was decided>
+
+## Alternatives Considered
+- <option A> — rejected because <reason>
+- <option B> — rejected because <reason>
+
+## Trade-offs Accepted
+<what is worse as a result of this decision>
+
+## Revisit When
+<condition that should trigger re-evaluation>
+```
+
+---
+
+## When to Create a Memory Issue
+
+| Trigger | Action |
+|---------|--------|
+| Phase completion | Create a lesson issue summarising what worked and what did not |
+| 3 or more retries on the same problem | Create a lesson issue before attempting again |
+| A pattern is discovered that could apply elsewhere | Create a lesson issue tagged with relevant modules |
+| A significant architectural choice is made | Create a decision issue immediately |
+| An approach is abandoned mid-phase | Create a lesson issue explaining why |
+
+---
+
+## Git as Memory
+
+At the start of a session working on an existing project, read recent git history before planning:
+
+```bash
+git log --oneline -20
+git log --oneline --since="7 days ago"
+```
+
+This surfaces what changed recently without opening every file. Combine with `gh issue list --label maxsim:lesson` to get both code history and recorded learnings.
+
+---
+
+## Claude Code Memory Integration
+
+When operating as a sub-agent within a MaxsimCLI workflow, scope memory to the project:
+
+- Read existing lesson and decision issues at session start before beginning research or planning
+- Write new issues at session end or at phase boundaries, not mid-task
+- Reference issue numbers in commit messages when a commit directly relates to a recorded decision (e.g., `closes #42` or `see DECISION #38`)

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

@@ -0,0 +1,126 @@
+---
+name: research
+description: Systematic investigation using parallel agents, source hierarchy, and Claude Code tool priority. Merges research methodology with tool selection best practices. Use when investigating codebase patterns, evaluating libraries, or gathering information before planning.
+---
+
+# Research Skill
+
+Produces reliable, structured findings before planning or implementation begins. Combines investigation methodology with the right tool choices to avoid wasted effort.
+
+---
+
+## 5-Step Research Process
+
+### Step 1 — Define Questions
+
+Before searching anything, write down the specific questions this research must answer. Vague investigations produce vague results.
+
+- One question per line
+- Mark each as: factual (has a definite answer) or evaluative (requires judgment)
+- Set a confidence threshold: what level of certainty is required before acting?
+
+### Step 2 — Identify Sources
+
+Map each question to its best source before opening any file.
+
+**Source hierarchy (highest to lowest trust):**
+
+1. Official documentation and specs
+2. Source code and type definitions in the repo
+3. Tests and usage examples in the codebase
+4. Changelogs and release notes
+5. Community discussions (Stack Overflow, GitHub issues)
+6. Blog posts and tutorials
+
+Always prefer sources higher in the hierarchy. Do not cite a tutorial when the source code is available.
+
+### Step 3 — Gather Evidence
+
+Use the correct tool for each task. Using the wrong tool produces slower or incomplete results.
+
+**Claude Code Tool Priority:**
+
+| Task | Use | Never Use |
+|------|-----|-----------|
+| Read a known file path | `Read` | `cat`, `head`, `tail` |
+| Search file contents | `Grep` | `grep`, `rg` in Bash |
+| Find files by name/pattern | `Glob` | `find`, `ls` |
+| Multi-step investigation across many files | `Agent` | Sequential Bash loops |
+| Single shell command or script | `Bash` | — |
+
+**Parallelise where possible.** When multiple files or sources are independent, read or search them in the same tool call batch rather than sequentially.
+
+**Time-box each source:** If a source has not yielded useful signal within 10 minutes of investigation, move on and flag it as inconclusive.
+
+### Step 4 — Cross-Reference
+
+Do not trust a single source. For any finding that will influence a decision:
+
+- Confirm in at least two independent sources
+- Note where sources disagree and record both positions
+- Flag anything that changed recently (check git log or changelog dates)
+
+### Step 5 — Structure Output
+
+Findings must be in a form that another agent or a human can act on without re-reading all the evidence.
+
+---
+
+## Confidence Tags
+
+Attach one tag to every finding:
+
+- `[HIGH]` — confirmed in authoritative source, cross-referenced
+- `[MEDIUM]` — single source, plausible but not verified
+- `[LOW]` — inferred or community-sourced, treat as hypothesis
+
+Never promote a `[LOW]` finding to a decision without additional verification.
+
+---
+
+## Structured Output Template
+
+```
+## Research: <topic>
+
+### Questions
+1. <question> — <factual|evaluative>
+
+### Findings
+1. <finding> [HIGH|MEDIUM|LOW]
+   Source: <file path or URL>
+   Evidence: <quote or line reference>
+
+### Conflicts
+- <source A> says X; <source B> says Y — reason for conflict unknown / likely due to <version>
+
+### Open Questions
+- <anything still unresolved>
+
+### Recommendation
+<one paragraph — what should happen next based on these findings>
+```
+
+---
+
+## Time-Boxing Rules
+
+| Research scope | Max time before checkpoint |
+|---------------|---------------------------|
+| Single function or file | 15 minutes |
+| Single module or package | 30 minutes |
+| Cross-repo or library evaluation | 60 minutes |
+
+If the time limit is reached, produce a partial output using the template above and flag it as incomplete. Do not continue without surfacing findings.
+
+---
+
+## When to Use Parallel Agents
+
+Spawn sub-agents when:
+
+- Investigating multiple independent libraries simultaneously
+- Comparing implementations across different parts of a large codebase
+- Source gathering and source evaluation can proceed concurrently
+
+Do not spawn agents for tasks that are inherently sequential (e.g., reading a file whose path depends on the output of a previous search).

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

@@ -1,10 +1,6 @@
 ---
 name: roadmap-writing
-description: >-
-  Phased planning with dependency graphs, success criteria, and requirement
-  mapping. Produces roadmaps with observable truths as success criteria.
-  Use when creating project roadmaps, breaking features into phases, or
-  structuring multi-phase work.
+description: Creates phased project roadmaps with dependency graphs, success criteria, and GitHub Milestone structure. Use when planning new projects, creating milestones, or breaking work into phases.
 ---
 
 # Roadmap Writing
@@ -13,92 +9,106 @@ A roadmap without success criteria is a wish list. Define what done looks like f
 
 ## Process
 
-### 1. SCOPE -- Understand the Project
+### 1. SCOPE — Understand the Project
 
 Before writing phases:
 
-- Read PROJECT.md for vision and constraints
-- Read REQUIREMENTS.md for v1/v2/out-of-scope boundaries
-- Check existing STATE.md for decisions and blockers
-- Identify the delivery target (MVP, v1, v2, etc.)
+- Identify the delivery target: MVP, v1, v2, specific feature set.
+- Clarify constraints: timeline, team size, known blockers.
+- Gather existing requirements or acceptance criteria.
+- Ask ONE clarifying question at a time if the scope is unclear.
 
-### 2. DECOMPOSE -- Break Into Phases
+### 2. DECOMPOSE — Break Into Phases
 
-Each phase should be:
+Each phase must be:
 
 | Property | Requirement |
-|----------|------------|
+|----------|-------------|
 | **Independently deliverable** | 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 |
+| **1–3 days of work** | Larger phases should be split; smaller ones should be merged |
+| **Clear boundary** | Determinable when done without ambiguity |
 | **Ordered by dependency** | No phase depends on a later phase |
 
 Phase numbering convention:
 
 | Format | When to Use |
-|--------|------------|
+|--------|-------------|
 | `01`, `02`, `03` | Standard sequential phases |
-| `01A`, `01B` | Parallel sub-phases that can execute concurrently |
+| `01A`, `01B` | Parallel sub-phases that can execute concurrently (same wave) |
 | `01.1`, `01.2` | Sequential sub-phases within a parent phase |
 
-### 3. DEFINE -- Write Each Phase
+### 3. DEFINE — Write Each Phase
 
 Every phase must include:
 
 ```markdown
-### Phase {number}: {name}
-**Goal**: {one sentence -- what this phase achieves}
+### Phase {N}: {name}
+**Goal**: {one sentence — what this phase achieves}
 **Depends on**: {phase numbers, or "Nothing" for the first phase}
-**Requirements**: {requirement IDs from REQUIREMENTS.md}
-**Success Criteria** (what must be TRUE):
-  1. {Observable truth -- verifiable by command, test, or inspection}
+**Wave**: {wave number for parallel execution planning}
+**Success Criteria** (what must be TRUE when this phase is done):
+  1. {Observable truth — verifiable by command, test, or inspection}
   2. {Observable truth}
-**Plans**: TBD
 ```
 
 Success criteria rules:
-- Each criterion must be testable -- "code is clean" is not testable; "no lint warnings" is testable
-- Include at least 2 criteria per phase
-- At least one criterion should be verifiable by running a command
-- Criteria describe the end state, not the process ("tests pass" not "write tests")
+- Each criterion must be testable — "code is clean" fails; "no lint warnings on `npm run lint`" passes.
+- At least 2 criteria per phase.
+- At least one criterion verifiable by running a command.
+- Criteria describe the end state, not the process ("tests pass" not "write tests").
 
-### 4. CONNECT -- Map Dependencies
+### 4. CONNECT — Map Dependencies and Waves
 
-- 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)
-- Every phase except the first must declare at least one dependency
+- Which phases can run in parallel? Assign the same wave number.
+- Which phases are strictly sequential? Use incrementing wave numbers.
+- Check for circular dependencies — this is a design error. Restructure if found.
+- Every phase except the first must declare at least one dependency.
 
-### 5. MAP REQUIREMENTS -- Ensure Coverage
+Wave assignment example:
 
-Every requirement ID from REQUIREMENTS.md must appear in at least one phase. Produce a coverage map:
+| Wave | Phases | Notes |
+|------|--------|-------|
+| 1 | 01 | Foundation — nothing depends on nothing |
+| 2 | 02A, 02B | Parallel — both depend on Phase 01 |
+| 3 | 03 | Depends on both 02A and 02B |
 
-```
-REQUIREMENT-ID -> Phase N
-```
+### 5. GITHUB MILESTONE STRUCTURE
 
-If any requirement is unmapped, either add it to a phase or explicitly mark it as out-of-scope.
+All roadmap artifacts live in GitHub — not in local planning files.
 
-### 6. MILESTONE -- Group Into Milestones
-
-Group phases into milestones that represent user-visible releases:
+**Milestones** map to user-visible releases:
 
 ```markdown
 ## Milestones
-- **v1.0 MVP** -- Phases 1-4
-- **v1.1 Polish** -- Phases 5-7
+- **v1.0 MVP** — Phases 01–04
+- **v1.1 Polish** — Phases 05–07
+```
+
+**GitHub Issue format** for each phase:
+
+```markdown
+Title: [Phase {N}] {Phase name}
+Body:
+**Goal**: {one sentence}
+**Depends on**: #{issue numbers}
+**Wave**: {number}
+**Success Criteria**:
+- [ ] {criterion 1}
+- [ ] {criterion 2}
 ```
 
-### 7. VALIDATE -- Check the Roadmap
+Assign each issue to the corresponding GitHub Milestone. Use issue references (`#N`) for dependency tracking, not free-form text.
+
+### 6. VALIDATE — Check the Roadmap
 
 | 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 |
-| Requirements are covered | Every requirement ID maps to at least one phase |
+| Success criteria are testable | Each criterion verifiable by command, test, or inspection |
+| Wave assignments are consistent | Parallel phases share a wave; sequential phases do not |
 
 ## Roadmap Format
 
@@ -106,25 +116,23 @@ Group phases into milestones that represent user-visible releases:
 # Roadmap: {project name}
 
 ## Overview
-{2-3 sentences: what the project is, what this roadmap covers}
+{2–3 sentences: what the project is, what this roadmap covers}
 
 ## Milestones
-- **{milestone name}** -- Phases {range} ({status})
+- **{milestone name}** — Phases {range}
 
-## Phases
-- [ ] **Phase {N}: {name}** - {one-line summary}
+## Phase Index
+- [ ] **Phase {N}: {name}** — {one-line summary} (Wave {W})
 
 ## Phase Details
+
 ### Phase {N}: {name}
 **Goal**: ...
 **Depends on**: ...
-**Requirements**: ...
+**Wave**: ...
 **Success Criteria** (what must be TRUE):
   1. ...
-**Plans**: TBD
-
-## Coverage Map
-REQUIREMENT-ID -> Phase N
+  2. ...
 ```
 
 ## Common Pitfalls
@@ -132,15 +140,10 @@ REQUIREMENT-ID -> Phase N
 | Pitfall | Why It Fails |
 |---------|-------------|
 | "We don't know enough to plan" | Plan what you know. Unknown phases get a research spike first. |
-| "Success criteria are too rigid" | Vague criteria are useless. Rigid criteria are adjustable. |
+| "Success criteria are too rigid" | Vague criteria are useless. Rigid criteria are adjustable. Update them when scope changes. |
 | "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. |
-
-Stop if you catch yourself writing a phase without success criteria, creating phases longer than 3 days of work, skipping dependency declarations, or writing vague criteria like "code is good".
-
-## MAXSIM Integration
+| "Dependencies are obvious" | Obvious to you now. Not obvious three weeks from now. |
+| "We'll add details later" | Later never comes. Write the details while context is fresh. |
+| "I'll track this in a local file" | Everything goes to GitHub. Local planning files do not survive context resets. |
 
-- The roadmap is read by MAXSIM agents via `roadmap read` -- format compliance is mandatory
-- Phase numbering must be parseable by `normalizePhaseName()` and `comparePhaseNum()`
-- Config `model_profile` in `.planning/config.json` affects agent assignment per phase
+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 storing roadmap data outside of GitHub.