maxsimcli 4.8.0 → 4.9.0

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

@@ -1,83 +1,69 @@
 ---
 name: using-maxsim
-alwaysApply: true
 description: >-
-  Routes all work through MAXSIM's spec-driven workflow: checks for planning
-  directory, determines active phase, and dispatches to the correct MAXSIM
-  command. Use when starting any work session, resuming work, or when unsure
-  which MAXSIM command to run.
+  Routes work through MAXSIM's spec-driven workflow: checks planning state,
+  determines active phase, dispatches to the correct MAXSIM command. Use when
+  starting work sessions, resuming work, or choosing which MAXSIM command to run.
 ---
 
 # Using MAXSIM
 
 MAXSIM is a spec-driven development system. Work flows through phases, plans, and tasks -- not ad-hoc coding.
 
-**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.
+**No implementation without a plan.** If there is no `.planning/` directory, run `/maxsim:init` first. If there is no current phase, run `/maxsim:plan` first. If there IS a plan, run `/maxsim:execute` to execute it.
 
-## Process
+## Routing
 
 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 routing table below
+4. **Route to the correct command** based on the table below
 
-### Routing Table
+### Command Surface (9 commands)
 
-| Situation | Route To |
-|-----------|----------|
+| Situation | Command |
+|-----------|---------|
 | 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` |
+| No ROADMAP.md or empty roadmap | `/maxsim:init` |
+| Active phase has no PLAN.md | `/maxsim:plan N` |
+| Active phase has PLAN.md, not started | `/maxsim:execute N` |
+| Phase complete, needs verification | `/maxsim:execute N` (auto-verifies) |
 | Bug found during execution | `/maxsim:debug` |
-| Phase complete, needs verification | `/maxsim:verify-phase` |
 | Quick standalone task | `/maxsim:quick` |
-| User asks for help | `/maxsim:help` |
+| Check overall status | `/maxsim:progress` |
+| Don't know what to do next | `/maxsim:go` |
+| Change workflow settings | `/maxsim:settings` |
+| Need command reference | `/maxsim:help` |
 
-### Available Skills
+### Agent Model (4 agents)
 
-Skills are behavioral rules that activate automatically based on context:
+MAXSIM uses 4 generic agent types. Specialization comes from the orchestrator's spawn prompt and on-demand skills, not from separate agent definitions.
 
-| Skill | Triggers When |
-|-------|---------------|
-| `using-maxsim` | Always (alwaysApply) -- entry point for all MAXSIM work |
-| `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 |
+| Agent | Role | Spawned By |
+|-------|------|-----------|
+| Executor | Implements plans with atomic commits and verified completion | `/maxsim:execute` |
+| Planner | Creates structured PLAN.md files from requirements | `/maxsim:plan` |
+| Researcher | Gathers domain knowledge and codebase context | `/maxsim:plan` (research stage) |
+| Verifier | Reviews code, checks specs, debugs failures | `/maxsim:execute` (review stage), `/maxsim:debug` |
+
+### Skills
+
+Skills load on-demand based on description matching or direct `/skill-name` invocation. They are not auto-loaded -- each skill activates only when its content is relevant to the current task.
+
+| Skill | When It Activates |
+|-------|-------------------|
+| `systematic-debugging` | Investigating bugs, test failures, or unexpected behavior |
+| `tdd` | Implementing business logic, APIs, data transformations |
+| `verification-before-completion` | Claiming work is done, tests pass, builds succeed |
 | `memory-management` | Recurring patterns, errors, or decisions worth persisting |
-| `brainstorming` | Before implementing any significant feature or design |
-| `roadmap-writing` | When creating or restructuring a project roadmap |
-| `maxsim-simplify` | Maintainability pass: reviewing code for duplication, dead code, and unnecessary complexity |
-| `code-review` | Correctness gate: reviewing implementation for security, interfaces, errors, and test coverage |
-| `sdd` | Executing sequential tasks where context rot is a concern (spec-driven dispatch) |
-| `maxsim-batch` | Parallelizing work across 3-30 independent units in isolated worktrees |
-
-### 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` |
+| `brainstorming` | Facing architectural choices or design decisions |
+| `roadmap-writing` | Creating or restructuring a project roadmap |
+| `maxsim-simplify` | Reviewing code for duplication, dead code, complexity |
+| `code-review` | Reviewing implementation for security, interfaces, quality |
+| `sdd` | Executing sequential tasks with fresh-agent isolation |
+| `maxsim-batch` | Parallelizing work across independent worktree units |
 
 ## Common Pitfalls
 
