maxsimcli 4.1.0 → 4.2.1

package/dist/assets/templates/commands/maxsim/artefakte.md

@@ -0,0 +1,122 @@
+---
+name: maxsim:artefakte
+description: View and manage project artefakte (decisions, acceptance criteria, no-gos)
+argument-hint: "[decisions|acceptance-criteria|no-gos] [--phase <N>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+View and manage the three artefakte documents that capture project-level and phase-level decisions:
+
+- **DECISIONS.md** — Architectural and design decisions with rationale
+- **ACCEPTANCE-CRITERIA.md** — Measurable criteria that define "done"
+- **NO-GOS.md** — Explicitly excluded scope items
+
+Supports listing all artefakte, reading a specific type, and appending new entries. When `--phase N` is provided, operations are scoped to that phase's artefakte directory.
+
+**CRITICAL — AskUserQuestion tool mandate:**
+Every single question to the user MUST use the `AskUserQuestion` tool. NEVER ask questions as plain text in your response. This includes menu selection, entry input, continuation prompts, and any other user interaction. If you need the user's input, use `AskUserQuestion`. No exceptions.
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+
+Parse from arguments:
+- **type**: first positional argument — one of `decisions`, `acceptance-criteria`, `no-gos` (optional)
+- **--phase N**: scope to phase N artefakte (optional)
+</context>
+
+<process>
+<step name="parse-arguments">
+Parse `$ARGUMENTS` to extract:
+- `type` — the first positional word if it matches `decisions`, `acceptance-criteria`, or `no-gos`
+- `phase` — the value after `--phase` if present
+
+Build the base command: `node ~/.claude/maxsim/bin/maxsim-tools.cjs`
+If `--phase` is set, append `--phase <N>` to all CLI calls below.
+</step>
+
+<step name="route-by-arguments">
+**If no type argument is provided**, go to Step 3 (overview).
+**If a type argument is provided**, go to Step 4 (read specific).
+</step>
+
+<step name="overview">
+Run via Bash:
+```
+node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-list [--phase <N>]
+```
+
+Display the result as a formatted summary showing each artefakte file's existence status and entry count.
+
+Then use `AskUserQuestion` to offer the user a choice:
+- "View decisions"
+- "View acceptance criteria"
+- "View no-gos"
+- "Add new entry"
+- "Done"
+
+Route based on selection:
+- View → go to Step 4 with the selected type
+- Add → go to Step 5
+- Done → end
+</step>
+
+<step name="read-specific">
+Run via Bash:
+```
+node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-read <type> [--phase <N>]
+```
+
+Display the content in a clean, readable format. If the file doesn't exist yet, say so and offer to create the first entry.
+
+Then use `AskUserQuestion` to offer:
+- "Add entry to this artefakte"
+- "View another artefakte"
+- "Done"
+
+Route based on selection:
+- Add → go to Step 5 with the current type
+- View another → use `AskUserQuestion` to pick which type, then repeat Step 4
+- Done → end
+</step>
+
+<step name="add-entry">
+If the artefakte type isn't known yet, use `AskUserQuestion` to ask:
+- "Which artefakte? (decisions / acceptance-criteria / no-gos)"
+
+Then use `AskUserQuestion` to get the entry text from the user:
+- For **decisions**: "What decision should be recorded? (include rationale)"
+- For **acceptance-criteria**: "What acceptance criterion should be added?"
+- For **no-gos**: "What should be explicitly excluded from scope? (include reason)"
+
+Run via Bash:
+```
+node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-append <type> --entry "<text>" [--phase <N>]
+```
+
+Confirm the entry was added. Then commit the change:
+```
+node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: add <type> artefakte entry" --files .planning/
+```
+
+Use `AskUserQuestion` to offer:
+- "Add another entry"
+- "View artefakte"
+- "Done"
+
+Route accordingly — Add another loops back to the top of Step 5, View goes to Step 3, Done ends.
+</step>
+</process>
+
+<success_criteria>
+- Artefakte overview accurately shows file existence and entry counts
+- Individual artefakte content is displayed clearly
+- New entries are appended and committed
+- Phase scoping works when --phase flag is provided
+- User can navigate between view/add/done without confusion
+</success_criteria>

package/dist/assets/templates/commands/maxsim/batch.md

