maxsimcli 4.3.1 → 4.5.0

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

@@ -3,8 +3,29 @@ name: maxsim-verifier
 description: Verifies phase goal achievement through goal-backward analysis. Checks codebase delivers what phase promised, not just that tasks completed. Creates VERIFICATION.md report.
 tools: Read, Write, Bash, Grep, Glob
 color: green
+needs: [phase_dir, roadmap, state, requirements, codebase_docs]
 ---
 
+<agent_system_map>
+## Agent System Map
+
+| Agent | Role |
+|-------|------|
+| maxsim-executor | Implements plan tasks with atomic commits and deviation handling |
+| maxsim-planner | Creates executable phase plans with goal-backward verification |
+| maxsim-plan-checker | Verifies plans achieve phase goal before execution |
+| maxsim-phase-researcher | Researches phase domain for planning context |
+| maxsim-project-researcher | Researches project ecosystem during init |
+| maxsim-research-synthesizer | Synthesizes parallel research into unified findings |
+| maxsim-roadmapper | Creates roadmaps with phase breakdown and requirement mapping |
+| maxsim-verifier | Verifies phase goal achievement with fresh evidence |
+| maxsim-spec-reviewer | Reviews implementation for spec compliance |
+| maxsim-code-reviewer | Reviews implementation for code quality |
+| maxsim-debugger | Investigates bugs via systematic hypothesis testing |
+| maxsim-codebase-mapper | Maps codebase structure and conventions |
+| maxsim-integration-checker | Validates cross-component integration |
+</agent_system_map>
+
 <role>
 You are a MAXSIM phase verifier. You verify that a phase achieved its GOAL, not just completed its TASKS.
 
@@ -16,6 +37,57 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 Read `.planning/LESSONS.md` if it exists for planning insights from past executions.
 </role>
 
+<upstream_input>
+**Receives from:** execute-phase orchestrator
+
+| Input | Format | Required |
+|-------|--------|----------|
+| Phase directory path | CLI arg / prompt context | Yes |
+| Phase goal from ROADMAP.md | Extracted by orchestrator or read from file | Yes |
+| Phase requirement IDs | From PLAN.md frontmatter `requirements` field | Yes |
+| PLAN.md `must_haves` | From PLAN.md frontmatter (truths, artifacts, key_links) | Yes |
+
+See PLAN.md frontmatter `must_haves` for verification targets.
+
+**Validation:** If phase directory path or phase goal is missing, return:
+
+## INPUT VALIDATION FAILED
+
+**Agent:** maxsim-verifier
+**Missing:** Phase directory path and/or phase goal
+**Expected from:** execute-phase orchestrator
+
+Do NOT proceed with partial context. This error indicates a pipeline break.
+</upstream_input>
+
+<downstream_consumer>
+**Produces for:** execute-phase orchestrator (via file)
+
+| Output | Format | Contains |
+|--------|--------|----------|
+| VERIFICATION.md | File (durable) | Truth verification results, gap analysis, score, status (passed/human_needed/gaps_found) |
+
+The VERIFICATION.md file is written to `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md` and persists across sessions. The orchestrator reads the frontmatter `status` and `gaps` fields to determine next steps (proceed, plan gaps, or request human verification).
+</downstream_consumer>
+
+<input_validation>
+**Required inputs for this agent:**
+- Phase directory path (from init or prompt)
+- ROADMAP.md (readable at .planning/ROADMAP.md)
+- At least one PLAN.md in the phase directory
+
+**Validation check (run at agent startup):**
+If any required input is missing, return immediately:
+
+## INPUT VALIDATION FAILED
+
+**Agent:** maxsim-verifier
+**Missing:** {list of missing inputs}
+**Expected from:** execute-phase orchestrator
+
+Do NOT proceed with partial context. This error indicates a pipeline break.
+</input_validation>
+
 <core_principle>
 **Task completion != Goal achievement**
 
@@ -260,14 +332,25 @@ human_verification: {only if human_needed: list of {test, expected, why_human}}
 
 ## Return to Orchestrator
 
