maxsimcli 4.8.0 → 4.9.0

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

@@ -1,33 +1,38 @@
 ---
 name: brainstorming
 description: >-
-  Explores multiple implementation approaches with trade-off analysis before
-  committing to a design direction. Use when starting a significant feature,
-  making architectural decisions, or choosing between design alternatives.
+  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.
 ---
 
 # Brainstorming
 
 The first idea is rarely the best idea. Explore the space before committing to a direction.
 
-**HARD GATE** -- No implementation without design approval. If you have not presented approaches, discussed trade-offs, and received explicit user approval, you cannot write implementation code. This is not a judgment call.
-
 ## Process
 
 ### 1. Frame the Problem
 
-Ask the user ONE question at a time to understand the problem space. Each answer informs the next question.
+Define the problem clearly before proposing solutions:
 
 - What is the goal? What does success look like?
 - What are the constraints (performance, compatibility, timeline)?
 - 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.
+
 ### 2. Research Context
 
-Before proposing solutions, gather evidence from the codebase and any existing planning artifacts. Read relevant code, check for prior decisions, and identify patterns already in use.
+Before proposing solutions, gather evidence:
 
-### 3. Present 2-3 Approaches
+- Read relevant code and check for prior decisions
+- Identify patterns already in use in the codebase
+- Check STATE.md for existing architectural decisions
+
+### 3. Present 3+ Approaches
 
 For each approach, provide:
 
@@ -35,55 +40,62 @@ For each approach, provide:
 |--------|---------|
 | **Summary** | One sentence |
 | **How it works** | 3-5 implementation bullets |
-| **Pros** | Concrete advantages (not vague -- "200 fewer lines" beats "simpler") |
+| **Pros** | Concrete advantages ("200 fewer lines" beats "simpler") |
 | **Cons** | Honest drawbacks -- do not hide weaknesses |
 | **Effort** | Low / Medium / High |
 | **Risk** | What could go wrong and how recoverable |
 
-Present exactly 2-3 approaches. If one 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 alternatives so the user can validate your reasoning.
 
 ### 4. Discuss and Refine
 
-Ask the user which approach they prefer 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.
+- 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
 
 ### 5. Get Explicit Approval
 
-The user must explicitly approve one approach (e.g., "Go with A", "Approved", "Ship it"). Vague responses like "Sounds good" or "Interesting" are not approval. If ambiguous, ask: "To confirm -- should I proceed with [specific approach]?"
+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]?"
 
 ### 6. Document the Decision
 
-Record the chosen approach, rejected alternatives with reasons, key implementation decisions, and risks. Use MAXSIM state tooling if available.
+Record: chosen approach, rejected alternatives with reasons, key implementation decisions, and risks.
 
-### 7. Implement the Approved Design
+## Output Format
 
-Only after steps 1-6. Follow the approved design. If implementation reveals a design flaw, stop and return to step 4.
+```markdown
+## Problem Statement
+[What needs to be decided]
 
-## Common Pitfalls
+## Approaches
 
-| Excuse | 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. |
+| # | Approach | Effort | Risk |
+|---|----------|--------|------|
+| A | [summary] | Low/Med/High | Low/Med/High |
+| B | [summary] | Low/Med/High | Low/Med/High |
+| C | [summary] | Low/Med/High | Low/Med/High |
 
-Stop immediately if you catch yourself: writing code before presenting approaches, presenting only one option, asking multiple questions at once, assuming approval without explicit confirmation, or skipping documentation.
+### Approach A: [name]
+[How it works, pros, cons]
 
-## Verification
+### Approach B: [name]
+[How it works, pros, cons]
 
-Before starting implementation, confirm:
+### Approach C: [name]
+[How it works, pros, cons]
 
-- [ ] Problem has been framed with user input (not assumptions)
-- [ ] Relevant code and context have been researched
-- [ ] 2-3 approaches presented with concrete trade-offs
-- [ ] User has explicitly approved one specific approach
-- [ ] Decision has been recorded
-- [ ] Design doc captures chosen approach, rejected alternatives, and risks
+## Selected: [letter]
+**Rationale:** [why this approach was chosen]
+**Rejected:** [why alternatives were not chosen]
+```
 
