maxsimcli 5.0.6 → 5.1.0

package/dist/assets/templates/references/continuation-format.md

@@ -52,7 +52,7 @@ Standard format for presenting next steps after completing a command or workflow
 
 **Also available:**
 - Review plan before executing
-- `/maxsim:plan --review 2` — check assumptions
+- `/maxsim:plan 2` — review and adjust assumptions
 
 ---
 ```
@@ -99,7 +99,6 @@ Add note that this is the last plan and what comes after:
 
 **Also available:**
 - `/maxsim:plan 2` — gather context first
-- `/maxsim:plan --research 2` — investigate unknowns
 - Review roadmap
 
 ---
@@ -128,7 +127,6 @@ Show completion status before next action:
 
 **Also available:**
 - `/maxsim:plan 3` — gather context first
-- `/maxsim:plan --research 3` — investigate unknowns
 - Review what Phase 2 built
 
 ---
@@ -149,7 +147,7 @@ When there's no clear primary action:
 
 **To discuss context first:** `/maxsim:plan 3`
 
-**To research unknowns:** `/maxsim:plan --research 3`
+**To research unknowns:** `/maxsim:plan 3`
 
 <sub>`/clear` first → fresh context window</sub>
 

package/dist/assets/templates/references/model-profiles.md

@@ -34,7 +34,7 @@ Model profiles control which Claude model each MAXSIM agent uses. This allows ba
 Orchestrators resolve model before spawning:
 
 ```
-1. Read .planning/config.json
+1. Read maxsim config (via maxsim-tools.cjs state load)
 2. Check model_overrides for agent-specific override
 3. If no override, look up agent in profile table
 4. Pass model parameter to Task call
@@ -60,7 +60,7 @@ Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `hai
 
 Runtime: `/maxsim:settings` (change profile)
 
-Per-project default: Set in `.planning/config.json`:
+Per-project default: Set in `maxsim.config.json`:
 ```json
 {
   "model_profile": "balanced"

package/dist/assets/templates/references/planning-config.md

@@ -47,7 +47,7 @@ INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs state load)
 # commit_docs is available in the JSON output
 
 # Or use init commands which include commit_docs:
-INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init execute-phase "1")
+INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init execute "1")
 # commit_docs is included in all init command outputs
 ```
 
@@ -101,7 +101,7 @@ To use uncommitted mode:
    git commit -m "chore: stop tracking planning docs"
    ```
 
-4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `complete-milestone` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.
+4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, merge commits should be created manually or via git after the phase/milestone completes.
 
 </setup_uncommitted_mode>
 
@@ -112,25 +112,24 @@ To use uncommitted mode:
 | Strategy | When branch created | Branch scope | Merge point |
 |----------|---------------------|--------------|-------------|
 | `none` | Never | N/A | N/A |
-| `phase` | At `execute-phase` start | Single phase | User merges after phase |
-| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `complete-milestone` |
+| `phase` | At `execute` start | Single phase | User merges after phase |
+| `milestone` | At first `execute` of milestone | Entire milestone | User merges after milestone |
 
 **When `git.branching_strategy: "none"` (default):**
 - All work commits to current branch
 - Standard MAXSIM behavior
 
 **When `git.branching_strategy: "phase"`:**
-- `execute-phase` creates/switches to a branch before execution
+- `execute` creates/switches to a branch before execution
 - Branch name from `phase_branch_template` (e.g., `maxsim/phase-03-authentication`)
 - All plan commits go to that branch
 - User merges branches manually after phase completion
-- `complete-milestone` offers to merge all phase branches
 
 **When `git.branching_strategy: "milestone"`:**
-- First `execute-phase` of milestone creates the milestone branch
+- First `execute` of milestone creates the milestone branch
 - Branch name from `milestone_branch_template` (e.g., `maxsim/v1.0-mvp`)
 - All phases in milestone commit to same branch
-- `complete-milestone` offers to merge milestone branch to main
+- User merges milestone branch to main when complete
 
 **Template variables:**
 
@@ -142,9 +141,9 @@ To use uncommitted mode:
 
 **Checking the config:**
 
-Use `init execute-phase` which returns all config as JSON:
+Use `init execute` which returns all config as JSON:
 ```bash
-INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init execute-phase "1")
+INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init execute "1")
 # JSON output includes: branching_strategy, phase_branch_template, milestone_branch_template
 ```
 
