maxsimcli 3.11.0 → 4.0.0

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

@@ -0,0 +1,185 @@
+---
+name: simplify
+description: Use after implementation and before commit — requires reviewing changed code for reuse opportunities, quality issues, and unnecessary complexity
+---
+
+# Simplify
+
+Every line of code is a liability. Less code that does the same thing is always better.
+
+**If you have not looked for ways to simplify, you are shipping the first draft.**
+
+## The Iron Law
+
+<HARD-GATE>
+NO COMMIT WITHOUT REVIEWING FOR SIMPLIFICATION.
+If you have not checked for duplication, dead code, and unnecessary complexity, you CANNOT commit.
+"It works" is the starting point, not the finish line.
+Violating this rule is a violation — not a preference.
+</HARD-GATE>
+
+## The Gate Function
+
+After implementation is complete and tests pass, BEFORE committing:
+
+### 1. DIFF — Review What Changed
+
+- Run `git diff --staged` (or `git diff` for unstaged changes)
+- Read every line you are about to commit
+- Flag anything that feels "off" — trust that instinct
+
+```bash
+# Review staged changes
+git diff --staged
+# Or all uncommitted changes
+git diff
+```
+
+### 2. DUPLICATION — Find Reuse Opportunities
+
+- Does any new code duplicate existing logic in the codebase?
+- Are there two or more blocks that do similar things and could share a helper?
+- Could an existing utility, library function, or helper replace new code?
+- Is there copy-paste from another file that should be extracted?
+
+**Rule of three:** If the same pattern appears three times, extract it. Two occurrences are acceptable.
+
+### 3. DEAD CODE — Remove What Is Not Used
+
+- Are there unused imports, variables, or functions?
+- Are there commented-out code blocks? (Delete them — git has history)
+- Are there unreachable branches or impossible conditions?
+- Are there parameters that are always passed the same value?
+
+**If it is not called, it does not belong. Delete it.**
+
+### 4. COMPLEXITY — Question Every Abstraction
+
+- Is there a wrapper that adds no value beyond indirection?
+- Is there a generic solution where a specific one would be simpler?
+- Are there feature flags, configuration options, or extension points for hypothetical future needs?
+- Could a 3-line inline block replace a 20-line abstraction?
+
+**The right amount of abstraction is the minimum needed for the current requirements.**
+
+### 5. CLARITY — Improve Readability
+
+- Are variable and function names self-explanatory?
+- Could a confusing block be rewritten more clearly without comments?
+- Are there nested conditions that could be flattened with early returns?
+- Is the control flow straightforward or unnecessarily clever?
+
+### 6. EFFICIENCY — Check for Obvious Issues
+
+- Are there O(n^2) operations where O(n) is straightforward?
+- Are there repeated computations that could be cached or hoisted?
+- Are there unnecessary allocations in hot paths?
+- Is data being transformed multiple times when once would suffice?
+
+**Only fix efficiency issues that are obvious. Do not optimize without evidence of a problem.**
+
+## Review Checklist
+
+| Category | Question | Action if Yes |
+|----------|----------|---------------|
+| Duplication | Same logic exists elsewhere? | Extract shared helper or reuse existing |
+| Duplication | Copy-paste from another file? | Extract to shared module |
+| Dead code | Unused imports or variables? | Delete them |
+| Dead code | Commented-out code? | Delete it (git has history) |
+| Complexity | Abstraction for one call site? | Inline it |
+| Complexity | Generic where specific suffices? | Simplify to specific |
+| Complexity | Config for hypothetical needs? | Remove until needed |
+| Clarity | Confusing variable name? | Rename to describe purpose |
+| Clarity | Deep nesting? | Flatten with early returns |
+| Efficiency | O(n^2) with obvious O(n) fix? | Fix it now |
+| Efficiency | Same computation in a loop? | Hoist outside the loop |
+
+## Common Rationalizations — REJECT THESE
+
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "It works, don't touch it" | Working is the minimum bar. Simplify before it becomes legacy. |
+| "We might need the flexibility later" | YAGNI. Add flexibility when you need it, not before. |
+| "Refactoring is risky" | Small simplifications with passing tests are safe. Large refactors are a separate task. |
+| "The duplication is minor" | Minor duplication compounds. Three occurrences is the threshold, not six. |
+| "I'll clean it up in a follow-up" | Follow-ups rarely happen. Simplify now while context is fresh. |
+| "It's just a few extra lines" | Every unnecessary line is maintenance cost. Delete it. |
+
+## Red Flags — STOP If You Catch Yourself:
+
+- Committing without reading your own diff
+- Keeping dead code "just in case"
+- Adding a utility class for a single use case
+- Building configuration for features no one has requested
+- Writing a comment to explain code that could be rewritten to be self-evident
+- Skipping simplification because "it's good enough"
+
+**If any red flag triggers: STOP. Review the diff again. Simplify before committing.**
+
+## Verification Checklist
+
+Before committing, confirm:
+
+- [ ] All staged changes have been reviewed line by line
+- [ ] No duplication with existing codebase logic (or duplication is below threshold)
+- [ ] No dead code: unused imports, variables, unreachable branches, commented code
+- [ ] No unnecessary abstractions, wrappers, or premature generalizations
+- [ ] Naming is clear and consistent with codebase conventions
+- [ ] No obvious efficiency issues (unnecessary O(n^2), repeated computations)
+- [ ] Tests still pass after simplification changes
+
+## In MAXSIM Plan Execution
+
+Simplification applies at the task level, after implementation and before commit:
+- After task implementation is complete and tests pass, run this review
+- Make simplification changes as part of the same commit (not a separate task)
+- If simplification reveals a larger refactoring opportunity, file a todo — do not scope-creep
+- Track significant simplifications in the task's commit message (e.g., "extracted shared helper for X")
+
+## Parallel 3-Reviewer Pattern (Execution Pipeline)
+
+When invoked as part of the Execute-Review-Simplify-Review cycle in `execute-plan.md`, simplification runs as 3 parallel review agents. Each reviewer focuses on one dimension:
+
+### Reviewer 1: Code Reuse
+- Find duplicated logic across the codebase (not just within changed files)
+- Identify copy-paste from other files that should be extracted to shared modules
+- Suggest shared helpers for patterns appearing 3+ times (Rule of Three)
+- Check if existing utility functions, library methods, or helpers could replace new code
+- **Output:** List of reuse opportunities with file paths and line ranges
+
+### Reviewer 2: Code Quality
+- Check naming consistency with codebase conventions (read CLAUDE.md first)
+- Verify error handling covers all external calls and edge cases
+- Look for dead code: unused imports, variables, unreachable branches, commented-out code
+- Check for unnecessary abstractions, wrappers, or premature generalizations
+- Verify security: no hardcoded secrets, no unsanitized inputs, no data exposure
+- **Output:** List of quality issues categorized by severity (BLOCKER, HIGH, MEDIUM)
+
+### Reviewer 3: Efficiency
+- Find O(n^2) operations where O(n) is straightforward
+- Identify repeated computations that could be cached or hoisted out of loops
+- Check for unnecessary allocations in hot paths
+- Look for redundant data transformations (data processed multiple times when once suffices)
+- Only flag obvious issues — do not optimize without evidence of a problem
+- **Output:** List of efficiency issues with suggested fixes
+
+### Consolidation
+
+After all 3 reviewers report, the orchestrating agent:
+1. Merges findings into a single deduplicated list
+2. Prioritizes: BLOCKER > HIGH > MEDIUM > informational
+3. Applies fixes for all actionable items (BLOCKER and HIGH)
+4. Files MEDIUM issues as todos if they require larger refactoring
+5. Runs tests to confirm fixes do not break anything
+6. Reports final status: CLEAN (nothing found), FIXED (issues found and resolved), or BLOCKED (cannot fix without architectural change)
+
+### Spawning Pattern
+
+Each reviewer is spawned as a parallel agent via the Agent tool:
+```
+# All 3 run in parallel
+Task(prompt="Reviewer 1: Code Reuse — {files_to_review} ...", subagent_type="maxsim-executor")
+Task(prompt="Reviewer 2: Code Quality — {files_to_review} ...", subagent_type="maxsim-executor")
+Task(prompt="Reviewer 3: Efficiency — {files_to_review} ...", subagent_type="maxsim-executor")
+# Wait for all 3 to complete, then consolidate
+```

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