@@ -0,0 +1,42 @@
+---
+name: maxsim:batch
+description: Decompose a large task into independent units and execute each in an isolated git worktree with its own PR
+argument-hint: "<task description>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Decompose a large task into independent units, execute each in an isolated git worktree, and produce one PR per unit.
+
+Batch mode uses the full MAXSIM system with worktree isolation:
+- Spawns maxsim-planner (batch mode) to decompose the task into independent units
+- Validates file independence across all units (no overlap allowed)
+- Spawns one worktree agent per unit, each with its own branch and PR
+- Tracks progress and handles failures with automatic retries
+- Records batch metadata in `.planning/batch/`
+
+**Use when:** Task has 3+ independent units that can be implemented in parallel.
+**Do not use when:** Fewer than 3 units (use `/maxsim:quick` instead) or units have sequential dependencies.
+</objective>
+
+<execution_context>
+@./workflows/batch.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+Context files are resolved inside the workflow (`init quick`) and delegated via `<files_to_read>` blocks.
+</context>
+
+<process>
+Execute the batch workflow from @./workflows/batch.md end-to-end.
+Preserve all workflow gates (validation, decomposition, independence check, agent spawning, tracking, state updates).
+</process>

package/dist/assets/templates/commands/maxsim/check-todos.md

@@ -22,6 +22,7 @@ Routes to the check-todos workflow which handles:
 
 <execution_context>
 @./workflows/check-todos.md
+@./references/thinking-partner.md
 </execution_context>
 
 <context>

package/dist/assets/templates/commands/maxsim/sdd.md

@@ -0,0 +1,39 @@
+---
+name: maxsim:sdd
+description: Execute a phase using Spec-Driven Dispatch — fresh agent per task with 2-stage review
+argument-hint: "<phase-number>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Execute phase plans using the Spec-Driven Dispatch (SDD) pattern. Each task is dispatched to a fresh-context subagent with minimal context. Two-stage review (spec compliance + code quality) runs between every task. No task starts until the previous task passes both review stages.
+
+SDD differs from standard execute-phase:
+- **Standard:** Single agent or segmented execution per plan
+- **SDD:** Fresh agent per task with mandatory inter-task review gates
+
+Context budget: ~10% orchestrator. 100% fresh per task agent. Zero context bleeding between tasks.
+</objective>
+
+<execution_context>
+@./workflows/sdd.md
+@./references/ui-brand.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS
+
+Context files are resolved inside the workflow via `maxsim-tools init execute-phase` and per-task `<files_to_read>` blocks.
+</context>
+
+<process>
+Execute the SDD workflow from @./workflows/sdd.md end-to-end.
+Preserve all workflow gates (task dispatch, 2-stage review, fix iteration cap, state updates, routing).
+</process>

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

@@ -38,4 +38,37 @@ You are a thinking partner, not a task executor. Your role is to help the user a
 
 </anti_patterns>
 
+<context_modes>
+
+**Project initialization** (new-project, init-existing): Focus on vision clarity, scope boundaries, surfacing hidden requirements. Push hard on "what problem are you solving?" and "who is this for?" Accept vague tech stack preferences early — they'll solidify during research.
+
+**Phase discussion** (discuss-phase): Focus on implementation decisions, gray area resolution, downstream impact. Challenge hand-wavy integration plans. Push for concrete acceptance criteria per deliverable.
+
+**Todo/bug triage** (add-todo --discuss, check-todos brainstorm): Focus on problem definition, scope containment, approach selection. Shorter rounds — 2-3 questions vs 4. Time-boxed to 20-30 min. Don't over-explore — capture enough to unblock, not to solve.
+
+**General discussion**: Default behaviors from core_behaviors apply. Read the energy — if the user is exploring, explore with them. If they want a quick answer, give it.
+
+</context_modes>
+
+<escalation_patterns>
+
+**Push harder on:**
+- Vague acceptance criteria — "it should work well" is not a criterion
+- Undefined error handling — "we'll handle errors" is not a plan
+- "Figure it out later" on decisions that block downstream work
+- Scope that keeps expanding without acknowledgment
+
+**Accept quickly:**
+- Aesthetic preferences (colors, fonts, naming)
+- Minor UX details that can be changed later
+- Tool/library choices when alternatives are roughly equivalent
+- Formatting preferences
+
+**Flag and move on:**
+- Decisions that need external input (API docs, stakeholder approval)
+- Blocked by unknowns outside the project scope
+- Performance targets without measurement baseline — "make it fast" needs a benchmark first, then move on
+
+</escalation_patterns>
+
 </thinking_partner>

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

