maxsimcli 4.2.2 → 4.3.0

package/dist/assets/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [4.2.3](https://github.com/maystudios/maxsimcli/compare/v4.2.2...v4.2.3) (2026-03-03)
+
+
+### Bug Fixes
+
+* **test:** mock node:fs in adapters test to handle shared.ts side effects ([648176f](https://github.com/maystudios/maxsimcli/commit/648176f411b47d6fe83fada2fb240d83481dd171))
+
+## [4.2.2](https://github.com/maystudios/maxsimcli/compare/v4.2.1...v4.2.2) (2026-03-03)
+
+
+### Bug Fixes
+
+* **hooks:** restore shebang in pre-push hook ([d03f1cb](https://github.com/maystudios/maxsimcli/commit/d03f1cbfd7001c60884c880d7feb73d85e3ffe05))
+
 ## [4.2.1](https://github.com/maystudios/maxsimcli/compare/v4.2.0...v4.2.1) (2026-03-02)
 
 

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

@@ -14,14 +14,14 @@ Skills with `alwaysApply: true` load automatically at conversation start:
 
 | Agent | Skills | Role |
 |-------|--------|------|
-| `maxsim-executor` | `tdd`, `verification-before-completion`, `using-maxsim` | Implements plan tasks with TDD and verified completion |
+| `maxsim-executor` | `tdd`, `verification-before-completion`, `using-maxsim`, `maxsim-simplify` | Implements plan tasks with TDD, verified completion, and simplification |
 | `maxsim-debugger` | `systematic-debugging`, `verification-before-completion` | Investigates bugs via reproduce-hypothesize-isolate-verify-fix cycle |
 | `maxsim-verifier` | `verification-before-completion` | Checks phase goal achievement with fresh evidence |
-| `maxsim-planner` | `using-maxsim` | Creates executable PLAN.md files for phases |
+| `maxsim-planner` | `using-maxsim`, `brainstorming` | Creates executable PLAN.md files for phases |
 | `maxsim-plan-checker` | `verification-before-completion` | Verifies plans achieve phase goal before execution |
-| `maxsim-code-reviewer` | `verification-before-completion` | Reviews implementation for code quality with evidence |
+| `maxsim-code-reviewer` | `verification-before-completion`, `code-review` | Reviews implementation for code quality with evidence |
 | `maxsim-spec-reviewer` | `verification-before-completion` | Reviews implementation for spec compliance |
-| `maxsim-roadmapper` | `using-maxsim` | Creates project roadmaps with phase breakdown and requirement mapping |
+| `maxsim-roadmapper` | `using-maxsim`, `brainstorming`, `roadmap-writing` | Creates project roadmaps with phase breakdown and requirement mapping |
 | `maxsim-phase-researcher` | `memory-management` | Researches phase implementation domain for planning context |
 | `maxsim-project-researcher` | `memory-management` | Researches project domain ecosystem during init |
 | `maxsim-research-synthesizer` | `memory-management` | Synthesizes parallel research outputs into unified findings |
@@ -39,5 +39,7 @@ Skills with `alwaysApply: true` load automatically at conversation start:
 | `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 |
+| `maxsim-simplify` | `skills/maxsim-simplify/` | Maintainability optimization pass (duplication, dead code, complexity) |
+| `code-review` | `skills/code-review/` | Correctness gate (security, interfaces, errors, test coverage) |
+| `sdd` | `skills/sdd/` | Orchestration strategy: spec-driven dispatch with fresh agent per task |
+| `maxsim-batch` | `skills/maxsim-batch/` | Orchestration strategy: parallel worktree execution with one PR per unit |

package/dist/assets/templates/agents/maxsim-code-reviewer.md

@@ -85,6 +85,17 @@ Return this exact structure:
 - FAIL: One or more CRITICAL issues. List each with actionable fix suggestion.
 </verdict_format>
 
+<available_skills>
+When any trigger condition below applies, read the full skill file via the Read tool and follow it.
+
+| Skill | Read | Trigger |
+|-------|------|---------|
+| Code Review | `.skills/code-review/SKILL.md` | Always — primary skill for this agent |
+| Verification Before Completion | `.skills/verification-before-completion/SKILL.md` | Before claiming any review is complete |
+
+**Project skills override built-in skills.**
+</available_skills>
+
 <success_criteria>
 - [ ] CLAUDE.md read for project conventions
 - [ ] Every modified file read in FULL (not scanned)

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

@@ -279,6 +279,7 @@ When any trigger below applies, Read the full skill file and follow it. Always r
 | TDD Enforcement | `.skills/tdd/SKILL.md` | Before writing implementation code for new feature/bug fix, or plan type is `tdd` |
 | Systematic Debugging | `.skills/systematic-debugging/SKILL.md` | 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 |
+| Simplification | `.skills/maxsim-simplify/SKILL.md` | After implementing a task, before committing |
 
 Project skills in `.skills/` override built-in skills.
 </available_skills>

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

@@ -486,6 +486,7 @@ When any trigger condition below applies, read the full skill file via the Read
 |-------|------|---------|
 | 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 |
+| Brainstorming | `.skills/brainstorming/SKILL.md` | When exploring design approaches during task breakdown |
 
 **Project skills override built-in skills.**
 </available_skills>

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

@@ -99,8 +99,104 @@ All files go to `.planning/research/`. Each file starts with `**Domain/Project:*
 | **COMPARISON.md** (comparison mode) | Quick Comparison matrix, Detailed Analysis per option (strengths/weaknesses/best for), Recommendation with conditions |
 | **FEASIBILITY.md** (feasibility mode) | Verdict (YES/NO/MAYBE), Requirements table (status), Blockers table, Recommendation |
 
+### Mandatory Enhanced Sections
+
+Every research output file (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md) MUST include these 5 sections in addition to the format above:
+
+#### 1. Trade-Off Matrix
+
+For each major choice, compare top 2-3 options in a structured table:
+
+```markdown
+## Trade-Off Matrix
+
+| Option | Pros | Cons | Risk | Effort |
+|--------|------|------|------|--------|
+| [Option A] | Fast setup, large community | Vendor lock-in risk | LOW | S |
+| [Option B] | Full control, no lock-in | Steeper learning curve | MED | M |
+| [Option C] | Best performance | Small ecosystem | HIGH | L |
+```
+
+Risk levels: LOW / MED / HIGH. Effort sizes: S (hours) / M (days) / L (week) / XL (weeks).
+
+#### 2. Decision Rationale
+
+For your primary recommendation: explain WHY this over alternatives, and when to reconsider:
+
+```markdown
+## Decision Rationale
+
+**Recommendation:** [X] over [Y]
+**Why:** [Specific technical reasoning tied to this project's constraints]
+**When to reconsider:** [Conditions that would change this recommendation]
+```
+
+#### 3. Code Examples
+
+Concrete, copy-pasteable snippets for recommended technologies:
+
+```markdown
+## Code Examples
+
+### [Technology] Setup
+[Import statements, config snippets, middleware/pattern examples]
+```
+
+Include: import statements, basic configuration, one usage pattern per recommended technology. These help downstream agents write correct code from day one.
+
+#### 4. Integration Warnings
+
+Cross-cutting concerns between recommended technologies:
+
+```markdown
+## Integration Warnings
+
+- **[Tech A] + [Tech B]:** [What to watch out for, version compatibility, known conflicts]
+- **[Tech C] + [Tech D]:** [Configuration gotchas, ordering requirements]
+```
+
+Flag any combination that requires special attention. "If X + Y, watch out for Z" format.
+
+#### 5. Effort Estimates
+
+T-shirt size complexity estimate per recommendation:
+
+```markdown
+## Effort Estimates
+
+| Recommendation | Effort | Notes |
+|---------------|--------|-------|
+| [Tech/Pattern A] | S | Drop-in, well-documented |
+| [Tech/Pattern B] | M | Requires config + testing |
+| [Tech/Pattern C] | L | Migration path needed |
+| [Tech/Pattern D] | XL | Significant architecture work |
+```
+
+Sizes: S = hours, M = days, L = week, XL = weeks. Be honest about complexity.
+
 </output_formats>
 
+<web_verification>
+
+**MUST verify version numbers and library status via web search.** Use Context7, WebSearch, or WebFetch to confirm:
+
+- Current stable versions of recommended libraries
+- Whether recommended libraries are actively maintained (last release date, open issues)
+- Known breaking changes in recent versions
+- Deprecation notices or migration paths
+
+Assign confidence levels to every factual claim:
+
+| Level | Meaning | When to Use |
+|-------|---------|-------------|
+| **HIGH** | Verified via web (Context7/official docs) | Version numbers, API signatures, feature availability confirmed online |
+| **MEDIUM** | Known from training data, unverified via web | Well-known facts that could not be live-verified (e.g., tool unavailable) |
+| **LOW** | Uncertain or single unverified source | Anything you are not confident about -- flag prominently |
+
+Mark each technology recommendation with its confidence level. Flag anything unverifiable with `[CONFIDENCE: LOW - unverified]`.
+
+</web_verification>
+
 <execution_flow>
 
 1. **Receive scope** — Parse project name/description, research mode, specific questions from orchestrator.

package/dist/assets/templates/agents/maxsim-research-synthesizer.md

@@ -58,18 +58,70 @@ Read all 4 files from `.planning/research/` and extract:
 
 Per area (Stack/Features/Architecture/Pitfalls): assign confidence level based on source quality. Identify gaps needing attention during planning.
 
-## Step 5: Write SUMMARY.md
+## Step 5: Produce Locked Decisions
+
+Extract the most impactful decisions from research into a **Locked Decisions** table. These flow to the planner as hard constraints.
+
+### Locked Decisions Format
+
+```markdown
+## Locked Decisions
+
+These decisions have been validated by research and approved by the user. They flow to the planner as constraints.
+
+| # | Decision | Rationale | Alternatives Rejected | Effort |
+|---|----------|-----------|----------------------|--------|
+| 1 | [e.g., Use PostgreSQL] | [Why this over alternatives] | [e.g., MongoDB (schema flexibility not needed)] | M |
+| 2 | [e.g., Use NextAuth] | [Why this over alternatives] | [e.g., Clerk (SaaS dependency)] | S |
+```
+
+### Rules for Locked Decisions
+
+- **Cross-reference PROJECT.md:** Read `.planning/PROJECT.md` Key Decisions section. Do NOT lock decisions that contradict what the user already decided during questioning. User decisions from questioning take precedence over research recommendations.
+- **Limit scope:** Only lock decisions that are architecturally significant (framework, database, auth, hosting, major patterns). Do NOT lock utility library choices.
+- **Include effort:** Every locked decision must have a T-shirt size effort estimate (S/M/L/XL).
+- **Rationale required:** Every locked decision must explain WHY, not just WHAT.
+
+## Step 5b: Approval Gate
+
+After producing locked decisions, the workflow MUST present them to the user before proceeding:
+
+**Approval gate instruction:** Present the Locked Decisions table to the user with the message: "These are the technology decisions from research. You can approve all, override specific decisions, or request changes." The user must explicitly approve before locked decisions flow to the planner. User can override any decision.
+
+Do NOT proceed to roadmap creation until the user has approved locked decisions.
+
+## Step 5c: Enrich PROJECT.md with Tech Stack Decisions
+
+After user approval, add a **Tech Stack Decisions** section to `.planning/PROJECT.md` containing the approved locked decisions. This makes PROJECT.md self-contained for downstream agents.
+
+```markdown
+## Tech Stack Decisions
+
+> Locked during research phase. Approved by user on {{date}}.
+
+| Category | Decision | Rationale |
+|----------|----------|-----------|
+| Database | PostgreSQL | Relational queries dominate; strong ecosystem |
+| Auth | NextAuth | Self-hosted, no vendor lock-in |
+| ...      | ...      | ...       |
+```
+
+Cross-reference: These decisions appear in both PROJECT.md (for quick agent reference) and `.planning/research/SUMMARY.md` (with full rationale and alternatives).
+
+## Step 6: Write SUMMARY.md
 
 Use template: `~/.claude/maxsim/templates/research-project/SUMMARY.md`
 Write to `.planning/research/SUMMARY.md`
 
-## Step 6: Commit All Research
+Include the Locked Decisions table in SUMMARY.md as a dedicated section.
+
+## Step 7: Commit All Research
 
 ```bash
 node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: complete project research" --files .planning/research/
 ```
 
-## Step 7: Return Summary
+## Step 8: Return Summary
 
 </execution_flow>
 

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

@@ -215,6 +215,17 @@ Use template from `~/.claude/maxsim/templates/state.md`. Key sections: Project R
 ```
 </structured_returns>
 
+<available_skills>
+When any trigger condition below applies, read the full skill file via the Read tool and follow it.
+
+| Skill | Read | Trigger |
+|-------|------|---------|
+| Brainstorming | `.skills/brainstorming/SKILL.md` | When exploring design approaches during phase identification |
+| Roadmap Writing | `.skills/roadmap-writing/SKILL.md` | When structuring phases, success criteria, and coverage validation |
+
+**Project skills override built-in skills.**
+</available_skills>
+
 <success_criteria>
 Roadmap is complete when:
 

package/dist/assets/templates/references/questioning.md

@@ -1,6 +1,6 @@
 <questioning_guide>
 
-Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
+Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation -- it's collaborative thinking.
 
 <philosophy>
 
@@ -36,9 +36,9 @@ A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
 
 **Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
 
-**Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
+**Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X -- tell me more."
 
-**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
+**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like -- offer to proceed.
 
 </how_to_question>
 
@@ -46,21 +46,21 @@ A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
 
 Use these as inspiration, not a checklist. Pick what's relevant to the thread.
 
-**Motivation — why this exists:**
+**Motivation -- why this exists:**
 - "What prompted this?"
 - "What are you doing today that this replaces?"
 - "What would you do if this existed?"
 
-**Concreteness — what it actually is:**
+**Concreteness -- what it actually is:**
 - "Walk me through using this"
-- "You said X — what does that actually look like?"
+- "You said X -- what does that actually look like?"
 - "Give me an example"
 
-**Clarification — what they mean:**
+**Clarification -- what they mean:**
 - "When you say Z, do you mean A or B?"
-- "You mentioned X — tell me more about that"
+- "You mentioned X -- tell me more about that"
 
-**Success — how you'll know it's working:**
+**Success -- how you'll know it's working:**
 - "How will you know this is working?"
 - "What does done look like?"
 
@@ -79,51 +79,199 @@ Use AskUserQuestion to help users think by presenting concrete options to react
 - Generic categories ("Technical", "Business", "Other")
 - Leading options that presume an answer
 - Too many options (2-4 is ideal)
-- Headers longer than 12 characters (hard limit — validation will reject them)
+- Headers longer than 12 characters (hard limit -- validation will reject them)
 
-**Example — vague answer:**
+**Example -- vague answer:**
 User says "it should be fast"
 
 - header: "Fast"
 - question: "Fast how?"
 - options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
 
-**Example — following a thread:**
+**Example -- following a thread:**
 User mentions "frustrated with current tools"
 
 - header: "Frustration"
 - question: "What specifically frustrates you?"
 - options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
 
-**Tip for users — modifying an option:**
+**Tip for users -- modifying an option:**
 Users who want a slightly modified version of an option can select "Other" and reference the option by number: `#1 but for finger joints only` or `#2 with pagination disabled`. This avoids retyping the full option text.
 
 </using_askuserquestion>
 
-<context_checklist>
+<domain_checklist>
 
-Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
+Track these domains silently as a background checklist. Mark each as COVERED, N/A, or UNCOVERED as conversation progresses. Do NOT show this checklist to the user. Do NOT switch to checklist mode. Do NOT fire rapid questions to cover domains.
 
-- [ ] What they're building (concrete enough to explain to a stranger)
-- [ ] Why it needs to exist (the problem or desire driving it)
-- [ ] Who it's for (even if just themselves)
-- [ ] What "done" looks like (observable outcomes)
+**Follow the user's thread first. Only weave checklist domains when natural pauses occur or when the user's response opens a related domain.**
 
-Four things. If they volunteer more, capture it.
+### Core
+- [ ] Auth approach (SSO, email/pass, OAuth, magic links, API keys, none)
+- [ ] Data model (relational, document, graph, key-value, file-based)
+- [ ] API style (REST, GraphQL, tRPC, gRPC, WebSocket, none/internal)
+- [ ] Deployment target (serverless, containers, VPS, edge, desktop, mobile)
+- [ ] Error handling strategy (exceptions, Result types, error boundaries, status codes)
+- [ ] Testing strategy (unit, integration, e2e, coverage targets, TDD)
 
-</context_checklist>
+### Infrastructure
+- [ ] Caching strategy (Redis, in-memory, CDN, service worker, none)
+- [ ] Search (full-text, Elasticsearch, Algolia, vector search, none)
+- [ ] Monitoring/logging (structured logs, APM, error tracking, analytics)
+- [ ] CI/CD (GitHub Actions, GitLab CI, CircleCI, none yet)
+- [ ] Environments (dev/staging/prod, single env, preview deploys)
+
+### UX/Product
+- [ ] User roles/permissions (RBAC, ABAC, simple admin/user, single-user)
+- [ ] Notifications (email, push, in-app, WebSocket, none)
+- [ ] File uploads (images, documents, media, user-generated content, none)
+- [ ] Internationalization (i18n needed, English only, later)
+- [ ] Accessibility (WCAG compliance level, not applicable)
+
+### Scale/Ops
+- [ ] Performance targets (response time, throughput, concurrent users)
+- [ ] Concurrency model (single-threaded, worker pools, event-driven, actors)
+- [ ] Data migration (from existing system, fresh start, import needed)
+- [ ] Backup/recovery (RTO/RPO targets, disaster recovery plan, not applicable)
+- [ ] Rate limiting (API limits, abuse prevention, quotas, not applicable)
+
+### Tracking Rules
+
+1. **One round = one AskUserQuestion call.** Count these, not messages.
+2. **Mark domains generously as N/A.** Not all 21 domains apply to every project. A CLI tool does not need file uploads, internationalization, backup/recovery, notifications, etc.
+3. **N/A counts as covered** for the coverage calculation.
+4. **Never mention the checklist or domains to the user.** This is your internal tracking only.
+5. **Weave naturally, never interrogate.** If a domain is uncovered after several rounds, find a natural segue from what the user already said.
+
+### N/A Decision Tree (examples by project type)
+
+**CLI tool:** Mark as N/A: file uploads, internationalization, accessibility, notifications, user roles, caching, search, backup/recovery, rate limiting, environments (unless multi-env deployment). Focus on: deployment target, testing strategy, error handling, CI/CD.
+
+**SaaS web app:** Most domains apply. Mark as N/A only if explicitly irrelevant (e.g., data migration if greenfield).
+
+**API/backend service:** Mark as N/A: accessibility, internationalization (usually), file uploads (if not applicable). Focus on: API style, auth, rate limiting, caching, monitoring.
+
+**Mobile app:** Mark as N/A: search (usually), environments (different model), rate limiting (server-side). Focus on: deployment target, offline strategy, push notifications, auth.
+
+**Static site / marketing:** Mark as N/A: auth, data model, caching, search, monitoring, most Scale/Ops. Focus on: deployment target, CI/CD, accessibility, internationalization.
+
+</domain_checklist>
+
+<gate_logic>
+
+The "Ready?" decision gate has strict conditions. Do NOT show it prematurely.
+
+### Conditions (ALL must be true)
+
+1. **Minimum rounds:** round_count >= 10 (one round = one AskUserQuestion call)
+2. **Coverage threshold:** 80% of relevant domains must be covered. Formula: covered_count / (total_domains - na_count) >= 0.80
+   - covered_count = domains with COVERED status
+   - na_count = domains with N/A status
+   - total_domains = 21
+3. **Core understanding:** You could write a clear PROJECT.md that a stranger would understand
+
+### Before showing "Ready?"
+
+Display a domain coverage summary by category (this is the ONE time coverage becomes visible):
+
+```
+I think I have a solid picture. Here's what we've covered:
+
+**Core:** Auth, data model, API style, deployment, error handling, testing
+**Infrastructure:** CI/CD, environments (caching: N/A, search: N/A, monitoring: N/A)
+**UX/Product:** User roles (notifications: N/A, uploads: N/A, i18n: N/A, accessibility: N/A)
+**Scale/Ops:** Performance targets (concurrency: N/A, migration: N/A, backup: N/A, rate limiting: N/A)
+
+Coverage: 10/12 relevant domains (83%)
+```
+
+Then present the decision gate:
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" -- Let's move forward
+  - "Keep exploring" -- I want to share more / ask me more
+
+If "Keep exploring" -- identify which uncovered domains might be relevant and weave them into conversation naturally. Loop until "Create PROJECT.md" selected.
+
+### Anti-Pattern Examples (interrogation prevention)
+
+**BAD:** "What about caching?" (out of nowhere, no connection to conversation)
+**GOOD:** "You mentioned handling 10K concurrent users -- have you thought about caching strategy?"
+
+**BAD:** "Let's talk about internationalization." (topic shift with no context)
+**GOOD:** "You said your users are spread across Europe -- will the interface need to support multiple languages?"
+
+**BAD:** "What's your monitoring approach?" (checklist-walking)
+**GOOD:** "With a distributed system like this, how will you know when something goes wrong in production?"
+
+**Explicit instruction:** Follow the user's thread first. Only weave checklist domains when natural pauses occur or when the user's response opens a related domain. If a domain is hard to weave naturally, it is probably N/A for this project -- mark it and move on.
+
+</gate_logic>
+
+<nogos_tracking>
+
+No-gos are captured as a side-channel during questioning. You accumulate them silently and present them for confirmation before writing NO-GOS.md.
+
+### During Questioning: Watch for Rejection Signals
+
+As the user talks, watch for these patterns and silently record them as candidate no-gos:
+
+- **Explicit rejections:** "I don't want X", "Never use Y", "No way we're doing Z"
+- **Past failures:** "Last time we tried X and it was terrible", "We burned on Y before"
+- **Strong opinions:** "Absolutely not Z", "Over my dead body", "That's an anti-pattern"
+- **Anti-patterns mentioned:** "The codebase already has too much of X", "I've seen Y fail everywhere"
+
+**Do NOT confirm each no-go individually as it comes up.** Silently accumulate them. The confirmation step comes later.
+
+### Challenge-Based Probing (after 5+ rounds, challenge-based elicitation)
+
+Once rapport is established (5+ rounds), weave these probes naturally when the conversation allows:
+
+- "What would make this project fail?"
+- "What shortcuts are tempting but dangerous for a project like this?"
+- "What did a previous version get wrong?" (if applicable)
+- "What's the one decision you'd regret in 6 months?"
+- "If a new developer joined, what mistakes would you warn them about?"
+
+**Timing:** These are conversation contributions, not interrogation questions. Weave them when the user pauses, reflects, or mentions past experience. Never fire them in sequence.
+
+### Domain-Aware Suggestions (domain-aware anti-pattern suggestions after understanding the project type)
+
+Once you understand what they're building, suggest common anti-patterns for that domain. Present these as food for thought, not a checklist:
+
+**SaaS:** shared-database multi-tenancy without isolation, storing secrets in code, vendor lock-in without abstraction layers, skipping audit logging, ignoring data residency requirements
+
+**CLI tool:** global mutable state, implicit dependencies on environment, breaking flag/option changes between versions, silent failures with zero exit code, writing to stdout when should be stderr
+
+**API/backend:** N+1 queries, unbounded response sizes, missing rate limits, sync operations that should be async, tight coupling between services, missing idempotency keys
+
+**Mobile app:** assuming always-online, blocking the main thread, ignoring battery/data impact, platform-specific assumptions, missing offline conflict resolution
+
+**Real-time system:** assuming ordered delivery, ignoring backpressure, unbounded queues, missing heartbeat/reconnection, no graceful degradation
+
+### Before Writing NO-GOS.md: Confirmation Step
+
+After the user selects "Create PROJECT.md" but BEFORE writing documents, present ALL collected no-gos:
+
+"Before I write the project documents, here are the no-gos I captured from our conversation -- things you want to explicitly avoid or forbid. Anything to add, remove, or adjust?"
+
+Present them in a clear list with the source context (what the user said that triggered each one). User confirms or adjusts. Only confirmed no-gos go into NO-GOS.md.
+
+</nogos_tracking>
 
 <decision_gate>
 
-When you could write a clear PROJECT.md, offer to proceed:
+When you could write a clear PROJECT.md AND the gate_logic conditions are met, offer to proceed:
 
 - header: "Ready?"
 - question: "I think I understand what you're after. Ready to create PROJECT.md?"
 - options:
-  - "Create PROJECT.md" — Let's move forward
-  - "Keep exploring" — I want to share more / ask me more
+  - "Create PROJECT.md" -- Let's move forward
+  - "Keep exploring" -- I want to share more / ask me more
 
-If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
+If "Keep exploring" -- ask what they want to add or identify gaps and probe naturally.
 
 Loop until "Create PROJECT.md" selected.
 
@@ -131,14 +279,17 @@ Loop until "Create PROJECT.md" selected.
 
 <anti_patterns>
 
-- **Checklist walking** — Going through domains regardless of what they said
-- **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
-- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
-- **Interrogation** — Firing questions without building on answers
-- **Rushing** — Minimizing questions to get to "the work"
-- **Shallow acceptance** — Taking vague answers without probing
-- **Premature constraints** — Asking about tech stack before understanding the idea
-- **User skills** — NEVER ask about user's technical experience. Claude builds.
+- **Checklist walking** -- Going through domains regardless of what they said
+- **Canned questions** -- "What's your core value?" "What's out of scope?" regardless of context
+- **Corporate speak** -- "What are your success criteria?" "Who are your stakeholders?"
+- **Interrogation** -- Firing questions without building on answers
+- **Rushing** -- Minimizing questions to get to "the work"
+- **Shallow acceptance** -- Taking vague answers without probing
+- **Premature constraints** -- Asking about tech stack before understanding the idea
+- **User skills** -- NEVER ask about user's technical experience. Claude builds.
+- **Visible progress tracking** -- NEVER show domain coverage during questioning (only at the gate)
+- **Rapid-fire domain questions** -- NEVER ask about multiple unrelated domains in one message
+- **Forced relevance** -- Trying to make irrelevant domains seem relevant just to check them off
 
 </anti_patterns>
 

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

@@ -1,9 +1,11 @@
 ---
 name: code-review
 description: >-
-  Reviews all changed code for security vulnerabilities, interface correctness,
-  error handling, test coverage, and quality before sign-off. Use when completing
-  a phase, reviewing implementation, or before approving changes for merge.
+  Correctness gate: reviews all changed code for security vulnerabilities,
+  interface correctness, error handling, test coverage, and quality. Answers
+  "Is this code correct and safe?" Use when completing a phase, reviewing
+  implementation, or before approving changes for merge. Not a maintainability
+  pass — that is maxsim-simplify's job.
 ---
 
 # Code Review

package/dist/assets/templates/skills/{batch-worktree → maxsim-batch}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: batch-worktree
+name: maxsim-batch
 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
+  3-30 independent units or orchestrating worktree-based parallel execution. Not
   for sequential dependencies or fewer than 3 units.
 ---
 
@@ -83,7 +83,7 @@ Before reporting completion, confirm:
 
 ## MAXSIM Integration
 
-When a plan specifies `skill: "batch-worktree"`:
+When a plan specifies `skill: "maxsim-batch"`:
 - 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

package/dist/assets/templates/skills/{simplify → maxsim-simplify}/SKILL.md

@@ -1,10 +1,11 @@
 ---
-name: simplify
+name: maxsim-simplify
 description: >-
-  Reviews changed code for reuse opportunities, unnecessary complexity, and
-  dead weight using three parallel review agents. Use when reviewing code
-  before committing, cleaning up implementations, or preparing changes for
-  review.
+  Maintainability optimization pass: finds duplication, dead code, and
+  unnecessary complexity. Answers "Is this code as simple as it can be?"
+  Use when reviewing code before committing, cleaning up implementations,
+  or preparing changes for review. Not a correctness gate — that is
+  code-review's job.
 ---
 
 # Simplify
@@ -134,7 +135,7 @@ Before reporting completion, confirm:
 
 ## MAXSIM Integration
 
-When a plan specifies `skill: "simplify"`:
+When a plan specifies `skill: "maxsim-simplify"`:
 - The orchestrator collects changed files from the implementation step
 - Three parallel reviewers (Reuse, Quality, Efficiency) are spawned
 - Findings are consolidated and fixes applied

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

@@ -54,8 +54,10 @@ Skills are behavioral rules that activate automatically based on context:
 | `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 |
-| `simplify` | When reviewing and cleaning up code changes |
-| `code-review` | When reviewing implementation quality |
+| `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