@@ -0,0 +1,120 @@
+---
+name: using-maxsim
+description: Entry skill that establishes MAXSIM workflow rules — triggers before any action to route work through the correct MAXSIM commands, skills, and agents
+alwaysApply: true
+---
+
+# Using MAXSIM
+
+MAXSIM is a spec-driven development system. Work flows through phases, plans, and tasks — not ad-hoc coding.
+
+**If you are about to write code without a plan, STOP. Route through MAXSIM first.**
+
+## The Iron Law
+
+<HARD-GATE>
+NO IMPLEMENTATION WITHOUT A PLAN.
+If there is no .planning/ directory, run `/maxsim:init` first.
+If there is no current phase, run `/maxsim:plan-phase` first.
+If there is no PLAN.md for the current phase, run `/maxsim:plan-phase` first.
+If there IS a plan, run `/maxsim:execute-phase` to execute it.
+Skipping the workflow is a violation — not a shortcut.
+</HARD-GATE>
+
+## When This Skill Triggers
+
+This skill applies to ALL work sessions. Before starting any task:
+
+1. **Check for `.planning/` directory** — if missing, initialize with `/maxsim:init`
+2. **Check STATE.md** — resume from last checkpoint if one exists
+3. **Check current phase** — determine what phase is active in ROADMAP.md
+4. **Route to the correct command** based on the situation (see routing table below)
+
+## Routing Table
+
+| Situation | Route To |
+|-----------|----------|
+| No `.planning/` directory | `/maxsim:init` |
+| No ROADMAP.md or empty roadmap | `/maxsim:plan-roadmap` |
+| Active phase has no PLAN.md | `/maxsim:plan-phase` |
+| Active phase has PLAN.md, not started | `/maxsim:execute-phase` |
+| Checkpoint exists in STATE.md | `/maxsim:resume-work` |
+| Bug found during execution | `/maxsim:debug` (triggers systematic-debugging skill) |
+| Phase complete, needs verification | `/maxsim:verify-phase` (triggers verification-before-completion skill) |
+| Quick standalone task | `/maxsim:quick` |
+| User asks for help | `/maxsim:help` |
+
+## Available Skills
+
+Skills are behavioral rules that activate automatically based on context:
+
+| Skill | Triggers When |
+|-------|---------------|
+| `using-maxsim` | Always (alwaysApply) — entry point for all MAXSIM work |
+| `systematic-debugging` | Any bug, test failure, or unexpected behavior encountered |
+| `tdd` | Implementing any feature or bug fix (write test first) |
+| `verification-before-completion` | Before claiming any work is complete or passing |
+| `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 |
+
+## Available Agents
+
+Agents are specialized subagent prompts spawned by MAXSIM commands:
+
+| Agent | Purpose | Triggered By |
+|-------|---------|-------------|
+| `maxsim-executor` | Executes plans with atomic commits | `/maxsim:execute-phase` |
+| `maxsim-planner` | Creates structured PLAN.md files | `/maxsim:plan-phase` |
+| `maxsim-debugger` | Investigates bugs systematically | `/maxsim:debug` |
+| `maxsim-verifier` | Verifies phase goal achievement | `/maxsim:verify-phase` |
+| `maxsim-roadmapper` | Creates project roadmaps | `/maxsim:plan-roadmap` |
+| `maxsim-phase-researcher` | Researches phase requirements | `/maxsim:plan-phase` |
+| `maxsim-code-reviewer` | Reviews code changes | `/maxsim:review` |
+| `maxsim-spec-reviewer` | Reviews specifications | `/maxsim:plan-roadmap` |
+| `maxsim-plan-checker` | Validates plan completeness | `/maxsim:plan-phase` |
+| `maxsim-project-researcher` | Researches project context | `/maxsim:init` |
+| `maxsim-research-synthesizer` | Synthesizes research findings | `/maxsim:plan-phase` |
+| `maxsim-codebase-mapper` | Maps codebase structure | `/maxsim:init` |
+| `maxsim-integration-checker` | Checks integration points | `/maxsim:verify-phase` |
+
+## Common Rationalizations — REJECT THESE
+
+| Excuse | Why It Violates the Rule |
+|--------|--------------------------|
+| "It's just a small fix" | Small fixes have context and consequences. Use `/maxsim:quick`. |
+| "I know what to do, I don't need a plan" | Plans catch what you miss. The plan is the checkpoint. |
+| "MAXSIM overhead is too much for this" | `/maxsim:quick` exists for lightweight tasks. Use it. |
+| "I'll plan it in my head" | Plans in your head die with context. Write them down. |
+| "The user said 'just do it'" | Route through `/maxsim:quick` — it is fast and still tracked. |
+
+## Red Flags — STOP If You Catch Yourself:
+
+- Writing implementation code without a PLAN.md
+- Skipping `/maxsim:init` because "the project is simple"
+- Ignoring STATE.md checkpoints from previous sessions
+- Working outside the current phase without explicit user approval
+- Making architectural decisions without documenting them in STATE.md
+- Finishing work without running verification
+
+**If any red flag triggers: STOP. Check the routing table. Follow the workflow.**
+
+## Verification Checklist
+
+Before ending any work session:
+
+- [ ] All work was routed through MAXSIM commands (not ad-hoc)
+- [ ] STATE.md reflects current progress and decisions
+- [ ] Any bugs encountered were debugged systematically (not guessed)
+- [ ] Tests were written before implementation (TDD)
+- [ ] Completion claims have verification evidence
+- [ ] Recurring patterns or errors were saved to memory
+
+## Integration with CLAUDE.md
+
+When a project has a `CLAUDE.md`, both apply:
+- `CLAUDE.md` defines project-specific conventions (language, tools, style)
+- MAXSIM skills define workflow rules (how work is structured and verified)
+- If they conflict, `CLAUDE.md` project conventions take priority for code style; MAXSIM takes priority for workflow structure

package/dist/assets/templates/templates/acceptance-criteria.md

@@ -0,0 +1,10 @@
+# Acceptance Criteria
+
+> Conditions that must be met for deliverables to be accepted.
+
+**Created:** {{date}}
+
+## Criteria
+
+| # | Criterion | Status | Verified |
+|---|-----------|--------|----------|

package/dist/assets/templates/templates/config.json

@@ -3,7 +3,7 @@
   "depth": "standard",
   "workflow": {
     "research": true,
-    "plan_check": true,
+    "plan_checker": true,
     "verifier": true,
     "auto_advance": false,
     "nyquist_validation": false

package/dist/assets/templates/templates/decisions.md

@@ -0,0 +1,10 @@
+# Decisions
+
+> Architectural and design decisions for this project.
+
+**Created:** {{date}}
+
+## Decision Log
+
+| # | Decision | Rationale | Date | Phase |
+|---|----------|-----------|------|-------|

package/dist/assets/templates/templates/no-gos.md

@@ -0,0 +1,9 @@
+# No-Gos
+
+> Things explicitly out of scope or forbidden.
+
+**Created:** {{date}}
+
+## Boundaries
+
+- _No entries yet._

package/dist/assets/templates/workflows/add-tests.md

@@ -141,10 +141,10 @@ If user selects "Cancel": exit gracefully.
 Before generating the test plan, discover the project's existing test structure:
 
 ```bash