@@ -172,7 +171,7 @@ if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
 fi
 ```
 
-**Merge options at complete-milestone:**
+**Merge options when completing a milestone:**
 
 | Option | Git command | Result |
 |--------|-------------|--------|

package/dist/assets/templates/references/self-improvement.md

@@ -0,0 +1,120 @@
+# Self-Improvement System
+
+MaxsimCLI v6 introduces an autoresearch-inspired feedback loop that lets the agent
+learn from previous sessions rather than starting cold every time.
+
+---
+
+## 1. Git-as-Memory
+
+At the start of each session the agent reads recent history directly from the repo:
+
+```
+git log --oneline -20
+```
+
+This gives an immediate, zero-overhead summary of what changed, what was shipped,
+and which tasks were completed. No external database required.
+
+**When to use it:**
+- Orient quickly at session start before reading any other file.
+- Detect whether a previous phase was committed or abandoned.
+- Spot regressions (a feature that was added and later reverted).
+
+---
+
+## 2. Agent Memory File
+
+Persistent learnings are stored in:
+
+```
+.claude/agent-memory/maxsim-learner/MEMORY.md
+```
+
+This file is appended automatically by the `maxsim-capture-learnings` Stop hook
+at the end of every session in a MaxsimCLI project. Each entry records:
+
+- The session date and ID.
+- How many commits were made.
+- The exact commit messages (oneline format).
+
+**Reading the file at session start** lets the agent recall:
+- Which approaches worked and were committed.
+- Which tasks were attempted repeatedly without a commit (likely failed).
+- Long-term trends across many sessions.
+
+---
+
+## 3. Results Tracking
+
+Track two categories explicitly in task notes or phase plans:
+
+| Category | Definition |
+|---|---|
+| Worked | Approach produced a commit or a passing test run. |
+| Failed | Approach was retried or abandoned without a commit. |
+
+Patterns that appear in the "Worked" column three or more times should be
+promoted to templates or standard operating procedures. Patterns that appear in
+the "Failed" column should be flagged before attempting again.
+
+---
+
+## 4. Verify + Guard Pattern
+
+Every self-improvement cycle must include a guard step to prevent regression:
+
+1. **Implement** — make the change.
+2. **Verify** — run the relevant test, build, or lint command and confirm it passes.
+3. **Guard** — if verification fails, revert immediately and record the failure.
+   Do not proceed to the next task with a broken baseline.
+
+This pattern keeps the main branch always green regardless of how many
+improvement iterations run.
+
+---
+
+## 5. Bounded Iterations
+
+To avoid infinite loops on hard problems, apply strict iteration limits:
+
+- **Max 3 retries per task.** After the third failure, escalate or skip.
+- Each retry must use a meaningfully different approach — no copy-paste retries.
+- Record the approach variation in the task log so the next session can
+  distinguish them.
+
+---
+
+## 6. Stuck Detection and Recovery
+
+If the agent records **5 consecutive failures** across sessions (i.e. 5 sessions
+with no new commit on a given task), the recovery protocol activates:
+
+1. **Stop** working on the task directly.
+2. **Decompose** — break the task into smaller, verifiable sub-tasks.
+3. **Ask** — surface the blocker explicitly in the next session's opening message.
+4. **Document** — add a `## Blocked` section to MEMORY.md describing what was
+   tried and what the error state is.
+
+Stuck detection relies on scanning MEMORY.md for repeated session entries that
+reference the same task with no intervening commit.
+
+---
+
+## Hook Integration
+
+The capture-learnings hook is registered as a `Stop` event hook during
+`maxsim install`. It only writes to MEMORY.md when `.claude/maxsim/config.json`
+exists, so it is a no-op in non-MaxsimCLI projects.
+
+To inspect accumulated learnings:
+
+```
+cat .claude/agent-memory/maxsim-learner/MEMORY.md
+```
+
+To reset learnings for a fresh start:
+
+```
+rm .claude/agent-memory/maxsim-learner/MEMORY.md
+```

package/dist/assets/templates/rules/conventions.md

