maxsimcli 3.5.3 → 3.7.0

package/dist/assets/templates/agents/maxsim-verifier.md

@@ -34,6 +34,17 @@ Goal-backward verification starts from the outcome and works backwards:
 3. What must be WIRED for those artifacts to function?
 
 Then verify each level against the actual codebase.
+
+**Evidence Gate:** Every verification finding must be backed by evidence:
+
+```
+CLAIM: [what you are verifying]
+EVIDENCE: [exact command or file read performed]
+OUTPUT: [relevant excerpt of actual output]
+VERDICT: PASS | FAIL
+```
+
+Do NOT state "verified" without producing an evidence block. Do NOT trust SUMMARY.md claims — verify against actual code and command output.
 </core_principle>
 
 <verification_process>
@@ -588,6 +599,38 @@ return <div>No messages</div>  // Always shows "no messages"
 
 </stub_detection_patterns>
 
+<anti_rationalization>
+
+## Iron Law
+
+<HARD-GATE>
+NO VERIFICATION PASS WITHOUT INDEPENDENT EVIDENCE FOR EVERY TRUTH.
+SUMMARY.md says it's done. CODE says otherwise. Trust the code.
+</HARD-GATE>
+
+## Common Rationalizations — REJECT THESE
+
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "SUMMARY says it's done" | SUMMARYs document what Claude SAID. You verify what EXISTS. |
+| "Task completed = goal achieved" | Task completion ≠ goal achievement. Verify the goal. |
+| "Tests pass = requirements met" | Tests can pass with incomplete implementation. Check requirements individually. |
+| "I trust the executor" | Trust is not verification. Check the code yourself. |
+| "The build succeeds" | A successful build does not prove functional correctness. |
+| "Most truths hold" | ALL truths must hold. Partial ≠ complete. |
+
+## Red Flags — STOP and reassess if you catch yourself:
+
+- About to mark a truth as "verified" without reading the actual code
+- Trusting SUMMARY.md claims without grep/read verification
+- Skipping a truth because "it was tested"
+- Writing "PASS" before checking every must_have individually
+- Feeling rushed to complete verification quickly
+
+**If any red flag triggers: STOP. Read the code. Run the command. Produce the evidence block. THEN make the claim.**
+
+</anti_rationalization>
+
 <success_criteria>
 
 - [ ] Previous VERIFICATION.md checked (Step 0)

package/dist/assets/templates/commands/maxsim/init-existing.md

@@ -0,0 +1,42 @@
+---
+name: maxsim:init-existing
+description: Initialize MAXSIM in an existing project with codebase scanning and smart defaults
+argument-hint: "[--auto]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+<context>
+**Flags:**
+- `--auto` — Automatic mode. Runs full codebase scan, infers everything from code, creates all docs without interaction. Review recommended after auto mode.
+</context>
+
+<objective>
+Initialize MAXSIM in an existing codebase through scan-first flow: codebase analysis, conflict resolution, scan-informed questioning, stage-aware document generation.
+
+**Creates:**
+- `.planning/codebase/` — full codebase analysis (4 mapper agents)
+- `.planning/PROJECT.md` — project context with current state summary
+- `.planning/config.json` — workflow preferences
+- `.planning/REQUIREMENTS.md` — stage-aware requirements
+- `.planning/ROADMAP.md` — milestone + suggested phases
+- `.planning/STATE.md` — pre-populated project memory
+
+**After this command:** Run `/maxsim:plan-phase 1` to start execution.
+</objective>
+
+<execution_context>
+@./workflows/init-existing.md
+@./references/questioning.md
+@./references/ui-brand.md
+@./templates/project.md
+@./templates/requirements.md
+</execution_context>
+
+<process>
+Execute the init-existing workflow from @./workflows/init-existing.md end-to-end.
+Preserve all workflow gates (conflict resolution, scan completion, validation, approvals, commits).
+</process>

