npm - maxsimcli - Versions diffs - 3.11.0 → 3.12.0 - Mend

maxsimcli 3.11.0 → 3.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (102) hide show

package/dist/.tsbuildinfo +1 -1
package/dist/assets/CHANGELOG.md +19 -0
package/dist/assets/dashboard/client/assets/index-CxFKStBk.css +32 -0
package/dist/assets/dashboard/client/assets/{index-CZ8WC97G.js → index-wtQDvXzr.js} +64 -64
package/dist/assets/dashboard/client/index.html +2 -2
package/dist/assets/templates/agents/AGENTS.md +82 -0
package/dist/assets/templates/commands/maxsim/settings.md +1 -1
package/dist/assets/templates/skills/code-review/SKILL.md +151 -0
package/dist/assets/templates/skills/memory-management/SKILL.md +174 -0
package/dist/assets/templates/skills/simplify/SKILL.md +137 -0
package/dist/assets/templates/skills/using-maxsim/SKILL.md +115 -0
package/dist/assets/templates/templates/config.json +1 -1
package/dist/assets/templates/workflows/add-tests.md +3 -3
package/dist/assets/templates/workflows/complete-milestone.md +1 -1
package/dist/assets/templates/workflows/execute-phase.md +4 -14
package/dist/assets/templates/workflows/init-existing.md +7 -3
package/dist/assets/templates/workflows/new-milestone.md +4 -0
package/dist/assets/templates/workflows/new-project.md +6 -2
package/dist/assets/templates/workflows/plan-phase.md +2 -2
package/dist/assets/templates/workflows/settings.md +8 -4
package/dist/assets/templates/workflows/verify-work.md +1 -1
package/dist/cli.cjs +265 -161
package/dist/cli.cjs.map +1 -1
package/dist/cli.js +73 -204
package/dist/cli.js.map +1 -1
package/dist/core/commands.d.ts.map +1 -1
package/dist/core/commands.js +4 -1
package/dist/core/commands.js.map +1 -1
package/dist/core/core.d.ts +18 -0
package/dist/core/core.d.ts.map +1 -1
package/dist/core/core.js +43 -13
package/dist/core/core.js.map +1 -1
package/dist/core/dashboard-launcher.d.ts +56 -0
package/dist/core/dashboard-launcher.d.ts.map +1 -0
package/dist/core/dashboard-launcher.js +243 -0
package/dist/core/dashboard-launcher.js.map +1 -0
package/dist/core/index.d.ts +3 -1
package/dist/core/index.d.ts.map +1 -1
package/dist/core/index.js +20 -2
package/dist/core/index.js.map +1 -1
package/dist/core/init.d.ts +0 -1
package/dist/core/init.d.ts.map +1 -1
package/dist/core/init.js +0 -1
package/dist/core/init.js.map +1 -1
package/dist/core/phase.d.ts.map +1 -1
package/dist/core/phase.js +7 -1
package/dist/core/phase.js.map +1 -1
package/dist/core/roadmap.d.ts.map +1 -1
package/dist/core/roadmap.js +1 -0
package/dist/core/roadmap.js.map +1 -1
package/dist/core/state.d.ts.map +1 -1
package/dist/core/state.js +7 -5
package/dist/core/state.js.map +1 -1
package/dist/core/types.d.ts +1 -2
package/dist/core/types.d.ts.map +1 -1
package/dist/core/types.js +1 -2
package/dist/core/types.js.map +1 -1
package/dist/install/adapters.d.ts +15 -0
package/dist/install/adapters.d.ts.map +1 -0
package/dist/install/adapters.js +203 -0
package/dist/install/adapters.js.map +1 -0
package/dist/install/copy.d.ts +15 -0
package/dist/install/copy.d.ts.map +1 -0
package/dist/install/copy.js +191 -0
package/dist/install/copy.js.map +1 -0
package/dist/install/dashboard.d.ts +16 -0
package/dist/install/dashboard.d.ts.map +1 -0
package/dist/install/dashboard.js +273 -0
package/dist/install/dashboard.js.map +1 -0
package/dist/install/hooks.d.ts +32 -0
package/dist/install/hooks.d.ts.map +1 -0
package/dist/install/hooks.js +285 -0
package/dist/install/hooks.js.map +1 -0
package/dist/install/index.d.ts +2 -0
package/dist/install/index.d.ts.map +1 -0
package/dist/install/index.js +598 -0
package/dist/install/index.js.map +1 -0
package/dist/install/manifest.d.ts +20 -0
package/dist/install/manifest.d.ts.map +1 -0
package/dist/install/manifest.js +135 -0
package/dist/install/manifest.js.map +1 -0
package/dist/install/patches.d.ts +11 -0
package/dist/install/patches.d.ts.map +1 -0
package/dist/install/patches.js +136 -0
package/dist/install/patches.js.map +1 -0
package/dist/install/shared.d.ts +50 -0
package/dist/install/shared.d.ts.map +1 -0
package/dist/install/shared.js +142 -0
package/dist/install/shared.js.map +1 -0
package/dist/install/uninstall.d.ts +6 -0
package/dist/install/uninstall.d.ts.map +1 -0
package/dist/install/uninstall.js +280 -0
package/dist/install/uninstall.js.map +1 -0
package/dist/install.cjs +763 -709
package/dist/install.cjs.map +1 -1
package/dist/mcp-server.cjs.map +1 -1
package/package.json +1 -1
package/dist/assets/dashboard/client/assets/index-DzJChB-D.css +0 -32
package/dist/install.d.ts +0 -2
package/dist/install.d.ts.map +0 -1
package/dist/install.js +0 -1841
package/dist/install.js.map +0 -1

