maxsimcli 4.8.0 → 4.9.0

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

@@ -1,6 +1,6 @@
 ---
 name: maxsim:help
-description: Show available MAXSIM commands and usage guide
+description: Show MAXSIM command reference and usage guide
 ---
 <objective>
 Display the complete MAXSIM command reference.
@@ -18,5 +18,5 @@ Output ONLY the reference content below. Do NOT add:
 
 <process>
 Output the complete MAXSIM command reference from @./workflows/help.md.
-Display the reference content directly — no additions or modifications.
+Display directly -- no additions or modifications.
 </process>

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

@@ -0,0 +1,52 @@
+---
+name: maxsim:init
+description: Initialize a new project or manage milestone lifecycle
+argument-hint: "[--auto]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+  - Glob
+  - Grep
+  - WebFetch
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+---
+<context>
+**Flags:**
+- `--auto` -- Automatic mode. After config questions, runs the appropriate flow without further interaction. For new projects, expects idea document via @ reference.
+</context>
+
+<objective>
+Unified project initialization. Detects whether this is a new project, existing project, or milestone lifecycle and routes to the appropriate workflow.
+
+**Creates (depending on scenario):**
+- `.planning/PROJECT.md` -- project context
+- `.planning/config.json` -- workflow preferences
+- `.planning/REQUIREMENTS.md` -- scoped requirements
+- `.planning/ROADMAP.md` -- phase structure
+- `.planning/STATE.md` -- project memory
+- `.planning/DECISIONS.md` -- key decisions with rationale
+- `.planning/ACCEPTANCE-CRITERIA.md` -- measurable success criteria
+- `.planning/NO-GOS.md` -- explicit exclusions and anti-patterns
+- `.planning/codebase/` -- codebase analysis (existing projects only)
+- `.planning/research/` -- domain research (optional)
+
+**After this command:** Run `/maxsim:plan 1` to start phase planning.
+</objective>
+
+<execution_context>
+@./workflows/init.md
+@./references/questioning.md
+@./references/thinking-partner.md
+@./references/ui-brand.md
+@./templates/project.md
+@./templates/requirements.md
+</execution_context>
+
+<process>
+Execute the init workflow from @./workflows/init.md end-to-end.
+Pass $ARGUMENTS through to the workflow for flag handling (--auto).
+</process>

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

@@ -0,0 +1,50 @@
+---
+name: maxsim:plan
+description: State-machine plan command — Discussion, Research, Planning stages with gate confirmations
+argument-hint: "[phase-number] [--force-research] [--skip-verify]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - WebFetch
+  - mcp__context7__*
+---
+<objective>
+Execute the plan state machine: Discussion -> Research -> Planning. Each stage produces artifacts, shows a gate summary, and waits for user confirmation before advancing.
+
+**How it works:**
+1. Detect current stage from phase artifacts (CONTEXT.md, RESEARCH.md, PLAN.md)
+2. Start at the earliest incomplete stage
+3. Run each stage via dedicated sub-workflow
+4. Show rich gate summary after each stage — wait for user confirmation
+5. Advance to next stage on confirmation
+
+**Re-entry:** If phase is already planned, show status and offer options (view, re-plan, execute).
+
+**Flags:**
+- `--force-research` — Re-run research even if RESEARCH.md exists
+- `--skip-verify` — Skip plan verification loop after planning stage
+</objective>
+
+<execution_context>
+@./workflows/plan.md
+@./references/ui-brand.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted)
+
+**Flags:**
+- `--force-research` — Re-run research even if RESEARCH.md exists
+- `--skip-verify` — Skip plan verification loop after planning stage
+
+Context files are resolved inside the workflow via `maxsim-tools init plan-phase` and per-subagent context assembly.
+</context>
+
+<process>
+Execute the plan workflow from @./workflows/plan.md end-to-end.
+Preserve all workflow gates (stage detection, discussion, research, planning, gate confirmations, re-entry flow).
+</process>

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

@@ -1,17 +1,18 @@
 ---
 name: maxsim:progress
-description: Check project progress, show context, and route to next action (execute or plan)
+description: Check project progress, milestone status, and route to next action
 allowed-tools:
   - Read
   - Bash
   - Grep
   - Glob
+  - Task
   - SlashCommand
 ---
 <objective>