@@ -86,24 +72,7 @@ Agents are specialized subagent prompts spawned by MAXSIM commands:
 - 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 of these occur: stop, check the routing table, follow the workflow.**
 
-## Verification
-
-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
-- [ ] Tests were written before implementation (TDD)
-- [ ] Completion claims have verification evidence
-- [ ] Recurring patterns or errors were saved to memory
-
-## MAXSIM Integration
-
-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` takes priority for code style; MAXSIM takes priority for workflow structure
+See also: `/verification-before-completion` for evidence-based completion claims.

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

@@ -1,27 +1,24 @@
 ---
 name: verification-before-completion
 description: >-
-  Requires running verification commands and reading actual output before making
-  any completion claims. Use when claiming work is done, tests pass, builds
-  succeed, or bugs are fixed. Prevents false completion claims.
+  Requires running verification commands and reading actual output before
+  completion claims. Covers the 5-step verification process and evidence block
+  format. Use when claiming work is done, tests pass, builds succeed, or bugs
+  are fixed.
 ---
 
 # Verification Before Completion
 
-Evidence before claims, always.
+Evidence before claims, always. No exceptions.
 
-**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.**
-
-## Process
+## The 5-Step Process
 
 Before claiming any status 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)
+2. **RUN** -- Execute the 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
+4. **VERIFY** -- Does the output actually confirm the claim? If NO: state the actual status with evidence. If YES: proceed.
 5. **CLAIM** -- Only now may you assert completion
 
 ### Evidence Block Format
@@ -35,9 +32,9 @@ 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.
+This format is required for task completion claims in MAXSIM plan execution.
 
-### What Counts as Verification
+## What Counts as Verification
 
 | Claim | Requires | Not Sufficient |
 |-------|----------|----------------|
@@ -59,7 +56,7 @@ This format is required for task completion claims in MAXSIM plan execution. It
 
 Stop if you catch yourself using "should", "probably", or "looks good" about unverified work, or expressing satisfaction before running verification.
 
-## Verification
+## Verification Checklist
 
 Before marking any work as complete:
 
@@ -71,13 +68,4 @@ Before marking any work as complete:
 - [ ] No "should", "probably", or "seems to" in your completion statement
 - [ ] Evidence block produced for the task completion claim
 
-## MAXSIM Integration
-
-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.
+See also: `/verification-gates` for the full gate framework with retry logic and escalation protocol.

package/dist/assets/templates/skills/verification-gates/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: verification-gates
+description: >-
+  Hard gate framework for evidence-based verification. Defines four gate types
+  (input validation, pre-action, completion, quality), retry logic with feedback,
+  anti-rationalization enforcement, and escalation protocol. Use when implementing
+  verification checkpoints, completion gates, or quality checks.
+user-invocable: false
+---
+
+# Verification Gates
+
+Evidence before claims, always. No exceptions.
+
+## Gate Types
+
+### 1. Input Validation Gate
+
+**When:** Before starting any work.
+**Purpose:** Verify all required inputs exist (files, env vars, CLI args, state).
+
+**Evidence required:**
+- File existence checks (`test -f path`)
+- Environment variable checks
+- State file readability
+
+**On failure:** Return structured error immediately. Do NOT attempt partial work.
+
+```
+AGENT RESULT: INPUT VALIDATION FAILED
+Missing: [list of missing inputs]
+Expected from: [source -- orchestrator, user, prior agent]
+```
+
+### 2. Pre-Action Gate
+
+**When:** Before destructive actions (file writes, git commits, PRs, deployments).
+**Purpose:** Verify intent and impact before irreversible changes.
+
+**Evidence required:**
+- State what will be changed
+- Confirm target files/branches are correct
+- Verify no unintended side effects (e.g., `git status` before commit)
+
+**On failure:** Abort the action. Report what was wrong and what would have happened.
+
+### 3. Completion Gate
+
+**When:** Before claiming any task, plan, or phase is done.
+**Purpose:** Verify all done criteria are met with fresh tool output.
+
+**HARD GATE -- No completion claims without fresh verification evidence.**
+
+Do NOT pass this gate by arguing it's "close enough", "minor issue", or "will fix later".
+Either evidence passes or it fails. No middle ground.
+Partial success is failure. "Good enough" is not enough.
+
+If you have not run the verification command in THIS turn, you cannot claim it passes.
+
+**Evidence required:**
+- Run every verification command from the task's verify block
+- Check every item in the done criteria list
+- Produce an evidence block for each claim
+
+### 4. Quality Gate
+
+**When:** After implementation, before marking work as shippable.
+**Purpose:** Verify code quality standards are met.
+
+**Evidence required:**
+- Test suite output (all passing, zero failures)
+- Build output (exit code 0)
+- Lint output (zero errors -- warnings acceptable if project allows)
+
+**On failure:** Fix quality issues before proceeding. Do not defer quality failures.
+
+## Anti-Rationalization
+
+FORBIDDEN PHRASES -- if you catch yourself using these, STOP. You are rationalizing:
+
+- "should work"
+- "probably passes"
+- "I'm confident that..."
+- "based on my analysis..."
+- "the logic suggests..."
+- "it's reasonable to assume..."
+
+These phrases replace evidence with reasoning. The gate requires tool output, not arguments.
+
+Additional forbidden rationalizations:
+- "It's close enough" -- close is not done
+- "Minor issue, will fix later" -- later is never
+- "The logic is correct so it must pass" -- run it and find out
+- "I already verified this in a previous step" -- previous steps are stale; verify now
+
+## Evidence Standard
+
+Any tool output qualifies as evidence: test output, build results, git diff, file reads, linter output, command exit codes.
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| "Tests pass" | Test command output showing 0 failures | Previous run, "should pass" |
+| "Build succeeds" | Build command with exit code 0 | Linter passing only |
+| "Bug is fixed" | Original failing test now passes | "Code changed, assumed fixed" |
+| "Task complete" | All done criteria checked with evidence | "I implemented everything" |
+| "No regressions" | Full test suite passing | "I only changed one file" |
+| "File created" | `test -f path` or Read tool output | "I wrote it with Write tool" |
+
+## Evidence Block Format
+
+```
+CLAIM: [what you are claiming]
+EVIDENCE: [exact command run in THIS turn]
+OUTPUT: [relevant excerpt of actual output]
+VERDICT: PASS | FAIL
+```
+
+Produce one evidence block per claim. Group related claims if verified by the same command.
+
+## Retry Protocol
+
+Maximum 2 retries (3 total attempts) per gate.
+
+**Retry feedback loop:**
+1. Gate fails -- capture: what failed, expected result, actual result
+2. Analyze the failure output (do not guess; read the error)
+3. Fix the identified issue
+4. Re-run the verification command
+5. Produce a new evidence block
+
+Each retry MUST include in its evidence block:
+- Attempt number (1/3, 2/3, 3/3)
+- What changed since last attempt
+- Fresh verification output
+
+**After 3rd failure -- escalation:**
+
+Return full failure context to orchestrator:
+
+```markdown
+## GATE FAILURE -- ESCALATION
+
+**Gate:** [gate type]
+**Attempts:** 3/3
+**Final evidence:**
+CLAIM: [claim]
+EVIDENCE: [command]
+OUTPUT: [output]
+VERDICT: FAIL
+
+**History:**
+- Attempt 1: [what failed, what was tried]
+- Attempt 2: [what failed, what was tried]
+- Attempt 3: [what failed -- escalating]
+
+**Recommended action:** [what the orchestrator or user should do]
+```
+
+## Audit Trail
+
+Log every gate attempt to GitHub Issues as a comment on the active phase issue:
+
+- Gate name and type
+- Attempt number
+- Evidence provided (abbreviated)
+- PASS or FAIL result
+- Timestamp
+
+This creates an auditable record of all verification activity for debugging and improvement.

package/dist/assets/templates/templates/UAT.md

@@ -98,7 +98,7 @@ skipped: [N]
 **Gaps:**
 - APPEND only when issue found (YAML format)
 - After diagnosis: fill `root_cause`, `artifacts`, `missing`, `debug_session`
-- This section feeds directly into /maxsim:plan-phase --gaps
+- This section feeds directly into /maxsim:plan --gaps
 
 </section_rules>
 
@@ -112,7 +112,7 @@ skipped: [N]
 4. UAT.md Gaps section updated with diagnosis:
    - Each gap gets `root_cause`, `artifacts`, `missing`, `debug_session` filled
 5. status → "diagnosed"
-6. Ready for /maxsim:plan-phase --gaps with root causes
+6. Ready for /maxsim:plan --gaps with root causes
 
 **After diagnosis:**
 ```yaml