-# Find existing test directories
-find . -type d -name "*test*" -o -name "*spec*" -o -name "*__tests__*" 2>/dev/null | head -20
+# Find existing test directories and files (cross-platform)
+git ls-files --others --cached --exclude-standard | grep -E "(test|spec|__tests__)" | head -20
 # Find existing test files for convention matching
-find . -type f \( -name "*.test.*" -o -name "*.spec.*" -o -name "*Tests.fs" -o -name "*Test.fs" \) 2>/dev/null | head -20
+git ls-files --others --cached --exclude-standard | grep -E "\.(test|spec)\.|Tests\.(fs|cs)|Test\.(fs|cs)" | head -20
 # Check for test runners
 ls package.json *.sln 2>/dev/null
 ```

package/dist/assets/templates/workflows/add-todo.md

@@ -5,6 +5,7 @@ Capture an idea, task, or issue that surfaces during a MAXSIM session as a struc
 <required_reading>
 Read all files referenced by the invoking prompt's execution_context before starting.
 @./references/dashboard-bridge.md
+@./references/thinking-partner.md
 </required_reading>
 
 <process>
@@ -42,6 +43,57 @@ Formulate:
 - `files`: Relevant paths with line numbers from conversation
 </step>
 
+<step name="discussion_mode">
+**Discussion mode triggers:**
+
+1. `--discuss` flag is present in $ARGUMENTS
+2. Complexity detected: title contains "refactor", "redesign", "migrate", "architecture", or problem description exceeds 3 sentences
+
+**If neither trigger:** Skip to infer_area (quick-add path).
+
+**If discussion mode activated:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► TODO DISCUSSION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Apply thinking-partner behaviors to clarify the todo before filing:
+
+**Round 1 — Scope clarification (2-3 questions):**
+
+Use AskUserQuestion to probe:
+- What exactly is the problem? (Challenge vagueness)
+- What does "done" look like for this? (Make abstract concrete)
+- Is this one thing or multiple things? (Surface hidden scope)
+
+**Round 2 — Approach exploration (2-3 questions):**
+
+Use AskUserQuestion to explore:
+- What approaches have you considered? (Propose alternatives with trade-offs)
+- What constraints exist? (Surface unstated assumptions)
+- What could go wrong? (Make consequences visible)
+
+**Round 3 — Readiness check:**
+
+Use AskUserQuestion:
+- header: "Todo"
+- question: "Ready to file this todo?"
+- options:
+  - "File it" -- Capture what we discussed
+  - "Keep discussing" -- I want to explore more
+  - "Split into multiple" -- This is actually several todos
+
+If "Keep discussing": ask 2-3 more probing questions, then check again.
+If "Split into multiple": help user define 2-3 separate todos, file each one.
+If "File it": continue to infer_area.
+
+**Discussion mode enriches the todo file** — the Problem section includes discussion insights, and a new "## Approach" section captures approach decisions (replacing "## Solution" with richer content).
+
+**Time budget:** 20-30 minutes max. After 6 rounds of questions, offer to file what you have.
+</step>
+
 <step name="infer_area">
 Infer area from file paths:
 
@@ -89,11 +141,14 @@ slug=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs generate-slug "$title" --raw)
 
 Write to `.planning/todos/pending/${date}-${slug}.md`:
 
+**Quick mode format:**
+
 ```markdown
 ---
 created: [timestamp]
 title: [title]
 area: [area]