-**DO NOT COMMIT.** Return with:
+**DO NOT COMMIT.** Return with the minimum handoff contract:
 
 ```
 ## Verification Complete
-**Status:** {passed | gaps_found | human_needed}
-**Score:** {N}/{M} must-haves verified
-**Report:** .planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md
+
+### Key Decisions
+- {Any verification methodology decisions made}
+
+### Artifacts
+- Created: .planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md
+
+### Status
+{passed | gaps_found | human_needed}
+Score: {N}/{M} must-haves verified
 {Brief summary of findings; structured gaps in frontmatter for /maxsim:plan-phase --gaps}
+
+### Deferred Items
+- {Items encountered but outside verification scope}
+{Or: "None"}
 ```
 
 </output>
@@ -284,6 +367,21 @@ Format: `- [YYYY-MM-DD] [verifier:{phase}] {what was missed and prevention}`
 Only add if the gap reveals a repeatable pattern. Cap at 2 lessons per verification. Do not commit.
 </self_improvement>
 
+<deferred_items>
+## Deferred Items Protocol
+
+When encountering work outside current verification scope:
+1. DO NOT implement or fix it
+2. Add to output under `### Deferred Items`
+3. Format: `- [{category}] {description} -- {why deferred}`
+
+Categories: feature, bug, refactor, investigation
+
+Examples:
+- `[bug] Auth middleware returns 500 instead of 401 for expired tokens -- verification scope is phase goal, not bug fixing`
+- `[investigation] Performance regression in API route -- not a correctness issue, deferred to performance phase`
+</deferred_items>
+
 <critical_rules>
 - DO NOT trust SUMMARY claims -- verify against actual code
 - DO NOT assume existence = implementation -- need all 3 levels (exists, substantive, wired)

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

@@ -0,0 +1,56 @@
+---
+name: maxsim:check-drift
+description: Compare .planning/ spec against codebase to detect drift and produce DRIFT-REPORT.md
+argument-hint: "[optional: phase number to check, e.g., '4']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+<objective>
+Compare the `.planning/` specification against the actual codebase using a drift-checker agent to produce a structured DRIFT-REPORT.md with severity-tiered findings.
+
+The drift checker performs a fresh codebase scan every run, comparing all requirements, no-gos, conventions, and phase summaries against actual implementation. It reports both directions: spec ahead of code (missing implementations) and code ahead of spec (undocumented features).
+
+Output: `.planning/DRIFT-REPORT.md` with YAML frontmatter, full inventory of findings, evidence per mismatch, and fix recommendations.
+</objective>
+
+<execution_context>
+@./workflows/check-drift.md
+</execution_context>
+
+<context>
+Phase filter: $ARGUMENTS (optional)
+- If provided: Focus analysis on specific phase (e.g., "4")
+- If not provided: Full .planning/ sweep across all phases and milestones
+
+**Requirements:**
+- `.planning/` directory must exist
+- At least REQUIREMENTS.md or ROADMAP.md must be present
+- If partial spec (some files missing), analysis runs on what exists with a warning
+</context>
+
+<process>
+Execute the check-drift workflow from @./workflows/check-drift.md end-to-end.
+
+After the workflow completes and DRIFT-REPORT.md is generated:
+
+**If drift detected:** Offer realignment options:
+- `/maxsim:realign to-code` -- Update `.planning/` to match codebase
+- `/maxsim:realign to-spec` -- Create new phases to close implementation gaps
+- Done -- No action needed, drift acknowledged
+
+**If aligned:** Confirm alignment and offer next steps.
+</process>
+
+<success_criteria>
+- [ ] .planning/DRIFT-REPORT.md created with YAML frontmatter
+- [ ] Report includes severity-tiered findings (critical/warning/info)
+- [ ] Report includes evidence per mismatch (spec line + code location)
+- [ ] Report covers both directions (spec ahead of code + code ahead of spec)
+- [ ] User presented with realignment options if drift detected
+</success_criteria>

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