@@ -136,7 +136,7 @@ skipped: [N]
 
 <lifecycle>
 
-**Creation:** When /maxsim:verify-work starts new session
+**Creation:** When /maxsim:execute (verification) starts new session
 - Extract tests from SUMMARY.md files
 - Set status to "testing"
 - Current Test points to test 1

package/dist/assets/templates/templates/VALIDATION.md

@@ -29,7 +29,7 @@ created: {date}
 
 - **After every task commit:** Run `{quick run command}`
 - **After every plan wave:** Run `{full suite command}`
-- **Before `/maxsim:verify-work`:** Full suite must be green
+- **Before `/maxsim:execute (verification)`:** Full suite must be green
 - **Max feedback latency:** {N} seconds
 
 ---

package/dist/assets/templates/templates/context.md

@@ -7,8 +7,8 @@ Template for `.planning/phases/XX-name/{phase_num}-CONTEXT.md` - captures implem
 **Key principle:** Categories are NOT predefined. They emerge from what was actually discussed for THIS phase. A CLI phase has CLI-relevant sections, a UI phase has UI-relevant sections.
 
 **Downstream consumers:**
-- `maxsim-phase-researcher` — Reads decisions to focus research (e.g., "card layout" → research card component patterns)
-- `maxsim-planner` — Reads decisions to create specific tasks (e.g., "infinite scroll" → task includes virtualization)
+- `researcher` — Reads decisions to focus research (e.g., "card layout" -> research card component patterns)
+- `planner` — Reads decisions to create specific tasks (e.g., "infinite scroll" -> task includes virtualization)
 
 ---
 
