maxsimcli 4.8.0 → 4.9.0

package/dist/assets/templates/workflows/plan-create.md

@@ -0,0 +1,298 @@
+<purpose>
+Planning stage sub-workflow for /maxsim:plan. Spawns the planner agent to create PLAN.md files, then optionally spawns the planner (in plan-checking mode) for verification with a revision loop.
+
+This file is loaded by the plan.md orchestrator. It does NOT handle gate confirmations or stage routing -- the orchestrator handles that. This sub-workflow focuses ONLY on creating and verifying plans.
+</purpose>
+
+<process>
+
+## Step 1: Check Prerequisites
+
+The orchestrator provides phase context. Verify we have what we need:
+
+- `phase_number`, `phase_name`, `phase_dir`, `padded_phase`, `phase_slug`
+- `planner_model`, `checker_model`, `plan_checker_enabled`
+- `commit_docs`
+- `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`
+- `phase_req_ids` (requirement IDs that this phase must address)
+- `--skip-verify` flag presence
+
+## Step 2: Resolve Models
+
+```bash
+PLANNER_MODEL=$(node .claude/maxsim/bin/maxsim-tools.cjs resolve-model planner --raw)
+CHECKER_MODEL=$(node .claude/maxsim/bin/maxsim-tools.cjs resolve-model planner --raw)
+```
+
+## Step 3: Check Existing Plans
+
+```bash
+ls "${phase_dir}"/*-PLAN.md 2>/dev/null
+```
+
+**If plans exist:** Offer options via natural conversation:
+```
+Phase {phase_number} already has plan(s):
+{list of existing plan files}
+
+1. Add more plans (keep existing)
+2. View existing plans
+3. Re-plan from scratch (deletes existing plans)
+```
+
+- If "Add more": Continue to Step 4 with existing plans preserved.
+- If "View": Display plan files, then re-offer options.
+- If "Re-plan": Delete existing PLAN.md files, continue to Step 4.
+
+**If no plans exist:** Continue to Step 4.
+
+## Step 4: Gather Context Paths
+
+Extract file paths from the orchestrator context (provided via init JSON):
+
+```bash
+STATE_PATH=$(echo "$INIT" | jq -r '.state_path // empty')
+ROADMAP_PATH=$(echo "$INIT" | jq -r '.roadmap_path // empty')
+REQUIREMENTS_PATH=$(echo "$INIT" | jq -r '.requirements_path // empty')
+RESEARCH_PATH=$(echo "$INIT" | jq -r '.research_path // empty')
+CONTEXT_PATH=$(echo "$INIT" | jq -r '.context_path // empty')
+```
+
+## Step 5: Spawn Planner
+
+Display:
+```
+Planning Phase {phase_number}: {phase_name}...
+```
+
+Construct the planner prompt:
+
+```markdown
+<planning_context>
+**Phase:** {phase_number}
+**Mode:** standard
+
+<files_to_read>
+- {state_path} (Project State)
+- {roadmap_path} (Roadmap)
+- {requirements_path} (Requirements)
+- {context_path} (USER DECISIONS from discussion stage)
+- {research_path} (Technical Research)
+</files_to_read>
+
+**Phase requirement IDs (every ID MUST appear in a plan's `requirements` field):** {phase_req_ids}
+
+**Project instructions:** Read ./CLAUDE.md if exists -- follow project-specific guidelines
+**Project skills:** Check .skills/ directory (if exists) -- read SKILL.md files, plans should account for project skill rules
+</planning_context>
+
+<downstream_consumer>
+Output consumed by /maxsim:execute. Plans need:
+- Frontmatter (wave, depends_on, files_modified, autonomous)
+- Tasks in XML format
+- Verification criteria
+- must_haves for goal-backward verification
+</downstream_consumer>
+
+<quality_gate>
+- [ ] PLAN.md files created in phase directory
+- [ ] Each plan has valid frontmatter
+- [ ] Tasks are specific and actionable
+- [ ] Dependencies correctly identified
+- [ ] Waves assigned for parallel execution
+- [ ] must_haves derived from phase goal
+</quality_gate>
+```
+
+Spawn the planner:
+
+```
+Task(
+  prompt=planner_prompt,
+  subagent_type="planner",
+  model="{planner_model}",
+  description="Plan Phase {phase_number}"
+)
+```
+
+## Step 6: Handle Planner Return
+
+Parse the planner's return message:
+
+- **`## PLANNING COMPLETE`:**
+  Validate PLAN.md files were created:
+  ```bash
+  ls "${phase_dir}"/*-PLAN.md 2>/dev/null | wc -l
+  ```
+
+  If plans found:
+  - Display plan count and filenames.
+  - If `--skip-verify` flag is set OR `plan_checker_enabled` is false: skip to Step 9.
+  - Otherwise: continue to Step 7 (verification).
+
+  If no plans found:
+  - Error: "Planner reported complete but no PLAN.md files found."
+  - Offer: retry or abort.
+
+- **`## CHECKPOINT REACHED`:**
+  Present checkpoint to user, get response, spawn continuation agent with checkpoint context. If planner needs a decision, relay it to the user.
+
+- **`## PLANNING INCONCLUSIVE`:**
+  Display what was attempted. Offer:
+  ```
+  Planning inconclusive after {N} attempts.
+
+  1. Provide more context and retry
+  2. Try with different approach
+  3. Abort
+  ```
+  Handle user choice accordingly.
+
+## Step 7: Spawn Plan Checker
+
+Initialize iteration tracking: `iteration_count = 1`.
+
+Display:
+```
+Verifying plans...
+```
+
+Construct the checker prompt:
+
+```markdown
+<verification_context>
+**Phase:** {phase_number}
+**Phase Goal:** {goal from ROADMAP}
+
+<files_to_read>
+- {phase_dir}/*-PLAN.md (Plans to verify)
+- {roadmap_path} (Roadmap)
+- {requirements_path} (Requirements)
+- {context_path} (USER DECISIONS from discussion stage)
+- {research_path} (Technical Research)
+</files_to_read>
+
+**Phase requirement IDs (MUST ALL be covered):** {phase_req_ids}
+
+**Project instructions:** Read ./CLAUDE.md if exists -- verify plans honor project guidelines
+**Project skills:** Check .skills/ directory (if exists) -- verify plans account for project skill rules
+</verification_context>
+
+<expected_output>
+- ## VERIFICATION PASSED -- all checks pass
+- ## ISSUES FOUND -- structured issue list
+</expected_output>
+```
+
+Spawn the checker:
+
+```
+Task(
+  prompt="## Task: Verify plans achieve phase goal\n\n## Suggested Skills: verification-gates\n\n" + checker_prompt,
+  subagent_type="planner",
+  model="{checker_model}",
+  description="Verify Phase {phase_number} plans"
+)
+```
+
+## Step 8: Handle Checker Return and Revision Loop
+
+- **`## VERIFICATION PASSED`:**
+  Display confirmation:
+  ```
+  Plan verification passed.
+  ```
+  Continue to Step 9.
+
+- **`## ISSUES FOUND`:**
+  Display the issues found. Check iteration count.
+
+  **If iteration_count < 3:**
+
+  Display:
+  ```
+  Sending plans back for revision... (iteration {iteration_count}/3)
+  ```
+
+  Construct revision prompt:
+
+  ```markdown
+  <revision_context>
+  **Phase:** {phase_number}
+  **Mode:** revision
+
+  <files_to_read>
+  - {phase_dir}/*-PLAN.md (Existing plans)
+  - {context_path} (USER DECISIONS from discussion stage)
+  </files_to_read>
+
+  **Checker issues:** {structured_issues_from_checker}
+  </revision_context>
+
+  <instructions>
+  Make targeted updates to address checker issues.
+  Do NOT replan from scratch unless issues are fundamental.
+  Return what changed.
+  </instructions>
+  ```
+
+  Spawn planner for revision:
+
+  ```
+  Task(
+    prompt=revision_prompt,
+    subagent_type="planner",
+    model="{planner_model}",
+    description="Revise Phase {phase_number} plans"
+  )
+  ```
+
+  After planner returns: increment `iteration_count`, re-spawn checker (go back to Step 7).
+
+  **If iteration_count >= 3:**
+
+  Display:
+  ```
+  Max verification iterations reached. {N} issues remain:
+  {issue list}
+
+  1. Force proceed -- accept plans with known issues
+  2. Provide guidance -- give planner hints and retry
+  3. Abort -- stop planning
+  ```
+
+  Wait for user choice.
+
+  - If "Force proceed": Continue to Step 9.
+  - If "Provide guidance": Get user input, re-spawn planner with user guidance, reset iteration_count, go to Step 7.
+  - If "Abort": Exit workflow.
+
+## Step 9: Commit Plans
+
+If `commit_docs` is true:
+
+```bash
+node .claude/maxsim/bin/maxsim-tools.cjs commit "docs(${padded_phase}): create phase plan" --files "${phase_dir}"
+```
+
+## Step 10: Return to Orchestrator
+
+After plans are created and optionally verified, return control to the plan.md orchestrator. Do NOT show gate confirmation or next steps -- the orchestrator handles the final gate.
+
+Display a brief completion message:
+```
+Planning complete. {plan_count} plan(s) created in {phase_dir}.
+```
+
+</process>
+
+<success_criteria>
+- Planner and checker models resolved from config
+- Existing plans detected and handled (add/view/replan options)
+- Planner agent spawned with full context (STATE.md, ROADMAP.md, REQUIREMENTS.md, CONTEXT.md, RESEARCH.md)
+- PLAN.md files created and validated
+- Checker verification loop runs (max 3 iterations) unless --skip-verify
+- Revision loop sends issues back to planner for targeted fixes
+- Plan files committed if commit_docs is true
+- Control returned to orchestrator without showing gate or next steps
+</success_criteria>

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