+mode: quick
 files:
   - [file:lines]
 ---
@@ -106,6 +161,40 @@ files:
 
 [approach hints or "TBD"]
 ```
+
+**Discussion mode format (enriched):**
+
+```markdown
+---
+created: [timestamp]
+title: [title]
+area: [area]
+mode: discussed
+files:
+  - [file:lines]
+---
+
+## Problem
+
+[problem description enriched with discussion insights]
+
+## Scope
+
+[What's in scope and what's not — from discussion round 1]
+
+## Approach
+
+[Approach decisions with trade-offs explored — from discussion round 2]
+[Include alternatives considered and why this approach was chosen]
+
+## Risks
+
+[What could go wrong — from discussion]
+
+## Solution
+
+[Concrete next steps or "TBD"]
+```
 </step>
 
 <step name="update_state">

package/dist/assets/templates/workflows/complete-milestone.md

@@ -128,7 +128,7 @@ Calculate milestone statistics:
 ```bash
 git log --oneline --grep="feat(" | head -20
 git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
-find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
+git ls-files --cached --exclude-standard -- "*.swift" "*.ts" "*.py" | xargs wc -l 2>/dev/null
 git log --format="%ai" FIRST_COMMIT | tail -1
 git log --format="%ai" LAST_COMMIT | head -1
 ```

package/dist/assets/templates/workflows/discuss-phase.md

@@ -12,6 +12,7 @@ You are a thinking partner, not an interviewer. The user is the visionary — yo
 
 <required_reading>
 @./references/dashboard-bridge.md
+@./references/thinking-partner.md
 </required_reading>
 
 <tool_mandate>
@@ -52,7 +53,7 @@ Every question directed at the user MUST use a structured tool. NEVER write a qu
 </downstream_awareness>
 
 <philosophy>
-**User = founder/visionary. Claude = builder.**
+**User = founder/visionary. Claude = thinking partner and builder.**
 
 The user knows:
 - How they imagine it working
@@ -67,6 +68,16 @@ The user doesn't know (and shouldn't be asked):
 - Success metrics (inferred from the work)
 
 Ask about vision and implementation choices. Capture decisions for downstream agents.
+
+**Thinking-partner behaviors (from thinking-partner.md):**
+- **Challenge vague answers** — "Cards" could mean many things. Push for specifics.
+- **Surface unstated assumptions** — "You're assuming mobile-first — is that intentional?"
+- **Propose alternatives with trade-offs** — Don't just accept first choice. Offer 2-3 options.
+- **Make consequences visible** — "Infinite scroll means no shareable page positions."
+- **Disagree constructively** — If an approach has risks, name them.
+- **Follow the thread** — Build on what they just said. Don't jump topics.
+
+Apply these behaviors within each discussion area. The user should feel like they're thinking through decisions with a collaborator, not answering a survey.
 </philosophy>
 
 <scope_guardrail>
@@ -314,6 +325,15 @@ Ask 4 questions per area before offering to continue or move on. Each answer oft
      - Loop: discuss new areas, then prompt again
    - If "I'm ready for context": Proceed to write_context
 
+**Adaptive probing (thinking-partner mode):**
+
+Within each area, adapt your questioning based on the user's certainty level:
+- **User is confident** (picks options quickly) — probe deeper: "You chose X — have you considered how that interacts with Y?"
+- **User is uncertain** (picks "Other", hedges) — propose alternatives: "Here are 3 approaches with trade-offs..."
+- **User defers** (picks "You decide") — accept but name consequences: "I'll go with X because [reason]. That means Y."
+
+Challenge decisions that may have hidden costs. If the user picks something that conflicts with an earlier decision, surface it: "Earlier you said A, but this implies B. Which takes priority?"
+
 **Question design:**
 - Options should be concrete, not abstract ("Cards" not "Option A")
 - Each answer should inform the next question
@@ -400,6 +420,70 @@ mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
 ```
 
 Write file.