@@ -277,7 +277,7 @@ The output should answer: "What does the researcher need to investigate? What ch
 
 **After creation:**
 - File lives in phase directory: `.planning/phases/XX-name/{phase_num}-CONTEXT.md`
-- `maxsim-phase-researcher` uses decisions to focus investigation
-- `maxsim-planner` uses decisions + research to create executable tasks
+- `researcher` uses decisions to focus investigation
+- `planner` uses decisions + research to create executable tasks
 - Downstream agents should NOT need to ask the user again about captured decisions
 </guidelines>

package/dist/assets/templates/templates/debug-subagent-prompt.md

@@ -1,6 +1,6 @@
 # Debug Subagent Prompt Template
 
-Template for spawning maxsim-debugger agent. The agent contains all debugging expertise - this template provides problem context only.
+Template for spawning verifier agent in debug mode. The agent contains all debugging expertise - this template provides problem context only.
 
 ---
 
@@ -55,14 +55,14 @@ Create: .planning/debug/{slug}.md
 ```python
 Task(
   prompt=filled_template,
-  subagent_type="maxsim-debugger",
+  subagent_type="verifier",
   description="Debug {slug}"
 )
 ```
 
 **From diagnose-issues (UAT):**
 ```python
-Task(prompt=template, subagent_type="maxsim-debugger", description="Debug UAT-001")
+Task(prompt=template, subagent_type="verifier", description="Debug UAT-001")
 ```
 
 ---

package/dist/assets/templates/templates/discovery.md

@@ -4,7 +4,7 @@ Template for `.planning/phases/XX-name/DISCOVERY.md` - shallow research for libr
 
 **Purpose:** Answer "which library/option should we use" questions during mandatory discovery in plan-phase.
 