@@ -29,7 +29,7 @@ Co-author line when AI-assisted: `Co-Authored-By: Claude <noreply@anthropic.com>
 | Skills | `.claude/skills/<kebab-case>/SKILL.md` |
 | Agents | `.claude/agents/<simple-name>.md` |
 | Rules | `.claude/rules/<topic>.md` |
-| Plans | `.planning/phases/XX-Name/XX-NN-PLAN.md` |
+| Plans | `phases/{phase}-{name}/{phase}-{plan}-PLAN.md` |
 
 Use kebab-case for directory names. Use UPPER_CASE for protocol files (SKILL.md, PLAN.md, STATE.md).
 

package/dist/assets/templates/rules/verification-protocol.md

@@ -54,4 +54,4 @@ These phrases indicate reasoning without evidence. Replace them with a verificat
 
 ## Retry Protocol
 
-When verification fails: read the error, fix the issue, re-run the command, produce a new evidence block. Maximum 3 total attempts per gate before escalating. The `verification-gates` skill provides detailed methodology for gate types, retry feedback, and escalation.
+When verification fails: read the error, fix the issue, re-run the command, produce a new evidence block. Maximum 3 total attempts per gate before escalating. The `verification` skill provides detailed methodology for gate types, retry feedback, and escalation.

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

@@ -1,10 +1,6 @@
 ---
 name: brainstorming
-description: >-
-  Multi-approach exploration before design decisions. Generates 3+ approaches
-  with tradeoff analysis before selecting. Use when facing architectural
-  choices, library selection, design decisions, or any problem with multiple
-  viable solutions.
+description: Explores multiple implementation approaches before committing to one. Produces a structured comparison table with effort/risk assessment. Use when starting features, facing design decisions, or multiple valid approaches exist.
 ---
 
 # Brainstorming
@@ -13,7 +9,7 @@ The first idea is rarely the best idea. Explore the space before committing to a
 
 ## Process
 
-### 1. Frame the Problem
+### 1. Understand the Goal
 
 Define the problem clearly before proposing solutions:
 
@@ -22,45 +18,52 @@ Define the problem clearly before proposing solutions:
 - What has been tried or considered already?
 - What are the non-negotiables vs. nice-to-haves?
 
-Ask the user ONE question at a time. Each answer informs the next question.
+Ask one question at a time. Each answer informs the next question. Do not front-load a list of questions.
 
 ### 2. Research Context
 
 Before proposing solutions, gather evidence:
 
-- Read relevant code and check for prior decisions
-- Identify patterns already in use in the codebase
-- Check STATE.md for existing architectural decisions
+- Read relevant code and check for prior decisions in the codebase.
+- Identify patterns already in use — prefer consistency over novelty.
+- Check for existing architectural decisions that constrain the options.
 
-### 3. Present 3+ Approaches
+### 3. Generate 3+ Approaches
 
-For each approach, provide:
+Present at least three distinct approaches. For each:
 
 | Aspect | Content |
 |--------|---------|
 | **Summary** | One sentence |
-| **How it works** | 3-5 implementation bullets |
+| **How it works** | 3–5 implementation bullets |
 | **Pros** | Concrete advantages ("200 fewer lines" beats "simpler") |
-| **Cons** | Honest drawbacks -- do not hide weaknesses |
+| **Cons** | Honest drawbacks — do not hide weaknesses |
 | **Effort** | Low / Medium / High |
-| **Risk** | What could go wrong and how recoverable |
+| **Risk** | What could go wrong and how recoverable it is |
 
-If one approach is clearly superior, say so -- but still present alternatives so the user can validate your reasoning.
+If one approach is clearly superior, say so — but still present the alternatives so the reasoning can be validated.
 
-### 4. Discuss and Refine
+### 4. Compare — Produce the Summary Table
 
-- Ask which approach the user prefers or whether they want a hybrid
-- Answer follow-up questions honestly
-- If no approach fits, propose new ones informed by the discussion
-- Continue one question at a time -- do not assume consensus
+Always include a top-level comparison table before the detailed breakdowns:
 
-### 5. Get Explicit Approval
+| # | Approach | Effort | Risk |
+|---|----------|--------|------|
+| A | [one-line summary] | Low/Med/High | Low/Med/High |
+| B | [one-line summary] | Low/Med/High | Low/Med/High |
+| C | [one-line summary] | Low/Med/High | Low/Med/High |
+
+### 5. Select with Rationale
 
-The user must explicitly approve one approach (e.g., "Go with A", "Approved"). Vague responses like "Sounds good" or "Interesting" are not approval. If ambiguous, ask: "To confirm -- should I proceed with [specific approach]?"
+State which approach is recommended and why. Reference specific tradeoffs — not just "it's simpler." If no approach fits cleanly, propose a hybrid informed by the analysis.
 
 ### 6. Document the Decision
 
-Record: chosen approach, rejected alternatives with reasons, key implementation decisions, and risks.
+Record:
+- Chosen approach and rationale
+- Rejected alternatives and reasons for rejection
+- Key implementation decisions that follow from the choice
+- Known risks and mitigation plan
 
 ## Output Format
 
@@ -88,14 +91,20 @@ Record: chosen approach, rejected alternatives with reasons, key implementation
 ## Selected: [letter]
 **Rationale:** [why this approach was chosen]
 **Rejected:** [why alternatives were not chosen]
+**Risks:** [known risks and mitigation]
 ```
 
