maxsimcli 3.11.0 → 4.0.0

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

@@ -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

@@ -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/roadmap-writing/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: roadmap-writing
+description: Use when creating or restructuring a project roadmap — requires phased planning with dependencies, success criteria, and MAXSIM-compatible format
+---
+
+# Roadmap Writing
+
+A roadmap without success criteria is a wish list. Define what done looks like for every phase.
+
+**If a phase does not have measurable success criteria, it is not a plan — it is a hope.**
+
+## The Iron Law
+
+<HARD-GATE>
+NO PHASE WITHOUT SUCCESS CRITERIA AND DEPENDENCIES.
+Every phase MUST have: a number, a name, a goal, success criteria (testable statements), and explicit dependencies.
+"We'll figure it out as we go" is not planning — it is drifting.
+Violating this rule is a violation — not flexibility.
+</HARD-GATE>
+
+## The Gate Function
+
+Follow these steps IN ORDER when creating or restructuring a roadmap.
+
+### 1. SCOPE — Understand the Project
+
+Before writing phases, understand what you are planning:
+
+- Read PROJECT.md for vision and constraints
+- Read REQUIREMENTS.md for v1/v2/out-of-scope boundaries
+- Check existing STATE.md for decisions and blockers
+- Identify the delivery target (MVP, v1, v2, etc.)
+
+```bash
+# Load project context
+node ~/.claude/maxsim/bin/maxsim-tools.cjs state read --raw
+
+# Check existing roadmap (if any)
+node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap read --raw
+```
+
+### 2. DECOMPOSE — Break Into Phases
+
+Each phase should be:
+
+| Property | Requirement |
+|----------|------------|
+| **Independently deliverable** | The phase produces a working increment — not a half-built feature |
+| **1-3 days of work** | Larger phases should be split; smaller ones should be merged |
+| **Clear boundary** | You can tell when the phase is done without ambiguity |
+| **Ordered by dependency** | No phase depends on a later phase |
+
+**Phase numbering convention:**
+
+| Format | When to Use |
+|--------|------------|
+| `01`, `02`, `03` | Standard sequential phases |
+| `01A`, `01B` | Parallel sub-phases that can execute concurrently |
+| `01.1`, `01.2` | Sequential sub-phases within a parent phase |
+
+Sort order: `01 < 01A < 01B < 01.1 < 01.2 < 02`
+
+### 3. DEFINE — Write Each Phase
+
+Every phase MUST include all of these fields:
+
+```markdown
+### Phase {number}: {name}
+**Goal**: {one sentence — what this phase achieves}
+**Depends on**: {phase numbers, or "Nothing" for the first phase}
+**Requirements**: {requirement IDs from REQUIREMENTS.md, if applicable}
+**Success Criteria** (what must be TRUE):
+  1. {Testable statement — can be verified with a command, test, or inspection}
+  2. {Testable statement}
+  3. {Testable statement}
+**Plans**: TBD
+```
+
+**Success criteria rules:**
+- Each criterion must be testable — "code is clean" is not testable; "no lint warnings" is testable
+- Include at least 2 criteria per phase
+- At least one criterion should be verifiable by running a command (test, build, lint)
+- Criteria describe the END STATE, not the process ("tests pass" not "write tests")
+
+### 4. CONNECT — Map Dependencies
+
+Draw the dependency graph:
+- Which phases can run in parallel? (Use letter suffixes: `03A`, `03B`)
+- Which phases are strictly sequential? (Use number suffixes: `03.1`, `03.2`)
+- Are there any circular dependencies? (This is a design error — restructure)
+
+**Rule: Every phase except the first must declare at least one dependency.**
+
+### 5. MILESTONE — Group Into Milestones
+
+Group phases into milestones that represent user-visible releases:
+
+```markdown
+## Milestones
+
+- **v1.0 MVP** — Phases 1-4
+- **v1.1 Polish** — Phases 5-7
+- **v2.0 Scale** — Phases 8-10
+```
+
+Each milestone should be a coherent deliverable that could ship independently.
+
+### 6. WRITE — Produce the Roadmap
+
+Assemble the complete ROADMAP.md:
+
+```markdown
+# Roadmap: {project name}
+
+## Overview
+
+{2-3 sentences: what the project is, what this roadmap covers, delivery strategy}
+
+## Milestones
+
+- {emoji} **{milestone name}** — Phases {range} ({status})
+
+## Phases
+
+- [ ] **Phase {N}: {name}** - {one-line summary}
+
+## Phase Details
+
+### Phase {N}: {name}
+**Goal**: ...
+**Depends on**: ...
+**Requirements**: ...
+**Success Criteria** (what must be TRUE):
+  1. ...
+**Plans**: TBD
+```
+
+### 7. VALIDATE — Check the Roadmap
+
+Before finalizing, verify:
+
+```bash
+# Write the roadmap (creates or overwrites .planning/ROADMAP.md)
+# Then verify phase structure
+node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap read --raw
+```
+
+| Check | How to Verify |
+|-------|--------------|
+| Every phase has success criteria | Read each phase detail section |
+| Dependencies are acyclic | Trace the dependency chain — no loops |
+| Phase numbering is sequential | Numbers increase, no gaps larger than 1 |
+| Milestones cover all phases | Every phase appears in exactly one milestone |
+| Success criteria are testable | Each criterion can be verified by command, test, or inspection |
+
+## Common Rationalizations — REJECT THESE
+
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "We don't know enough to plan" | Plan what you know. Unknown phases get a research spike first. |
+| "The roadmap will change anyway" | Plans change — that is expected. No plan guarantees drift. |
+| "Success criteria are too rigid" | Vague criteria are useless. Rigid criteria are adjustable. |
+| "One big phase is simpler" | Big phases hide complexity and delay feedback. Split them. |
+| "Dependencies are obvious" | Obvious to you now. Not obvious to the agent running phase 5 next week. |
+| "We'll add details later" | Later never comes. Write the details now while context is fresh. |
+
+## Red Flags — STOP If You Catch Yourself:
+
+- Writing a phase without success criteria
+- Creating phases longer than 3 days of work
+- Skipping dependency declarations
+- Writing vague criteria like "code is good" or "feature works"
+- Creating circular dependencies between phases
+- Putting all work in one or two massive phases
+
+**If any red flag triggers: STOP. Review the phase structure and fix it.**
+
+## Verification Checklist
+
+Before finalizing a roadmap, confirm:
+
+- [ ] Every phase has a number, name, goal, dependencies, and success criteria
+- [ ] Success criteria are testable (verifiable by command, test, or inspection)
+- [ ] Dependencies form a DAG (no circular dependencies)
+- [ ] Phase numbering follows MAXSIM convention (01, 01A, 01B, 01.1, etc.)
+- [ ] Phases are 1-3 days of work each
+- [ ] Milestones group phases into coherent deliverables
+- [ ] ROADMAP.md matches the expected format for MAXSIM CLI parsing
+- [ ] Overview section summarizes the project and delivery strategy
+
+## In MAXSIM Plan Execution
+
+Roadmap writing integrates with the MAXSIM lifecycle:
+- Use during project initialization (`/maxsim:plan-phase`) to create the initial roadmap
+- Use when restructuring after a significant scope change or pivot
+- The roadmap is read by MAXSIM agents via `roadmap read` — format compliance is mandatory
+- Phase numbering must be parseable by `normalizePhaseName()` and `comparePhaseNum()` in core
+- Config `model_profile` in `.planning/config.json` affects agent assignment per phase

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