@@ -0,0 +1,347 @@
+<purpose>
+Discussion stage sub-workflow for /maxsim:plan. Extracts implementation decisions that downstream agents (researcher, planner) need. Analyzes the phase to identify gray areas, lets the user choose what to discuss, then deep-dives each selected area until satisfied.
+
+This file is loaded by the plan.md orchestrator. It does NOT handle gate confirmations or stage routing -- the orchestrator handles that. This sub-workflow focuses ONLY on running the discussion and writing CONTEXT.md.
+
+You are a thinking partner, not an interviewer. The user is the visionary -- you are the builder. Your job is to capture decisions that will guide research and planning, not to figure out implementation yourself.
+</purpose>
+
+<required_reading>
+@./references/thinking-partner.md
+</required_reading>
+
+<downstream_awareness>
+**CONTEXT.md feeds into:**
+
+1. **researcher** -- Reads CONTEXT.md to know WHAT to research
+   - "User wants card-based layout" -> researcher investigates card component patterns
+   - "Infinite scroll decided" -> researcher looks into virtualization libraries
+
+2. **planner** -- Reads CONTEXT.md to know WHAT decisions are locked
+   - "Pull-to-refresh on mobile" -> planner includes that in task specs
+   - "Claude's Discretion: loading skeleton" -> planner can decide approach
+
+**Your job:** Capture decisions clearly enough that downstream agents can act on them without asking the user again.
+
+**Not your job:** Figure out HOW to implement. That's what research and planning do with the decisions you capture.
+</downstream_awareness>
+
+<philosophy>
+**User = founder/visionary. Claude = thinking partner and builder.**
+
+The user knows:
+- How they imagine it working
+- What it should look/feel like
+- What's essential vs nice-to-have
+- Specific behaviors or references they have in mind
+
+The user doesn't know (and shouldn't be asked):
+- Codebase patterns (researcher reads the code)
+- Technical risks (researcher identifies these)
+- Implementation approach (planner figures this out)
+- Success metrics (inferred from the work)
+
+Ask about vision and implementation choices. Capture decisions for downstream agents.
+
+**Thinking-partner behaviors (from thinking-partner.md):**
+- **Challenge vague answers** -- "Cards" could mean many things. Push for specifics.
+- **Surface unstated assumptions** -- "You're assuming mobile-first -- is that intentional?"
+- **Propose alternatives with trade-offs** -- Don't just accept first choice. Offer 2-3 options.
+- **Make consequences visible** -- "Infinite scroll means no shareable page positions."
+- **Disagree constructively** -- If an approach has risks, name them.
+- **Follow the thread** -- Build on what they just said. Don't jump topics.
+
+Apply these behaviors within each discussion area. The user should feel like they're thinking through decisions with a collaborator, not answering a survey.
+</philosophy>
+
+<scope_guardrail>
+**CRITICAL: No scope creep.**
+
+The phase boundary comes from ROADMAP.md and is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities.
+
+**Allowed (clarifying ambiguity):**
+- "How should posts be displayed?" (layout, density, info shown)
+- "What happens on empty state?" (within the feature)
+- "Pull to refresh or manual?" (behavior choice)
+
+**Not allowed (scope creep):**
+- "Should we also add comments?" (new capability)
+- "What about search/filtering?" (new capability)
+- "Maybe include bookmarking?" (new capability)
+
+**The heuristic:** Does this clarify how we implement what's already in the phase, or does it add a new capability that could be its own phase?
+
+**When user suggests scope creep:**
+```
+"[Feature X] would be a new capability -- that's its own phase.
+Want me to note it for the roadmap backlog?
+
+For now, let's focus on [phase domain]."
+```
+
+Capture the idea in a "Deferred Ideas" section. Don't lose it, don't act on it.
+</scope_guardrail>
+
+<gray_area_identification>
+Gray areas are **implementation decisions the user cares about** -- things that could go multiple ways and would change the result.
+
+**How to identify gray areas:**
+
+1. **Read the phase goal** from ROADMAP.md
+2. **Understand the domain** -- What kind of thing is being built?
+   - Something users SEE -> visual presentation, interactions, states matter
+   - Something users CALL -> interface contracts, responses, errors matter
+   - Something users RUN -> invocation, output, behavior modes matter
+   - Something users READ -> structure, tone, depth, flow matter
+   - Something being ORGANIZED -> criteria, grouping, handling exceptions matter
+3. **Generate phase-specific gray areas** -- Not generic categories, but concrete decisions for THIS phase
+
+**Don't use generic category labels** (UI, UX, Behavior). Generate specific gray areas:
+
+```
+Phase: "User authentication"
+-> Session handling, Error responses, Multi-device policy, Recovery flow
+
+Phase: "Organize photo library"
+-> Grouping criteria, Duplicate handling, Naming convention, Folder structure
+
+Phase: "CLI for database backups"
+-> Output format, Flag design, Progress reporting, Error recovery
+
+Phase: "API documentation"
+-> Structure/navigation, Code examples depth, Versioning approach, Interactive elements
+```
+
+**The key question:** What decisions would change the outcome that the user should weigh in on?
+
+**Claude handles these (don't ask):**
+- Technical implementation details
+- Architecture patterns
+- Performance optimization
+- Scope (roadmap defines this)
+</gray_area_identification>
+
+<process>
+
+## Step 1: Initialize
+
+Phase number, name, and directory come from the orchestrator context.
+
+```bash
+INIT=$(node .claude/maxsim/bin/maxsim-tools.cjs init phase-op "${PHASE}")
+```
+
+Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `plan_count`, `roadmap_exists`, `planning_exists`.
+
+**If `phase_found` is false:** Error -- the orchestrator should have caught this, but fail safe.
+
+## Step 2: Check Existing Context
+
+Check if CONTEXT.md already exists using `has_context` from init.
+
+```bash
+ls ${phase_dir}/*-CONTEXT.md 2>/dev/null
+```
+
+**If exists:**
+
+Ask the user (via natural conversation):
+```
+Phase {phase_number} already has context. What would you like to do?
+1. Update it -- review and revise existing context
+2. View it -- show me what's there
+3. Use as-is -- keep existing context and return to orchestrator
+```
+
+- If "Update": Load existing CONTEXT.md, continue to Step 3.
+- If "View": Display CONTEXT.md contents, then offer update/use-as-is.
+- If "Use as-is": Return control to orchestrator.
+
+**If doesn't exist:** Continue to Step 3.
+
+## Step 3: Analyze Phase
+
+Analyze the phase to identify gray areas worth discussing.
+
+**Read the phase description from ROADMAP.md and determine:**
+
+1. **Domain boundary** -- What capability is this phase delivering? State it clearly.
+
+2. **Gray areas by category** -- For each relevant category, identify 1-2 specific ambiguities that would change implementation.
+
+3. **Skip assessment** -- If no meaningful gray areas exist (pure infrastructure, clear-cut implementation), note this but still present options.
+
+**Output your analysis internally, then present to user.**
+
+## Step 4: Present Gray Areas
+
+Present the domain boundary and gray areas to the user.
+
+**State the boundary:**
+```
+Phase {phase_number}: {name}
+Domain: {what this phase delivers -- from your analysis}
+
+We'll clarify HOW to implement this.
+(New capabilities belong in other phases.)
+```
+
+**Then present gray areas for selection (via natural conversation):**
+```
+Which areas do you want to discuss for {phase_name}?
+
+1. {Specific area 1} -- {what decisions this covers}
+2. {Specific area 2} -- {what decisions this covers}
+3. {Specific area 3} -- {what decisions this covers}
+4. {Specific area 4} -- {what decisions this covers}
+
+Select by number (e.g., "1, 3" or "all").
+```
+
+Generate 3-4 **phase-specific** gray areas, not generic categories. Each should be a concrete decision area.
+
+## Step 5: Discuss Areas
+
+For each selected area, conduct a focused discussion loop.
+
+**Philosophy: 4 questions, then check.**
+
+Ask 4 questions per area before offering to continue or move on. Each answer often reveals the next question.
+
+**For each area:**
+
+1. **Announce the area:**
+   ```
+   Let's talk about {Area}.
+   ```
+
+2. **Ask 4 questions via natural conversation:**
+   - Specific decisions for this area
+   - Offer 2-3 concrete choices per question
+   - Include "You decide" as an option when reasonable -- captures Claude discretion
+
+3. **After 4 questions, check:**
+   ```
+   More questions about {area}, or move to next?
+   ```
+   - If "More" -> ask 4 more, then check again
+   - If "Next" -> proceed to next selected area
+
+4. **After all initially-selected areas complete:**
+   - Summarize what was captured from the discussion so far
+   ```
+   We've discussed {list areas}. Any remaining gray areas to explore, or ready to create context?
+
+   1. Explore more gray areas
+   2. Ready to create context
+   ```
+   - If "Explore more": Identify 2-4 additional gray areas, present for selection, loop.
+   - If "Ready": Proceed to Step 6.
+
+**Adaptive probing (thinking-partner mode):**
+
+Within each area, adapt your questioning based on the user's certainty level:
+- **User is confident** (picks options quickly) -- probe deeper: "You chose X -- have you considered how that interacts with Y?"
+- **User is uncertain** (hedges) -- propose alternatives: "Here are 3 approaches with trade-offs..."
+- **User defers** (picks "You decide") -- accept but name consequences: "I'll go with X because [reason]. That means Y."
+
+Challenge decisions that may have hidden costs. If the user picks something that conflicts with an earlier decision, surface it: "Earlier you said A, but this implies B. Which takes priority?"
+
+**Question design:**
+- Options should be concrete, not abstract ("Cards" not "Option A")
+- Each answer should inform the next question
+- If user gives free text, reflect it back and confirm
+
+**Scope creep handling:**
+If user mentions something outside the phase domain:
+```
+"[Feature] sounds like a new capability -- that belongs in its own phase.
+I'll note it as a deferred idea.
+
+Back to [current area]: [return to current question]"
+```
+
+Track deferred ideas internally.
+</process>
+
+## Step 6: Write Context
+
+Create CONTEXT.md capturing decisions made.
+
+**Find or create phase directory:**
+
+Use values from init: `phase_dir`, `phase_slug`, `padded_phase`.
+
+If `phase_dir` is null (phase exists in roadmap but no directory):
+```bash
+mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
+```
+
+**File location:** `${phase_dir}/${padded_phase}-CONTEXT.md`
+
+**Structure the content by what was discussed:**
+
+```markdown
+# Phase {X} Context: {Name}
+
+**Phase Goal:** {goal from ROADMAP.md}
+**Created:** {date}
+**Requirements:** {requirement IDs if any}
+
+## 1. {Category 1 that was discussed}
+
+### {Decision Area}
+- {Decision or preference captured}
+- {Another decision if applicable}
+
+### {Decision Area}
+- {Decision or preference captured}
+
+## 2. {Category 2 that was discussed}
+
+### {Decision Area}
+- {Decision or preference captured}
+
+## {N}. Claude's Discretion
+
+{Areas where user said "you decide" -- note that Claude has flexibility here}
+
+## Deferred Ideas (Captured for Future Phases)
+
+| Idea | Target |
+|------|--------|
+| {Deferred idea} | {suggested phase} |
+
+{If none: "None -- discussion stayed within phase scope"}
+
+---
+*Context created: {date}*
+*Decisions: {N} across {M} areas*
+```
+
+Write the file.
+
+**Commit context:**
+```bash
+node .claude/maxsim/bin/maxsim-tools.cjs commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+
+## Step 7: Return to Orchestrator
+
+After writing CONTEXT.md, return control to the plan.md orchestrator. Do NOT show gate confirmation or next steps -- the orchestrator handles the gate between Discussion and Research.
+
+Display a brief completion message:
+```
+Discussion complete. CONTEXT.md written to {path}.
+```
+
+<success_criteria>
+- Phase validated against roadmap
+- Gray areas identified through intelligent analysis (not generic questions)
+- User selected which areas to discuss
+- Each selected area explored until user satisfied
+- Scope creep redirected to deferred ideas
+- CONTEXT.md captures actual decisions, not vague vision
+- Deferred ideas preserved for future phases
+- Control returned to orchestrator without showing gate or next steps
+</success_criteria>