maxsimcli 4.0.0 → 4.0.2

package/README.md

@@ -23,7 +23,7 @@ MAXSIM solves this by offloading work to fresh-context subagents, each with a si
 npx maxsimcli@latest
 ```
 
-**Works with Claude Code, OpenCode, Gemini CLI, and Codex — on Mac, Windows, and Linux.**
+**Works with Claude Code — on Mac, Windows, and Linux.**
 
 > ⚠️ **Early Alpha** — APIs, commands, and workflows may change between releases. Expect rough edges.
 
@@ -75,7 +75,7 @@ That's the loop. Discuss → Plan → Execute → Verify. Each phase is isolated
 
 ## How It Works
 
-MAXSIM installs 30+ slash commands into your AI runtime. Each command is a structured workflow that spawns specialized subagents with fresh context.
+MAXSIM installs 32 slash commands, 11 skills, and an MCP server into Claude Code. Each command is a structured workflow that spawns specialized subagents with fresh context.
 
 ### The Core Loop
 
@@ -251,27 +251,18 @@ npx maxsimcli@latest
 ```
 
 The installer prompts you to choose:
-1. **Runtime** — Claude Code, OpenCode, Gemini, Codex, or all
-2. **Location** — Global (all projects) or local (current project only)
+1. **Location** — Global (all projects) or local (current project only)
 
-Verify with:
-- Claude Code / Gemini: `/maxsim:help`
-- OpenCode: `/maxsim-help`
-- Codex: `$maxsim-help`
+Verify with: `/maxsim:help`
 
 <details>
 <summary><strong>Non-interactive Install (Docker, CI, Scripts)</strong></summary>
 
 ```bash
-npx maxsimcli --claude --global    # Claude Code → ~/.claude/
-npx maxsimcli --opencode --global  # OpenCode → ~/.config/opencode/
-npx maxsimcli --gemini --global    # Gemini CLI → ~/.gemini/
-npx maxsimcli --codex --global     # Codex → ~/.codex/
-npx maxsimcli --all --global       # All runtimes
+npx maxsimcli --claude --global    # Global install → ~/.claude/
+npx maxsimcli --claude --local     # Project-scoped install → ./.claude/
 ```
 
-Add `--local` instead of `--global` for project-scoped installs.
-
 </details>
 
 ---