-## MAXSIM Integration
+## Common Pitfalls
 
-Brainstorming applies before significant implementation work within MAXSIM workflows:
+| Excuse | 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. |
 
-- Use during phase planning when design choices affect multiple tasks
-- Use before any task introducing new architecture, patterns, or external dependencies
-- Decision records in STATE.md persist across sessions -- future agents inherit context
-- If a session spans multiple interactions, record partial progress in STATE.md blockers
+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,33 +1,28 @@
 ---
 name: code-review
 description: >-
-  Correctness gate: reviews all changed code for security vulnerabilities,
-  interface correctness, error handling, test coverage, and quality. Answers
-  "Is this code correct and safe?" Use when completing a phase, reviewing
-  implementation, or before approving changes for merge. Not a maintainability
-  pass — that is maxsim-simplify's job.
+  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.
 ---
 
 # Code Review
 
 Shipping unreviewed code is shipping unknown risk. Review before sign-off.
 
-**HARD GATE: NO PHASE SIGN-OFF WITHOUT REVIEWING ALL CHANGED CODE.** If every diff introduced in this phase has not been read, the phase cannot be marked complete. Passing tests do not prove code quality.
+## Review Dimensions
 
-## Process
-
-Follow these steps in order before approving any phase or significant implementation.
+Follow these dimensions in order for every review.
 
 ### 1. SCOPE -- Identify All Changes
 
-- Diff against the phase starting point to see every changed file
+- 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
 
-Review every changed file for:
-
 | Category | What to Look For |
 |----------|-----------------|
 | Injection | Unsanitized user input in SQL, shell commands, HTML output, template strings |
@@ -36,7 +31,7 @@ Review every changed file for:
 | Data exposure | Secrets in logs, overly broad API responses, sensitive data in error messages |
 | Dependencies | New dependencies with known vulnerabilities, unnecessary dependencies |
 
-**Any security issue is a blocking finding. No exceptions.**
+Any security issue is a blocking finding. No exceptions.
 
 ### 3. INTERFACES -- Verify API Contracts
 
@@ -44,7 +39,6 @@ Review every changed file for:
 - Are return types accurate and complete?
 - Do error types cover all failure modes?
 - Are breaking changes documented and intentional?
-- Do exported interfaces maintain backward compatibility?
 
 ### 4. ERROR HANDLING -- Check Failure Paths
 
@@ -60,51 +54,13 @@ Review every changed file for:
 - Are edge cases tested?
 - Do tests verify behavior, not implementation details?
 
-### 6. QUALITY -- Assess Maintainability
+### 6. CONVENTIONS -- Assess Compliance
 
 - Is naming consistent with existing codebase conventions?
-- Are there duplication opportunities that should be extracted?
 - Is the complexity justified by the requirements?
 - Are comments present where logic is non-obvious?
 
-## Common Pitfalls
-
-| Issue | Reality |
-|-------|---------|
-| "Tests pass, so the code is fine" | Tests verify behavior, not code quality. Review is separate. |
-| "I wrote it, so I know it's correct" | Author bias is real. Review as if someone else wrote it. |
-| "It's just a small change" | Small changes cause large outages. |
-| "Generated code doesn't need review" | Generated code has the same bugs. Review it. |
-
-Stop if you catch yourself skipping files because they "look fine," approving without reading actual code, or rushing through review to meet a deadline.
-
-## Verification
-
-Before signing off on a phase, confirm:
-
-- [ ] All changed files have been reviewed (not just the "important" ones)
-- [ ] No security vulnerabilities found (or all found issues resolved)
-- [ ] Public interfaces match their contracts and documentation
-- [ ] Error handling covers all external calls and edge cases
-- [ ] Test coverage exists for new public functions and error paths
-- [ ] Naming and style are consistent with codebase conventions
-- [ ] No blocker or high severity issues remain open
-
-### Severity Reference
-
-| Severity | Category | Example |
-|----------|----------|---------|
-| Blocker | Security vulnerability | SQL injection, XSS, hardcoded secrets |
-| Blocker | Broken interface | Public API returns wrong type |
-| Blocker | Data loss risk | Destructive operation without confirmation |
-| High | Performance regression | O(n^2) where O(n) is trivial |
-| High | Missing critical tests | No tests for error paths or new public API |
-| Medium | Naming inconsistency | Convention mismatch with existing codebase |
-| Medium | Dead code | Unreachable branches, unused imports |
-
-Blocker and High severity issues block sign-off. Medium issues should be filed for follow-up.
-
-### Review Output Format
+## Review Output Format
 
 ```
 REVIEW SCOPE: [number] files changed, [number] additions, [number] deletions
@@ -112,14 +68,37 @@ SECURITY: PASS | ISSUES FOUND (list)
 INTERFACES: PASS | ISSUES FOUND (list)
 ERROR HANDLING: PASS | ISSUES FOUND (list)
 TEST COVERAGE: PASS | GAPS FOUND (list)
-QUALITY: PASS | ISSUES FOUND (list)
+CONVENTIONS: PASS | ISSUES FOUND (list)
 VERDICT: APPROVED | BLOCKED (list blocking issues)
 ```
 