package/dist/assets/dashboard/client/index.html CHANGED Viewed

@@ -10,8 +10,8 @@
       href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700;800;900&family=Geist+Mono:wght@400;500;600;700&display=swap"
       rel="stylesheet"
     />
-    <script type="module" crossorigin src="/assets/index-CZ8WC97G.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DzJChB-D.css">
+    <script type="module" crossorigin src="/assets/index-wtQDvXzr.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CxFKStBk.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/assets/templates/agents/AGENTS.md ADDED Viewed

@@ -0,0 +1,82 @@
+# AGENTS.md — Agent-Skill Registry
+This file maps MAXSIM agents to the skills they should auto-load and enforce during execution.
+## How This Registry Works
+When a MAXSIM agent is spawned, it checks this registry to determine which skills apply. Skills are behavioral rules that constrain agent actions — they are not optional guidelines.
+Agents load skills by reading `SKILL.md` from each skill directory listed in their entry below. Skills are loaded once at agent startup and enforced throughout the session.
+## Registry
+### maxsim-executor
+**Skills:** `tdd`, `verification-before-completion`, `using-maxsim`
+The executor implements plan tasks. TDD ensures tests are written before code. Verification ensures completion claims have evidence. Using-maxsim ensures work stays within the plan structure.
+### maxsim-debugger
+**Skills:** `systematic-debugging`, `verification-before-completion`
+The debugger investigates bugs. Systematic-debugging enforces the reproduce-hypothesize-isolate-verify-fix cycle. Verification ensures the fix is confirmed with evidence before claiming resolution.
+### maxsim-verifier
+**Skills:** `verification-before-completion`
+The verifier checks phase goal achievement. Verification-before-completion is its core purpose — every claim must have fresh evidence.
+### maxsim-planner
+**Skills:** `using-maxsim`
+The planner creates PLAN.md files. Using-maxsim ensures plans reference the correct workflow structure and available skills.
+### maxsim-code-reviewer
+**Skills:** `verification-before-completion`
+The code reviewer checks implementation quality. Verification ensures review findings are backed by evidence from the codebase, not assumptions.
+### maxsim-roadmapper
+**Skills:** `using-maxsim`
+The roadmapper creates project roadmaps. Using-maxsim ensures roadmaps align with the MAXSIM phase structure.
+### maxsim-phase-researcher
+**Skills:** `memory-management`
+The phase researcher gathers context for planning. Memory-management ensures valuable research findings are persisted for future sessions.
+### maxsim-project-researcher
+**Skills:** `memory-management`
+The project researcher analyzes project structure during init. Memory-management ensures architectural patterns and conventions are saved.
+### maxsim-integration-checker
+**Skills:** `verification-before-completion`
+The integration checker validates cross-component wiring. Verification ensures integration claims are tested, not assumed.
+## Skill Reference
+| Skill | Directory | Purpose |
+|-------|-----------|---------|
+| `systematic-debugging` | `skills/systematic-debugging/` | Root cause investigation before fixes |
+| `tdd` | `skills/tdd/` | Failing test before implementation |
+| `verification-before-completion` | `skills/verification-before-completion/` | Evidence before completion claims |
+| `using-maxsim` | `skills/using-maxsim/` | Workflow routing and structure |
+| `memory-management` | `skills/memory-management/` | Pattern and error persistence |
+## Adding New Skills
+1. Create a directory under `skills/` with a `SKILL.md` file
+2. Follow the existing skill format (frontmatter + Iron Law + Gate Function + Red Flags)
+3. Add the skill to the relevant agent entries in this registry
+4. Add the skill to the reference table above