-Check project progress, summarize recent work and what's ahead, then intelligently route to the next action - either executing an existing plan or creating the next one.
+Check project progress, milestone status, and offer milestone completion when all phases are done. Shows GitHub Issues-based progress alongside local ROADMAP.md progress for cross-validation.
 
-Provides situational awareness before continuing work.
+Provides situational awareness before continuing work, detects phase gaps, and intelligently routes to the next action.
 </objective>
 
 <execution_context>

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

@@ -1,7 +1,7 @@
 ---
 name: maxsim:quick
-description: Execute a quick task with MAXSIM guarantees (atomic commits, state tracking) but skip optional agents
-argument-hint: "[--full]"
+description: Execute a quick task with MAXSIM guarantees, or capture todos for later work
+argument-hint: "[--full] [--todo]"
 allowed-tools:
   - Read
   - Write
@@ -13,16 +13,18 @@ allowed-tools:
   - AskUserQuestion
 ---
 <objective>
-Execute small, ad-hoc tasks with MAXSIM guarantees (atomic commits, STATE.md tracking).
+Execute small, ad-hoc tasks with MAXSIM guarantees (atomic commits, STATE.md tracking). Also supports "save for later" -- capturing ideas as GitHub Issues with 'todo' label for future work.
 
 Quick mode is the same system with a shorter path:
-- Spawns maxsim-planner (quick mode) + maxsim-executor(s)
+- Spawns planner (quick mode) + executor(s)
 - Quick tasks live in `.planning/quick/` separate from planned phases
 - Updates STATE.md "Quick Tasks Completed" table (NOT ROADMAP.md)
 
 **Default:** Skips research, plan-checker, verifier. Use when you know exactly what to do.
 
 **`--full` flag:** Enables plan-checking (max 2 iterations) and post-execution verification. Use when you want quality guarantees without full milestone ceremony.
+
+**`--todo` flag:** Enters todo management mode. List, capture, complete, and triage todos without executing tasks. "Save for later" creates a local todo + best-effort GitHub Issue with 'todo' label.
 </objective>
 
 <execution_context>

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

@@ -9,14 +9,15 @@ allowed-tools:
 ---
 
 <objective>
-Interactive configuration of MAXSIM workflow agents and model profile via multi-question prompt.
+Interactive configuration of MAXSIM workflow agents, model profile, and pipeline settings via multi-question prompt. Includes integrated profile management with model assignment details per tier.
 
 Routes to the settings workflow which handles:
 - Config existence ensuring
 - Current settings reading and parsing
-- Interactive 5-question prompt (model, research, plan_checker, verifier, branching)
+- Interactive prompt (model profile, research, plan_checker, verifier, auto-advance, nyquist, branching)
+- Profile description showing actual model assignments per profile tier
 - Config merging and writing
-- Confirmation display with quick command references
+- Confirmation display
 </objective>
 
 <execution_context>

package/dist/assets/templates/references/continuation-format.md

@@ -44,7 +44,7 @@ Standard format for presenting next steps after completing a command or workflow
 
 **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
 
-`/maxsim:execute-phase 2`
+`/maxsim:execute 2`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -52,7 +52,7 @@ Standard format for presenting next steps after completing a command or workflow
 
 **Also available:**
 - Review plan before executing
-- `/maxsim:list-phase-assumptions 2` — check assumptions
+- `/maxsim:plan --review 2` — check assumptions
 
 ---
 ```
@@ -69,7 +69,7 @@ Add note that this is the last plan and what comes after:
 **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
 <sub>Final plan in Phase 2</sub>
 
-`/maxsim:execute-phase 2`
+`/maxsim:execute 2`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -91,15 +91,15 @@ Add note that this is the last plan and what comes after:
 
 **Phase 2: Authentication** — JWT login flow with refresh tokens
 
-`/maxsim:plan-phase 2`
+`/maxsim:plan 2`
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- `/maxsim:discuss-phase 2` — gather context first
-- `/maxsim:research-phase 2` — investigate unknowns
+- `/maxsim:plan 2` — gather context first
+- `/maxsim:plan --research 2` — investigate unknowns
 - Review roadmap
 
 ---
@@ -120,15 +120,15 @@ Show completion status before next action:
 
 **Phase 3: Core Features** — User dashboard, settings, and data export
 
-`/maxsim:plan-phase 3`
+`/maxsim:plan 3`
 
 <sub>`/clear` first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- `/maxsim:discuss-phase 3` — gather context first
-- `/maxsim:research-phase 3` — investigate unknowns
+- `/maxsim:plan 3` — gather context first
+- `/maxsim:plan --research 3` — investigate unknowns
 - Review what Phase 2 built
 
 ---
@@ -145,11 +145,11 @@ When there's no clear primary action:
 
 **Phase 3: Core Features** — User dashboard, settings, and data export
 
-**To plan directly:** `/maxsim:plan-phase 3`
+**To plan directly:** `/maxsim:plan 3`
 
-**To discuss context first:** `/maxsim:discuss-phase 3`
+**To discuss context first:** `/maxsim:plan 3`
 
-**To research unknowns:** `/maxsim:research-phase 3`
+**To research unknowns:** `/maxsim:plan --research 3`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -169,7 +169,7 @@ All 4 phases shipped
 
 **Start v1.1** — questioning → research → requirements → roadmap
 
-`/maxsim:new-milestone`
+`/maxsim:init`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -214,7 +214,7 @@ Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with slidi
 ## To Continue
 
 Run `/clear`, then paste:
-/maxsim:execute-phase 2
+/maxsim:execute 2
 ```
 
 User has no idea what 02-03 is about.
