maxsimcli 4.4.0 → 4.5.0

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>

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

@@ -0,0 +1,343 @@
+<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. `.planning/ROADMAP.md` exists -- if not, stop and tell the user to initialize the project.
+</sanity_check>
+
+<purpose>
+Triage an unknown problem, idea, or bug into the right size -- quick todo or new phase -- through collaborative discussion.
+
+You are a thinking partner, not a form collector. The user has something on their mind -- help them clarify it, size it, and file it in the right place. Then offer the next action so momentum continues.
+
+**Key distinction:** This workflow triages an UNKNOWN item into the right size. `/maxsim:discuss-phase` gathers decisions for a KNOWN phase. They are complementary, not overlapping.
+</purpose>
+
+<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>
+
+<tool_mandate>
+**CRITICAL -- Structured user interaction is MANDATORY.**
+
+Every question directed at the user MUST use a structured tool. NEVER write a question as plain text and wait for the user to respond. This applies to:
+
+- Existing todo confirmation
+- Every clarifying question during discussion
+- Triage size classification proposal
+- Filing confirmation
+- Next action offers
+- Any follow-up or clarification
+
+**Tool selection:** At workflow start, probe for the dashboard (see @dashboard-bridge). Then:
+- **DASHBOARD_ACTIVE = true** -- use `mcp__maxsim-dashboard__ask_question` (questions appear in browser). Follow the schema translation rules from @dashboard-bridge.
+- **DASHBOARD_ACTIVE = false** -- use `AskUserQuestion` (questions appear in terminal).
+
+**The rule is simple:** If you need input from the user -- use the appropriate structured tool based on dashboard availability. Zero exceptions.
+</tool_mandate>
+
+<process>
+
+<step name="init_context">
+Load project state and todo context:
+
+```bash
+STATE=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs state-load --raw)
+```
+
+Check `planning_exists` from state. **Hard stop** if false -- tell user to run `/maxsim:new-project` first.
+
+```bash
+INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init todos)
+```
+
+Extract from init JSON: `commit_docs`, `date`, `timestamp`, `todo_count`, `todos`, `pending_dir`, `todos_dir_exists`.
+
+Ensure directories exist:
+```bash
+mkdir -p .planning/todos/pending .planning/todos/done
+```
+
+Parse user input from $ARGUMENTS (if any):
+- If arguments provided: store as `user_input` for use in detect_existing_todo and gather_context
+- If no arguments: `user_input` is empty -- will ask interactively in gather_context
+
+Note existing areas from the todos array for consistency in later area inference.
+</step>
+
+<step name="detect_existing_todo">
+**Only runs if `user_input` is non-empty.**
+
+Search pending todos for a title or slug match against the user's input:
+
+```bash
+# Search for matching words in existing todo titles
+grep -l -i "[key words from user_input]" .planning/todos/pending/*.md 2>/dev/null
+```
+
+Also compare against the `todos` array from init context -- check `title` and filename fields for partial matches.
+
+**If a match is found:**
+
+Use AskUserQuestion:
+- header: "Existing Todo"
+- question: "Found a pending todo that might match: **[todo title]**. Want to discuss this one?"
+- options:
+  - "Yes, discuss this todo" -- Load its context and continue discussion about it
+  - "No, this is something new" -- Proceed as a new item
+
+If "Yes": Read the matched todo file. Use its content as context for the discussion. The user may want to refine scope, change priority, or decide to work on it now.
+
+If "No": Proceed to gather_context as a new item, using `user_input` as the starting description.
+
+**If no match found (or no user_input):**
+
+Proceed to gather_context.
+</step>
+
+<step name="gather_context">
+Use adaptive questioning to understand what the user is describing.
+
+**Apply thinking-partner behaviors from @./references/thinking-partner.md:**
+- Challenge vague descriptions -- "broken" means what exactly?
+- Surface unstated assumptions -- "this should be easy" might hide complexity
+- Propose alternatives if the user's framing suggests a different approach
+- Follow the thread -- build each question on the previous answer
+
+**If `user_input` is non-empty (user provided a description):**
+
+Start by reflecting back what you understood, then ask your first clarifying question.
+
+Use AskUserQuestion:
+- header: "Clarify"
+- question: Based on the user's description, ask the most important clarifying question. For example: "You mentioned [X]. What specifically is the problem -- is it [scenario A] or [scenario B]?"
+- options: 2-3 concrete options that capture likely answers, plus the implicit "Other" for free-text
+
+**If `user_input` is empty (no arguments):**
+
+Use AskUserQuestion:
+- header: "Discuss"
+- question: "What's on your mind? Describe the problem, idea, or bug you want to discuss."
+- options: (none -- free text only, do not provide options for the opening question)
+
+**After the first response, ask 1-2 more adaptive follow-up questions:**
+
+Each follow-up uses AskUserQuestion with header, question, and options tailored to what the user just said.
+
+**Adaptive depth:**
+- If answers reveal the item is simple and well-defined (clear problem, clear scope, obvious size): move to triage after 2 questions
+- If answers reveal complexity (multiple systems involved, unclear scope, competing approaches): ask up to 2 more questions before triage
+- Maximum: 4 questions before triage. Read the room -- don't over-probe simple bugs.
+
+**What to extract from the discussion:**
+- `title`: 3-10 word descriptive title (action verb preferred)
+- `problem`: What is wrong or why this is needed
+- `scope_hint`: Simple fix, or touches multiple systems?
+- `files`: Any file paths or areas mentioned
+- `size_signal`: Does this feel like a quick todo or a multi-day phase?
+</step>
+
+<step name="triage">
+Based on gathered context, propose a size classification.
+
+**Assess the item:**
+- Quick todo: Well-defined problem, clear fix, single area, could be done in one session
+- Phase: Touches multiple systems, needs research, unclear approach, requires planning
+
+**Present classification via AskUserQuestion:**
+- header: "Size"
+- question: "Based on what you described, this looks like [your assessment with brief explanation]. Does that match?"
+- options:
+  - "Quick fix (todo)" -- File as a todo for later or work on it now
+  - "Needs a phase" -- Too big for a todo, add to the roadmap as a new phase
+  - "Let me explain more" -- I want to provide more context before deciding
+
+Include a brief explanation of WHY you suggest the classification you suggest. For example: "This sounds like a focused bug fix in one file -- a quick todo should cover it." Or: "This touches auth, database, and the API layer -- that's phase-sized work."
+
+**CRITICAL: Always present this as a question. Never auto-route.** Even if the size is obvious, the user confirms.
+
+**If user selects "Let me explain more":**
+Loop back to gather_context for 1-2 more questions, then return to triage with updated assessment.
+
+**If user selects "Quick fix (todo)":**
+Proceed to file_as_todo.
+
+**If user selects "Needs a phase":**
+Proceed to file_as_phase.
+</step>
+
+<step name="file_as_todo">
+File the item as a todo using existing maxsim-tools.cjs commands.
+
+**1. Generate slug:**
+```bash
+slug=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs generate-slug "$title" --raw)
+```
+
+**2. Infer area from discussion context:**
+
+Use file paths and topic from the discussion to infer area:
+
+| Path pattern | Area |
+|--------------|------|
+| `src/api/*`, `api/*` | `api` |
+| `src/components/*`, `src/ui/*` | `ui` |
+| `src/auth/*`, `auth/*` | `auth` |
+| `src/db/*`, `database/*` | `database` |
+| `tests/*`, `__tests__/*` | `testing` |
+| `docs/*` | `docs` |
+| `.planning/*` | `planning` |
+| `scripts/*`, `bin/*` | `tooling` |
+| No files or unclear | `general` |
+
+Use existing areas from init context if a similar match exists.
+
+**3. Check for duplicates:**
+```bash
+# Search for key words from title in existing todos
+grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null
+```
+
+If potential duplicate found, read the existing todo and compare scope.
+
+If overlapping, use AskUserQuestion:
+- header: "Duplicate?"
+- question: "A similar todo already exists: **[existing title]**. What would you like to do?"
+- options:
+  - "Skip" -- Keep the existing todo as-is
+  - "Replace" -- Update the existing todo with new context from this discussion
+  - "Add anyway" -- Create a separate todo (they cover different aspects)
+
+If "Skip": Jump to offer_next_action (nothing filed).
+If "Replace": Update the existing file instead of creating new.
+If "Add anyway": Continue creating new todo.
+
+**4. Create todo file:**
+
+Use values from init context: `timestamp` and `date` are already available.
+
+Write to `.planning/todos/pending/${date}-${slug}.md`:
+
+```markdown
+---
+created: [timestamp]
+title: [title]
+area: [area]
+mode: discussed
+files:
+  - [file paths from discussion, if any]
+---
+
+## Problem
+
+[Problem description enriched with discussion insights -- enough context for a future Claude session to understand weeks later]
+
+## Solution
+
+[Approach hints from the discussion, or "TBD" if only the problem was clarified]
+```
+
+**5. Commit:**
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: add todo [slug]" --files .planning/todos/pending/${date}-${slug}.md
+```
+
+Confirm to user: "Filed as todo: **[title]**"
+
+Proceed to offer_next_action.
+</step>
+
+<step name="file_as_phase">
+File the item as a new phase on the roadmap.
+
+**1. Gather phase details via AskUserQuestion:**
+- header: "Phase"
+- question: "What should this phase be called? And in one sentence, what's the goal?"
+- options: (none -- free text for naming)
+
+Parse the response to extract:
+- `phase_name`: Short name (2-5 words)
+- `phase_goal`: One-sentence goal description
+
+**2. Preview and confirm via AskUserQuestion:**
+
+First, check the current roadmap to determine what the next phase number would be:
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap analyze --raw
+```
+
+- header: "Confirm"
+- question: "This would add **Phase [N]: [phase_name]** to the roadmap with goal: *[phase_goal]*. Proceed?"
+- options:
+  - "Yes, add it" -- Add to roadmap
+  - "Let me adjust" -- I want to change the name or goal
+  - "Cancel" -- Don't add anything
+
+If "Let me adjust": Ask again for name/goal, then re-preview.
+If "Cancel": Jump to offer_next_action (nothing filed).
+If "Yes, add it": Continue.
+
+**3. Create the phase:**
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs phase add "[phase_name]"
+```
+
+**4. Commit:**
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: add phase [phase_name]" --files .planning/ROADMAP.md .planning/phases/
+```
+
+Confirm to user: "Added to roadmap: **Phase [N]: [phase_name]**"
+
+Proceed to offer_next_action.
+</step>
+
+<step name="offer_next_action">
+After filing (or skipping), offer contextual next actions.
+
+**If filed as todo:**
+
+Use AskUserQuestion:
+- header: "Next"
+- question: "Todo filed. What would you like to do next?"
+- options:
+  - "Work on it now" -- Start a quick task with /maxsim:quick
+  - "Save for later" -- It's captured, move on
+  - "Check all todos" -- See pending todos with /maxsim:check-todos
+
+If "Work on it now": Tell the user to run `/maxsim:quick [todo-title]` (print the command, do not auto-execute).
+If "Save for later": Confirm and end workflow.
+If "Check all todos": Tell the user to run `/maxsim:check-todos`.
+
+**If filed as phase:**
+
+Use AskUserQuestion:
+- header: "Next"
+- question: "Phase added to roadmap. What would you like to do next?"
+- options:
+  - "Discuss it" -- Gather implementation context with /maxsim:discuss-phase [phase]
+  - "Plan it" -- Jump to planning with /maxsim:plan-phase [phase]
+  - "Save for later" -- It's on the roadmap, move on
+
+If "Discuss it": Tell the user to run `/maxsim:discuss-phase [phase-number]`.
+If "Plan it": Tell the user to run `/maxsim:plan-phase [phase-number]`.
+If "Save for later": Confirm and end workflow.
+
+**If nothing was filed (duplicate skip or cancel):**
+
+Confirm that no action was taken and the discussion is complete.
+
+**User always chooses -- no auto-start.** Print the recommended command for the user to copy and run, do not execute it.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] User's problem/idea/bug understood through adaptive discussion
+- [ ] Existing todo detected if user referenced one
+- [ ] Triage routing confirmed by user before any filing
+- [ ] Item filed correctly (todo file in pending, or phase added to roadmap)
+- [ ] Git commit created for the filed item
+- [ ] Next action offered with concrete commands to run
+</success_criteria>

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

@@ -127,6 +127,14 @@ CONTEXT: [✓ if has_context | - if not]
 [Next phase/plan objective from roadmap analyze]
 ```
 
+**Performance metrics table truncation:**
+
+When displaying the performance metrics table from STATE.md (the `## Performance Metrics` section):
+- Show only the **last 20 entries** (most recent) by default.
+- If there are more than 20 metric entries in STATE.md, add a note above the table: `Showing last 20 of {total} metrics entries.`
+- This is a **display-time truncation only** — STATE.md retains all metrics as the source of truth. Do not modify or remove older entries from STATE.md.
+- If there are 20 or fewer entries, show all without any truncation note.
+
 </step>
 
 <step name="route">