maxsimcli 4.8.0 → 4.10.0

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

@@ -1,248 +0,0 @@
-<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/check-todos.md

@@ -1,261 +0,0 @@
-<purpose>
-List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
-</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="init_context">
-Load todo context:
-
-```bash
-INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init todos)
-```
-
-Extract from init JSON: `todo_count`, `todos`, `pending_dir`.
-
-If `todo_count` is 0:
-```
-No pending todos.
-
-Todos are captured during work sessions with /maxsim:add-todo.
-
----
-
-Would you like to:
-
-1. Continue with current phase (/maxsim:progress)
-2. Add a todo now (/maxsim:add-todo)
-```
-
-Exit.
-</step>
-
-<step name="parse_filter">
-Check for area filter in arguments:
-- `/maxsim:check-todos` → show all
-- `/maxsim:check-todos api` → filter to area:api only
-</step>
-
-<step name="list_todos">
-Use the `todos` array from init context (already filtered by area if specified).
-
-Parse and display as numbered list:
-
-```
-Pending Todos:
-
-1. Add auth token refresh (api, 2d ago)
-2. Fix modal z-index issue (ui, 1d ago)
-3. Refactor database connection pool (database, 5h ago)
-
----
-
-Reply with a number to view details, or:
-- `/maxsim:check-todos [area]` to filter by area
-- `q` to exit
-```
-
-Format age as relative time from created timestamp.
-</step>
-
-<step name="handle_selection">
-Wait for user to reply with a number.
-
-If valid: load selected todo, proceed.
-If invalid: "Invalid selection. Reply with a number (1-[N]) or `q` to exit."
-</step>
-
-<step name="load_context">
-Read the todo file completely. Display:
-
-```
-## [title]
-
-**Area:** [area]
-**Created:** [date] ([relative time] ago)
-**Files:** [list or "None"]
-
-### Problem
-[problem section content]
-
-### Solution
-[solution section content]
-```
-
-If `files` field has entries, read and briefly summarize each.
-</step>
-
-<step name="check_roadmap">
-Check for roadmap (can use init progress or directly check file existence):
-
-If `.planning/ROADMAP.md` exists:
-1. Check if todo's area matches an upcoming phase
-2. Check if todo's files overlap with a phase's scope
-3. Note any match for action options
-</step>
-
-<step name="offer_actions">
-**If todo maps to a roadmap phase:**
-
-Use AskUserQuestion:
-- header: "Action"
-- question: "This todo relates to Phase [N]: [name]. What would you like to do?"
-- options:
-  - "Work on it now" — move to done, start working
-  - "Add to phase plan" — include when planning Phase [N]
-  - "Brainstorm approach" — think through before deciding
-  - "Put it back" — return to list
-
-**If no roadmap match:**
-
-Use AskUserQuestion:
-- header: "Action"
-- question: "What would you like to do with this todo?"
-- options:
-  - "Work on it now" — move to done, start working
-  - "Create a phase" — /maxsim:add-phase with this scope
-  - "Brainstorm approach" — think through before deciding
-  - "Put it back" — return to list
-</step>
-
-<step name="execute_action">
-**Work on it now:**
-```bash
-mv ".planning/todos/pending/[filename]" ".planning/todos/done/"
-```
-Update STATE.md todo count. Present problem/solution context. Begin work or ask how to proceed.
-
-**Add to phase plan:**
-Note todo reference in phase planning notes. Keep in pending. Return to list or exit.
-
-**Create a phase:**
-Display: `/maxsim:add-phase [description from todo]`
-Keep in pending. User runs command in fresh context.
-
-**Brainstorm approach:**
-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.
-</step>
-
-<step name="update_state">
-After any action that changes todo count:
-
-Re-run `init todos` to get updated count, then update STATE.md "### Pending Todos" section if exists.
-</step>
-
-<step name="git_commit">
-If todo was moved to done/, commit the change:
-
-```bash
-git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true
-node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: start work on todo - [title]" --files .planning/todos/done/[filename] .planning/STATE.md
-```
-
-Tool respects `commit_docs` config and gitignore automatically.
-
-Confirm: "Committed: docs: start work on todo - [title]"
-</step>
-
-</process>
-
-<success_criteria>
-- [ ] All pending todos listed with title, area, age
-- [ ] Area filter applied if specified
-- [ ] Selected todo's full context loaded
-- [ ] Roadmap context checked for phase match
-- [ ] Appropriate actions offered
-- [ ] Selected action executed
-- [ ] STATE.md updated if todo count changed
-- [ ] Changes committed to git (if todo moved to done/)
-</success_criteria>

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