@@ -306,7 +297,7 @@ Project settings live in `.planning/config.json`, created during `/maxsim:new-pr
 
 ### Model Profiles
 
-MAXSIM has **4 model profiles** that control which Claude model each of the 11 specialized agents uses:
+MAXSIM has **4 model profiles** that control which Claude model each of the 13 specialized agents uses:
 
 | Profile | Planners & Executors | Researchers | Orchestrators |
 |---------|---------------------|-------------|---------------|
@@ -356,7 +347,7 @@ The context bar shows a 10-segment indicator that turns red and blinks above 95%
 
 ## Agents
 
-11 specialized subagents, each with fresh context and a single responsibility:
+13 specialized subagents, each with fresh context and a single responsibility:
 
 | Agent | Role |
 |-------|------|
@@ -367,6 +358,8 @@ The context bar shows a 10-segment indicator that turns red and blinks above 95%
 | `maxsim-roadmapper` | Creates project roadmaps with phase breakdown |
 | `maxsim-plan-checker` | Verifies plans will achieve the phase goal |
 | `maxsim-executor` | Implements plans with atomic commits |
+| `maxsim-spec-reviewer` | Reviews implementation for spec compliance after execution |
+| `maxsim-code-reviewer` | Reviews implementation for code quality and patterns |
 | `maxsim-verifier` | Goal-backward verification after execution |
 | `maxsim-debugger` | Scientific-method debugging with persistent state |
 | `maxsim-integration-checker` | Verifies cross-phase integration and E2E flows |
@@ -374,6 +367,39 @@ The context bar shows a 10-segment indicator that turns red and blinks above 95%
 
 ---
 
+## Skills
+
+MAXSIM includes 11 built-in skills that enforce workflow constraints and best practices. Skills auto-trigger based on context — they're not optional guidelines, they're active workflow enforcement.
+
+| Skill | Description |
+|-------|-------------|
+| `batch-worktree` | Run parallel tasks in isolated git worktrees |
+| `brainstorming` | Structured ideation and feature exploration |
+| `code-review` | Automated code review with quality checks |
+| `memory-management` | Persistent memory across sessions |
+| `roadmap-writing` | Guided roadmap and requirements authoring |
+| `sdd` | Spec-driven development workflow |
+| `simplify` | Review changed code for reuse, quality, and efficiency |
+| `systematic-debugging` | Root-cause investigation before attempting fixes |
+| `tdd` | Test-driven development — failing test before implementation |
+| `using-maxsim` | Guide for effective MAXSIM usage |
+| `verification-before-completion` | Verify work before claiming completion |
+
+---
+
+## MCP Server
+
+MAXSIM installs an MCP (Model Context Protocol) server that exposes project tools directly to Claude Code. The server is auto-configured during installation via `.mcp.json`.
+
+**Exposed tools:**
+- **Phase operations** — list, add, complete, and remove phases
+- **State management** — read/update STATE.md (decisions, blockers, metrics)
+- **Todo operations** — create, list, and complete todos
+
+The MCP server runs as a stdio process managed by Claude Code — no manual startup needed.
+
+---
+
 ## Contributing
 
 MAXSIM is open source and contributions are welcome.

package/dist/assets/CHANGELOG.md

@@ -1,3 +1,63 @@
+## [4.0.1](https://github.com/maystudios/maxsimcli/compare/v4.0.0...v4.0.1) (2026-03-02)
+
+
+### Bug Fixes
+
+* **mcp:** bundle MCP server dependencies and update README with skills/MCP docs ([7724966](https://github.com/maystudios/maxsimcli/commit/772496696167d8723873b6645826327472824560))
+
+# [4.0.0](https://github.com/maystudios/maxsimcli/compare/v3.12.0...v4.0.0) (2026-03-02)
+
+
+* feat!: remove non-Claude adapters and simplify install to Claude-only ([e640107](https://github.com/maystudios/maxsimcli/commit/e640107bc7d66fd6b6a22778fc3f5aa2f720f1ae))
+
+
+### Bug Fixes
+
+* **core:** add actionable context to catch blocks across core modules ([3bda2eb](https://github.com/maystudios/maxsimcli/commit/3bda2eb3767500a2500cd4ce394af90a79ef1c8a))
+* **core:** replace Unix find with cross-platform fs walk ([#22](https://github.com/maystudios/maxsimcli/issues/22)) ([8dddae4](https://github.com/maystudios/maxsimcli/commit/8dddae4f2af7fa2c0e398025779c4fcc85389244))
+* **core:** replace Unix find with cross-platform fs walk for Windows compatibility ([b121ae6](https://github.com/maystudios/maxsimcli/commit/b121ae68d5d38733960e9ff72c2f7a982f54d739))
+* **dashboard:** increase health check timeout to 10s and verify multi-project isolation ([bee185c](https://github.com/maystudios/maxsimcli/commit/bee185c91e730896040afef63eaac5d782cefc28))
+* **install:** add .mcp.json backup and install recovery safety ([77eb4fe](https://github.com/maystudios/maxsimcli/commit/77eb4feeafd141eca94349f19615fcee97bb6718))
+* **install:** move skills install path from agents/skills/ to skills/ ([436712a](https://github.com/maystudios/maxsimcli/commit/436712a4adee7c86ae9480a6aa93e52ff017338a))
+* **install:** remove dead isCodex reference and reject deprecated runtime flags ([#21](https://github.com/maystudios/maxsimcli/issues/21)) ([9a4af80](https://github.com/maystudios/maxsimcli/commit/9a4af80c5543fcd69970fbac4f9c71c9f5821388))
+* resolve duplicate CmdResult and update tests for CmdResult pattern ([1e02d4b](https://github.com/maystudios/maxsimcli/commit/1e02d4b7df95d3833fd92f3413870a18ff1be3d4))
+* **state:** harden STATE.md parsing for format drift resilience ([9881d1c](https://github.com/maystudios/maxsimcli/commit/9881d1c9f6b1810aa5838f651aa16f9bd87cdf5d))
+
+
+### Features
+
+* add artefakte system, context loader, and start command (Units 1, 9, 10) ([dbbc2b4](https://github.com/maystudios/maxsimcli/commit/dbbc2b4d35412f9b51e100a9aa2bd027dcd4e398))
+* add brainstorming and roadmap-writing skills (Units 7, 8) ([1b8c64c](https://github.com/maystudios/maxsimcli/commit/1b8c64c2c5dec6f2873df1cc79a5002b176f7e96))
+* async I/O for hot-path commands and phase-list pagination (Phase 10) ([19e7741](https://github.com/maystudios/maxsimcli/commit/19e7741c8df1567a08f59282235b217855d4cd85))
+* **execution:** wire Execute-Review-Simplify-Review cycle into execution pipeline ([7a6a998](https://github.com/maystudios/maxsimcli/commit/7a6a998aeb707288930d99e36c06ba0cac23dfae))
+* **mcp:** complete E2E Q&A routing between Claude Code and dashboard ([ac3115a](https://github.com/maystudios/maxsimcli/commit/ac3115a7e120ae9b1e597ae6f9afe664449640a2))
+* rewrite workflows with thinking-partner behavior and artefakte integration (Units 2-6) ([f44b4f4](https://github.com/maystudios/maxsimcli/commit/f44b4f4589df9f94fc3b927a88e5683c2b5bbf2d))
+* **skills:** add batch-worktree and sdd skill templates ([84997be](https://github.com/maystudios/maxsimcli/commit/84997be21443de3213636f862c480ca32caed254))
+* **skills:** add skill-list, skill-install, skill-update CLI commands ([d848acd](https://github.com/maystudios/maxsimcli/commit/d848acd678e19a4eb1bf947e15a972786a801ef0))
+* **skills:** register using-maxsim skill for auto-trigger at conversation start ([d5f0a50](https://github.com/maystudios/maxsimcli/commit/d5f0a50ab625655cf1d3e53eebbb86661b011bf3))
+* unified dashboard mode with enhanced MCP Q&A and multi-project support (Units 11-14) ([b26205e](https://github.com/maystudios/maxsimcli/commit/b26205ebffb1770daa6f2bbb82ced801af8800eb))
+
+
+### BREAKING CHANGES
+
+* Remove OpenCode, Gemini, and Codex runtime support.
+MAXSIM v2.0 is Claude Code-only.
+
+- Delete adapter files: opencode.ts, gemini.ts, codex.ts
+- Delete transforms/: tool-maps.ts, frontmatter.ts, content.ts
+- Simplify adapter registry to export only claudeAdapter
+- Narrow RuntimeName type to 'claude' literal
+- Narrow AdapterConfig.commandStructure to 'nested' only
+- Remove --opencode, --gemini, --codex, --both, --all CLI flags
+- Remove promptRuntime() multi-runtime selector
+- Remove copyFlattenedCommands() and copyCommandsAsCodexSkills()
+- Remove configureOpencodePermissions() and parseJsonc()
+- Remove non-Claude branches from install, uninstall, hooks, manifest
+- Simplify shared.ts to use claudeAdapter directly (no adapter map)
+- Update help text and banner for Claude-only messaging
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+
 # [3.12.0](https://github.com/maystudios/maxsimcli/compare/v3.11.0...v3.12.0) (2026-03-01)
 
 

package/dist/assets/templates/skills/batch-worktree/SKILL.md

@@ -1,123 +1,76 @@
 ---
 name: batch-worktree
-description: Orchestrate parallel work across isolated git worktrees with independent PRs
+description: >-
+  Decomposes large tasks into independent units and executes each in an isolated
+  git worktree with its own branch and PR. Use when parallelizing work across
+  5-30 independent units or orchestrating worktree-based parallel execution. Not
+  for sequential dependencies or fewer than 3 units.
 ---
 
 # Batch Worktree
 
 Decompose large tasks into independent units, execute each in an isolated worktree, and produce one PR per unit.
 
-**If units share overlapping files, you cannot parallelize them. Serialize or redesign.**
-
-## When to Use
-
-- The task is decomposable into 5-30 independent units
-- Each unit can be implemented, tested, and merged independently
-- Units touch non-overlapping files (no merge conflicts between units)
-- You want parallel execution with isolated git state per unit
-
-Do NOT use this skill when:
-- Units have sequential dependencies (use SDD instead)
-- The task has fewer than 3 units (overhead is not worth it)
-- Units modify the same files (merge conflicts will block you)
-
-## The Iron Law
-
-<HARD-GATE>
-EVERY UNIT MUST BE INDEPENDENTLY MERGEABLE.
-If merging unit A would break the build without unit B, they are not independent — combine them or serialize them.
-No exceptions. No "we'll merge them in order." No "it'll probably be fine."
-Violating this rule produces unmergeable PRs — wasted work.
-</HARD-GATE>
+**HARD GATE: Every unit must be independently mergeable. If merging unit A would break the build without unit B, they are not independent. Combine them or serialize them. No exceptions.**
 
 ## Process
 
-### 1. DECOMPOSE — Split Task into Independent Units
-
-- List all units with a clear one-line description each
-- For each unit, list the files it will create or modify
-- Verify NO file appears in more than one unit
-- If overlap exists: merge the overlapping units into one, or extract shared code into a prerequisite unit that runs first
-
-```bash
-# Document the decomposition
-node .claude/maxsim/bin/maxsim-tools.cjs state-add-decision "Batch decomposition: N units identified, no file overlap confirmed"
-```
+### 1. Research -- Analyze and Decompose
 
-### 2. VALIDATE — Confirm Independence
+List all units with a one-line description each. For each unit, list the files it will create or modify. Verify no file appears in more than one unit. If overlap exists, merge the overlapping units into one or extract shared code into a prerequisite unit that runs first.
 
-For each pair of units, verify:
+For each pair of units, confirm:
 - No shared file modifications
-- No runtime dependency (unit A's output is not unit B's input)
+- No runtime dependency (unit A output is not unit B input)
 - Each unit's tests pass without the other unit's changes
 
-If validation fails: redesign the decomposition. Do not proceed with overlapping units.
+If validation fails, redesign the decomposition before proceeding.
 
-### 3. SPAWN — Create Worktree Per Unit
+### 2. Plan -- Define Unit Specifications
 
-For each unit, create an isolated worktree and spawn an agent:
+For each unit, prepare a specification containing:
+- Unit description and acceptance criteria
+- The list of files it owns (and only those files)
+- The base branch to branch from
+- Instructions to implement, test, commit, push, and create a PR
 
-```bash
-# Create worktree branch for each unit
-git worktree add .claude/worktrees/unit-NN unit/NN-description -b unit/NN-description
-```
+Record the decomposition decision:
 
-Spawn one agent per unit with `isolation: "worktree"`. Each agent receives:
-- The unit description and acceptance criteria
-- The list of files it owns (and ONLY those files)
-- The base branch to branch from
-- Instructions to: implement, test, commit, push, create PR
+```
+node .claude/maxsim/bin/maxsim-tools.cjs state-add-decision "Batch decomposition: N units identified, no file overlap confirmed"
+```
 
-### 4. EXECUTE — Each Agent Works Independently
+### 3. Spawn -- Create Worktree Per Unit
 
-Each spawned agent follows this sequence:
-1. Read the unit description and relevant source files
-2. Implement the changes (apply TDD or simplify skills as configured)
-3. Run tests — all must pass
-4. Commit with a descriptive message referencing the unit
-5. Push the branch
-6. Create a PR with unit description as the body
+For each unit, create an isolated worktree and spawn an agent with `isolation: "worktree"`. Each agent receives its unit specification and works independently through: read relevant source, implement changes, run tests, commit, push, create PR.
 
-### 5. TRACK — Monitor Progress
+### 4. Track -- Monitor Progress
 
 Maintain a status table and update it as agents report back:
 
-```markdown
 | # | Unit | Status | PR |
 |---|------|--------|----|
 | 1 | description | done | #123 |