@@ -222,7 +222,7 @@ User has no idea what 02-03 is about.
 ### Don't: Missing /clear explanation
 
 ```
-`/maxsim:plan-phase 3`
+`/maxsim:plan 3`
 
 Run /clear first.
 ```
@@ -242,7 +242,7 @@ Sounds like an afterthought. Use "Also available:" instead.
 
 ```
 ```
-/maxsim:plan-phase 3
+/maxsim:plan 3
 ```
 ```
 

package/dist/assets/templates/references/model-profile-resolution.md

@@ -19,7 +19,7 @@ Look up the agent in the table for the resolved profile. Pass the model paramete
 ```
 Task(
   prompt="...",
-  subagent_type="maxsim-planner",
+  subagent_type="planner",
   model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
 )
 ```

package/dist/assets/templates/references/model-profiles.md

@@ -6,17 +6,10 @@ Model profiles control which Claude model each MAXSIM agent uses. This allows ba
 
 | Agent | `quality` | `balanced` | `budget` |
 |-------|-----------|------------|----------|
-| maxsim-planner | opus | opus | sonnet |
-| maxsim-roadmapper | opus | sonnet | sonnet |
-| maxsim-executor | opus | sonnet | sonnet |
-| maxsim-phase-researcher | opus | sonnet | haiku |
-| maxsim-project-researcher | opus | sonnet | haiku |
-| maxsim-research-synthesizer | sonnet | sonnet | haiku |
-| maxsim-debugger | opus | sonnet | sonnet |
-| maxsim-codebase-mapper | sonnet | haiku | haiku |
-| maxsim-verifier | sonnet | sonnet | haiku |
-| maxsim-plan-checker | sonnet | sonnet | haiku |
-| maxsim-integration-checker | sonnet | sonnet | haiku |
+| planner | opus | sonnet | haiku |
+| executor | opus | sonnet | sonnet |
+| researcher | opus | sonnet | haiku |
+| verifier | sonnet | sonnet | haiku |
 
 ## Profile Philosophy
 
@@ -55,8 +48,8 @@ Override specific agents without changing the entire profile:
 {
   "model_profile": "balanced",
   "model_overrides": {
-    "maxsim-executor": "opus",
-    "maxsim-planner": "haiku"
+    "executor": "opus",
+    "planner": "haiku"
   }
 }
 ```
@@ -65,7 +58,7 @@ Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `hai
 
 ## Switching Profiles
 