package/dist/assets/templates/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior — requires root cause investigation before attempting any fix
+---
+
+# Systematic Debugging
+
+Random fixes waste time and create new bugs. Find the root cause first.
+
+**If you have not identified the root cause, you are guessing — not debugging.**
+
+## The Iron Law
+
+<HARD-GATE>
+NO FIX ATTEMPTS WITHOUT UNDERSTANDING ROOT CAUSE.
+If you have not completed the REPRODUCE and HYPOTHESIZE steps, you CANNOT propose a fix.
+"Let me just try this" is guessing, not debugging.
+Violating this rule is a violation — not a time-saving shortcut.
+</HARD-GATE>
+
+## The Gate Function
+
+Follow these steps IN ORDER for every bug, test failure, or unexpected behavior.
+
+### 1. REPRODUCE — Confirm the Problem
+
+- Run the failing command or test. Capture the EXACT error output.
+- Can you trigger it reliably? What are the exact steps?
+- If not reproducible: gather more data — do not guess.
+
+```bash
+# Example: reproduce a test failure
+npx vitest run path/to/failing.test.ts
+```
+
+### 2. HYPOTHESIZE — Form a Theory
+
+- Read the error message COMPLETELY (stack trace, line numbers, exit codes)
+- Check recent changes: `git diff`, recent commits, new dependencies
+- Trace data flow: where does the bad value originate?
+- State your hypothesis clearly: "I think X is the root cause because Y"
+
+### 3. ISOLATE — Narrow the Scope
+
+- Find the SMALLEST reproduction case
+- In multi-component systems, add diagnostic logging at each boundary
+- Identify which SPECIFIC layer or component is failing
+- Compare against working examples in the codebase
+
+### 4. VERIFY — Test Your Hypothesis
+
+- Make the SMALLEST possible change to test your hypothesis
+- Change ONE variable at a time — never multiple things simultaneously
+- If hypothesis is wrong: form a NEW hypothesis, do not stack fixes
+
+### 5. FIX — Address the Root Cause
+
+- Write a failing test that reproduces the bug (see TDD skill)
+- Implement a SINGLE fix that addresses the root cause
+- No "while I'm here" improvements — fix only the identified issue
+
+### 6. CONFIRM — Verify the Fix
+
+- Run the original failing test: it must now pass
+- Run the full test suite: no regressions
+- Verify the original error no longer occurs
+
+```bash
+# Confirm the specific fix
+npx vitest run path/to/fixed.test.ts
+# Confirm no regressions
+npx vitest run
+```
+
+## Common Rationalizations — REJECT THESE
+
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "I think I know what it is" | Thinking is not evidence. Reproduce first, then hypothesize. |
+| "Let me just try this fix" | "Just try" = guessing. You have skipped REPRODUCE and HYPOTHESIZE. |
+| "Quick patch for now, investigate later" | "Later" never comes. Patches mask the real problem. |
+| "Multiple changes at once saves time" | You cannot isolate what worked. You will create new bugs. |
+| "The issue is simple, I don't need the process" | Simple bugs have root causes too. The process is fast for simple bugs. |
+| "I'm under time pressure" | Systematic debugging IS faster than guess-and-check thrashing. |
+| "The reference is too long, I'll skim it" | Partial understanding guarantees partial fixes. Read it completely. |
+
+## Red Flags — STOP If You Catch Yourself:
+
+- Changing code before reproducing the error
+- Proposing a fix before reading the full error message and stack trace
+- Trying random fixes hoping one will work
+- Changing multiple things simultaneously
+- Saying "it's probably X" without evidence
+- Applying a fix that did not work, then adding another fix on top
+- On your 3rd failed fix attempt (this signals an architectural problem — escalate)
+
+**If any red flag triggers: STOP. Return to step 1 (REPRODUCE).**
+
+**If 3+ fix attempts have failed:** The issue is likely architectural, not a simple bug. Document what you have tried and escalate to the user for a design decision.
+
+## Verification Checklist
+
+Before claiming a bug is fixed, confirm:
+
+- [ ] The original error has been reproduced reliably
+- [ ] Root cause has been identified with evidence (not guessed)
+- [ ] A failing test reproduces the bug
+- [ ] A single, targeted fix addresses the root cause
+- [ ] The failing test now passes
+- [ ] The full test suite passes (no regressions)
+- [ ] The original error no longer occurs when running the original steps
+
+## Debugging in MAXSIM Context
+
+When debugging during plan execution, MAXSIM deviation rules apply:
+- **Rule 1 (Auto-fix bugs):** You may auto-fix bugs found during execution, but you must still follow this debugging process.
+- **Rule 4 (Architectural changes):** If 3+ fix attempts fail, STOP and return a checkpoint — this is an architectural decision for the user.
+- Track all debugging deviations for SUMMARY.md documentation.

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

