maxsimcli 4.1.0 → 4.2.0

package/dist/assets/templates/workflows/check-todos.md

@@ -138,7 +138,91 @@ Display: `/maxsim:add-phase [description from todo]`
 Keep in pending. User runs command in fresh context.
 
 **Brainstorm approach:**
-Keep in pending. Start discussion about problem and approaches.
+Keep in pending. Enter structured thinking-partner discussion to clarify and enrich the todo.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► TODO BRAINSTORM
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Apply thinking-partner behaviors from `@./references/thinking-partner.md` to explore the todo before deciding next steps.
+
+**Round 1 — Problem clarity (2-3 questions):**
+
+Use AskUserQuestion to probe:
+- What exactly is the problem? (Challenge vagueness — if the todo description is abstract, push for specifics)
+- What does "done" look like? (Make abstract concrete — what observable change marks completion?)
+- Is this one thing or multiple? (Surface hidden scope — does this todo contain sub-tasks?)
+
+Build on the todo's existing Problem and Solution sections. Quote specifics from the todo to ground the discussion.
+
+**Round 2 — Approach exploration (2-3 questions):**
+
+Use AskUserQuestion to explore:
+- What approaches have you considered? (Propose 2-3 alternatives with trade-offs if the user has no strong opinion)
+- What constraints exist? (Surface unstated assumptions — time, dependencies, tech debt, team knowledge)
+- What could go wrong? (Make consequences visible — breaking changes, performance, migration risk)
+
+Follow the thread from Round 1. React to the user's energy — if they are excited about an approach, dig into it. If uncertain, help narrow options.
+
+**Round 3 — Readiness check:**
+
+Use AskUserQuestion:
+- header: "Todo"
+- question: "Ready to refine this todo with what we discussed?"
+- options:
+  - "Refine todo" — Update with discussion insights
+  - "Keep discussing" — Explore more
+  - "Split into multiple" — This is actually several todos
+
+If "Keep discussing": ask 2-3 more probing questions focusing on the most important open question, then check readiness again.
+If "Split into multiple": help the user define 2-3 separate todos. For each, create a new todo file in `.planning/todos/pending/` using the enriched format below. Commit all new files.
+If "Refine todo": continue to enrichment below.
+
+**After discussion — enrich the todo file:**
+
+Rewrite the selected todo's markdown file with enriched content:
+
+```markdown
+---
+created: [preserve original]
+title: [preserve or refine from discussion]
+area: [preserve or update]
+mode: discussed
+files:
+  - [preserve and add any new files surfaced]
+---
+
+## Problem
+
+[Problem description enriched with discussion insights from Round 1]
+
+## Scope
+
+[What is in scope and out of scope — from Round 1 clarity questions]
+
+## Approach
+
+[Chosen approach with trade-offs explored — from Round 2]
+[Include alternatives considered and why this approach was chosen]
+
+## Risks
+
+[What could go wrong — from Round 2 consequences discussion]
+
+## Solution
+
+[Concrete next steps or "TBD"]
+```
+
+Commit the updated todo:
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: enrich todo after brainstorm - [title]" --files [todo-file-path] .planning/STATE.md
+```
+
+**Time budget:** 20-30 minutes max. After 6 rounds of questions, offer to file what you have.
 
 **Put it back:**
 Return to list_todos step.

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

@@ -50,6 +50,8 @@ Every question directed at the user MUST use a structured tool. NEVER write a qu
 **Your job:** Capture decisions clearly enough that downstream agents can act on them without asking the user again.
 
 **Not your job:** Figure out HOW to implement. That's what research and planning do with the decisions you capture.
+
+**Phase-scoped artefakte:** In addition to project-level artefakte (DECISIONS.md, ACCEPTANCE-CRITERIA.md, NO-GOS.md), this workflow creates phase-scoped copies in the phase directory. These contain ONLY the entries from this phase's discussion, giving downstream agents focused context without needing to parse the full project-level files.
 </downstream_awareness>
 
 <philosophy>
@@ -484,6 +486,35 @@ If no no-gos emerged from discussion, skip this append.
 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
 ```
 