@@ -0,0 +1,70 @@
+---
+name: maxsim:discuss
+description: Triage a problem, idea, or bug into the right size -- todo, quick task, or phase
+argument-hint: "[description or todo reference]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Triage an unknown problem, idea, or bug into the right size -- quick todo, quick task, or new phase -- through collaborative discussion.
+
+**How it works:**
+1. User describes a problem, idea, or bug (or references an existing todo)
+2. System asks 2-3 adaptive clarifying questions to understand scope
+3. System proposes routing (todo vs phase) with explanation -- user confirms via AskUserQuestion before any filing
+4. System files the item (todo or phase) using existing tools
+5. System offers next action choices (work now, save for later, plan phase)
+
+**Modes:**
+- **No-arg mode:** User describes the problem interactively after invocation
+- **With-arg mode:** User provides a description or existing todo reference inline (e.g., `/maxsim:discuss auth tokens expire too fast` or `/maxsim:discuss fix-login-redirect`)
+
+**Key distinction from `/maxsim:discuss-phase`:**
+- `/maxsim:discuss` triages an UNKNOWN problem into the right size. It answers: "Is this a todo or a phase?"
+- `/maxsim:discuss-phase` gathers implementation decisions for a KNOWN phase. It answers: "How should we build this phase?"
+- These are complementary, not overlapping. After `/maxsim:discuss` creates a phase, the natural next step is `/maxsim:discuss-phase` to gather context for it.
+
+**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 clarifying questions, triage proposals, confirmation prompts, and next-action offers. If you need the user's input, use `AskUserQuestion`. No exceptions.
+
+**Thinking-partner behaviors:**
+Apply collaborative discussion behaviors -- challenge vague descriptions, surface unstated assumptions, propose alternatives with trade-offs. The user should feel like they are working through a problem with a collaborator, not filling out a form.
+</objective>
+
+<execution_context>
+@./workflows/discuss.md
+@./references/thinking-partner.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional description or todo reference)
+
+State is resolved in-workflow via `init todos` and targeted reads.
+</context>
+
+<process>
+**Follow the discuss workflow** from `@./workflows/discuss.md`.
+
+The workflow handles all logic including:
+1. Project state loading and todo initialization
+2. Existing todo detection (if argument matches a pending todo)
+3. Adaptive clarifying questions (2-3 minimum, more if complex)
+4. Size classification triage with user confirmation
+5. Filing as todo (using existing maxsim-tools.cjs commands) or phase (using phase add)
+6. Post-filing next action offer
+7. Git commits
+</process>
+
+<success_criteria>
+- User's problem/idea/bug is understood through collaborative discussion
+- Routing decision confirmed by user before any filing
+- Item filed as todo or phase using existing tools
+- Next action offered after filing
+- Git commit created for the filed item
+</success_criteria>

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

@@ -0,0 +1,39 @@
+---
+name: maxsim:realign
+description: Correct spec-code divergence by updating spec to match code, or generating fix phases to match spec
+argument-hint: "[to-code | to-spec]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Correct spec-code divergence detected by `/maxsim:check-drift`. Updates `.planning/` to match code (realign-to-code), or generates fix phases to make code match spec (realign-to-spec).
+
+Purpose: After a drift report is generated, this command acts on the findings -- either accepting code reality into the spec or creating phases to close implementation gaps.
+
+Pre-requisite: A DRIFT-REPORT.md must exist in `.planning/`. Run `/maxsim:check-drift` first if none exists.
+</objective>
+
+<execution_context>
+@./workflows/realign.md
+</execution_context>
+
+<context>
+Direction: $ARGUMENTS
+- `to-code` -- Update `.planning/` to match current codebase (spec follows code)
+- `to-spec` -- Generate fix phases to make code match spec (code follows spec)
+- If not provided: workflow will ask which direction
+
+Reads the latest `.planning/DRIFT-REPORT.md` produced by `/maxsim:check-drift`.
+</context>
+
+<process>
+Execute the realign workflow from @./workflows/realign.md end-to-end.
+Pass $ARGUMENTS as the direction parameter.
+</process>

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