-For deep ecosystem research ("how do experts build this"), use `/maxsim:research-phase` which produces RESEARCH.md.
+For deep ecosystem research ("how do experts build this"), use `/maxsim:plan --research` which produces RESEARCH.md.
 
 ---
 
@@ -142,5 +142,5 @@ Create `.planning/phases/XX-name/DISCOVERY.md`:
 - Niche/complex domains (3D, games, audio, shaders)
 - Need ecosystem knowledge, not just library choice
 - "How do experts build this" questions
-- Use `/maxsim:research-phase` for these
+- Use `/maxsim:plan --research` for these
 </guidelines>

package/dist/assets/templates/templates/phase-prompt.md

@@ -1,6 +1,6 @@
 # Phase Prompt Template
 
-> **Note:** Planning methodology is in `agents/maxsim-planner.md`.
+> **Note:** Planning methodology is in `agents/planner.md`.
 > This template defines the PLAN.md output format that the agent produces.
 
 Template for `.planning/phases/XX-name/{phase}-{plan}-PLAN.md` - executable phase plans optimized for parallel execution.
@@ -134,7 +134,7 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 | `user_setup` | No | Array of human-required setup items (external services) |
 | `must_haves` | Yes | Goal-backward verification criteria (see below) |
 
-**Wave is pre-computed:** Wave numbers are assigned during `/maxsim:plan-phase`. Execute-phase reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.
+**Wave is pre-computed:** Wave numbers are assigned during `/maxsim:plan`. Execute-phase reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.
 
 **Must-haves enable verification:** The `must_haves` field carries goal-backward requirements from planning to execution. After all plans complete, execute-phase spawns a verification subagent that checks these criteria against the actual codebase.
 

package/dist/assets/templates/templates/planner-subagent-prompt.md

@@ -1,6 +1,6 @@
 # Planner Subagent Prompt Template
 
-Template for spawning maxsim-planner agent. The agent contains all planning expertise - this template provides planning context only.
+Template for spawning planner agent. The agent contains all planning expertise - this template provides planning context only.
 
 ---
 
@@ -34,7 +34,7 @@ Template for spawning maxsim-planner agent. The agent contains all planning expe
 </planning_context>
 
 <downstream_consumer>
-Output consumed by /maxsim:execute-phase
+Output consumed by /maxsim:execute
 Plans must be executable prompts with:
 - Frontmatter (wave, depends_on, files_modified, autonomous)
 - Tasks in XML format
@@ -68,20 +68,20 @@ Before returning PLANNING COMPLETE:
 
 ## Usage
 
-**From /maxsim:plan-phase (standard mode):**
+**From /maxsim:plan (standard mode):**
 ```python
 Task(
   prompt=filled_template,
-  subagent_type="maxsim-planner",
+  subagent_type="planner",
   description="Plan Phase {phase}"
 )
 ```
 
-**From /maxsim:plan-phase --gaps (gap closure mode):**
+**From /maxsim:plan --gaps (gap closure mode):**
 ```python
 Task(
   prompt=filled_template,  # with mode: gap_closure
-  subagent_type="maxsim-planner",
+  subagent_type="planner",
   description="Plan gaps for Phase {phase}"
 )
 ```
@@ -114,4 +114,4 @@ Continue: {standard | gap_closure}
 
 ---
 
-**Note:** Planning methodology, task breakdown, dependency analysis, wave assignment, TDD detection, and goal-backward derivation are baked into the maxsim-planner agent. This template only passes context.
+**Note:** Planning methodology, task breakdown, dependency analysis, wave assignment, TDD detection, and goal-backward derivation are baked into the planner agent. This template only passes context.

package/dist/assets/templates/templates/project.md

@@ -170,7 +170,7 @@ PROJECT.md evolves throughout the project lifecycle.
 
 For existing codebases:
 
-1. **Map codebase first** via `/maxsim:map-codebase`
+1. **Map codebase first** via `/maxsim:init (codebase mapping)`
 
 2. **Infer Validated requirements** from existing code:
    - What does the codebase actually do?

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

@@ -18,7 +18,7 @@ Template for `.planning/phases/XX-name/{phase_num}-RESEARCH.md` - comprehensive
 <user_constraints>
 ## User Constraints (from CONTEXT.md)
 