-| 2 | description | in-progress | — |
-| 3 | description | failed | — |
-```
+| 2 | description | in-progress | -- |
+| 3 | description | failed | -- |
 
 Statuses: `pending`, `in-progress`, `done`, `failed`, `needs-review`
 
-### 6. REPORT — Collect Results
-
-When all units complete:
-- List all created PRs
-- Flag any failed units with error summaries
-- If any unit failed: spawn a fix agent for that unit only
-
-## Handling Failures
+Failure handling:
+- Unit fails tests: spawn a fix agent in the same worktree
+- Merge conflict: decomposition was wrong, fix overlap and re-run unit
+- Agent times out: re-spawn with the same unit description
+- 3+ failures on same unit: stop and escalate to user
 
-| Situation | Action |
-|-----------|--------|
-| Unit fails tests | Spawn a fix agent in the same worktree |
-| Unit has merge conflict | The decomposition was wrong — fix overlap, re-run unit |
-| Agent times out | Re-spawn with the same unit description |
-| 3+ failures on same unit | Stop and escalate to user — likely an architectural issue |
+When all units complete, list all created PRs and flag any failed units with error summaries. If any unit failed, spawn a fix agent for that unit only.
 
-## Common Rationalizations — REJECT THESE
+## Common Pitfalls
 
-| Excuse | Why It Violates the Rule |
-|--------|--------------------------|
-| "The overlap is minor" | Minor overlap = merge conflicts. Split the shared code into a prerequisite unit. |
-| "We'll merge in the right order" | Order-dependent merges are not independent. Serialize those units. |
-| "It's faster to do them all in one branch" | One branch means one context window. Worktrees give each unit fresh context. |
-| "Only 2 units, let's still use worktrees" | Worktree overhead is not worth it for <3 units. Use sequential execution. |
+- "The overlap is minor" -- Minor overlap causes merge conflicts. Split shared code into a prerequisite unit.
+- "We'll merge in the right order" -- Order-dependent merges are not independent. Serialize those units.
+- "Only 2 units, let's still use worktrees" -- Worktree overhead is not worth it for fewer than 3 units. Use sequential execution.
 
-## Verification Checklist
+## Verification
 
 Before reporting completion, confirm:
 
@@ -128,7 +81,7 @@ Before reporting completion, confirm:
 - [ ] No PR depends on another PR being merged first
 - [ ] Status table is complete with all PR links
 
-## In MAXSIM Plan Execution
+## MAXSIM Integration
 
 When a plan specifies `skill: "batch-worktree"`:
 - The orchestrator decomposes the plan's tasks into independent units

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

@@ -1,159 +1,89 @@
 ---
 name: brainstorming
-description: Use before implementing any significant feature or design — requires exploring multiple approaches and getting explicit design approval before writing code
+description: >-
+  Explores multiple implementation approaches with trade-off analysis before
+  committing to a design direction. Use when starting a significant feature,
+  making architectural decisions, or choosing between design alternatives.
 ---
 
 # Brainstorming
 
 The first idea is rarely the best idea. Explore the space before committing to a direction.
 
-**If you have not considered alternatives, you are building the first thing that came to mind.**
+**HARD GATE** -- No implementation without design approval. If you have not presented approaches, discussed trade-offs, and received explicit user approval, you cannot write implementation code. This is not a judgment call.
 
-## The Iron Law
+## Process
 
-<HARD-GATE>
-NO IMPLEMENTATION WITHOUT DESIGN APPROVAL.
-If you have not presented approaches, discussed trade-offs, and received explicit approval, you CANNOT write implementation code.
-"I already know the best approach" is an assumption, not a conclusion.
-Violating this rule is a violation — not a judgment call.
-</HARD-GATE>
+### 1. Frame the Problem
 
-## The Gate Function
-
-Follow these steps IN ORDER before implementing any significant feature, architecture change, or design decision.
-
-### 1. FRAME — Define the Problem
-
-Ask the user ONE question at a time to understand the problem space. Do not bundle multiple questions — each response informs the next question.
+Ask the user ONE question at a time to understand the problem space. Each answer informs the next question.
 
 - What is the goal? What does success look like?
 - What are the constraints (performance, compatibility, timeline)?
-- What has already been tried or considered?
+- What has been tried or considered already?
 - What are the non-negotiables vs. nice-to-haves?
 
-**Rule: ONE question at a time. Wait for the answer before asking the next.**
-
-### 2. RESEARCH — Understand the Context
-
-Before proposing solutions, gather evidence:
+### 2. Research Context
 
-- Read the relevant code and understand current architecture
-- Check `.planning/` for existing decisions and constraints
-- Review ROADMAP.md for phase dependencies and scope
-- Identify related patterns already in the codebase
+Before proposing solutions, gather evidence from the codebase and any existing planning artifacts. Read relevant code, check for prior decisions, and identify patterns already in use.
 
-```bash
-# Check existing decisions
-node ~/.claude/maxsim/bin/maxsim-tools.cjs state read --raw
-
-# Check current roadmap context
-node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap read --raw
-```
-
-### 3. PROPOSE — Present 2-3 Approaches
+### 3. Present 2-3 Approaches
 
 For each approach, provide:
 
-| Aspect | What to Include |
-|--------|----------------|
-| **Summary** | One-sentence description of the approach |
-| **How it works** | Key implementation steps (3-5 bullets) |
-| **Pros** | Concrete advantages — not vague ("simpler" is vague, "200 fewer lines" is concrete) |
-| **Cons** | Honest drawbacks — do not hide weaknesses to sell a preferred option |
-| **Effort** | Relative complexity (low / medium / high) |
-| **Risk** | What could go wrong and how recoverable is it |
-
-**Present exactly 2-3 approaches.** One option is not brainstorming. Four or more creates decision paralysis.
-
-If one approach is clearly superior, say so — but still present alternatives so the user can validate your reasoning.
+| Aspect | Content |
+|--------|---------|
+| **Summary** | One sentence |
+| **How it works** | 3-5 implementation bullets |
+| **Pros** | Concrete advantages (not vague -- "200 fewer lines" beats "simpler") |
+| **Cons** | Honest drawbacks -- do not hide weaknesses |
+| **Effort** | Low / Medium / High |
+| **Risk** | What could go wrong and how recoverable |
 
-### 4. DISCUSS — Refine with the User
+Present exactly 2-3 approaches. If one is clearly superior, say so -- but still present alternatives so the user can validate your reasoning.
 
-- Ask the user which approach they prefer (or if they want a hybrid)
-- Answer follow-up questions honestly — do not advocate for a single approach
-- If the user raises concerns, address them specifically
-- If no approach fits, propose new ones informed by the discussion
+### 4. Discuss and Refine
 
-**Continue ONE question at a time. Do not assume consensus until stated.**
+Ask the user which approach they prefer or whether they want a hybrid. Answer follow-up questions honestly. If no approach fits, propose new ones informed by the discussion. Continue one question at a time -- do not assume consensus.
 
-### 5. DECIDE — Get Explicit Approval
+### 5. Get Explicit Approval
 
-The user must explicitly approve the chosen approach. Acceptable approvals:
+The user must explicitly approve one approach (e.g., "Go with A", "Approved", "Ship it"). Vague responses like "Sounds good" or "Interesting" are not approval. If ambiguous, ask: "To confirm -- should I proceed with [specific approach]?"
 
-- "Go with approach A"
-- "Let's do option 2"
-- "Approved" / "LGTM" / "Ship it"
+### 6. Document the Decision
 
-Not acceptable as approval:
+Record the chosen approach, rejected alternatives with reasons, key implementation decisions, and risks. Use MAXSIM state tooling if available.
 
-- "Sounds good" (too vague — clarify which approach)
-- "Interesting" (not a decision)
-- Silence (not consent)
+### 7. Implement the Approved Design
 
-**If approval is ambiguous, ask: "To confirm — should I proceed with [specific approach]?"**
+Only after steps 1-6. Follow the approved design. If implementation reveals a design flaw, stop and return to step 4.
 
-### 6. DOCUMENT — Record the Decision
+## Common Pitfalls
 
-After approval, write a design doc and record the decision:
-
-```bash
-# Record the decision in STATE.md
-node ~/.claude/maxsim/bin/maxsim-tools.cjs add-decision \
-  --phase "current-phase" \
-  --summary "Chose approach X for [feature] because [reason]" \
-  --rationale "Evaluated 3 approaches: A (rejected — too complex), B (rejected — performance risk), C (approved — best trade-off of simplicity and extensibility)"
-```
-
-The design doc should include:
-- **Chosen approach** and why
-- **Rejected alternatives** and why they were rejected
-- **Key implementation decisions** that flow from the choice
-- **Risks** and mitigation strategies
-
-### 7. IMPLEMENT — Build the Approved Design
-
-Only after steps 1-6 are complete:
-- Follow the approved design — do not deviate without re-discussion
-- If implementation reveals a flaw in the design, STOP and return to step 4
-- Reference the design doc in commit messages
-
-## Common Rationalizations — REJECT THESE
-
-| Excuse | Why It Violates the Rule |
-|--------|--------------------------|
-| "I already know the best approach" | You know YOUR preferred approach. Alternatives may be better. |
-| "There's only one way to do this" | There is almost never only one way. You have not looked hard enough. |
-| "The user won't care about the design" | Users care about the outcome. Bad design leads to bad outcomes. |
+| Excuse | Reality |
+|--------|---------|
+| "I already know the best approach" | You know your preferred approach. Alternatives may be better. |
+| "There's only one way to do this" | There is almost never only one way. |
 | "Brainstorming slows us down" | Building the wrong thing is slower. 30 minutes of design saves days of rework. |
-| "I'll refactor if the first approach is wrong" | Refactoring is expensive. Choosing well upfront is cheaper. |
-| "The scope is too small for brainstorming" | If it touches architecture, it needs brainstorming regardless of size. |
-
-## Red Flags — STOP If You Catch Yourself:
 
-- Writing implementation code before presenting approaches to the user
-- Presenting only one approach and calling it "brainstorming"
-- Asking multiple questions at once instead of one at a time
-- Assuming approval without an explicit statement
-- Skipping the documentation step because "we'll remember"
-- Deviating from the approved design without discussion
+Stop immediately if you catch yourself: writing code before presenting approaches, presenting only one option, asking multiple questions at once, assuming approval without explicit confirmation, or skipping documentation.
 
-**If any red flag triggers: STOP. Return to the appropriate step.**
-
-## Verification Checklist
+## Verification
 
 Before starting implementation, confirm:
 
 - [ ] Problem has been framed with user input (not assumptions)
 - [ ] Relevant code and context have been researched
-- [ ] 2-3 approaches have been presented with concrete trade-offs
+- [ ] 2-3 approaches presented with concrete trade-offs
 - [ ] User has explicitly approved one specific approach
-- [ ] Decision has been recorded in STATE.md
+- [ ] Decision has been recorded
 - [ ] Design doc captures chosen approach, rejected alternatives, and risks
 
-## In MAXSIM Plan Execution
+## MAXSIM Integration
+
+Brainstorming applies before significant implementation work within MAXSIM workflows:
 
-Brainstorming applies before significant implementation work:
 - Use during phase planning when design choices affect multiple tasks
-- Use before any task that introduces new architecture, patterns, or external dependencies
-- The decision record in STATE.md persists across sessions — future agents inherit context
-- If a brainstorming session spans multiple interactions, record partial progress in STATE.md blockers
+- Use before any task introducing new architecture, patterns, or external dependencies
+- Decision records in STATE.md persist across sessions -- future agents inherit context
+- If a session spans multiple interactions, record partial progress in STATE.md blockers