-## MAXSIM Integration
+### Severity Reference
+
+| 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 |
+
+Blocker and High severity issues block approval. Medium issues should be filed for follow-up.
+
+## Spec Review vs Code Review
+
+| 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 |
+
+Both reviews are needed -- spec review alone does not catch security issues, and code review alone does not catch missing requirements.
+
+## Common Pitfalls
+
+| Issue | Reality |
+|-------|---------|
+| "Tests pass, so the code is fine" | Tests verify behavior, not code quality. Review is separate. |
+| "I wrote it, so I know it's correct" | Author bias is real. Review as if someone else wrote it. |
+| "It's just a small change" | Small changes cause large outages. |
+| "Generated code doesn't need review" | Generated code has the same bugs. Review it. |
 
-Code review applies at phase boundaries:
-- After all tasks in a phase are complete, run this review before marking the phase done
-- Blocking issues must be resolved before phase completion
-- Medium issues should be captured as todos for the next phase
-- The review summary should be included in the phase SUMMARY.md
+See also: `/maxsim-simplify` for maintainability optimization (duplication, dead code, complexity).

package/dist/assets/templates/skills/commit-conventions/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: commit-conventions
+description: >-
+  Commit message format using conventional commits with scope. Defines atomic
+  commit rules, breaking change markers, and co-author attribution for
+  AI-assisted work. Use when creating git commits, reviewing commit messages,
+  or establishing commit conventions for a project.
+user-invocable: false
+---
+
+# Commit Conventions
+
+Consistent commit messages that enable automated versioning, changelogs, and clear project history.
+
+## Conventional Commit Format
+
+```
+{type}({scope}): {description}
+
+- {key change 1}
+- {key change 2}
+```
+
+### Types
+
+| Type | When | Triggers |
+|------|------|---------|
+| `feat` | New feature or capability | Minor version bump |
+| `fix` | Bug fix | Patch version bump |
+| `chore` | Build, deps, config, maintenance | No version bump |
+| `docs` | Documentation only | No version bump |
+| `test` | Adding or fixing tests | No version bump |
+| `refactor` | Code change that's neither fix nor feature | No version bump |
+
+### Breaking Changes
+
+Append `!` after the type for breaking changes:
+
+```
+feat!(install): require Node 20 minimum
+fix!(config): rename model_profile to profile
+```
+
+Breaking changes trigger a major version bump.
+
+### Scope
+
+Scope identifies the area of change:
+
+- Phase work: `feat(04-01):`, `fix(phase-04):`
+- Module: `fix(install):`, `refactor(core):`
+- Component: `feat(dashboard):`, `test(cli):`
+
+## Atomic Commits
+
+One logical change per commit:
+
+- **DO:** Separate feature implementation from test additions
+- **DO:** Commit each task in a plan individually
+- **DO NOT:** Bundle unrelated changes in one commit
+- **DO NOT:** Include "fix typo" changes in feature commits
+
+## Co-Author Attribution
+
+When work is AI-assisted, include the co-author line:
+
+```
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+## Commit Message Guidelines
+
+- **Subject line:** Under 72 characters, imperative mood ("add" not "added")
+- **Body:** Bullet points for key changes (optional for small commits)
+- **Why over what:** The diff shows what changed; the message explains why

package/dist/assets/templates/skills/evidence-collection/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: evidence-collection
+description: >-
+  Systematic evidence gathering using tool output before making claims. Covers
+  what counts as evidence, the collection process, and common pitfalls that lead
+  to false claims. Use when verifying work completion, checking test results,
+  validating build success, or before any completion gate.
+user-invocable: false
+---
+
+# Evidence Collection
+
+Gather fresh evidence using tool output before making any claim. Evidence must come from THIS turn -- not prior turns, not cached knowledge, not reasoning.
+
+## Collection Process
+
+For each claim you need to support:
+
+1. **IDENTIFY** -- What command proves this claim?
+   - Pick the most direct verification (e.g., `npm test` for "tests pass", not "I wrote the test")
+   - If no single command exists, identify all required checks
+
+2. **RUN** -- Execute the command fresh in THIS turn
+   - Do not reuse output from a previous turn
+   - Do not rely on output from a different command
+   - Run the full command, not a partial check
+
+3. **READ** -- Read the complete output
+   - Check the exit code (0 = success, non-zero = failure)
+   - Read all output, not just the summary line
+   - Look for warnings or partial failures hidden in verbose output
+
+4. **CHECK** -- Does the output actually confirm the claim?
+   - Match output against specific expected values
+   - A passing build does not mean passing tests
+   - A created file does not mean correct file contents
+
+5. **CITE** -- Include the evidence in your response
+   - Use the evidence block format
+   - Quote specific output lines, not paraphrased summaries
+
+## What Counts as Evidence
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| "Tests pass" | Test command output showing 0 failures | Previous run, "should pass", partial run |
+| "Build succeeds" | Build command with exit code 0 | Linter passing, "logs look clean" |
+| "Bug is fixed" | Original failing test now passes | "Code changed, assumed fixed" |
+| "Task complete" | All done criteria checked with evidence | "I implemented everything in the plan" |
+| "No regressions" | Full test suite passing | "I only changed one file" |
+| "File created" | Read tool or `test -f` output | "I ran the Write tool" (verify it wrote) |
+| "Content correct" | Read tool showing expected content | "I wrote the correct content" |
+| "API responds" | curl/fetch output with status code | "Server is running" without calling it |
+
+## Evidence Block Format
+
+```
+CLAIM: [what you are claiming]
+EVIDENCE: [exact command run in THIS turn]
+OUTPUT: [relevant excerpt of actual output]
+VERDICT: PASS | FAIL
+```
+
+## Common Pitfalls
+
+| Excuse | Why It Fails |
+|--------|-------------|
+| "Should work now" | "Should" is not evidence. Run the command. |
+| "I'm confident in the logic" | Confidence is not evidence. Run it. |
+| "The linter passed" | Linter passing does not mean tests pass or build succeeds. |
+| "I only changed one line" | One line can break everything. Verify. |
+| "The subagent reported success" | Trust test output and VCS diffs, not agent reports. |
+| "I already checked this" | In a previous turn. Evidence expires each turn. Run it again. |
+| "The error was in a different file" | Side effects cross files. Run the full suite. |
+| "It compiled, so it works" | Compilation checks types, not logic. Run tests. |
+
+## Key Rules
+
+- **THIS-turn only**: Evidence from prior turns is stale. Always re-run.
+- **Tool output only**: Your reasoning, analysis, and confidence are not evidence.
+- **Full output**: Read the complete output, not just the first or last line.
+- **Specific citations**: Quote the output. "It passed" is not a citation.
+- **One block per claim**: Each distinct claim needs its own evidence or an explicit grouping note.
+
+## See Also
+
+The `verification-gates` skill defines the gate framework where evidence collection is applied. The always-loaded `verification-protocol` rule provides the enforcement language.

package/dist/assets/templates/skills/handoff-contract/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: handoff-contract
+description: >-
+  Structured return format for agent handoffs. Defines Key Decisions, Artifacts,
+  Status, and Deferred Items sections that every agent must include when returning
+  results. Use when completing any agent task, returning results to orchestrator,
+  or transitioning between workflow stages.
+user-invocable: false
+---
+
+# Handoff Contract
+
+Every agent returns results using this structured format. The orchestrator depends on these sections for state tracking, artifact management, and pipeline decisions.
+
+## Required Return Sections
+
+### Key Decisions
+
+Document decisions made during execution that affect downstream work:
+
+```markdown
+### Key Decisions
+- Chose X over Y because [reason]
+- Deferred Z to [phase/plan] because [reason]
+```
+
+Include: technology choices, scope adjustments, interpretation of ambiguous requirements. Omit: routine implementation details.
+
+### Artifacts
+
+List all files created or modified, grouped by action:
+
+```markdown
+### Artifacts
+- Created: path/to/new-file.ts
+- Created: path/to/another-file.md
+- Modified: path/to/existing-file.ts
+```
+
+Use absolute paths from project root. Include every file touched, not just the primary deliverables.
+
+### Status
+
+One of three values:
+
+| Status | Meaning | Orchestrator Action |
+|--------|---------|-------------------|
+| `complete` | All tasks done, verification passed | Advance to next plan or stage |
+| `blocked` | Cannot proceed without external input | Present blocker to user, await resolution |
+| `partial` | Some tasks done, stopped at checkpoint | Resume from checkpoint with user input |
+
+```markdown
+### Status
+complete
+```
+
+### Deferred Items
+
+Work discovered but not implemented (outside current scope):
+
+```markdown
+### Deferred Items
+- [feature] Add caching layer -- not in current plan scope
+- [bug] Race condition in parallel writes -- needs investigation
+- [refactor] Extract shared validation logic -- deferred to Phase 5
+```
+
+If none: `### Deferred Items\nNone`
+
+Categories: `feature`, `bug`, `refactor`, `investigation`