@@ -0,0 +1,118 @@
+---
+name: tdd
+description: Use when implementing any feature or bug fix — requires writing a failing test before any implementation code
+---
+
+# Test-Driven Development (TDD)
+
+Write the test first. Watch it fail. Write minimal code to pass. Clean up.
+
+**If you did not watch the test fail, you do not know if it tests the right thing.**
+
+## The Iron Law
+
+<HARD-GATE>
+NO IMPLEMENTATION CODE WITHOUT A FAILING TEST FIRST.
+If you wrote production code before the test, DELETE IT. Start over.
+No exceptions. No "I'll add tests after." No "keep as reference."
+Violating this rule is a violation — not a judgment call.
+</HARD-GATE>
+
+## The Gate Function
+
+Follow this cycle for every behavior change, feature addition, or bug fix.
+
+### 1. RED — Write Failing Test
+
+- Write ONE minimal test that describes the desired behavior
+- Test name describes what SHOULD happen, not implementation details
+- Use real code paths — mocks only when unavoidable (external APIs, databases)
+
+### 2. VERIFY RED — Run the Test
+
+```bash
+# Run the test suite for this file
+npx vitest run path/to/test.test.ts
+```
+
+- Test MUST fail (not error — fail with an assertion)
+- Failure message must match the missing behavior
+- If test passes immediately: you are testing existing behavior — rewrite it
+
+### 3. GREEN — Write Minimal Code
+
+- Write the SIMPLEST code that makes the test pass
+- Do NOT add features the test does not require
+- Do NOT refactor yet — that comes next
+
+### 4. VERIFY GREEN — Run All Tests
+
+```bash
+npx vitest run
+```
+
+- The new test MUST pass
+- ALL existing tests MUST still pass
+- If any test fails: fix code, not tests
+
+### 5. REFACTOR — Clean Up (Tests Still Green)
+
+- Remove duplication, improve names, extract helpers
+- Run tests after every change — they must stay green
+- Do NOT add new behavior during refactor
+
+### 6. REPEAT — Next failing test for next behavior
+
+## Common Rationalizations — REJECT THESE
+
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "Too simple to test" | Simple code breaks. The test takes 30 seconds to write. |
+| "I'll add tests after" | Tests written after pass immediately — they prove nothing. |
+| "The test framework isn't set up yet" | Set it up. That is part of the task, not a reason to skip. |
+| "I know the code works" | Knowledge is not evidence. A passing test is evidence. |
+| "TDD is slower for this task" | TDD is faster than debugging. Every "quick skip" creates debt. |
+| "Let me keep the code as reference" | You will adapt it instead of writing test-first. Delete means delete. |
+| "I need to explore the design first" | Explore, then throw it away. Start implementation with TDD. |
+
+## Red Flags — STOP If You Catch Yourself:
+
+- Writing implementation code before writing a test
+- Writing a test that passes on the first run (you are testing existing behavior)
+- Skipping the VERIFY RED step ("I know it will fail")
+- Adding features beyond what the current test requires
+- Skipping the REFACTOR step to save time
+- Rationalizing "just this once" or "this is different"
+- Keeping pre-TDD code "as reference" while writing tests
+
+**If any red flag triggers: STOP. Delete the implementation. Write the test first.**
+
+## Verification Checklist
+
+Before claiming TDD compliance, confirm:
+
+- [ ] Every new function/method has a corresponding test
+- [ ] Each test was written BEFORE its implementation
+- [ ] Each test was observed to FAIL before implementation was written
+- [ ] Each test failed for the expected reason (missing behavior, not syntax error)
+- [ ] Minimal code was written to pass each test
+- [ ] All tests pass after implementation
+- [ ] Refactoring (if any) did not break any tests
+
+Cannot check all boxes? You skipped TDD. Start over.
+
+## When Stuck
+
+| Problem | Solution |
+|---------|----------|
+| Don't know how to test it | Write the assertion first. What should the output be? |
+| Test setup is too complex | The design is too complex. Simplify the interface. |
+| Must mock everything | Code is too coupled. Use dependency injection. |
+| Existing code has no tests | Add tests for the code you are changing. Start the cycle now. |
+
+## Integration with MAXSIM
+
+In MAXSIM plan execution, tasks marked `tdd="true"` follow this cycle with per-step commits:
+- **RED commit:** `test({phase}-{plan}): add failing test for [feature]`
+- **GREEN commit:** `feat({phase}-{plan}): implement [feature]`
+- **REFACTOR commit (if changes made):** `refactor({phase}-{plan}): clean up [feature]`