-Runtime: `/maxsim:set-profile <profile>`
+Runtime: `/maxsim:settings` (change profile)
 
 Per-project default: Set in `.planning/config.json`:
 ```json
@@ -76,17 +69,17 @@ Per-project default: Set in `.planning/config.json`:
 
 ## Design Rationale
 
-**Why Opus for maxsim-planner?**
+**Why Opus for planner?**
 Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
 
-**Why Sonnet for maxsim-executor?**
+**Why Sonnet for executor?**
 Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
 
-**Why Sonnet (not Haiku) for verifiers in balanced?**
+**Why Sonnet (not Haiku) for verifier in balanced?**
 Verification requires goal-backward reasoning - checking if code *delivers* what the phase promised, not just pattern matching. Sonnet handles this well; Haiku may miss subtle gaps.
 
-**Why Haiku for maxsim-codebase-mapper?**
-Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.
+**Why Haiku for researcher in budget?**
+Read-only exploration and pattern extraction. Research is guided by orchestrator questions; Haiku can follow structured research protocols effectively at lower cost.
 
 **Why `inherit` instead of passing `opus` directly?**
 Claude Code's `"opus"` alias maps to a specific model version. Organizations may block older opus versions while allowing newer ones. MAXSIM returns `"inherit"` for opus-tier agents, causing them to use whatever opus version the user has configured in their session. This avoids version conflicts and silent fallbacks to Sonnet.

package/dist/assets/templates/rules/conventions.md

@@ -0,0 +1,51 @@
+# MAXSIM Conventions
+
+These conventions apply to all MAXSIM-managed work. Follow them alongside project-specific CLAUDE.md conventions.
+
+## Commit Messages
+
+Use conventional commits with scope:
+
+| Prefix | When |
+|--------|------|
+| `fix(scope):` | Bug fix |
+| `feat(scope):` | New feature |
+| `chore(scope):` | Build, deps, maintenance |
+| `docs(scope):` | Documentation only |
+| `test(scope):` | Adding or fixing tests |
+| `refactor(scope):` | Neither fix nor feature |
+| `fix!(scope):` / `feat!(scope):` | Breaking change |
+
+Scope reflects the area of change: `fix(install):`, `feat(phase-04):`, `refactor(core):`.
+
+Atomic commits: one logical change per commit. Do not bundle unrelated changes.
+
+Co-author line when AI-assisted: `Co-Authored-By: Claude <noreply@anthropic.com>`
+
+## File Naming
+
+| Type | Path Pattern |
+|------|-------------|
+| Skills | `.claude/skills/<kebab-case>/SKILL.md` |
+| Agents | `.claude/agents/<simple-name>.md` |
+| Rules | `.claude/rules/<topic>.md` |
+| Plans | `.planning/phases/XX-Name/XX-NN-PLAN.md` |
+
+Use kebab-case for directory names. Use UPPER_CASE for protocol files (SKILL.md, PLAN.md, STATE.md).
+
+## Code Style
+
+- Follow the project CLAUDE.md for language-specific conventions
+- TypeScript: async-only functions (no sync duplicates)
+- Markdown: ATX headers (`#`), no trailing whitespace, blank line before headers
+- Keep files focused: one responsibility per module
+
+## Deferred Items
+
+When encountering work outside current scope, log it instead of implementing it:
+
+```
+- [{category}] {description} -- {why deferred}
+```
+
+Categories: `feature`, `bug`, `refactor`, `investigation`

package/dist/assets/templates/rules/verification-protocol.md

@@ -0,0 +1,57 @@
+# Verification Protocol
+
+Evidence before claims, always. No exceptions.
+
+## HARD GATE
+
+**No completion claims without fresh verification evidence.**
+
+This gate is non-negotiable. There is no advisory mode, no config override, no escape hatch. Either evidence passes or it fails. No middle ground. Partial success is failure. "Good enough" is not enough.
+
+Do NOT pass this gate by arguing it's "close enough", "minor issue", or "will fix later".
+
+## THIS-Turn Requirement
+
+If you have not run the verification command in THIS turn, you cannot claim it passes.
+
+Evidence must come from tool output executed in the current turn. Prior turn results, cached knowledge, and reasoning are not evidence. Any tool output qualifies: test output, build results, git diff, file reads, linter output.
+
+## Evidence Block Format
+
+Every completion claim requires an evidence block:
+
+```
+CLAIM: [what you are claiming]
+EVIDENCE: [exact command run in THIS turn]
+OUTPUT: [relevant excerpt of actual output]
+VERDICT: PASS | FAIL
+```
+
+If VERDICT is FAIL: do NOT commit. Fix the issue, re-run verification, produce a new evidence block.
+
+## FORBIDDEN PHRASES
+
+If you catch yourself using any of these, STOP immediately. You are rationalizing instead of verifying:
+
+- "should work"
+- "probably passes"
+- "I'm confident that..."
+- "based on my analysis..."
+- "the logic suggests..."
+- "it's reasonable to assume..."
+
+These phrases indicate reasoning without evidence. Replace them with a verification command and its actual output.
+
+## What Counts as Evidence
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| "Tests pass" | Test command output showing 0 failures | Previous run, "should pass" |
+| "Build succeeds" | Build command with exit code 0 | Linter passing only |
+| "Bug is fixed" | Original failing test now passes | "Code changed, assumed fixed" |
+| "Task complete" | All done criteria checked with evidence | "I implemented everything" |
+| "No regressions" | Full test suite passing | "I only changed one file" |
+
+## Retry Protocol
+
+When verification fails: read the error, fix the issue, re-run the command, produce a new evidence block. Maximum 3 total attempts per gate before escalating. The `verification-gates` skill provides detailed methodology for gate types, retry feedback, and escalation.