+**Create phase-scoped artefakte:**
+
+After appending to project-level artefakte, create phase-scoped copies containing ONLY the entries from this phase's discussion. These give downstream agents (researcher, planner, executor) focused phase-specific context without parsing the full project-level files.
+
+For each artefakte type that had entries appended in the previous step:
+
+**Decisions (if phase decisions were captured):**
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-write decisions --phase ${phase_num} --content "# Phase ${phase_num}: ${phase_name} — Decisions\n\n| # | Decision | Rationale | Alternatives Considered | Status |\n|---|----------|-----------|------------------------|--------|\n[phase-specific decision entries from the discussion above]"
+```
+
+**Acceptance Criteria (if phase criteria were defined):**
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-write acceptance-criteria --phase ${phase_num} --content "# Phase ${phase_num}: ${phase_name} — Acceptance Criteria\n\n[phase-specific criteria entries from the discussion above, each as a - [ ] checkbox line]"
+```
+
+**No-Gos (if phase no-gos emerged):**
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-write no-gos --phase ${phase_num} --content "# Phase ${phase_num}: ${phase_name} — No-Gos\n\n[phase-specific no-go entries from the discussion above, each as a - bullet]"
+```
+
+Only create artefakte files for types that actually had entries — skip any type where no relevant decisions/criteria/no-gos emerged.
+
+Include the phase-scoped artefakte files in the same git commit as the project-level artefakte:
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs(${padded_phase}): create phase-scoped artefakte from discussion" --files "${phase_dir}/"
+```
+
 </step>
 
 <step name="confirm_creation">

package/dist/assets/templates/workflows/execute-plan.md