@@ -0,0 +1,420 @@
+<sanity_check>
+Before executing any step in this workflow, verify:
+1. The current directory contains a `.planning/` folder — if not, stop and tell the user to run `/maxsim:new-project` first.
+2. Git is initialized (`git rev-parse --git-dir` succeeds) — worktrees require a git repository.
+3. `.planning/ROADMAP.md` exists — if not, stop and tell the user to initialize the project.
+</sanity_check>
+
+<purpose>
+Decompose a large task into independent units, execute each in an isolated git worktree, and produce one PR per unit. Each unit gets its own branch, worktree, and PR — enabling parallel implementation with zero merge conflicts.
+
+Follows the batch-worktree skill process: Research (decompose) -> Plan (validate independence) -> Spawn (worktree agents) -> Track (progress and failures).
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+@./references/dashboard-bridge.md
+</required_reading>
+
+<process>
+
+<step name="initialize" priority="first">
+Load context in one call:
+
+```bash
+INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init quick "$DESCRIPTION")
+```
+
+Parse JSON for: `planner_model`, `executor_model`, `slug`, `date`, `timestamp`, `roadmap_exists`, `planning_exists`.
+
+**If `roadmap_exists` is false:** Error — Batch mode requires an active project with ROADMAP.md. Run `/maxsim:new-project` first.
+
+Verify git is available:
+```bash
+git rev-parse --git-dir > /dev/null 2>&1 || echo "ERROR: Not a git repository"
+```
+
+Store `BASE_BRANCH`:
+```bash
+BASE_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+```
+</step>
+
+<step name="gather_task">
+Parse `$ARGUMENTS` for the task description.
+
+If `$ARGUMENTS` is empty, prompt user interactively:
+
+```
+AskUserQuestion(
+  header: "Batch Task",
+  question: "Describe the large task to decompose into independent worktree units.",
+  followUp: null
+)
+```
+
+Store response as `$DESCRIPTION`.
+
+If still empty, re-prompt: "Please provide a task description."
+
+Display banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM > BATCH WORKTREE EXECUTION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Task: ${DESCRIPTION}
+ Base branch: ${BASE_BRANCH}
+```
+</step>
+
+<step name="decompose">
+Spawn maxsim-planner with batch-specific prompt to produce a decomposition:
+
+```
+Task(
+  prompt="
+<planning_context>
+
+**Mode:** batch
+**Description:** ${DESCRIPTION}
+**Base branch:** ${BASE_BRANCH}
+
+<files_to_read>
+- .planning/STATE.md (Project State)
+- .planning/ROADMAP.md (Phase structure)
+- ./CLAUDE.md (if exists — follow project-specific guidelines)
+- .skills/batch-worktree/SKILL.md (if exists — batch-worktree constraints)
+</files_to_read>
+
+**Project skills:** Check .skills/ directory (if exists) — read SKILL.md files, plans should account for project skill rules
+
+</planning_context>
+
+<constraints>
+- Decompose into 3-30 independent units
+- Each unit MUST be independently mergeable (hard gate from batch-worktree skill)
+- If fewer than 3 units are identified, STOP and recommend /maxsim:quick instead
+- No file may appear in more than one unit
+- No runtime dependency between units (unit A output must not be unit B input)
+- Each unit must have: title, description, files owned, acceptance criteria
+</constraints>
+
+<output>
+Write decomposition to: .planning/batch/${slug}/DECOMPOSITION.md
+
+Format:
+---
+task: ${DESCRIPTION}
+date: ${date}
+base_branch: ${BASE_BRANCH}
+unit_count: N
+status: pending
+---
+
+## Units
+
+### Unit 1: [Title]
+**Description:** ...
+**Files owned:**
+- path/to/file1.ts
+- path/to/file2.ts
+**Acceptance criteria:**
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+### Unit 2: [Title]
+...
+
+## Independence Matrix
+[For each pair of units, confirm no file overlap and no runtime dependency]
+
+Return: ## PLANNING COMPLETE with unit count and decomposition path
+</output>
+",
+  subagent_type="maxsim-planner",
+  model="{planner_model}",
+  description="Batch decomposition: ${DESCRIPTION}"
+)
+```
+
+After planner returns:
+1. Verify decomposition exists at `.planning/batch/${slug}/DECOMPOSITION.md`
+2. Extract unit count
+3. If unit count < 3: warn user and suggest `/maxsim:quick` instead. Ask: "Continue with batch (${unit_count} units) or switch to quick mode?"
+4. Report: "Decomposition complete: ${unit_count} units identified"
+
+If decomposition not found, error: "Planner failed to create DECOMPOSITION.md"
+</step>
+
+<step name="validate_independence">
+Read the DECOMPOSITION.md and validate file independence across all units.
+
+For each pair of units:
+1. Extract the files owned by each unit
+2. Compute the intersection
+3. If any file appears in more than one unit, the validation fails
+
+**If validation fails:**
+
+Report the overlapping files and which units conflict:
+```
+## Independence Validation Failed
+
+| File | Unit A | Unit B |
+|------|--------|--------|
+| path/to/file.ts | Unit 1: Title | Unit 3: Title |
+```
+
+Return to planner with revision prompt:
+```
+Task(
+  prompt="
+<revision_context>
+
+<files_to_read>
+- .planning/batch/${slug}/DECOMPOSITION.md (Existing decomposition)
+</files_to_read>
+
+**Independence validation failed.** The following files appear in multiple units:
+${overlap_table}
+
+Options:
+1. Merge overlapping units into one
+2. Extract shared files into a prerequisite unit that runs first
+3. Redesign the split so each file belongs to exactly one unit
+
+Revise DECOMPOSITION.md to resolve all overlaps.
+</revision_context>
+",
+  subagent_type="maxsim-planner",
+  model="{planner_model}",
+  description="Revise batch decomposition: fix overlaps"
+)
+```
+
+Re-validate after revision. If validation fails a second time, stop and escalate to user.
+
+**If validation passes:**
+
+```
+Independence validated: ${unit_count} units, no file overlap
+```
+</step>
+
+<step name="record_decision">
+Record the decomposition decision in STATE.md:
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs state add-decision --phase "batch" --summary "Batch decomposition: ${unit_count} units, no file overlap confirmed"
+```
+</step>
+
+<step name="spawn_worktree_agents">
+For each unit in the decomposition, spawn a worktree agent.
+
+Display progress table header:
+```
+## Spawning Worktree Agents
+
+| # | Unit | Status | PR |
+|---|------|--------|----|
+```
+
+For each unit (spawn all with `run_in_background: true` for parallel execution):
+
+```
+Task(
+  subagent_type="general-purpose",
+  model="{executor_model}",
+  isolation="worktree",
+  run_in_background=true,
+  prompt="
+You are implementing Unit ${unit_number} of a batch worktree execution.
+
+<unit_spec>
+**Title:** ${unit_title}
+**Description:** ${unit_description}
+**Base branch:** ${BASE_BRANCH}
+**Branch name:** batch/${slug}/unit-${unit_number}
+**Files owned (ONLY touch these files):**
+${unit_files}
+**Acceptance criteria:**
+${unit_criteria}
+</unit_spec>
+
+<files_to_read>
+- ./CLAUDE.md (if exists — follow project-specific guidelines)
+- .planning/STATE.md (Project state)
+- .skills/ (if exists — list skills, read SKILL.md for each, follow relevant rules)
+</files_to_read>
+
+<instructions>
+1. Create branch: git checkout -b batch/${slug}/unit-${unit_number}
+2. Implement the changes described in the unit spec
+3. ONLY modify files listed in 'Files owned' — do not touch any other files
+4. Run tests relevant to your changes
+5. Commit atomically with message: feat(batch): ${unit_title}
+6. Push branch: git push -u origin batch/${slug}/unit-${unit_number}
+7. Create PR: gh pr create --title 'batch(${slug}): ${unit_title}' --body '## Unit ${unit_number}: ${unit_title}\n\n${unit_description}\n\nPart of batch: ${DESCRIPTION}'
+8. Return the PR URL
+
+If tests fail, fix and retry. If you cannot fix after 2 attempts, report failure with error details.
+</instructions>
+
+<output>
+Return one of:
+- ## UNIT COMPLETE\nPR: <url>
+- ## UNIT FAILED\nError: <details>
+</output>
+",
+  description="Batch unit ${unit_number}: ${unit_title}"
+)
+```
+</step>
+
+<step name="track_progress">
+As agents complete, update the status table:
+
+| # | Unit | Status | PR |
+|---|------|--------|----|
+| 1 | title | done | #123 |
+| 2 | title | in-progress | -- |
+| 3 | title | failed | -- |
+
+Statuses: `pending`, `in-progress`, `done`, `failed`
+
+After each agent returns:
+1. Parse output for `## UNIT COMPLETE` or `## UNIT FAILED`
+2. Extract PR URL if complete
+3. Update status table
+4. Report progress: "${completed}/${unit_count} units complete"
+
+Wait for all agents to finish before proceeding.
+</step>
+
+<step name="handle_failures">
+For each failed unit:
+
+**Attempt 1 — spawn fix agent:**
+```
+Task(
+  subagent_type="general-purpose",
+  model="{executor_model}",
+  isolation="worktree",
+  prompt="
+Unit ${unit_number} failed with error:
+${error_details}
+
+<unit_spec>
+${original_unit_spec}
+</unit_spec>
+
+Fix the failing unit. The worktree and branch already exist.
+Check out the existing branch, diagnose the failure, fix it, test, commit, push, create PR.
+",
+  description="Fix batch unit ${unit_number}: ${unit_title}"
+)
+```
+
+**Merge conflict detected:** Flag to user — decomposition had hidden overlap.
+```
+AskUserQuestion(
+  header: "Merge Conflict in Unit ${unit_number}",
+  question: "Unit ${unit_number} (${unit_title}) has a merge conflict. This suggests the decomposition missed a dependency. Options:\n1. Fix manually\n2. Skip this unit\n3. Abort remaining units",
+  followUp: null
+)
+```
+
+**3+ failures on same unit:** Stop retrying and escalate:
+```
+## Unit ${unit_number} Escalated
+
+Unit "${unit_title}" failed 3+ times. Manual intervention required.
+Error history: ${error_summaries}
+Branch: batch/${slug}/unit-${unit_number}
+```
+</step>
+
+<step name="report">
+After all units are resolved (complete or escalated):
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM > BATCH EXECUTION COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Task: ${DESCRIPTION}
+Units: ${completed_count}/${unit_count} complete
+
+| # | Unit | Status | PR |
+|---|------|--------|----|
+${final_status_table}
+
+${failed_count > 0 ? "Failed units require manual attention." : "All units completed successfully."}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Update STATE.md with batch completion:
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs state add-decision --phase "batch" --summary "Batch complete: ${completed_count}/${unit_count} units done. PRs: ${pr_list}"
+```
+</step>
+
+<step name="commit_metadata">
+Store batch record in `.planning/batch/` directory.
+
+Update DECOMPOSITION.md frontmatter status:
+- All units done: `status: complete`
+- Some failed: `status: partial`
+
+Create `.planning/batch/${slug}/RESULTS.md`:
+```markdown
+---
+task: ${DESCRIPTION}
+date: ${date}
+status: ${all_done ? "complete" : "partial"}
+units_total: ${unit_count}
+units_complete: ${completed_count}
+units_failed: ${failed_count}
+---
+
+## Results
+
+| # | Unit | Status | PR | Branch |
+|---|------|--------|----|--------|
+${results_table}
+
+## Failed Units
+${failed_summaries or "None"}
+```
+
+Commit metadata:
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs(batch): ${DESCRIPTION}" --files .planning/batch/${slug}/DECOMPOSITION.md .planning/batch/${slug}/RESULTS.md .planning/STATE.md
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `.planning/` and git repository verified
+- [ ] User provides task description
+- [ ] Decomposition produces 3+ independent units
+- [ ] File independence validated across all unit pairs
+- [ ] Decision recorded in STATE.md
+- [ ] One worktree agent spawned per unit
+- [ ] Each agent creates its own branch and PR
+- [ ] Progress tracked with status table
+- [ ] Failed units retried once before escalation
+- [ ] Final report lists all PRs and flags failures
+- [ ] Batch metadata committed to `.planning/batch/`
+</success_criteria>
+
+<failure_handling>
+- **classifyHandoffIfNeeded false failure:** Agent reports "failed" with `classifyHandoffIfNeeded is not defined` error — Claude Code bug, not MAXSIM. Check if branch exists and has commits. If so, treat as success.
+- **Independence validation fails twice:** Stop, present overlaps to user, ask for manual decomposition guidance.
+- **Agent fails to create PR:** Check if `gh` CLI is authenticated. If not, report branch name for manual PR creation.
+- **All agents fail:** Likely systemic issue (git config, permissions). Stop and report for investigation.
+- **Fewer than 3 units identified:** Suggest `/maxsim:quick` instead. Do not force worktree overhead for small tasks.
+</failure_handling>