package/dist/assets/templates/commands/maxsim/settings.md CHANGED Viewed

@@ -14,7 +14,7 @@ Interactive configuration of MAXSIM workflow agents and model profile via multi-
 Routes to the settings workflow which handles:
 - Config existence ensuring
 - Current settings reading and parsing
-- Interactive 5-question prompt (model, research, plan_check, verifier, branching)
+- Interactive 5-question prompt (model, research, plan_checker, verifier, branching)
 - Config merging and writing
 - Confirmation display with quick command references
 </objective>

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

@@ -0,0 +1,151 @@
+---
+name: code-review
+description: Use after completing a phase or significant implementation — requires reviewing all changed code for critical issues before sign-off
+---
+# Code Review
+Shipping unreviewed code is shipping unknown risk. Review before sign-off.
+**If you have not reviewed every changed file, you cannot approve the phase.**
+## The Iron Law
+<HARD-GATE>
+NO PHASE SIGN-OFF WITHOUT REVIEWING ALL CHANGED CODE.
+If you have not read every diff introduced in this phase, you CANNOT mark it complete.
+"It works" is not "it's correct." Passing tests do not prove code quality.
+Violating this rule is a violation — not a shortcut.
+</HARD-GATE>
+## The Gate Function
+Follow these steps IN ORDER before approving any phase or significant implementation.
+### 1. SCOPE — Identify All Changes
+- Run `git diff` against the phase's starting point to see every changed file
+- List all new files, modified files, and deleted files
+- Do NOT skip generated files, config changes, or "minor" edits
+```bash
+# Example: see all changes since phase branch point
+git diff --stat main...HEAD
+git diff main...HEAD
+```
+### 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 |
+| 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 |
+**Any security issue is a blocking finding. No exceptions.**
+### 3. INTERFACES — Verify API Contracts
+- Do public function signatures match their documentation?
+- 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 (or is the break intentional)?
+### 4. ERROR HANDLING — Check Failure Paths
+- Are all external calls (I/O, network, user input) 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)?
+### 5. TESTS — Evaluate Coverage
+- Does every new public function have corresponding tests?
+- Do tests cover both success and failure paths?
+- Are edge cases tested (empty, null, boundary, error conditions)?
+- Do tests verify behavior, not implementation details?
+### 6. QUALITY — Assess Maintainability
+- Is naming consistent with the existing codebase conventions?
+- Are there code duplication opportunities that should be extracted?
+- Is the complexity justified by the requirements?
+- Are comments present where logic is non-obvious (and absent where code is self-evident)?
+## Critical Issues — Block Phase Sign-Off
+These categories MUST be resolved before the phase can be marked complete:
+| Severity | Category | Example |
+|----------|----------|---------|
+| **Blocker** | Security vulnerability | SQL injection, XSS, hardcoded secrets |
+| **Blocker** | Broken interface | Public API returns wrong type, missing required field |
+| **Blocker** | Missing error handling | Unhandled promise rejection, swallowed exceptions on I/O |
+| **Blocker** | Data loss risk | Destructive operation without confirmation, missing transaction |
+| **High** | Performance regression | O(n^2) where O(n) is trivial, unbounded memory allocation |
+| **High** | Missing critical tests | No tests for error paths, no tests for new public API |
+| **Medium** | Naming inconsistency | Convention mismatch with existing codebase |
+| **Medium** | Dead code | Unreachable branches, unused imports, commented-out code |
+**Blocker and High severity issues block sign-off. Medium issues should be filed for follow-up.**
+## Common Rationalizations — REJECT THESE
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "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. Review proportional effort, not zero effort. |
+| "We'll clean it up later" | "Later" accumulates. Fix blockers now, file medium issues. |
+| "The deadline is tight" | Shipping broken code costs more time than reviewing. |
+| "Generated code doesn't need review" | Generated code has the same bugs. Review it. |
+## Red Flags — STOP If You Catch Yourself:
+- Skipping files because they "look fine" from the diff stat
+- Approving without reading the actual code changes
+- Ignoring a gut feeling that something is wrong
+- Rushing through review to meet a deadline
+- Assuming tests cover everything without checking
+- Skipping error handling review because "the happy path works"
+**If any red flag triggers: STOP. Go back to step 1 (SCOPE) and review properly.**
+## Verification Checklist
+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
+## Review Output Format
+Produce a review summary for phase documentation:
+```
+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)
+QUALITY: PASS | ISSUES FOUND (list)
+VERDICT: APPROVED | BLOCKED (list blocking issues)
+```
+## In MAXSIM Plan Execution
+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

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

