maxsimcli 3.12.0 → 4.0.0

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

@@ -8,6 +8,14 @@ When a MAXSIM agent is spawned, it checks this registry to determine which skill
 
 Agents load skills by reading `SKILL.md` from each skill directory listed in their entry below. Skills are loaded once at agent startup and enforced throughout the session.
 
+### Auto-Trigger Skills
+
+Skills with `alwaysApply: true` in their frontmatter are loaded automatically at the start of every conversation, without requiring an explicit command or agent spawn. This ensures foundational workflow rules are always active.
+
+| Skill | Purpose |
+|-------|---------|
+| `using-maxsim` | Routes all work through MAXSIM commands — prevents ad-hoc coding without plans |
+
 ## Registry
 
 ### maxsim-executor
@@ -71,8 +79,12 @@ The integration checker validates cross-component wiring. Verification ensures i
 | `systematic-debugging` | `skills/systematic-debugging/` | Root cause investigation before fixes |
 | `tdd` | `skills/tdd/` | Failing test before implementation |
 | `verification-before-completion` | `skills/verification-before-completion/` | Evidence before completion claims |
-| `using-maxsim` | `skills/using-maxsim/` | Workflow routing and structure |
+| `using-maxsim` | `skills/using-maxsim/` | Workflow routing and structure (alwaysApply) |
 | `memory-management` | `skills/memory-management/` | Pattern and error persistence |
+| `brainstorming` | `skills/brainstorming/` | Multi-approach exploration before design |
+| `roadmap-writing` | `skills/roadmap-writing/` | Phased planning with success criteria |
+| `simplify` | `skills/simplify/` | Code simplification and cleanup |
+| `code-review` | `skills/code-review/` | Implementation quality review |
 
 ## Adding New Skills
 

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

@@ -1273,8 +1273,8 @@ When any trigger condition below applies, read the full skill file via the Read
 
 | Skill | Read | Trigger |
 |-------|------|---------|
-| Systematic Debugging | `.agents/skills/systematic-debugging/SKILL.md` | Always — you are a debugger, this is your primary skill |
-| Verification Before Completion | `.agents/skills/verification-before-completion/SKILL.md` | Before claiming a bug is fixed or a debug session is complete |
+| Systematic Debugging | `.skills/systematic-debugging/SKILL.md` | Always — you are a debugger, this is your primary skill |
+| Verification Before Completion | `.skills/verification-before-completion/SKILL.md` | Before claiming a bug is fixed or a debug session is complete |
 
 **Project skills override built-in skills.**
 

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

@@ -23,7 +23,7 @@ Before executing, discover project context:
 
 **Self-improvement lessons:** Read `.planning/LESSONS.md` if it exists — accumulated lessons from past executions on this codebase. Apply them proactively to avoid known mistakes before they become deviations.
 
-**Project skills:** Check `.agents/skills/` directory if it exists:
+**Project skills:** Check `.skills/` directory if it exists:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation
@@ -612,11 +612,11 @@ Do not rely on memory of the skill content — always read the file fresh.
 
 | Skill | Read | Trigger |
 |-------|------|---------|
-| TDD Enforcement | `.agents/skills/tdd/SKILL.md` | Before writing implementation code for a new feature, bug fix, or when plan type is `tdd` |
-| Systematic Debugging | `.agents/skills/systematic-debugging/SKILL.md` | When encountering any bug, test failure, or unexpected behavior during execution |
-| Verification Before Completion | `.agents/skills/verification-before-completion/SKILL.md` | Before claiming any task is done, fixed, or passing |
+| TDD Enforcement | `.skills/tdd/SKILL.md` | Before writing implementation code for a new feature, bug fix, or when plan type is `tdd` |
+| Systematic Debugging | `.skills/systematic-debugging/SKILL.md` | When encountering any bug, test failure, or unexpected behavior during execution |
+| Verification Before Completion | `.skills/verification-before-completion/SKILL.md` | Before claiming any task is done, fixed, or passing |
 
-**Project skills override built-in skills.** If a skill with the same name exists in `.agents/skills/` in the project, load that one instead.
+**Project skills override built-in skills.** If a skill with the same name exists in `.skills/` in the project, load that one instead.
 
 </available_skills>
 

package/dist/assets/templates/agents/maxsim-phase-researcher.md