+
+**Generate phase-specific artefakte:**
+
+After writing CONTEXT.md, append phase-specific entries to the project-level artefakte files.
+
+**Append to DECISIONS.md:**
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-append .planning/DECISIONS.md
+```
+
+Append content:
+
+```markdown
+
+## Phase [X]: [Name]
+
+| # | Decision | Rationale | Alternatives Considered | Status |
+|---|----------|-----------|------------------------|--------|
+| [next #] | [Decision from discussion] | [Why chosen] | [What else was offered] | Locked |
+```
+
+**Append to ACCEPTANCE-CRITERIA.md:**
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-append .planning/ACCEPTANCE-CRITERIA.md
+```
+
+Append content under "Phase-Level Criteria":
+
+```markdown
+
+### Phase [X]: [Name]
+
+- [ ] [Observable outcome from decisions — e.g., "User sees card-based layout on feed page"]
+- [ ] [Observable outcome from decisions — e.g., "Infinite scroll loads next batch on scroll"]
+- [ ] [Observable outcome from decisions — e.g., "Empty state shows onboarding prompt"]
+```
+
+**Append to NO-GOS.md (if applicable):**
+
+If any "don't do this" or "avoid this approach" decisions were made during discussion:
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-append .planning/NO-GOS.md
+```
+
+Append content:
+
+```markdown
+
+## Phase [X]: [Name]
+
+- [Approach to avoid] -- [why, from discussion]
+```
+
+If no no-gos emerged from discussion, skip this append.
+
+**Commit artefakte updates:**
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs(${padded_phase}): update artefakte from phase discussion" --files .planning/DECISIONS.md .planning/ACCEPTANCE-CRITERIA.md .planning/NO-GOS.md
+```
+
 </step>
 
 <step name="confirm_creation">