@@ -0,0 +1,174 @@
+---
+name: memory-management
+description: Use when encountering recurring patterns, errors, or decisions that should persist across sessions — defines when and how to save to project memory
+---
+# Memory Management
+Context dies with each session. Patterns discovered but not saved are patterns lost.
+**If you encountered it twice, save it. You will encounter it again.**
+## The Iron Law
+<HARD-GATE>
+RECURRING PATTERNS MUST BE PERSISTED.
+If you have seen the same error, pattern, or decision twice in this session or across sessions, you MUST save it.
+"I'll remember" is a lie — your context resets. Write it down.
+Violating this rule guarantees repeated mistakes across sessions.
+</HARD-GATE>
+## When to Save
+### Auto-Save Triggers (MUST save)
+These situations require immediate memory persistence:
+| Trigger | Threshold | What to Save |
+|---------|-----------|-------------|
+| Same error encountered | 2+ occurrences | Error pattern, root cause, fix |
+| Same debugging path followed | 2+ times | The shortcut or solution |
+| Architectural decision made | Once (if significant) | Decision, rationale, alternatives rejected |
+| Non-obvious convention discovered | Once | The convention and where it applies |
+| Workaround for tooling/framework quirk | Once | The quirk and the workaround |
+| Project-specific pattern confirmed | 2+ uses | The pattern and when to apply it |
+### Do NOT Save
+- Session-specific context (current task details, in-progress work)
+- Information already in CLAUDE.md or project documentation
+- Speculative conclusions from reading a single file
+- Temporary workarounds that will be removed
+- Obvious patterns that any developer would know
+## Where to Save
+Memory files live in `.claude/memory/` (for Claude Code) or the equivalent runtime memory directory.
+### File Organization
+```
+.claude/memory/
+  MEMORY.md          # Index file — always loaded into context
+  patterns.md        # Code patterns and conventions
+  errors.md          # Error patterns and solutions
+  architecture.md    # Architectural decisions and rationale
+  tooling.md         # Tool quirks and workarounds
+```
+- **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
+### Memory Entry Format
+Each entry should follow this structure:
+```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)
+```
+## The Gate Function
+When you encounter something worth remembering:
+### 1. DETECT — Recognize the Pattern
+- Is this the same error/pattern you saw before?
+- Is this a decision that will affect future work?
+- Is this a non-obvious convention or quirk?
+### 2. CHECK — Avoid Duplicates
+- Read the existing memory files first
+- If the pattern is already documented, update it (don't duplicate)
+- If it contradicts existing memory, investigate which is correct
+### 3. WRITE — Persist the Memory
+- Add to the appropriate topic file
+- Update MEMORY.md index if adding a new topic
+- Keep entries concise — future you needs the answer, not the journey
+### 4. VERIFY — Confirm the Save
+- Re-read the file to confirm the entry was written correctly
+- Ensure the entry is actionable (someone reading it can act on it)
+## Error Pattern Detection
+When debugging, track errors in a mental tally:
+```
+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
+```
+### What Makes a Good Error Memory
+Good:
+```markdown
+## Vitest "cannot find module" for path aliases
+**Context:** When running tests that import from `@maxsim/core`
+**Error:** `Cannot find module '@maxsim/core/types'`
+**Fix:** Add `resolve.alias` to `vitest.config.ts` matching tsconfig paths
+**Evidence:** Hit 3 times across phases 01-03 (Feb 2026)
+```
+Bad:
+```markdown
+## Test error
+There was an error with tests. Fixed it by changing config.
+```
+## Common Rationalizations — REJECT THESE
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "I'll remember this" | No you won't. Context resets. Write it down. |
+| "It's too specific to save" | Specific is good. Generic memories are useless. |
+| "Memory files are messy" | Organize them. Messy files > lost knowledge. |
+| "This only applies to this project" | Project memory IS project-scoped. Save it. |
+| "Someone else documented this" | If it's not in your memory files, you won't find it next session. |
+| "I'll save it later" | You'll forget to. Save it now. |
+## Red Flags — STOP If You Catch Yourself:
+- Encountering the same error for the second time without saving it
+- Making the same architectural decision you made in a previous session
+- Debugging a problem you already solved before
+- Saying "I think we fixed this before" without finding the memory entry
+- Leaving a session without updating memory for patterns discovered
+**If any red flag triggers: STOP. Write the memory entry NOW, before continuing.**
+## Verification Checklist
+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)
+## Integration with MAXSIM
+During plan execution, the executor and researcher 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/simplify/SKILL.md ADDED Viewed