@@ -26,7 +26,7 @@ Before researching, discover project context:
 
 **Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
 
-**Project skills:** Check `.agents/skills/` directory if it exists:
+**Project skills:** Check `.skills/` directory if it exists:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during research
@@ -559,7 +559,7 @@ When any trigger condition below applies, read the full skill file via the Read
 
 | Skill | Read | Trigger |
 |-------|------|---------|
-| Verification Before Completion | `.agents/skills/verification-before-completion/SKILL.md` | Before concluding research with confidence ratings |
+| Verification Before Completion | `.skills/verification-before-completion/SKILL.md` | Before concluding research with confidence ratings |
 
 **Project skills override built-in skills.**
 

package/dist/assets/templates/agents/maxsim-plan-checker.md

@@ -33,7 +33,7 @@ Before verifying, discover project context:
 
 **Self-improvement lessons:** Read `.planning/LESSONS.md` if it exists — accumulated lessons from past executions. Use planning insights as an additional verification dimension: flag plans that repeat known gap patterns or ignore documented codebase conventions.
 
-**Project skills:** Check `.agents/skills/` directory if it exists:
+**Project skills:** Check `.skills/` directory if it exists:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during verification
@@ -707,7 +707,7 @@ When any trigger condition below applies, read the full skill file via the Read
 
 | Skill | Read | Trigger |
 |-------|------|---------|
-| Verification Before Completion | `.agents/skills/verification-before-completion/SKILL.md` | Before issuing final PASS/FAIL verdict on a plan |
+| Verification Before Completion | `.skills/verification-before-completion/SKILL.md` | Before issuing final PASS/FAIL verdict on a plan |
 
 **Project skills override built-in skills.**
 

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

@@ -35,7 +35,7 @@ Before planning, discover project context:
 
 **Self-improvement lessons:** Read `.planning/LESSONS.md` if it exists — accumulated lessons from past executions on this codebase. Apply planning insights proactively: avoid known gaps, include wiring tasks for patterns that historically broke, reference codebase-specific conventions in task actions.
 
-**Project skills:** Check `.agents/skills/` directory if it exists:
+**Project skills:** Check `.skills/` directory if it exists:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during planning
@@ -1199,8 +1199,8 @@ When any trigger condition below applies, read the full skill file via the Read
 
 | Skill | Read | Trigger |
 |-------|------|---------|
-| TDD Enforcement | `.agents/skills/tdd/SKILL.md` | When identifying TDD candidates during task breakdown |
-| Verification Before Completion | `.agents/skills/verification-before-completion/SKILL.md` | When writing <verify> sections for tasks |
+| TDD Enforcement | `.skills/tdd/SKILL.md` | When identifying TDD candidates during task breakdown |
+| Verification Before Completion | `.skills/verification-before-completion/SKILL.md` | When writing <verify> sections for tasks |
 
 **Project skills override built-in skills.**
 

package/dist/assets/templates/commands/maxsim/add-todo.md

@@ -12,11 +12,16 @@ allowed-tools:
 <objective>
 Capture an idea, task, or issue that surfaces during a MAXSIM session as a structured todo for later work.
 
+**Modes:**
+- **Quick mode (default):** Fast capture — extract, file, commit. Use when the todo is clear.
+- **Discussion mode (`--discuss`):** Collaborative thinking for complex todos — clarify scope, surface assumptions, explore approach before filing. 20-30 min max.
+
 Routes to the add-todo workflow which handles:
 - Directory structure creation
 - Content extraction from arguments or conversation
 - Area inference from file paths
 - Duplicate detection and resolution
+- Discussion mode for complex todos (optional)
 - Todo file creation with frontmatter
 - STATE.md updates
 - Git commits
@@ -24,11 +29,15 @@ Routes to the add-todo workflow which handles:
 
 <execution_context>
 @./workflows/add-todo.md
+@./references/thinking-partner.md
 </execution_context>
 
 <context>
 Arguments: $ARGUMENTS (optional todo description)
 
+**Flags:**
+- `--discuss` — Enter discussion mode for complex todos. Clarify scope and approach before filing.
+
 State is resolved in-workflow via `init todos` and targeted reads.
 </context>
 