@@ -411,45 +411,114 @@ Task(
 
 **Stage 3: Simplify** — Spawn 3 parallel reviewers to catch reuse opportunities, quality issues, and inefficiencies.
 
+**Reviewer 1 — Code Reuse:**
+
 ```
 Task(
-  subagent_type="maxsim-executor",
+  subagent_type="maxsim-code-reviewer",
   prompt="
     <objective>
-    Run simplification review on plan {phase}-{plan} with 3 parallel reviewers.
+    Review plan {phase}-{plan} for code reuse opportunities.
     </objective>
 
+    <files_to_review>
+    {List all files created/modified during execution from SUMMARY.md key-files}
+    </files_to_review>
+
     <instructions>
-    Spawn 3 parallel review agents for the files modified in this plan:
-
-    Agent 1 — Code Reuse:
-    - Find duplicated logic across the codebase
-    - Identify copy-paste from other files that should be extracted
-    - Suggest shared helpers for patterns appearing 3+ times
-    - Check if existing utilities could replace new code
-
-    Agent 2 — Code Quality:
-    - Check naming consistency with codebase conventions
-    - Verify error handling covers all external calls
-    - Look for dead code: unused imports, unreachable branches, commented-out code
-    - Check for unnecessary abstractions or premature generalizations
-
-    Agent 3 — Efficiency:
-    - Find O(n^2) operations where O(n) is straightforward
-    - Identify repeated computations that could be cached or hoisted
-    - Check for unnecessary allocations in hot paths
-    - Look for redundant data transformations
-
-    After all 3 agents report:
-    1. Consolidate findings into a single list
-    2. Apply fixes for all actionable items (skip speculative optimizations)
-    3. Run tests to confirm fixes do not break anything
-    4. Report: CLEAN (no issues found), FIXED (issues found and resolved), or BLOCKED (issues found but cannot fix without architectural change)
+    1. Scan all changed files for duplicated patterns
+    2. Cross-reference against existing shared utilities and helpers
+    3. Flag any logic that appears 3+ times without extraction
+    4. Check if existing utilities could replace new code
+    5. Output: list of reuse opportunities with file paths and line ranges
+    6. Verdict: CLEAN (no issues) or ISSUES_FOUND (list)
     </instructions>
+  "
+)
+```
+
+**Reviewer 2 — Code Quality:**
+
+```
+Task(
+  subagent_type="maxsim-code-reviewer",
+  prompt="
+    <objective>
+    Review plan {phase}-{plan} for code quality issues.
+    </objective>
 
     <files_to_review>
     {List all files created/modified during execution from SUMMARY.md key-files}
     </files_to_review>
+
+    <instructions>
+    1. Check naming consistency with codebase conventions
+    2. Verify error handling covers all external calls
+    3. Look for dead code: unused imports, unreachable branches, commented-out code
+    4. Check for unnecessary abstractions or premature generalizations
+    5. Output: list of quality issues categorized by severity (BLOCKER/HIGH/MEDIUM)
+    6. Verdict: CLEAN (no issues) or ISSUES_FOUND (list)
+    </instructions>
+  "
+)
+```
+
+**Reviewer 3 — Efficiency:**
+
+```
+Task(
+  subagent_type="maxsim-code-reviewer",
+  prompt="
+    <objective>
+    Review plan {phase}-{plan} for efficiency issues.
+    </objective>
+
+    <files_to_review>
+    {List all files created/modified during execution from SUMMARY.md key-files}
+    </files_to_review>
+
+    <instructions>
+    1. Find over-engineered solutions (parametrization serving one case, generic interfaces with one implementor)
+    2. Identify repeated computations that could be cached or hoisted
+    3. Check for unnecessary allocations in hot paths
+    4. Look for redundant data transformations
+    5. Output: list of efficiency issues with suggested removals
+    6. Verdict: CLEAN (no issues) or ISSUES_FOUND (list)
+    </instructions>
+  "
+)
+```
+
+**Consolidation (after all 3 reviewers complete):**
+
+After all three reviewers report:
+- If ALL returned CLEAN: report CLEAN immediately, skip to next stage
+- If ANY returned ISSUES_FOUND:
+  1. Merge findings into deduplicated list
+  2. Spawn single executor to apply fixes:
+
+```
+Task(
+  subagent_type="maxsim-executor",
+  prompt="
+    <objective>
+    Apply simplification fixes for plan {phase}-{plan} based on reviewer findings.
+    </objective>
+
+    <findings>
+    {Merged deduplicated list of ISSUES_FOUND from all reviewers — BLOCKER and HIGH first, skip speculative optimizations}
+    </findings>
+
+    <files_to_review>
+    {List all files created/modified during execution from SUMMARY.md key-files}
+    </files_to_review>
+
+    <instructions>
+    1. Apply fixes for all actionable items (BLOCKER and HIGH severity first)
+    2. Skip speculative optimizations that lack clear evidence
+    3. Run tests to confirm fixes do not break anything
+    4. Report: FIXED (issues found and resolved) or BLOCKED (cannot fix without architectural change)
+    </instructions>
   "
 )
 ```

package/dist/assets/templates/workflows/help.md

@@ -111,6 +111,30 @@ Execute all plans in a phase.
 
 Usage: `/maxsim:execute-phase 5`
 
+**`/maxsim:sdd <phase-number>`**
+Execute a phase using Spec-Driven Dispatch — fresh agent per task with 2-stage review.
+
+- Each task dispatched to a fresh subagent with minimal context
+- Mandatory two-stage review (spec compliance + code quality) between every task
+- No task starts until the previous passes both review stages
+- Fix agents spawned for failed reviews (up to 3 attempts)
+
+Use when context rot is a concern or for sequential tasks requiring strict quality gates.
+
+Usage: `/maxsim:sdd 3`
+
+**`/maxsim:batch <task description>`**
+Decompose a large task into independent units and execute each in an isolated git worktree.
+
+- Spawns planner to decompose task into 5-30 independent units
+- Validates no file overlap between units
+- Each unit runs in its own worktree with its own branch and PR
+- Tracks progress via status table, handles failures with retries
+
+Use for large parallelizable changes where each unit can be independently merged.
+
+Usage: `/maxsim:batch "Migrate all API endpoints to new auth middleware"`
+
 ### Quick Mode
 
 **`/maxsim:quick`**
@@ -243,6 +267,7 @@ Capture idea or task as todo from current conversation.
 
 Usage: `/maxsim:add-todo` (infers from conversation)
 Usage: `/maxsim:add-todo Add auth token refresh`
+Usage: `/maxsim:add-todo --discuss Refactor auth module` (collaborative discussion before filing)
 
 **`/maxsim:check-todos [area]`**
 List pending todos and select one to work on.
@@ -256,6 +281,25 @@ List pending todos and select one to work on.
 Usage: `/maxsim:check-todos`
 Usage: `/maxsim:check-todos api`
 
+### Artefakte Management
+
+**`/maxsim:artefakte [type] [--phase <N>]`**
+View and manage project decisions, acceptance criteria, and no-gos.
+
+- No arguments: lists all artefakte documents with status
+- With type (`decisions`, `acceptance-criteria`, `no-gos`): view specific document
+- With `--phase N`: scope to phase-level artefakte
+- Interactive: add entries, view documents, switch between types
+
+Artefakte documents:
+- `DECISIONS.md` — Architectural and design decisions with rationale
+- `ACCEPTANCE-CRITERIA.md` — Conditions that must be met for deliverables
+- `NO-GOS.md` — Things explicitly out of scope or forbidden
+
+Usage: `/maxsim:artefakte`
+Usage: `/maxsim:artefakte decisions`
+Usage: `/maxsim:artefakte no-gos --phase 3`
+
 ### User Acceptance Testing
 
 **`/maxsim:verify-work [phase]`**
@@ -343,6 +387,9 @@ Usage: `/maxsim:update`
 ├── PROJECT.md            # Project vision
 ├── ROADMAP.md            # Current phase breakdown
 ├── STATE.md              # Project memory & context
+├── DECISIONS.md          # Architectural decisions with rationale
+├── ACCEPTANCE-CRITERIA.md # Success conditions for deliverables
+├── NO-GOS.md             # Explicit exclusions and boundaries
 ├── config.json           # Workflow mode & gates
 ├── todos/                # Captured ideas and tasks
 │   ├── pending/          # Todos waiting to be worked on