@@ -1,153 +0,0 @@
-<purpose>
-
-Archive accumulated phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`. Identifies which phases belong to each completed milestone, shows a dry-run summary, and moves directories on confirmation.
-
-</purpose>
-
-<required_reading>
-
-1. `.planning/MILESTONES.md`
-2. `.planning/milestones/` directory listing
-3. `.planning/phases/` directory listing
-@./references/dashboard-bridge.md
-
-</required_reading>
-
-<process>
-
-<step name="identify_completed_milestones">
-
-Read `.planning/MILESTONES.md` to identify completed milestones and their versions.
-
-```bash
-cat .planning/MILESTONES.md
-```
-
-Extract each milestone version (e.g., v1.0, v1.1, v2.0).
-
-Check which milestone archive dirs already exist:
-
-```bash
-ls -d .planning/milestones/v*-phases 2>/dev/null
-```
-
-Filter to milestones that do NOT already have a `-phases` archive directory.
-
-If all milestones already have phase archives:
-
-```
-All completed milestones already have phase directories archived. Nothing to clean up.
-```
-
-Stop here.
-
-</step>
-
-<step name="determine_phase_membership">
-
-For each completed milestone without a `-phases` archive, read the archived ROADMAP snapshot to determine which phases belong to it:
-
-```bash
-cat .planning/milestones/v{X.Y}-ROADMAP.md
-```
-
-Extract phase numbers and names from the archived roadmap (e.g., Phase 1: Foundation, Phase 2: Auth).
-
-Check which of those phase directories still exist in `.planning/phases/`:
-
-```bash
-ls -d .planning/phases/*/ 2>/dev/null
-```
-
-Match phase directories to milestone membership. Only include directories that still exist in `.planning/phases/`.
-
-</step>
-
-<step name="show_dry_run">
-
-Present a dry-run summary for each milestone:
-
-```
-## Cleanup Summary
-
-### v{X.Y} — {Milestone Name}
-These phase directories will be archived:
-- 01-foundation/
-- 02-auth/
-- 03-core-features/
-
-Destination: .planning/milestones/v{X.Y}-phases/
-
-### v{X.Z} — {Milestone Name}
-These phase directories will be archived:
-- 04-security/
-- 05-hardening/
-
-Destination: .planning/milestones/v{X.Z}-phases/
-```
-
-If no phase directories remain to archive (all already moved or deleted):
-
-```
-No phase directories found to archive. Phases may have been removed or archived previously.
-```
-
-Stop here.
-
-AskUserQuestion: "Proceed with archiving?" with options: "Yes — archive listed phases" | "Cancel"
-
-If "Cancel": Stop.
-
-</step>
-
-<step name="archive_phases">
-
-For each milestone, move phase directories:
-
-```bash
-mkdir -p .planning/milestones/v{X.Y}-phases
-```
-
-For each phase directory belonging to this milestone:
-
-```bash
-mv .planning/phases/{dir} .planning/milestones/v{X.Y}-phases/
-```
-
-Repeat for all milestones in the cleanup set.
-
-</step>
-
-<step name="commit">
-
-Commit the changes:
-
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "chore: archive phase directories from completed milestones" --files .planning/milestones/ .planning/phases/
-```
-
-</step>
-
-<step name="report">
-
-```
-Archived:
-{For each milestone}
-- v{X.Y}: {N} phase directories → .planning/milestones/v{X.Y}-phases/
-
-.planning/phases/ cleaned up.
-```
-
-</step>
-
-</process>
-
-<success_criteria>
-
-- [ ] All completed milestones without existing phase archives identified
-- [ ] Phase membership determined from archived ROADMAP snapshots
-- [ ] Dry-run summary shown and user confirmed
-- [ ] Phase directories moved to `.planning/milestones/v{X.Y}-phases/`
-- [ ] Changes committed
-
-</success_criteria>