@@ -39,9 +48,10 @@ The workflow handles all logic including:
 1. Directory ensuring
 2. Existing area checking
 3. Content extraction (arguments or conversation)
-4. Area inference
-5. Duplicate checking
-6. File creation with slug generation
-7. STATE.md updates
-8. Git commits
+4. Discussion mode (if `--discuss` flag or complexity detected)
+5. Area inference
+6. Duplicate checking
+7. File creation with slug generation
+8. STATE.md updates
+9. Git commits
 </process>

package/dist/assets/templates/commands/maxsim/discuss-phase.md

@@ -29,6 +29,7 @@ Every single question to the user MUST use the `AskUserQuestion` tool. NEVER ask
 
 <execution_context>
 @./workflows/discuss-phase.md
+@./references/thinking-partner.md
 @./templates/context.md
 </execution_context>
 

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

@@ -24,6 +24,9 @@ Initialize MAXSIM in an existing codebase through scan-first flow: codebase anal
 - `.planning/REQUIREMENTS.md` — stage-aware requirements
 - `.planning/ROADMAP.md` — milestone + suggested phases
 - `.planning/STATE.md` — pre-populated project memory
+- `.planning/DECISIONS.md` — key decisions with rationale (artefakte)
+- `.planning/ACCEPTANCE-CRITERIA.md` — measurable success criteria (artefakte)
+- `.planning/NO-GOS.md` — explicit exclusions and anti-patterns (artefakte)
 
 **After this command:** Run `/maxsim:plan-phase 1` to start execution.
 </objective>
@@ -31,6 +34,7 @@ Initialize MAXSIM in an existing codebase through scan-first flow: codebase anal
 <execution_context>
 @./workflows/init-existing.md
 @./references/questioning.md
+@./references/thinking-partner.md
 @./references/ui-brand.md
 @./templates/project.md
 @./templates/requirements.md

package/dist/assets/templates/commands/maxsim/new-project.md

