maxsimcli 4.15.3 → 4.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maxsimcli",
-  "version": "4.15.3",
+  "version": "4.16.0",
   "private": false,
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, Gemini and Codex by MayStudios.",
   "bin": {

package/dist/assets/templates/references/dashboard-bridge.md

@@ -1,59 +0,0 @@
-<dashboard_bridge>
-
-## Dashboard Mode Detection
-
-At the START of this workflow (before any user interaction), probe for the dashboard MCP server:
-
-Call `mcp__maxsim-dashboard__get_phase_status` (no parameters).
-
-- **Success** (returns JSON) → set `DASHBOARD_ACTIVE = true` for this workflow session
-- **Failure** (tool not found, connection error) → set `DASHBOARD_ACTIVE = false`
-
-Probe **once** per workflow. Do not re-probe. If the dashboard was not detected, use standard tools throughout.
-
-**Mid-workflow fallback:** If an MCP call fails after a successful probe (dashboard crashed), fall back to `AskUserQuestion` for that call and set `DASHBOARD_ACTIVE = false` for the remainder.
-
-## Question Routing
-
-**When `DASHBOARD_ACTIVE = true`:** Use `mcp__maxsim-dashboard__ask_question` for ALL user questions.
-
-**When `DASHBOARD_ACTIVE = false`:** Use `AskUserQuestion` as normal.
-
-### Schema Translation: AskUserQuestion → ask_question
-
-When routing to the dashboard MCP tool, translate fields as follows:
-
-**Merge header into question:**
-```
-AskUserQuestion: header="Context", question="Which areas need discussion?"
-→ ask_question:  question="**Context** — Which areas need discussion?"
-```
-
-**Convert options:**
-```
-AskUserQuestion: options=[{label: "Cards", description: "Grid layout"}]
-→ ask_question:  options=[{value: "cards", label: "Cards", description: "Grid layout"}]
-```
-
-Rules:
-1. Prepend `header` as bold prefix: `"**{header}** — {question}"`
-2. Option `value` = slugified `label` (lowercase, spaces→hyphens)
-3. Option `label` and `description` map directly
-4. Always set `allow_free_text: true` (equivalent to AskUserQuestion's implicit "Other")
-5. For `multiSelect`: prefix question with "Select all that apply:" and number each option. Parse the user's comma-separated response to determine selections.
-6. The MCP tool returns a plain string. Match it against option `label` or `value` to identify the selection. Non-matching text = free-text "Other" input.
-
-## Lifecycle Events
-
-Use `mcp__maxsim-dashboard__submit_lifecycle_event` to report workflow progress to the dashboard. Only emit when `DASHBOARD_ACTIVE = true`.
-
-| Event type | When to emit | Fields |
-|---|---|---|
-| `phase-started` | execute-phase: after init, before first wave | `phase_name`, `phase_number` |
-| `plan-started` | execute-phase: before spawning each plan executor | `phase_name`, `phase_number`, `step` (1-based plan index), `total_steps` |
-| `plan-complete` | execute-phase: after executor returns success | `phase_name`, `phase_number`, `step`, `total_steps` |
-| `phase-complete` | execute-phase: after roadmap update | `phase_name`, `phase_number` |
-
-**Fire-and-forget.** If the call fails, ignore and continue. Never gate workflow progress on lifecycle event delivery.
-
-</dashboard_bridge>

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

@@ -1,501 +0,0 @@
-<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:init` first.
-2. `.planning/ROADMAP.md` exists — if not, stop and tell the user to initialize the project.
-</sanity_check>
-
-<deprecation_notice>
-**DEPRECATED — Use plan.md + sub-workflows instead.**
-
-This file (plan-phase.md) is a legacy monolithic workflow that writes artifacts to local `.planning/phases/` directories. It has been superseded by the GitHub-first planning workflow:
-
-- **Canonical orchestrator:** `@./workflows/plan.md`
-- **Discussion stage:** `@./workflows/plan-discuss.md`
-- **Research stage:** `@./workflows/plan-research.md`
-- **Planning stage:** `@./workflows/plan-create.md`
-
-The canonical workflow stores all artifacts (context decisions, research findings, plans) as GitHub Issue comments instead of local files, and uses GitHub Issue state for stage detection and re-entry.
-
-**This file is retained for reference only.** Do not use it for new work. Any fixes or improvements should be made to the canonical sub-workflows above.
-</deprecation_notice>
-
-<purpose>
-[LEGACY] Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification. Default flow: Research (if needed) -> Plan -> Verify -> Done. Orchestrates researcher, planner, and planner (plan-checking mode) agents with a revision loop (max 3 iterations).
-
-NOTE: This workflow writes artifacts to local `.planning/phases/` directories. The current canonical workflow (plan.md + sub-workflows) stores artifacts on GitHub Issues instead.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-
-@./references/ui-brand.md
-@./references/dashboard-bridge.md
-</required_reading>
-
-<process>
-
-## 1. Initialize
-
-Load all context in one call (paths only to minimize orchestrator context):
-
-```bash
-INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init plan-phase "$PHASE")
-```
-
-Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `plan_count`, `planning_exists`, `roadmap_exists`, `phase_req_ids`.
-
-**File paths (for <files_to_read> blocks):** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `verification_path`, `uat_path`. These are null if files don't exist.
-
-**If `planning_exists` is false:** Error — run `/maxsim:init` first.
-
-## 2. Parse and Normalize Arguments
-
-Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`).
-
-**If no phase number:** Detect next unplanned phase from roadmap.
-
-**If `phase_found` is false:** Validate phase exists in ROADMAP.md. If valid, create the directory using `phase_slug` and `padded_phase` from init:
-```bash
-mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
-```
-
-**Existing artifacts from init:** `has_research`, `has_plans`, `plan_count`.
-
-## 3. Validate Phase
-
-```bash
-PHASE_INFO=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap get-phase "${PHASE}")
-```
-
-**If `found` is false:** Error with available phases. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
-
-## 4. Load CONTEXT.md
-
-Check `context_path` from init JSON.
-
-If `context_path` is not null, display: `Using phase context from: ${context_path}`
-
-**If `context_path` is null (no CONTEXT.md exists):**
-
-Use AskUserQuestion:
-- header: "No context"
-- question: "No CONTEXT.md found for Phase {X}. Plans will use research and requirements only — your design preferences won't be included. Continue or capture context first?"
-- options:
-  - "Continue without context" — Plan using research + requirements only
-  - "Run discuss-phase first" — Capture design decisions before planning
-
-If "Continue without context": Proceed to step 5.
-If "Run discuss-phase first": Display `/maxsim:plan {X}` (discussion stage) and exit workflow.
-
-## 5. Handle Research
-
-**Skip if:** `--gaps` flag, `--skip-research` flag, or `research_enabled` is false (from init) without `--research` override.
-
-**If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
-
-**If RESEARCH.md missing OR `--research` flag:**
-
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► RESEARCHING PHASE {X}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning researcher...
-```
-
-### Spawn researcher
-
-```bash
-PHASE_DESC=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap get-phase "${PHASE}" | jq -r '.section')
-```
-
-Research prompt:
-
-```markdown
-<objective>
-Research how to implement Phase {phase_number}: {phase_name}
-Answer: "What do I need to know to PLAN this phase well?"
-</objective>
-
-<files_to_read>
-- {context_path} (USER DECISIONS from /maxsim:plan discussion stage)
-- {requirements_path} (Project requirements)
-- {state_path} (Project decisions and history)
-</files_to_read>
-
-<additional_context>
-**Phase description:** {phase_description}
-**Phase requirement IDs (MUST address):** {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, research should account for project skill patterns
-</additional_context>
-
-<output>
-Write to: {phase_dir}/{phase_num}-RESEARCH.md
-</output>
-```
-
-```
-Task(
-  prompt=research_prompt,
-  subagent_type="researcher",
-  model="{researcher_model}",
-  description="Research Phase {phase}"
-)
-```
-
-### Handle Researcher Return
-
-- **`## RESEARCH COMPLETE`:** Display confirmation, continue to step 6
-- **`## RESEARCH BLOCKED`:** Display blocker, offer: 1) Provide context, 2) Skip research, 3) Abort
-
-## 5.5. Create Validation Strategy (if Nyquist enabled)
-
-**Skip if:** `workflow.nyquist_validation` is false in `.planning/config.json`.
-
-After researcher completes, check if RESEARCH.md contains a Validation Architecture section:
-
-```bash
-grep -l "## Validation Architecture" "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null
-```
-
-**If found:**
-1. Read validation template from `~/.claude/maxsim/templates/VALIDATION.md`
-2. Write to `${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md`
-3. Fill frontmatter: replace `{N}` with phase number, `{phase-slug}` with phase slug, `{date}` with current date
-4. If `commit_docs` is true:
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs commit-docs "docs(phase-${PHASE}): add validation strategy"
-```
-
-**If not found (and nyquist enabled):** Display warning:
-```
-⚠ Nyquist validation enabled but researcher did not produce a Validation Architecture section.
-  Continuing without validation strategy. Plans may fail Dimension 8 check.
-```
-
-## 6. Check Existing Plans
-
-```bash
-ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null
-```
-
-**If exists:** Offer: 1) Add more plans, 2) View existing, 3) Replan from scratch.
-
-## 7. Use Context Paths from INIT
-
-Extract from 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')
-VERIFICATION_PATH=$(echo "$INIT" | jq -r '.verification_path // empty')
-UAT_PATH=$(echo "$INIT" | jq -r '.uat_path // empty')
-CONTEXT_PATH=$(echo "$INIT" | jq -r '.context_path // empty')
-```
-
-## 8. Spawn planner Agent
-
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► PLANNING PHASE {X}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning planner...
-```
-
-Planner prompt:
-
-```markdown
-<planning_context>
-**Phase:** {phase_number}
-**Mode:** {standard | gap_closure}
-
-<files_to_read>
-- {state_path} (Project State)
-- {roadmap_path} (Roadmap)
-- {requirements_path} (Requirements)
-- {context_path} (USER DECISIONS from /maxsim:plan discussion stage)
-- {research_path} (Technical Research)
-- {verification_path} (Verification Gaps - if --gaps)
-- {uat_path} (UAT Gaps - if --gaps)
-</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>
-```
-
-```
-Task(
-  prompt=filled_prompt,
-  subagent_type="planner",
-  model="{planner_model}",
-  description="Plan Phase {phase}"
-)
-```
-
-## 9. Handle Planner Return
-
-- **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.
-- **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
-- **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
-
-## 10. Spawn planner Agent (Plan Verification Mode)
-
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► VERIFYING PLANS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning plan checker...
-```
-
-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 /maxsim:plan discussion stage)
-- {research_path} (Technical Research — includes Validation Architecture)
-</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>
-```
-
-```
-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} plans"
-)
-```
-
-## 11. Handle Checker Return
-
-- **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 13.
-- **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
-
-## 12. Revision Loop (Max 3 Iterations)
-
-Track `iteration_count` (starts at 1 after initial plan + check).
-
-**If iteration_count < 3:**
-
-Display: `Sending back to planner for revision... (iteration {N}/3)`
-
-Revision prompt:
-
-```markdown
-<revision_context>
-**Phase:** {phase_number}
-**Mode:** revision
-
-<files_to_read>
-- {PHASE_DIR}/*-PLAN.md (Existing plans)
-- {context_path} (USER DECISIONS from /maxsim:plan 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>
-```
-
-```
-Task(
-  prompt=revision_prompt,
-  subagent_type="planner",
-  model="{planner_model}",
-  description="Revise Phase {phase} plans"
-)
-```
-
-After planner returns -> spawn checker again (step 10), increment iteration_count.
-
-**If iteration_count >= 3:**
-
-Display: `Max iterations reached. {N} issues remain:` + issue list
-
-Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
-
-## 13. Present Final Status
-
-Route to `<offer_next>` OR `auto_advance` depending on flags/config.
-
-## 14. Auto-Advance Check
-
-Check for auto-advance trigger:
-
-1. Parse `--auto` flag from $ARGUMENTS
-2. Read `workflow.auto_advance` from config:
-   ```bash
-   AUTO_CFG=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
-   ```
-
-**If `--auto` flag present OR `AUTO_CFG` is true:**
-
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► AUTO-ADVANCING TO EXECUTE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Plans ready. Spawning execute-phase...
-```
-
-Spawn execute-phase as Task with direct workflow file reference (do NOT use Skill tool — Skills don't resolve inside Task subagents):
-```
-Task(
-  prompt="
-    <objective>
-    You are the execute-phase orchestrator. Execute all plans for Phase ${PHASE}: ${PHASE_NAME}.
-    </objective>
-
-    <execution_context>
-    @./workflows/execute-phase.md
-    @./references/checkpoints.md
-    @./references/tdd.md
-    @./references/model-profile-resolution.md
-    </execution_context>
-
-    <arguments>
-    PHASE=${PHASE}
-    ARGUMENTS='${PHASE} --auto --no-transition'
-    </arguments>
-
-    <instructions>
-    1. Read execute-phase.md from execution_context for your complete workflow
-    2. Follow ALL steps: initialize, handle_branching, validate_phase, discover_and_group_plans, execute_waves, aggregate_results, close_parent_artifacts, verify_phase_goal, update_roadmap
-    3. The --no-transition flag means: after verification + roadmap update, STOP and return status. Do NOT run transition.md.
-    4. When spawning executor agents, use subagent_type='executor' with the existing @file pattern from the workflow
-    5. When spawning verifier agents, use subagent_type='verifier'
-    6. Preserve the classifyHandoffIfNeeded workaround (spot-check on that specific error)
-    7. Do NOT use the Skill tool or /maxsim: commands
-    </instructions>
-  ",
-  subagent_type="general-purpose",
-  description="Execute Phase ${PHASE}"
-)
-```
-
-**Handle execute-phase return:**
-- **PHASE COMPLETE** → Display final summary:
-  ```
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   MAXSIM ► PHASE ${PHASE} COMPLETE ✓
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Auto-advance pipeline finished.
-
-  Next: /maxsim:plan ${NEXT_PHASE} --auto
-  ```
-- **GAPS FOUND / VERIFICATION FAILED** → Display result, stop chain:
-  ```
-  Auto-advance stopped: Execution needs review.
-
-  Review the output above and continue manually:
-  /maxsim:execute ${PHASE}
-  ```
-
-**If neither `--auto` nor config enabled:**
-Route to `<offer_next>` (existing behavior).
-
-</process>
-
-<offer_next>
-Output this markdown directly (not as a code block):
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► PHASE {X} PLANNED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Phase {X}: {Name}** — {N} plan(s) in {M} wave(s)
-
-| Wave | Plans | What it builds |
-|------|-------|----------------|
-| 1    | 01, 02 | [objectives] |
-| 2    | 03     | [objective]  |
-
-Research: {Completed | Used existing | Skipped}
-Verification: {Passed | Passed with override | Skipped}
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Execute Phase {X}** — run all {N} plans
-
-/maxsim:execute {X}
-
-<sub>/clear first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-
-**Also available:**
-- cat .planning/phases/{phase-dir}/*-PLAN.md — review plans
-- /maxsim:plan {X} --research — re-research first
-
-───────────────────────────────────────────────────────────────
-</offer_next>
-
-<success_criteria>
-- [ ] .planning/ directory validated
-- [ ] Phase validated against roadmap
-- [ ] Phase directory created if needed
-- [ ] CONTEXT.md loaded early (step 4) and passed to ALL agents
-- [ ] Research completed (unless --skip-research or --gaps or exists)
-- [ ] researcher spawned with CONTEXT.md
-- [ ] Existing plans checked
-- [ ] planner spawned with CONTEXT.md + RESEARCH.md
-- [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled)
-- [ ] planner (plan-check mode) spawned with CONTEXT.md
-- [ ] Verification passed OR user override OR max iterations with user decision
-- [ ] User sees status between agent spawns
-- [ ] User knows next steps
-</success_criteria>