package/dist/assets/templates/skills/input-validation/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: input-validation
+description: >-
+  Validates required inputs exist before agent work begins. Checks file paths,
+  environment variables, and CLI arguments at startup. Use at agent startup to
+  fail fast with structured error instead of proceeding with missing context.
+user-invocable: false
+---
+
+# Input Validation
+
+Validate all required inputs before doing any work. Fail fast with a structured error -- never attempt partial work with missing context.
+
+## Process
+
+At agent startup, before any implementation:
+
+1. **List required inputs** -- files, env vars, CLI args, state files
+2. **Check each input exists** -- use tool calls, not assumptions
+3. **Collect all missing inputs** -- do not stop at the first missing item
+4. **If any missing: return structured error immediately**
+
+## Structured Error Format
+
+```
+AGENT RESULT: INPUT VALIDATION FAILED
+
+Missing:
+- [input 1] -- [what it is, where it should come from]
+- [input 2] -- [what it is, where it should come from]
+
+Expected from: [source -- orchestrator spawn prompt, user environment, prior agent output]
+```
+
+## Validation Checks by Type
+
+| Input Type | How to Check | Example |
+|-----------|-------------|---------|
+| File path | `test -f "path"` or Read tool | PLAN.md, STATE.md, config.json |
+| Directory | `test -d "path"` | .planning/, templates/ |
+| Env variable | `echo "$VAR"` or `test -n "$VAR"` | GITHUB_TOKEN, NODE_ENV |
+| CLI argument | Check prompt context for required fields | Phase number, plan number |
+| Prior output | Check expected file or git commit exists | SUMMARY.md from previous plan |
+
+## Rules
+
+- **Check ALL inputs before reporting** -- collect the complete list of missing items
+- **Do NOT attempt partial work** -- if inputs are missing, the output will be wrong
+- **Do NOT guess missing values** -- return the error and let the orchestrator fix it
+- **Include the source** -- tell the user where the missing input should come from
+- **This is a hard gate** -- no workarounds, no "I'll proceed without it"