+## Explicit Approval Required
+
+The user must explicitly approve one approach before any implementation begins. Vague responses like "Sounds good" or "Interesting" are not approval. If ambiguous, ask: "To confirm — should I proceed with [specific approach]?"
+
 ## Common Pitfalls
 
-| Excuse | Reality |
-|--------|---------|
+| Pitfall | Reality |
+|---------|---------|
 | "I already know the best approach" | You know your preferred approach. Alternatives may be better. |
 | "There's only one way to do this" | There is almost never only one way. |
 | "Brainstorming slows us down" | Building the wrong thing is slower. 30 minutes of design saves days of rework. |
+| "The user will just pick the first one" | Present the best option last — anchoring on the first wastes the analysis. |
 
 Stop immediately if you catch yourself writing code before presenting approaches, presenting only one option, asking multiple questions at once, or assuming approval without explicit confirmation.

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

@@ -1,27 +1,18 @@
 ---
 name: code-review
 description: >-
-  Code quality review covering security, interfaces, error handling, test
-  coverage, and conventions. Produces structured findings with severity and
-  evidence. Use when reviewing pull requests, completed implementations, or
-  code changes.
+  Performs multi-dimensional code review covering security, quality, spec
+  compliance, and maintainability. Use when reviewing completed implementations
+  or before merging changes.
 ---
 
 # Code Review
 
-Shipping unreviewed code is shipping unknown risk. Review before sign-off.
+Shipping unreviewed code is shipping unknown risk. Every implementation review covers five dimensions.
 
 ## Review Dimensions
 
-Follow these dimensions in order for every review.
-
-### 1. SCOPE -- Identify All Changes
-
-- Diff against the starting point to see every changed file
-- List all new, modified, and deleted files
-- Do not skip generated files, config changes, or minor edits
-
-### 2. SECURITY -- Check for Vulnerabilities
+### 1. Security
 
 | Category | What to Look For |
 |----------|-----------------|
@@ -29,76 +20,108 @@ Follow these dimensions in order for every review.
 | Authentication | Missing auth checks, hardcoded credentials, tokens in source |
 | Authorization | Missing permission checks, privilege escalation paths |
 | Data exposure | Secrets in logs, overly broad API responses, sensitive data in error messages |
-| Dependencies | New dependencies with known vulnerabilities, unnecessary dependencies |
+| Dependencies | New packages with known CVEs, unnecessary new dependencies |
+
+Any security issue is a Blocker. No exceptions. No deferrals.
 
-Any security issue is a blocking finding. No exceptions.
+### 2. Quality
 
-### 3. INTERFACES -- Verify API Contracts
+- 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, concurrent access?
+- Are there obvious performance problems: N+1 queries, unbounded loops, missing pagination?
 
-- Do public function signatures match their documentation?
-- Are return types accurate and complete?
-- Do error types cover all failure modes?
+### 3. Spec Compliance
+
+- Does the implementation match what was planned?
+- Are all tasks from the plan completed?
+- Are acceptance criteria met?
 - Are breaking changes documented and intentional?
+- Does the scope match the plan — neither over-built nor under-built?
 
-### 4. ERROR HANDLING -- Check Failure Paths
+### 4. Maintainability
 
-- 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)?
+- Is naming consistent with existing codebase conventions?
+- Is complexity justified by the requirements? Could this be simpler?
+- Are comments present where logic is non-obvious?
+- Is there duplicated logic that should be extracted?
+- Would a new contributor understand this code without asking?
 
-### 5. TESTS -- Evaluate Coverage
+### 5. Test Coverage
 
 - Does every new public function have corresponding tests?
 - Do tests cover both success and failure paths?
 - Are edge cases tested?
 - Do tests verify behavior, not implementation details?