@@ -24,6 +24,9 @@ Initialize a new project through unified flow: questioning → research (optiona
 - `.planning/REQUIREMENTS.md` — scoped requirements
 - `.planning/ROADMAP.md` — phase structure
 - `.planning/STATE.md` — project memory
+- `.planning/DECISIONS.md` — key decisions with rationale (artefakte)
+- `.planning/ACCEPTANCE-CRITERIA.md` — measurable success criteria (artefakte)
+- `.planning/NO-GOS.md` — explicit exclusions and anti-patterns (artefakte)
 
 **After this command:** Run `/maxsim:plan-phase 1` to start execution.
 </objective>
@@ -31,6 +34,7 @@ Initialize a new project through unified flow: questioning → research (optiona
 <execution_context>
 @./workflows/new-project.md
 @./references/questioning.md
+@./references/thinking-partner.md
 @./references/ui-brand.md
 @./templates/project.md
 @./templates/requirements.md

package/dist/assets/templates/references/thinking-partner.md

@@ -0,0 +1,41 @@
+<thinking_partner>
+
+You are a thinking partner, not a task executor. Your role is to help the user arrive at better decisions through collaborative reasoning.
+
+<core_behaviors>
+
+**Challenge vague answers.** When the user says something unclear, don't accept it. Push for specifics. "Good UX" means what? "It should be fast" — fast how? "Users need X" — which users, doing what?
+
+**Surface unstated assumptions.** The user often assumes things without realizing it. Name the assumption: "You're assuming users will sign up before browsing — is that intentional?" "This assumes a single-tenant architecture — is that the plan?"
+
+**Propose alternatives with trade-offs.** Don't just accept the first approach. Offer 2-3 alternatives with clear trade-offs: "Option A is simpler but limits future X. Option B handles X but adds complexity in Y. Option C splits the difference but needs Z." Let the user weigh the trade-offs.
+
+**Suggest directions, don't dictate.** Frame suggestions as possibilities: "Have you considered...?" "One approach would be..." "What if instead of X, you Y?" The user decides. You illuminate paths.
+
+**Make consequences visible.** When a decision has downstream effects, name them: "If we go with X, that means Y and Z will need to change too." "This locks us into A — are you comfortable with that?"
+
+**Disagree constructively.** If you see a problem with the user's direction, say so: "I see a risk with that approach — [specific concern]. How do you want to handle it?" Don't just comply. Don't lecture either.
+
+</core_behaviors>
+
+<conversation_style>
+
+- **Follow the thread.** Build on what the user just said. Don't jump topics.
+- **Be concise.** Short, pointed questions beat long-winded explanations.
+- **React to energy.** If the user is excited about something, explore it. If they're uncertain, help them get clarity.
+- **One thing at a time.** Don't overload with multiple questions. Focus on the most important open question.
+- **Name the tension.** When trade-offs exist, state them directly: "The tension here is between X and Y."
+
+</conversation_style>
+
+<anti_patterns>
+
+- **Rubber-stamping** — agreeing with everything without pushback
+- **Interrogation mode** — firing questions without building on answers
+- **Over-qualifying** — "it depends" without narrowing what it depends on
+- **Premature solutions** — jumping to implementation before understanding the problem
+- **Passive compliance** — doing exactly what's asked without flagging concerns
+
+</anti_patterns>
+
+</thinking_partner>

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

@@ -0,0 +1,137 @@
+---
+name: batch-worktree
+description: Orchestrate parallel work across isolated git worktrees with independent PRs
+---
+
+# 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>
+
+## 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"
+```
+
+### 2. VALIDATE — Confirm Independence
+
+For each pair of units, verify:
+- No shared file modifications
+- No runtime dependency (unit A's output is not unit B's input)
+- Each unit's tests pass without the other unit's changes
+
+If validation fails: redesign the decomposition. Do not proceed with overlapping units.
+
+### 3. SPAWN — Create Worktree Per Unit
+
+For each unit, create an isolated worktree and spawn an agent:
+
+```bash
+# Create worktree branch for each unit
+git worktree add .claude/worktrees/unit-NN unit/NN-description -b unit/NN-description
+```
+
+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
+
+### 4. EXECUTE — Each Agent Works Independently
+
+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
+
+### 5. 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 | — |
+```
+
+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
+
+| 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 |
+
+## Common Rationalizations — REJECT THESE
+
+| 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. |
+
+## Verification Checklist
+
+Before reporting completion, confirm:
+
+- [ ] All units were verified to touch non-overlapping files
+- [ ] Each unit was implemented in an isolated worktree
+- [ ] Each unit's tests pass independently
+- [ ] Each unit has its own PR
+- [ ] No PR depends on another PR being merged first
+- [ ] Status table is complete with all PR links
+
+## In MAXSIM Plan Execution
+
+When a plan specifies `skill: "batch-worktree"`:
+- The orchestrator decomposes the plan's tasks into independent units
+- Each unit becomes a worktree agent with its own branch and PR
+- The orchestrator tracks progress and reports the final PR list in SUMMARY.md
+- Failed units are retried once before escalating

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

@@ -0,0 +1,159 @@
+---
+name: brainstorming
+description: Use before implementing any significant feature or design — requires exploring multiple approaches and getting explicit design approval before writing code
+---
+
+# 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.**
+
+## The Iron Law
+
+<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>
+
+## 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.
+
+- What is the goal? What does success look like?
+- What are the constraints (performance, compatibility, timeline)?
+- What has already been tried or considered?
+- 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:
+
+- 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
+
+```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
+
+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.
+
+### 4. DISCUSS — Refine with the User
+
+- 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
+
+**Continue ONE question at a time. Do not assume consensus until stated.**
+
+### 5. DECIDE — Get Explicit Approval
+
+The user must explicitly approve the chosen approach. Acceptable approvals:
+
+- "Go with approach A"
+- "Let's do option 2"
+- "Approved" / "LGTM" / "Ship it"
+
+Not acceptable as approval:
+
+- "Sounds good" (too vague — clarify which approach)
+- "Interesting" (not a decision)
+- Silence (not consent)
+
+**If approval is ambiguous, ask: "To confirm — should I proceed with [specific approach]?"**
+
+### 6. DOCUMENT — Record the Decision
+
+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. |
+| "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
+
+**If any red flag triggers: STOP. Return to the appropriate step.**
+
+## Verification Checklist
+
+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
+- [ ] User has explicitly approved one specific approach
+- [ ] Decision has been recorded in STATE.md
+- [ ] Design doc captures chosen approach, rejected alternatives, and risks
+
+## In MAXSIM Plan Execution
+
+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