maxsimcli 4.3.1 → 4.5.0

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/execute-phase.md

@@ -174,12 +174,16 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
    - Verify first 2 files from `key-files.created` exist on disk
    - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
    - Check for `## Self-Check: FAILED` marker
-   - **Check for `## Review Cycle` section** — verify all review stages show PASS/APPROVED/CLEAN/FIXED (not BLOCKED or FAIL)
+   - **Check for `## Review Cycle` section** — verify both review stages (Spec and Code) show PASS or SKIPPED (not BLOCKED or FAIL)
 
    If ANY spot-check fails: report which plan failed, route to failure handler — ask "Retry plan?" or "Continue with remaining waves?"
 
    If review cycle is missing or has unresolved issues: flag the plan as **review-incomplete** — ask "Run review cycle for this plan?" or "Continue (review will block phase completion)?"
 
+   **Note:** The executor agent runs the two-stage review (Spec Review + Code Review) after each wave. The orchestrator does NOT run reviews itself -- it only checks the executor's review results in SUMMARY.md. If review is missing, the executor failed to run it, and the orchestrator should offer to re-run the affected plan.
+
+   Review stages to check: `Spec:` and `Code:` lines in `## Review Cycle`. Both must be PASS or SKIPPED for the plan to be considered review-complete.
+
    If pass — **emit plan-complete lifecycle event** (if `DASHBOARD_ACTIVE`):
    ```
    mcp__maxsim-dashboard__submit_lifecycle_event(
@@ -279,10 +283,10 @@ After all waves:
 2. **03-02**: [one-liner from SUMMARY.md]
 
 ### Review Cycle Summary
-| Plan | Spec Review | Code Review | Simplify | Final Review |
-|------|-------------|-------------|----------|--------------|
-| 03-01 | PASS | APPROVED | CLEAN | — |
-| 03-02 | PASS | APPROVED | FIXED | APPROVED |
+| Plan | Spec Review | Code Review | Retries |
+|------|-------------|-------------|---------|
+| 03-01 | PASS | PASS | 0 |
+| 03-02 | PASS | PASS | 1 |
 
 [Aggregate review findings from each plan's SUMMARY.md `## Review Cycle` section.
 If any plan has no Review Cycle section: mark as "NOT RUN" and flag for attention.
@@ -295,7 +299,7 @@ If any plan has unresolved BLOCKED/FAIL status: list the blocking issues below.]
 [Aggregate from SUMMARYs, or "None"]
 ```
 
-**Phase completion gate:** If any plan has unresolved review issues (BLOCKED or FAIL in any review stage), the phase CANNOT proceed to `verify_phase_goal`. Present unresolved issues and offer:
+**Phase completion gate:** If any plan has unresolved review issues (BLOCKED or FAIL in Spec Review or Code Review stages), the phase CANNOT proceed to `verify_phase_goal`. Present unresolved issues and offer:
 - "Fix review issues now" — re-run the review cycle for affected plans
 - "Override and continue" — mark as acknowledged, proceed (adds warning to VERIFICATION.md)
 </step>

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">

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

@@ -288,6 +288,116 @@ Note: For quick tasks producing multiple plans (rare), spawn executors in parall
 
 ---
 
+**Step 6.3: Two-Stage Review**
+
+Run spec-compliance and code-quality review on the completed quick task. This applies to ALL quick tasks regardless of model profile or `--full` flag (per locked decision: "Quick means fast planning, not skipped quality gates").
+
+Display banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► REVIEWING RESULTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Running two-stage review...
+```
+
+1. Read the completed SUMMARY.md from `${QUICK_DIR}/${next_num}-SUMMARY.md` to understand what was built.
+2. Get modified files: `git diff --name-only HEAD~{N}` where N = number of commits from the executor.
+3. Read the quick plan at `${QUICK_DIR}/${next_num}-PLAN.md` to get task specs.
+
+**Spec Review:**
+
+```
+Task(
+  prompt="
+    <review_context>
+    **Plan:** quick-${next_num}
+    **Description:** ${DESCRIPTION}
+
+    <task_specs>
+    {Copy task specs (action, done criteria, files) from ${QUICK_DIR}/${next_num}-PLAN.md}
+    </task_specs>
+
+    <modified_files>
+    {output of git diff --name-only HEAD~N}
+    </modified_files>
+
+    <plan_frontmatter>
+    {Plan frontmatter including requirements if present}
+    </plan_frontmatter>
+    </review_context>
+  ",
+  subagent_type="maxsim-spec-reviewer",
+  model="{executor_model}",
+  description="Spec review: ${DESCRIPTION}"
+)
+```
+
+Parse output frontmatter for `status:` field.
+If FAIL: fix issues, commit (`fix(quick-${next_num}): address spec review findings`), retry (max 2 retries).
+On retry exhaustion (3 total attempts):
+
+```
+## REVIEW BLOCKED
+
+**Stage:** Spec Compliance
+**Task:** quick-${next_num}: ${DESCRIPTION}
+**Attempts:** 3 (initial + 2 retries)
+**Failing Issues:**
+- {issue list from review}
+
+**Options:**
+1. Fix manually and continue
+2. Skip review for this task
+3. Abort execution
+```
+
+STOP and wait for user decision.
+
+**Code Review:**
+
+```
+Task(
+  prompt="
+    <review_context>
+    **Plan:** quick-${next_num}
+
+    <modified_files>
+    {output of git diff --name-only HEAD~N, updated after any spec-review fix commits}
+    </modified_files>
+
+    <conventions>
+    {Content of .planning/CONVENTIONS.md or .planning/codebase/CONVENTIONS.md, or 'No CONVENTIONS.md found'}
+    </conventions>
+
+    <test_results>
+    {Last 20 lines of npm test output if package.json exists, or 'No tests available'}
+    </test_results>
+    </review_context>
+  ",
+  subagent_type="maxsim-code-reviewer",
+  model="{executor_model}",
+  description="Code review: ${DESCRIPTION}"
+)
+```
+
+Same retry logic as spec review (max 2 retries, then REVIEW BLOCKED with user options).
+
+**Record review results** in the quick task SUMMARY.md:
+
+Append `## Review Cycle` section to `${QUICK_DIR}/${next_num}-SUMMARY.md`:
+```markdown
+## Review Cycle
+- Spec: {PASS/FAIL/SKIPPED} ({retry_count} retries)
+- Code: {PASS/FAIL/SKIPPED} ({retry_count} retries)
+- Issues: {critical_count} critical, {warning_count} warnings
+```
+
+If `--full` flag was set: this review is part of the full quality pipeline (alongside plan-checking and verification that `--full` already enables).
+If `--full` was NOT set: the review STILL runs (per locked decision).
+
+---
+
 **Step 6.5: Verification (only when `$FULL_MODE`)**
 
 Skip this step entirely if NOT `$FULL_MODE`.