@@ -0,0 +1,137 @@
+---
+name: simplify
+description: Use after implementation and before commit — requires reviewing changed code for reuse opportunities, quality issues, and unnecessary complexity
+---
+# Simplify
+Every line of code is a liability. Less code that does the same thing is always better.
+**If you have not looked for ways to simplify, you are shipping the first draft.**
+## The Iron Law
+<HARD-GATE>
+NO COMMIT WITHOUT REVIEWING FOR SIMPLIFICATION.
+If you have not checked for duplication, dead code, and unnecessary complexity, you CANNOT commit.
+"It works" is the starting point, not the finish line.
+Violating this rule is a violation — not a preference.
+</HARD-GATE>
+## The Gate Function
+After implementation is complete and tests pass, BEFORE committing:
+### 1. DIFF — Review What Changed
+- Run `git diff --staged` (or `git diff` for unstaged changes)
+- Read every line you are about to commit
+- Flag anything that feels "off" — trust that instinct
+```bash
+# Review staged changes
+git diff --staged
+# Or all uncommitted changes
+git diff
+```
+### 2. DUPLICATION — Find Reuse Opportunities
+- Does any new code duplicate existing logic in the codebase?
+- Are there two or more blocks that do similar things and could share a helper?
+- Could an existing utility, library function, or helper replace new code?
+- Is there copy-paste from another file that should be extracted?
+**Rule of three:** If the same pattern appears three times, extract it. Two occurrences are acceptable.
+### 3. DEAD CODE — Remove What Is Not Used
+- Are there unused imports, variables, or functions?
+- Are there commented-out code blocks? (Delete them — git has history)
+- Are there unreachable branches or impossible conditions?
+- Are there parameters that are always passed the same value?
+**If it is not called, it does not belong. Delete it.**
+### 4. COMPLEXITY — Question Every Abstraction
+- Is there a wrapper that adds no value beyond indirection?
+- Is there a generic solution where a specific one would be simpler?
+- Are there feature flags, configuration options, or extension points for hypothetical future needs?
+- Could a 3-line inline block replace a 20-line abstraction?
+**The right amount of abstraction is the minimum needed for the current requirements.**
+### 5. CLARITY — Improve Readability
+- Are variable and function names self-explanatory?
+- Could a confusing block be rewritten more clearly without comments?
+- Are there nested conditions that could be flattened with early returns?
+- Is the control flow straightforward or unnecessarily clever?
+### 6. EFFICIENCY — Check for Obvious Issues
+- Are there O(n^2) operations where O(n) is straightforward?
+- Are there repeated computations that could be cached or hoisted?
+- Are there unnecessary allocations in hot paths?
+- Is data being transformed multiple times when once would suffice?
+**Only fix efficiency issues that are obvious. Do not optimize without evidence of a problem.**
+## Review Checklist
+| Category | Question | Action if Yes |
+|----------|----------|---------------|
+| Duplication | Same logic exists elsewhere? | Extract shared helper or reuse existing |
+| Duplication | Copy-paste from another file? | Extract to shared module |
+| Dead code | Unused imports or variables? | Delete them |
+| Dead code | Commented-out code? | Delete it (git has history) |
+| Complexity | Abstraction for one call site? | Inline it |
+| Complexity | Generic where specific suffices? | Simplify to specific |
+| Complexity | Config for hypothetical needs? | Remove until needed |
+| Clarity | Confusing variable name? | Rename to describe purpose |
+| Clarity | Deep nesting? | Flatten with early returns |
+| Efficiency | O(n^2) with obvious O(n) fix? | Fix it now |
+| Efficiency | Same computation in a loop? | Hoist outside the loop |
+## Common Rationalizations — REJECT THESE
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "It works, don't touch it" | Working is the minimum bar. Simplify before it becomes legacy. |
+| "We might need the flexibility later" | YAGNI. Add flexibility when you need it, not before. |
+| "Refactoring is risky" | Small simplifications with passing tests are safe. Large refactors are a separate task. |
+| "The duplication is minor" | Minor duplication compounds. Three occurrences is the threshold, not six. |
+| "I'll clean it up in a follow-up" | Follow-ups rarely happen. Simplify now while context is fresh. |
+| "It's just a few extra lines" | Every unnecessary line is maintenance cost. Delete it. |
+## Red Flags — STOP If You Catch Yourself:
+- Committing without reading your own diff
+- Keeping dead code "just in case"
+- Adding a utility class for a single use case
+- Building configuration for features no one has requested
+- Writing a comment to explain code that could be rewritten to be self-evident
+- Skipping simplification because "it's good enough"
+**If any red flag triggers: STOP. Review the diff again. Simplify before committing.**
+## Verification Checklist
+Before committing, confirm:
+- [ ] All staged changes have been reviewed line by line
+- [ ] No duplication with existing codebase logic (or duplication is below threshold)
+- [ ] No dead code: unused imports, variables, unreachable branches, commented code
+- [ ] No unnecessary abstractions, wrappers, or premature generalizations
+- [ ] Naming is clear and consistent with codebase conventions
+- [ ] No obvious efficiency issues (unnecessary O(n^2), repeated computations)
+- [ ] Tests still pass after simplification changes
+## In MAXSIM Plan Execution
+Simplification applies at the task level, after implementation and before commit:
+- After task implementation is complete and tests pass, run this review
+- Make simplification changes as part of the same commit (not a separate task)
+- If simplification reveals a larger refactoring opportunity, file a todo — do not scope-creep
+- Track significant simplifications in the task's commit message (e.g., "extracted shared helper for X")