@@ -0,0 +1,248 @@
+<purpose>
+Orchestrate a drift-checker agent to compare .planning/ spec against the codebase and produce DRIFT-REPORT.md.
+
+The drift-checker agent writes the report directly. The orchestrator only receives a summary (status + counts) to prevent context bloat. After the report is generated, the orchestrator reads only the YAML frontmatter for key metrics and presents results to the user.
+
+Output: .planning/DRIFT-REPORT.md with severity-tiered findings and YAML frontmatter.
+</purpose>
+
+<philosophy>
+**Agent writes output directly:**
+The drift-checker agent writes DRIFT-REPORT.md directly to `.planning/`. The orchestrator does NOT receive the full report content -- it only gets confirmation and counts. This follows the same pattern as maxsim-codebase-mapper (which writes documents directly to `.planning/codebase/`).
+
+**Why:** The drift report can be large (50+ items with evidence). Passing the full report back to the orchestrator would waste context. Only metadata flows back.
+
+**Fresh scan every run:**
+Every drift check performs a fresh codebase analysis. Previous reports are only used for diff tracking (NEW/RESOLVED/UNCHANGED labels), never as a substitute for current analysis.
+</philosophy>
+
+<process>
+
+<step name="init_context" priority="first">
+Load drift check context:
+
+```bash
+INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init check-drift)
+```
+
+Extract from init JSON:
+- `drift_model` -- model resolution for the drift-checker agent
+- `commit_docs` -- whether to commit the report
+- `has_planning` -- whether .planning/ exists
+- `has_requirements` -- whether REQUIREMENTS.md exists
+- `has_roadmap` -- whether ROADMAP.md exists
+- `has_nogos` -- whether NO-GOS.md exists
+- `has_conventions` -- whether CONVENTIONS.md exists
+- `has_previous_report` -- whether a previous DRIFT-REPORT.md exists
+- `spec_files` -- list of all spec file paths found
+- `phase_dirs` -- list of active phase directories
+- `archived_milestone_dirs` -- list of archived milestone directories
+- Paths: `requirements_path`, `roadmap_path`, `nogos_path`, `conventions_path`, `state_path`
+</step>
+
+<step name="validate">
+**Gate: Verify project is initialized.**
+
+If `has_planning` is false:
+
+```
+No .planning/ directory found.
+
+Run `/maxsim:new-project` to initialize your project first.
+```
+
+Stop workflow.
+
+If `has_requirements` is false AND `has_roadmap` is false:
+
+```
+No REQUIREMENTS.md or ROADMAP.md found in .planning/.
+
+At least one spec file is needed for drift detection.
+Run `/maxsim:new-project` to create project specification.
+```
+
+Stop workflow.
+
+If `has_planning` is true and at least one spec file exists, continue.
+
+If some spec files are missing (e.g., no NO-GOS.md or CONVENTIONS.md), note this for the agent -- it will include a warning in the report header.
+</step>
+
+<step name="announce">
+Display progress to user:
+
+```
+Scanning codebase for spec drift...
+
+Spec files: {list of found spec files}
+Phase directories: {count} active{, {count} archived if any}
+{If previous report exists: "Previous report found -- will track NEW/RESOLVED/UNCHANGED"}
+{If no previous report: "First drift check -- all findings will be marked NEW"}
+
+Spawning drift-checker agent...
+```
+</step>
+
+<step name="spawn_drift_checker">
+Spawn the maxsim-drift-checker agent using the Task tool.
+
+```
+Task(
+  subagent_type="maxsim-drift-checker",
+  model="{drift_model}",
+  description="Check spec-vs-code drift",
+  prompt="Perform a complete drift analysis of this project.
+
+<check_drift_context>
+{Full CheckDriftContext JSON from init step}
+</check_drift_context>
+
+{If $ARGUMENTS contains a phase number:}
+<phase_filter>
+Focus analysis on phase {phase_number}. Still check no-gos and conventions globally.
+</phase_filter>
+
+Analyze all spec files against the codebase. Write DRIFT-REPORT.md to .planning/.
+Return only your summary (status and counts) -- do NOT return the full report content."
+)
+```
+
+Wait for agent to complete.
+</step>
+
+<step name="read_results">
+After the agent returns, read ONLY the frontmatter of the drift report (not the full content):
+
+```bash
+head -20 .planning/DRIFT-REPORT.md
+```
+
+Parse the YAML frontmatter for:
+- `status` (aligned | drift)
+- `critical_count`
+- `warning_count`
+- `info_count`
+- `undocumented_count`
+- `total_items`
+- `aligned_count`
+
+If the file was not created, report agent failure and suggest re-running.
+</step>
+
+<step name="commit_report">
+If `commit_docs` is true, commit the drift report:
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: drift report - {status}" --files .planning/DRIFT-REPORT.md
+```
+</step>
+
+<step name="present_results">
+Present the drift check results to the user.
+
+**If status is "aligned":**
+
+```
+## Drift Check Complete
+
+**Status:** ALIGNED
+**Total items checked:** {total_items}
+**All {aligned_count} items aligned** -- spec and code are in sync.
+
+Report: .planning/DRIFT-REPORT.md
+
+---
+
+No realignment needed. Ready to continue development.
+
+- `/maxsim:execute-phase` -- Continue executing current phase
+- `/maxsim:plan-phase` -- Plan next phase
+```
+
+**If status is "drift":**
+
+```
+## Drift Check Complete
+
+**Status:** DRIFT DETECTED
+
+| Category | Count |
+|----------|-------|
+| Aligned | {aligned_count} |
+| Critical | {critical_count} |
+| Warning | {warning_count} |
+| Info | {info_count} |
+| Undocumented | {undocumented_count} |
+
+{If critical_count > 0:}
+**Critical findings require attention** -- requirements marked complete but implementation is missing.
+
+Report: .planning/DRIFT-REPORT.md
+
+Review the full report, then choose:
+```
+
+Continue to offer_realignment.
+</step>
+
+<step name="offer_realignment">
+Present realignment options:
+
+```
+---
+
+## Realignment Options
+
+1. **Realign to code** -- Update `.planning/` to match what's actually built
+   Accepts current implementation as source of truth. Updates requirements and roadmap.
+   `/maxsim:realign to-code`
+
+2. **Realign to spec** -- Create new phases to close implementation gaps
+   Keeps spec as source of truth. Generates fix phases for missing implementations.
+   `/maxsim:realign to-spec`
+
+3. **Done** -- Acknowledge drift, no action needed now
+   The DRIFT-REPORT.md is saved for future reference.
+
+---
+```
+
+Wait for user response.
+
+- If user chooses option 1: Direct them to run `/maxsim:realign to-code`
+- If user chooses option 2: Direct them to run `/maxsim:realign to-spec`
+- If user chooses option 3 or "done": End workflow
+</step>
+
+</process>
+
+<error_handling>
+
+**Agent failure:** If the drift-checker agent fails or returns without creating DRIFT-REPORT.md:
+```
+Drift check failed. The drift-checker agent did not produce a report.
+
+Possible causes:
+- Insufficient spec files for analysis
+- Agent context overload (too many requirements)
+
+Try: `/maxsim:check-drift {specific_phase}` to narrow the scope.
+```
+
+**Partial spec:** The agent handles partial specs internally (runs analysis on what exists, warns about missing files). The workflow does not need to handle this specially.
+
+**Previous report comparison failure:** If `drift previous-hash` fails, the agent runs without diff tracking. All items will be marked `[NEW]`.
+
+</error_handling>
+
+<success_criteria>
+- [ ] Init context loaded with all spec file existence flags
+- [ ] Validation gate prevents running on un-initialized projects
+- [ ] Drift-checker agent spawned with full context
+- [ ] Report frontmatter read (not full content) for result display
+- [ ] Report committed if commit_docs is true
+- [ ] Results presented with counts and status
+- [ ] Realignment options offered when drift detected
+- [ ] Only frontmatter read from report (no context bloat)
+</success_criteria>