package/dist/assets/templates/skills/agent-system-map/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: agent-system-map
+description: >-
+  Registry of MAXSIM's 4 agent types with their roles, base tools, preloaded
+  skills, and typical tasks. Documents the orchestrator-mediated communication
+  pattern where agents return results to the orchestrator for pipeline routing.
+  Use when spawning agents, understanding agent capabilities, or designing
+  agent interactions.
+user-invocable: false
+---
+
+# Agent System Map
+
+MAXSIM uses 4 generic agent types. Specialization comes from orchestrator instructions and skills, not from separate agent definitions.
+
+## Agent Registry
+
+| Agent | Role | Base Tools | Preloaded Skills |
+|-------|------|-----------|-----------------|
+| **executor** | Implements plans with atomic commits and verified completion | Read, Write, Edit, Bash, Grep, Glob | handoff-contract, evidence-collection, commit-conventions |
+| **planner** | Creates structured PLAN.md files from requirements and research | Read, Bash, Grep, Glob | handoff-contract |
+| **researcher** | Investigates technical domains and produces structured findings | Read, Bash, Grep, Glob, WebFetch | research-methodology, handoff-contract |
+| **verifier** | Verifies work quality, spec compliance, and goal achievement | Read, Bash, Grep, Glob | verification-gates, evidence-collection, handoff-contract |
+
+## Specialization via Orchestrator
+
+The orchestrator provides task-specific context in the spawn prompt. The same `verifier` agent handles code review, spec review, debugging, and integration checking based on what the orchestrator asks:
+
+| Task | Orchestrator Instruction |
+|------|------------------------|
+| Code review | "Review these files for code quality, security, and conventions" |
+| Spec review | "Check these files against the plan's must_haves and done criteria" |
+| Debugging | "Investigate this failing test using systematic hypothesis testing" |
+| Integration check | "Validate cross-component integration for these changed files" |
+
+## Communication Pattern: Orchestrator-Mediated
+
+**Subagents CANNOT spawn other subagents.** This is a Claude Code platform constraint. All agent-to-agent communication routes through the orchestrator.
+
+```
+Orchestrator
+  |-- spawns --> Researcher (returns findings)
+  |-- spawns --> Planner (returns PLAN.md)
+  |-- spawns --> Executor (returns SUMMARY.md)
+  |-- spawns --> Verifier (returns verification report)
+```
+
+**Flow:**
+1. Orchestrator spawns Agent A with task + context
+2. Agent A executes, produces results using handoff contract
+3. Agent A returns to orchestrator
+4. Orchestrator reads results, decides next step
+5. Orchestrator spawns Agent B with Agent A's results as context
+
+Agents never call each other directly. The orchestrator is the single routing point.
+
+## Spawn Prompt Format
+
+When spawning an agent, use natural language with markdown sections:
+
+```markdown
+## Task
+[What the agent should do -- specific, actionable]
+
+## Context
+[Phase, plan, prior results, relevant decisions]
+
+## Files to Read
+- [file paths the agent should read at startup]
+
+## Suggested Skills
+- [skills that may be helpful for this task]
+
+## Success Criteria
+- [measurable outcomes the orchestrator will check]
+```
+
+The orchestrator carries the specialization context. Agents are generic -- the spawn prompt makes them specific.
+
+## Model Selection
+
+Each agent type has a default model from the config profile:
+
+| Profile | Executor | Planner | Researcher | Verifier |
+|---------|----------|---------|------------|----------|
+| quality | opus | opus | opus | sonnet |
+| balanced | sonnet | sonnet | sonnet | sonnet |
+| budget | sonnet | haiku | haiku | haiku |
+
+The orchestrator can override per-spawn for complex tasks (e.g., force opus for critical research).
+
+Agents use `model: inherit` in their frontmatter -- the orchestrator or CLI resolves the actual model at spawn time based on the config profile.