+- Would a test failure actually catch a regression?
 
-### 6. CONVENTIONS -- Assess Compliance
+## Severity Levels
 
-- Is naming consistent with existing codebase conventions?
-- Is the complexity justified by the requirements?
-- Are comments present where logic is non-obvious?
+| Severity | Definition | Action |
+|----------|------------|--------|
+| Blocker | Security vulnerability, data loss risk, broken public API contract | Block merge. Fix before any other work. |
+| High | Missing critical tests, no error path handling, performance regression | Fix now. File issue if fix takes >30min. |
+| Medium | Naming inconsistency, dead code, convention mismatch, weak tests | File for follow-up. Do not block merge. |
+| Low | Style preference, minor naming, optional improvement | Comment only. No tracking required. |
+
+Blocker and High block approval. Medium and Low do not.
 
-## Review Output Format
+## Parallel Review Pattern
+
+For large diffs (10+ files), spawn one review agent per dimension in parallel:
 
 ```
-REVIEW SCOPE: [number] files changed, [number] additions, [number] deletions
-SECURITY: PASS | ISSUES FOUND (list)
-INTERFACES: PASS | ISSUES FOUND (list)
-ERROR HANDLING: PASS | ISSUES FOUND (list)
-TEST COVERAGE: PASS | GAPS FOUND (list)
-CONVENTIONS: PASS | ISSUES FOUND (list)
-VERDICT: APPROVED | BLOCKED (list blocking issues)
+Agent 1: Security review only
+Agent 2: Quality and error handling only
+Agent 3: Spec compliance only
+Agent 4: Maintainability only
+Agent 5: Test coverage only
 ```
 
-### Severity Reference
+Each agent returns findings in the output format below. The orchestrator collates findings and produces the final verdict.
+
+## Output Format
 
-| Severity | Examples |
-|----------|---------|
-| Blocker | SQL injection, XSS, hardcoded secrets, broken public API, data loss risk |
-| High | Performance regression, missing critical tests, no error path tests |
-| Medium | Naming inconsistency, dead code, convention mismatch |
+```
+REVIEW SCOPE: [N] files changed, [N] additions, [N] deletions
 
-Blocker and High severity issues block approval. Medium issues should be filed for follow-up.
+SECURITY: PASS | [BLOCKER] description
+QUALITY: PASS | [HIGH] description
+SPEC COMPLIANCE: PASS | [HIGH] description
+MAINTAINABILITY: PASS | [MEDIUM] description
+TEST COVERAGE: PASS | [HIGH] description
 
-## Spec Review vs Code Review
+VERDICT: APPROVED | BLOCKED
 
-| Dimension | Spec Review | Code Review |
-|-----------|------------|-------------|
-| Question | Does it match the requirements? | Is the code correct and quality? |
-| Checks | Acceptance criteria, requirement coverage, scope | Security, interfaces, errors, tests, conventions |
-| Output | PASS/FAIL per requirement | APPROVED/BLOCKED per dimension |
+Blocking issues:
+- [BLOCKER] [file:line] SQL query uses string concatenation with user input
+- [HIGH] [file:line] No error handling on database connection failure
 
-Both reviews are needed -- spec review alone does not catch security issues, and code review alone does not catch missing requirements.
+Follow-up items:
+- [MEDIUM] [file] Function name `doThing` does not describe behavior
+```
 
 ## Common Pitfalls
 
-| Issue | Reality |
-|-------|---------|
+| Assumption | 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. |
 | "Generated code doesn't need review" | Generated code has the same bugs. Review it. |
+| "Security issues can be fixed later" | Security issues deferred are security issues shipped. |
+
+## Spec Review vs Code Review
+
+These are different activities. Both are required.
+
+| Dimension | Spec Review | Code Review |
+|-----------|------------|-------------|
+| Question | Does it match the requirements? | Is the code correct and quality? |
+| Checks | Acceptance criteria, requirement coverage, scope | Security, quality, errors, tests, maintainability |
+| Output | PASS/FAIL per requirement | APPROVED/BLOCKED per dimension |
+
+Spec review alone misses security issues. Code review alone misses missing requirements. Run both.
 
-See also: `/maxsim-simplify` for maintainability optimization (duplication, dead code, complexity).
+See also: `/maxsim-simplify` for maintainability optimization (duplication, dead code, complexity reduction).