package/dist/assets/templates/skills/using-maxsim/SKILL.md ADDED Viewed

@@ -0,0 +1,115 @@
+---
+name: using-maxsim
+description: Entry skill that establishes MAXSIM workflow rules — triggers before any action to route work through the correct MAXSIM commands, skills, and agents
+---
+# Using MAXSIM
+MAXSIM is a spec-driven development system. Work flows through phases, plans, and tasks — not ad-hoc coding.
+**If you are about to write code without a plan, STOP. Route through MAXSIM first.**
+## The Iron Law
+<HARD-GATE>
+NO IMPLEMENTATION WITHOUT A PLAN.
+If there is no .planning/ directory, run `/maxsim:init` first.
+If there is no current phase, run `/maxsim:plan-phase` first.
+If there is no PLAN.md for the current phase, run `/maxsim:plan-phase` first.
+If there IS a plan, run `/maxsim:execute-phase` to execute it.
+Skipping the workflow is a violation — not a shortcut.
+</HARD-GATE>
+## When This Skill Triggers
+This skill applies to ALL work sessions. Before starting any task:
+1. **Check for `.planning/` directory** — if missing, initialize with `/maxsim:init`
+2. **Check STATE.md** — resume from last checkpoint if one exists
+3. **Check current phase** — determine what phase is active in ROADMAP.md
+4. **Route to the correct command** based on the situation (see routing table below)
+## Routing Table
+| Situation | Route To |
+|-----------|----------|
+| No `.planning/` directory | `/maxsim:init` |
+| No ROADMAP.md or empty roadmap | `/maxsim:plan-roadmap` |
+| Active phase has no PLAN.md | `/maxsim:plan-phase` |
+| Active phase has PLAN.md, not started | `/maxsim:execute-phase` |
+| Checkpoint exists in STATE.md | `/maxsim:resume-work` |
+| Bug found during execution | `/maxsim:debug` (triggers systematic-debugging skill) |
+| Phase complete, needs verification | `/maxsim:verify-phase` (triggers verification-before-completion skill) |
+| Quick standalone task | `/maxsim:quick` |
+| User asks for help | `/maxsim:help` |
+## Available Skills
+Skills are behavioral rules that activate automatically based on context:
+| Skill | Triggers When |
+|-------|---------------|
+| `systematic-debugging` | Any bug, test failure, or unexpected behavior encountered |
+| `tdd` | Implementing any feature or bug fix (write test first) |
+| `verification-before-completion` | Before claiming any work is complete or passing |
+| `memory-management` | Recurring patterns, errors, or decisions worth persisting |
+| `using-maxsim` | Always — entry point for all MAXSIM work |
+## Available Agents
+Agents are specialized subagent prompts spawned by MAXSIM commands:
+| Agent | Purpose | Triggered By |
+|-------|---------|-------------|
+| `maxsim-executor` | Executes plans with atomic commits | `/maxsim:execute-phase` |
+| `maxsim-planner` | Creates structured PLAN.md files | `/maxsim:plan-phase` |
+| `maxsim-debugger` | Investigates bugs systematically | `/maxsim:debug` |
+| `maxsim-verifier` | Verifies phase goal achievement | `/maxsim:verify-phase` |
+| `maxsim-roadmapper` | Creates project roadmaps | `/maxsim:plan-roadmap` |
+| `maxsim-phase-researcher` | Researches phase requirements | `/maxsim:plan-phase` |
+| `maxsim-code-reviewer` | Reviews code changes | `/maxsim:review` |
+| `maxsim-spec-reviewer` | Reviews specifications | `/maxsim:plan-roadmap` |
+| `maxsim-plan-checker` | Validates plan completeness | `/maxsim:plan-phase` |
+| `maxsim-project-researcher` | Researches project context | `/maxsim:init` |
+| `maxsim-research-synthesizer` | Synthesizes research findings | `/maxsim:plan-phase` |
+| `maxsim-codebase-mapper` | Maps codebase structure | `/maxsim:init` |
+| `maxsim-integration-checker` | Checks integration points | `/maxsim:verify-phase` |
+## Common Rationalizations — REJECT THESE
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "It's just a small fix" | Small fixes have context and consequences. Use `/maxsim:quick`. |
+| "I know what to do, I don't need a plan" | Plans catch what you miss. The plan is the checkpoint. |
+| "MAXSIM overhead is too much for this" | `/maxsim:quick` exists for lightweight tasks. Use it. |
+| "I'll plan it in my head" | Plans in your head die with context. Write them down. |
+| "The user said 'just do it'" | Route through `/maxsim:quick` — it is fast and still tracked. |
+## Red Flags — STOP If You Catch Yourself:
+- Writing implementation code without a PLAN.md
+- Skipping `/maxsim:init` because "the project is simple"
+- Ignoring STATE.md checkpoints from previous sessions
+- Working outside the current phase without explicit user approval
+- Making architectural decisions without documenting them in STATE.md
+- Finishing work without running verification
+**If any red flag triggers: STOP. Check the routing table. Follow the workflow.**
+## Verification Checklist
+Before ending any work session:
+- [ ] All work was routed through MAXSIM commands (not ad-hoc)
+- [ ] STATE.md reflects current progress and decisions
+- [ ] Any bugs encountered were debugged systematically (not guessed)
+- [ ] Tests were written before implementation (TDD)
+- [ ] Completion claims have verification evidence
+- [ ] Recurring patterns or errors were saved to memory
+## Integration with CLAUDE.md
+When a project has a `CLAUDE.md`, both apply:
+- `CLAUDE.md` defines project-specific conventions (language, tools, style)
+- MAXSIM skills define workflow rules (how work is structured and verified)
+- If they conflict, `CLAUDE.md` project conventions take priority for code style; MAXSIM takes priority for workflow structure