@@ -0,0 +1,175 @@
+---
+name: sdd
+description: Dispatch fresh subagent per task with 2-stage review between tasks
+---
+
+# Spec-Driven Dispatch (SDD)
+
+Execute tasks sequentially, each in a fresh subagent with clean context. Review every task before moving to the next.
+
+**If the previous task did not pass review, you do not start the next task.**
+
+## When to Use
+
+- Tasks are sequential and each builds on the previous
+- Context rot is a concern (long plans, many files, complex logic)
+- Each task benefits from starting with a clean context window
+- You want enforced quality gates between tasks
+
+Do NOT use this skill when:
+- Tasks are independent and can run in parallel (use batch-worktree instead)
+- The plan has only 1-2 small tasks (overhead is not worth it)
+- All tasks modify the same small set of files (single-agent execution is simpler)
+
+## The Iron Law
+
+<HARD-GATE>
+NO TASK STARTS UNTIL THE PREVIOUS TASK PASSES 2-STAGE REVIEW.
+If the review found issues, they must be fixed before the next task begins.
+No "we'll fix it later." No "it's close enough." No skipping review for simple tasks.
+Violating this rule ships unreviewed code — the exact problem SDD prevents.
+</HARD-GATE>
+
+## Process
+
+### 1. LOAD — Read the Plan
+
+- Read the plan file (PLAN.md) to get the ordered task list
+- For each task, identify: description, acceptance criteria, relevant files
+- Confirm task order makes sense (later tasks may depend on earlier ones)
+
+```bash
+# Load plan context
+INIT=$(node .claude/maxsim/bin/maxsim-tools.cjs init execute-phase "${PHASE}")
+```
+
+### 2. DISPATCH — Spawn Fresh Agent Per Task
+
+For each task in order:
+
+1. Assemble the task context:
+   - Task description and acceptance criteria from the plan
+   - Only the files relevant to this specific task
+   - Results from previous tasks (commit hashes, created files) — NOT the full previous context
+2. Spawn a fresh `general-purpose` agent with this minimal context
+3. The agent implements the task, runs tests, and commits
+
+```bash
+# Record task dispatch
+node .claude/maxsim/bin/maxsim-tools.cjs state-add-decision "SDD: dispatching task N — [description]"
+```
+
+### 3. REVIEW — 2-Stage Quality Gate
+
+After each task completes, run two review stages before proceeding:
+
+#### Stage 1: Spec Compliance
+
+- Does the implementation match the task description?
+- Are all acceptance criteria met?
+- Were only the specified files modified (no scope creep)?
+- Do the changes align with the plan's intent?
+
+**Verdict:** PASS or FAIL with specific issues.
+
+#### Stage 2: Code Quality
+
+- Are there obvious bugs, edge cases, or error handling gaps?
+- Is the code readable and consistent with codebase conventions?
+- Are there unnecessary complications or dead code?
+- Do all tests pass?
+
+```bash
+# Run tests to verify
+npx vitest run
+```
+
+**Verdict:** PASS or FAIL with specific issues.
+
+### 4. FIX — Address Review Failures
+
+If either review stage fails:
+
+1. Spawn a NEW fresh agent with:
+   - The original task description
+   - The review feedback (specific issues found)
+   - The current state of the files
+2. The fix agent addresses ONLY the review issues — no new features
+3. Re-run both review stages on the fixed code
+4. If 3 fix attempts fail: STOP and escalate to the user
+
+### 5. ADVANCE — Move to Next Task
+
+Only after both review stages pass:
+- Record the task as complete
+- Note the commit hash and any files created/modified
+- Pass this minimal summary (not full context) to the next task's agent
+
+```bash
+# Record task completion
+node .claude/maxsim/bin/maxsim-tools.cjs state-add-decision "SDD: task N complete — [summary]"
+```
+
+### 6. REPORT — Final Summary
+
+After all tasks complete:
+- List each task with its status and commit hash
+- Note any tasks that required fix iterations
+- Summarize the total changes made
+
+## Context Management Rules
+
+Each agent receives ONLY what it needs:
+
+| Context Item | Included? |
+|-------------|-----------|
+| Task description + acceptance criteria | Always |
+| Files relevant to this task | Always |
+| Previous task commit hashes | Always |
+| Previous task full diff | Never |
+| Previous task agent conversation | Never |
+| PROJECT.md / REQUIREMENTS.md | Only if task references project-level concerns |
+| Full codebase | Never — only specified files |
+
+**The point of SDD is fresh context. Loading the previous agent's full context defeats the purpose.**
+
+## Common Rationalizations — REJECT THESE
+
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "This task is simple, skip review" | Simple tasks still have bugs. Review takes seconds for simple code. |
+| "Review is slowing us down" | Unreviewed code slows you down more when bugs compound across tasks. |
+| "Just pass the full context forward" | Full context = context rot. Minimal summaries keep agents effective. |
+| "Fix it in the next task" | The next task's agent does not know about the bug. Fix it now. |
+| "The agent knows best, trust it" | Agents make mistakes. That is why review exists. |
+
+## Red Flags — STOP If You Catch Yourself:
+
+- Starting a new task before the previous one passed review
+- Passing full conversation history to the next agent
+- Skipping Stage 1 or Stage 2 of the review
+- Accumulating "fix later" items across tasks
+- On the 3rd fix attempt for the same review issue (escalate to user)
+
+**If any red flag triggers: STOP. Complete the review cycle for the current task before proceeding.**
+
+## Verification Checklist
+
+Before reporting completion, confirm:
+
+- [ ] Every task was executed by a fresh agent with minimal context
+- [ ] Every task passed both spec compliance and code quality review
+- [ ] No task was skipped or started before the previous task passed review
+- [ ] Fix iterations (if any) are documented
+- [ ] All tests pass after the final task
+- [ ] Summary includes per-task status and commit hashes
+
+## In MAXSIM Plan Execution
+
+When a plan specifies `skill: "sdd"`:
+- The orchestrator reads tasks from PLAN.md in order
+- Each task is dispatched to a fresh subagent
+- 2-stage review runs between every task
+- Failed reviews trigger fix agents (up to 3 attempts)
+- Progress is tracked in STATE.md via decision entries
+- Final results are recorded in SUMMARY.md