-**CRITICAL:** If CONTEXT.md exists from /maxsim:discuss-phase, copy locked decisions here verbatim. These MUST be honored by the planner.
+**CRITICAL:** If CONTEXT.md exists from /maxsim:plan (discussion stage), copy locked decisions here verbatim. These MUST be honored by the planner.
 
 ### Locked Decisions
 [Copy from CONTEXT.md `## Decisions` section - these are NON-NEGOTIABLE]

package/dist/assets/templates/templates/state.md

@@ -145,10 +145,10 @@ Updated after each plan completion.
 
 **Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
 
-**Pending Todos:** Ideas captured via /maxsim:add-todo
+**Pending Todos:** Ideas captured via /maxsim:quick --todo
 - Count of pending todos
 - Reference to .planning/todos/pending/
-- Brief list if few, count if many (e.g., "5 pending todos — see /maxsim:check-todos")
+- Brief list if few, count if many (e.g., "5 pending todos — see /maxsim:quick --todo")
 
 **Blockers/Concerns:** From "Next Phase Readiness" sections
 - Issues that affect future work

package/dist/assets/templates/templates/summary.md

@@ -109,6 +109,28 @@ _Note: TDD tasks may have multiple commits (test → feat → refactor)_
 
 [Note: "Deviations from Plan" documents unplanned work that was handled automatically via deviation rules. "Issues Encountered" documents problems during planned work that required problem-solving.]
 
+## Review Cycle
+
+| Stage | Result | Attempts | Duration | Findings |
+|-------|--------|----------|----------|----------|
+| Spec Review | {PASS|FAIL|OVERRIDDEN} | {N}/3 | {X}s | {summary or "All requirements met"} |
+| Code Review | {APPROVED|BLOCKED|OVERRIDDEN} | {N}/3 | {X}s | {summary or "No blocking issues"} |
+| Simplify | {CLEAN|FIXED|BLOCKED|SKIPPED|OVERRIDDEN} | {N}/3 | {X}s | {summary or "N/A"} |
+| Final Review | {APPROVED|BLOCKED|SKIPPED|N/A|OVERRIDDEN} | {N}/3 | {X}s | {summary or "N/A"} |
+
+**Total review time:** {total}s
+**Escalations:** {count} ({details or "None"})
+
+[Populated by the executor after the review cycle completes. See execute-plan.md review_cycle step for stage definitions and retry/escalation protocol.]
+
+## Requirement Evidence
+
+| Requirement | Evidence | Status |
+|-------------|----------|--------|
+| {REQ-ID from plan frontmatter} | {specific file/test/behavior that satisfies it} | {MET|PARTIAL|UNMET} |
+
+[Populated by the executor during SUMMARY creation using the `requirements` array from the PLAN.md frontmatter. Each requirement ID from the plan must have an evidence entry. If no requirements field in plan frontmatter, this section can be omitted.]
+
 ## User Setup Required
 
 [If USER-SETUP.md was generated:]
@@ -224,6 +246,25 @@ The one-liner should tell someone what actually shipped.
 ## Issues Encountered
 - jsonwebtoken CommonJS import failed in Edge runtime - switched to jose (planned library change, worked as expected)
 
+## Review Cycle
+
+| Stage | Result | Attempts | Duration | Findings |
+|-------|--------|----------|----------|----------|
+| Spec Review | PASS | 1/3 | 45s | All requirements met |
+| Code Review | APPROVED | 2/3 | 82s | Fixed missing error handler on login endpoint (attempt 1) |
+| Simplify | FIXED | 1/3 | 67s | Extracted shared JWT helper, removed unused bcrypt import |
+| Final Review | APPROVED | 1/3 | 38s | Simplification changes verified |
+
+**Total review time:** 232s
+**Escalations:** 0 (None)
+
+## Requirement Evidence
+
+| Requirement | Evidence | Status |
+|-------------|----------|--------|
+| AUTH-01 | src/app/api/auth/login/route.ts implements JWT login with refresh | MET |
+| AUTH-02 | src/middleware.ts validates tokens on protected routes | MET |
+
 ## Next Phase Readiness
 - Auth foundation complete, ready for feature development
 - User registration endpoint needed before public launch