package/dist/assets/templates/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: verification-before-completion
+description: Use before claiming any work is complete, fixed, or passing — requires running verification commands and reading output before making success claims
+---
+
+# Verification Before Completion
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Evidence before claims, always.**
+
+## The Iron Law
+
+<HARD-GATE>
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.
+If you have not run the verification command in this turn, you CANNOT claim it passes.
+"Should work" is not evidence. "I'm confident" is not evidence.
+Violating this rule is a violation — not a special case.
+</HARD-GATE>
+
+## The Gate Function
+
+BEFORE claiming any status, expressing satisfaction, or marking a task done:
+
+1. **IDENTIFY:** What command proves this claim?
+2. **RUN:** Execute the FULL command (fresh, in this turn — not a previous run)
+3. **READ:** Read the FULL output. Check the exit code. Count failures.
+4. **VERIFY:** Does the output actually confirm the claim?
+   - If NO: State the actual status with evidence
+   - If YES: State the claim WITH the evidence
+5. **CLAIM:** Only now may you assert completion
+
+**Skip any step = lying, not verifying.**
+
+### Evidence Block Format
+
+When claiming task completion, build completion, or test passage, produce:
+
+```
+CLAIM: [what you are claiming]
+EVIDENCE: [exact command run in this turn]
+OUTPUT: [relevant excerpt of actual output]
+VERDICT: PASS | FAIL
+```
+
+This format is required for task completion claims in MAXSIM plan execution. It is NOT required for intermediate status updates like "I have read the file" or "here is the plan."
+
+## Common Rationalizations — REJECT THESE
+
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "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. |
+| "Just this once" | NO EXCEPTIONS. This is the rule, not a guideline. |
+| "I only changed one line" | One line can break everything. Verify. |
+| "The subagent reported success" | Trust test output and VCS diffs, not agent reports. |
+| "Partial check is enough" | Partial proves nothing about the unchecked parts. |
+
+## Red Flags — STOP If You Catch Yourself:
+
+- Using "should", "probably", "seems to", or "looks good" about unverified work
+- Expressing satisfaction ("Great!", "Perfect!", "Done!") before running verification
+- About to commit or push without running the test/build command in THIS turn
+- Trusting a subagent's completion report without independent verification
+- Thinking "the last run was clean, I only changed one line"
+- About to mark a MAXSIM task as done without running the `<verify>` block
+- Relying on a previous turn's test output as current evidence
+
+**If any red flag triggers: STOP. Run the command. Read the output. THEN make the claim.**
+
+## What Counts as Verification
+
+| 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 is complete" | All done criteria checked with evidence | "I implemented everything in the plan" |
+| "No regressions" | Full test suite passing | "I only changed one file" |
+
+## Verification Checklist
+
+Before marking any work as complete:
+
+- [ ] Identified the verification command for every claim
+- [ ] Ran each verification command fresh in this turn
+- [ ] Read the full output (not just the summary line)
+- [ ] Checked exit codes (0 = success, non-zero = failure)
+- [ ] Evidence supports every completion claim
+- [ ] No "should", "probably", or "seems to" in your completion statement
+- [ ] Evidence block produced for the task completion claim
+
+## In MAXSIM Plan Execution
+
+The executor's task commit protocol requires verification BEFORE committing:
+1. Run the task's `<verify>` block (automated checks)
+2. Confirm the `<done>` criteria are met with evidence
+3. Produce an evidence block for the task completion
+4. Only then: stage files and commit
+
+The verifier agent independently re-checks all claims — do not assume the verifier will catch what you missed.