maxsimcli 4.15.4 → 4.16.0

package/dist/assets/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [4.15.4](https://github.com/maystudios/maxsimcli/compare/v4.15.3...v4.15.4) (2026-03-12)
+
+
+### Bug Fixes
+
+* remove stale references to dashboard, plan-phase, milestones shims and enhance statusline ([b895bf2](https://github.com/maystudios/maxsimcli/commit/b895bf22228117e93ad36cfb358777a4591109ed))
+
 ## [4.15.3](https://github.com/maystudios/maxsimcli/compare/v4.15.2...v4.15.3) (2026-03-11)
 
 

package/dist/assets/templates/agents/AGENTS.md

@@ -7,7 +7,7 @@
 | Agent | Role | Tools | Preloaded Skills | On-Demand Skills |
 |-------|------|-------|-----------------|-----------------|
 | `executor` | Implements plans with atomic commits and deviation handling | Read, Write, Edit, Bash, Grep, Glob | handoff-contract, evidence-collection, commit-conventions | tool-priority-guide, agent-system-map |
-| `planner` | Creates PLAN.md files with task breakdown and goal-backward verification | Read, Write, Bash, Grep, Glob | handoff-contract, input-validation | research-methodology, agent-system-map |
+| `planner` | Creates plans (posted as GitHub Issue comments) with task breakdown and goal-backward verification | Read, Write, Bash, Grep, Glob | handoff-contract, input-validation | research-methodology, agent-system-map |
 | `researcher` | Investigates domains with source evaluation and confidence levels | Read, Bash, Grep, Glob, WebFetch | handoff-contract, evidence-collection | research-methodology, tool-priority-guide |
 | `verifier` | Verifies work against specifications with fresh evidence and hard gates | Read, Bash, Grep, Glob | verification-gates, evidence-collection, handoff-contract | agent-system-map, tool-priority-guide |
 

package/dist/assets/templates/agents/executor.md

@@ -19,7 +19,7 @@ You are a plan executor. You implement plans atomically -- one commit per task,
 ## Input Validation
 
 Before any work, verify required inputs exist:
-- Plan content (provided by the orchestrator from a GitHub Issue comment, or as a PLAN.md file path)
+- Plan content (provided by the orchestrator from a GitHub Issue comment)
 - STATE.md readable -- `test -f .planning/STATE.md`
 
 If missing, return immediately:

package/dist/assets/templates/agents/planner.md

@@ -2,8 +2,8 @@
 name: planner
 description: >-
   Creates executable phase plans with task breakdown, dependency analysis,
-  and goal-backward verification. Use when planning phases, creating PLAN.md
-  files, breaking work into tasks, or performing gap closure planning.
+  and goal-backward verification. Use when planning phases, creating plans
+  (posted as GitHub Issue comments), breaking work into tasks, or performing gap closure planning.
 tools: Read, Write, Bash, Grep, Glob
 model: inherit
 skills:
@@ -24,13 +24,13 @@ Context and research input is provided from GitHub Issue comments (type: `contex
 Before any work, verify required inputs exist:
 - ROADMAP.md -- `test -f .planning/ROADMAP.md`
 - REQUIREMENTS.md -- `test -f .planning/REQUIREMENTS.md`
-- Phase directory -- `test -d .planning/phases/{phase}/` (if running in local mode) or context provided in spawn prompt (if running in GitHub mode)
+- Phase context provided in spawn prompt (GitHub Issues is the source of truth)
 
 If missing, return immediately using the input-validation error format.
 
 ## Planning Protocol
 
-1. **Load context** -- read ROADMAP.md, REQUIREMENTS.md, and context/research provided from GitHub Issue comments (or local CONTEXT.md, RESEARCH.md if in local mode)
+1. **Load context** -- read ROADMAP.md, REQUIREMENTS.md, and context/research provided from GitHub Issue comments
 2. **Identify scope** -- extract phase goal, requirements, and user decisions from context
 3. **Break into tasks** -- each task is an atomic unit with clear action, done criteria, verify block, and file list
 4. **Build dependency graph** -- identify which tasks depend on others

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

@@ -109,17 +109,12 @@ When `phase_issue_number` is set (GitHub integration active):
 
 **Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip non-gap_closure plans. If all filtered: "No matching incomplete plans" → exit.
 
-**Fallback -- no GitHub integration:**
+**If GitHub integration is NOT active** (`phase_issue_number` is not set):
 
-When `phase_issue_number` is not set, use local file scanning:
-
-```bash
-PLAN_INDEX=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs phase-plan-index "${PHASE_NUMBER}")
+GitHub Issues is the source of truth for plans. Report the error and exit:
+```
+GitHub integration required. Ensure GitHub Issues is configured: run /maxsim:init to set up.
 ```
-
-Parse JSON for: `phase`, `plans[]` (each with `id`, `wave`, `autonomous`, `objective`, `files_modified`, `task_count`, `has_summary`), `waves` (map of wave number → plan IDs), `incomplete`, `has_checkpoints`.
-
-**Skip plans where `has_summary: true`** (local SUMMARY.md file present). If `--gaps-only`: also skip non-gap_closure plans.
 
 Report:
 ```
@@ -307,7 +302,7 @@ For each wave:
 
 1. **Describe what's being built (BEFORE spawning):**
 
-   Read each plan's `<objective>` from the plan comment content (or local PLAN.md in fallback). Extract what's being built and why.
+   Read each plan's `<objective>` from the plan comment content. Extract what's being built and why.
 
    ```
    ---
@@ -550,12 +545,6 @@ When GitHub integration is active, look for `<!-- maxsim:type=uat -->` comments
 mcp_get_issue_detail(issue_number: parent_phase_issue_number)
 ```
 
-As fallback, check local files:
-```bash
-PARENT_INFO=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs find-phase "${PARENT_PHASE}" --raw)
-# Extract directory from PARENT_INFO JSON, then find UAT file in that directory
-```
-
 **If no parent UAT found:** Skip this step (gap-closure may have been triggered by VERIFICATION.md instead).
 
 **3. Update UAT gap statuses:**
@@ -612,11 +601,6 @@ mcp_get_issue_detail(issue_number: phase_issue_number)
 
 Look for `<!-- maxsim:type=verification -->` comment and parse `status:` field.
 
-Fallback:
-```bash
-grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
-```
-
 | Status | Action |
 |--------|--------|
 | `passed` | → update_roadmap |
@@ -758,7 +742,7 @@ Plan content passed directly from GitHub comments to subagents — no local PLAN
 - **Dependency chain breaks:** Wave 1 fails → Wave 2 dependents likely fail → user chooses attempt or skip
 - **All agents in wave fail:** Systemic issue → stop, report for investigation
 - **Checkpoint unresolvable:** "Skip this plan?" or "Abort phase execution?" → record partial progress in STATE.md
-- **GitHub integration unavailable:** Fall back to local file I/O for all plan reading and summary writing
+- **GitHub integration unavailable:** Report error — GitHub Issues is the source of truth for plans and summaries
 </failure_handling>
 
 <resumption>

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

@@ -51,25 +51,13 @@ mcp_detect_external_edits(issue_number: phase_issue_number)
 
 If external edits detected: warn user and offer to re-read the plan before proceeding.
 
-**Fallback -- no GitHub context:**
+**If no GitHub context is available:**
 
-If no `phase_issue_number` or `plan_comment_body` was passed:
+GitHub Issues is the source of truth for plans. If no `phase_issue_number` or `plan_comment_body` was passed, report the error and exit:
 
-```bash
-# Use plans/summaries from INIT JSON, or list files
-ls .planning/phases/XX-name/*-PLAN.md 2>/dev/null | sort
-ls .planning/phases/XX-name/*-SUMMARY.md 2>/dev/null | sort
 ```
-
-Find first PLAN without matching SUMMARY. Decimal phases supported (`01.1-hotfix/`).
-
-<if mode="yolo">
-Auto-approve: `⚡ Execute {phase}-{plan}-PLAN.md [Plan X of Y for Phase Z]` → parse_segments.
-</if>
-
-<if mode="interactive" OR="custom with gates.execute_next_plan true">
-Present plan identification, wait for confirmation.
-</if>
+Plan content must be provided via GitHub Issue comment. Ensure GitHub integration is configured.
+```
 </step>
 
 <step name="record_start_time">
@@ -144,12 +132,7 @@ Pattern B only (verify-only checkpoints). Skip for A/C.
 
 The plan content IS the execution instructions. Follow exactly. If plan references CONTEXT.md: honor user's vision throughout.
 
-When plan was loaded from a GitHub comment (github_context passed): the plan content is already in memory from the load_plan_from_github step.
-
-When plan is loaded from a local file (fallback):
-```bash
-cat .planning/phases/XX-name/{phase}-{plan}-PLAN.md
-```
+The plan content is already in memory from the load_plan_from_github step (loaded from the GitHub Issue comment passed by the orchestrator).
 </step>
 
 <step name="pre_execution_gates">
@@ -193,7 +176,7 @@ fi
 node ~/.claude/maxsim/bin/maxsim-tools.cjs phases list --type summaries --raw
 # Extract the second-to-last summary from the JSON result
 ```
-If previous phase has unresolved issues (check summary comments on phase issue or local SUMMARY.md "Issues Encountered" / "Next Phase Readiness" blockers): AskUserQuestion(header="Previous Issues", options: "Proceed anyway" | "Address first" | "Review previous").
+If previous phase has unresolved issues (check summary comments on phase issue for "Issues Encountered" / "Next Phase Readiness" blockers): AskUserQuestion(header="Previous Issues", options: "Proceed anyway" | "Address first" | "Review previous").
 </step>
 
 <step name="execute">
@@ -449,7 +432,7 @@ mcp_post_comment(
 
 Record the comment URL/ID as `SUMMARY_COMMENT_ID` for future reference.
 
-**Fallback (no GitHub integration):** Write `{phase}-{plan}-SUMMARY.md` to `.planning/phases/XX-name/` as before.
+GitHub Issues is the source of truth -- summaries are always posted as GitHub comments.
 </step>
 
 <step name="review_cycle">
@@ -1038,7 +1021,7 @@ mcp_post_comment(
 )
 ```
 
-**Fallback (no GitHub integration):** Write VERIFICATION.md and UAT.md to the phase directory as before.
+GitHub Issues is the source of truth -- verification and UAT results are always posted as GitHub comments.
 </step>
 
 <step name="update_codebase_map">
@@ -1066,12 +1049,6 @@ mcp_list_sub_issues(issue_number: phase_issue_number)
 
 Count open vs closed sub-issues. Map closed count to plans complete.
 
-Fallback (no GitHub):
-```bash
-ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l
-ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
-```
-
 | Condition | Route | Action |
 |-----------|-------|--------|
 | open task sub-issues remain | **A: More plans** | Find next incomplete plan (by open sub-issues or missing summary comment). Yolo: auto-continue. Interactive: show next plan, suggest `/maxsim:execute {phase}`. STOP here. |

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

@@ -87,10 +87,13 @@ When GitHub integration is active (`phase_issue_number` is set):
    - `plan_count`: total plan comments found
    - `incomplete_count`: count of incomplete plans
 
-When GitHub integration is NOT active (no `phase_issue_number`), fall back to local file scanning:
-```bash
-PLAN_INDEX=$(node .claude/maxsim/bin/maxsim-tools.cjs phase-plan-index "${PHASE_NUMBER}")
+When GitHub integration is NOT active (no `phase_issue_number`):
+```
+No plans found for Phase {phase_number}. GitHub Issues is the source of truth for plans.
+
+Ensure GitHub integration is configured: run /maxsim:init to set up GitHub Issues.
 ```
+Exit workflow.
 
 ### 2b. Check for External Edits (WIRE-06)
 
@@ -332,11 +335,6 @@ mcp_get_issue_detail(issue_number: phase_issue_number)
 
 Look for the `<!-- maxsim:type=verification -->` comment and parse the `status:` field from its body.
 
-Also fall back to reading locally:
-```bash
-grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
-```
-
 **If `passed`:** Show verification gate and proceed to completion.
 
 ```
@@ -510,7 +508,7 @@ Display final results:
 
 <success_criteria>
 - [ ] Phase validated against roadmap
-- [ ] Plan inventory loaded from GitHub issue comments (falling back to local files if no GitHub integration)
+- [ ] Plan inventory loaded from GitHub issue comments (GitHub Issues is the source of truth)
 - [ ] External edit detection warns user if phase issue was modified externally
 - [ ] Current state correctly detected from task sub-issue closure and summary comments
 - [ ] Re-entry flow works for already-executed phases

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

@@ -160,7 +160,7 @@ Rule 5: Phase "To Do" on GitHub board (not yet started)?
   -> Action: /maxsim:plan {N}
   -> Reasoning: "Phase {N} ({name}) needs planning."
 
-  Sub-check: Does local CONTEXT.md exist?
+  Sub-check: Does a context comment exist on the phase GitHub Issue?
   -> If yes: "Discussion complete, ready for research + planning."
   -> If no: "Starting from discussion stage."
 
@@ -233,7 +233,7 @@ Or describe what you'd like to do:
 - If no phases exist on board: show `/maxsim:plan` prominently
 - Always include `/maxsim:quick` as it is always relevant
 - Always include an open-ended fallback ("Or describe what you'd like to do")
-- If GitHub not available (mcp calls fail): fall back to local ROADMAP analysis and note degraded mode
+- If GitHub not available (mcp calls fail): note degraded mode, recommend resolving GitHub connectivity
 
 Wait for user selection, then dispatch the chosen command.
 </step>

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

@@ -85,10 +85,9 @@ Call `mcp_query_board` with the project number (from init context / config). Gro
 | Done        | 3     | #9, #10, #11 |
 ```
 
-**Cross-validate with local ROADMAP.md:**
-- Run `ROADMAP=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap analyze)` to get local phase data
-- Compare local completion status against GitHub board status
-- Highlight any discrepancies between local and GitHub state in the Issues Detected section
+**Cross-reference with local ROADMAP.md (for phase ordering only -- GitHub is authoritative for status):**
+- Run `ROADMAP=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap analyze)` to get local phase ordering data
+- If local ROADMAP phase list differs from GitHub Issues, note in Issues Detected section (GitHub is the source of truth)
 </step>
 
 <step name="live_github_detail">
@@ -217,9 +216,9 @@ Identify the in-progress or interrupted phase (from `mcp_get_all_progress` or `m
 
 **Route B: Phase needs planning**
 
-Check if `{phase_num}-CONTEXT.md` exists in phase directory.
+Check if a `<!-- maxsim:type=context -->` comment exists on the phase GitHub Issue.
 
-**If CONTEXT.md exists:**
+**If context comment exists:**
 
 ```
 ---
@@ -236,7 +235,7 @@ Check if `{phase_num}-CONTEXT.md` exists in phase directory.
 ---
 ```
 
-**If CONTEXT.md does NOT exist:**
+**If no context comment exists:**
 
 ```
 ---
@@ -244,7 +243,7 @@ Check if `{phase_num}-CONTEXT.md` exists in phase directory.
 ## ▶ Next Up
 
 **Phase {N}: {Name}** — {Goal from ROADMAP.md}
-<sub>No context yet — /maxsim:plan will start with discussion</sub>
+<sub>No context comment yet — /maxsim:plan will start with discussion</sub>
 
 `/maxsim:plan {phase}`
 
@@ -335,8 +334,8 @@ Ready to plan the next milestone.
 - All work complete → offer milestone completion via `/maxsim:init`
 - Blockers present → highlight before offering to continue
 - External edits detected → surface in Issues Detected section before routing
-- Discrepancy between local ROADMAP and GitHub board → surface in Issues Detected, ask user to reconcile
-- GitHub not available (mcp calls fail) → fall back to local ROADMAP analysis and note degraded mode
+- Discrepancy between local ROADMAP and GitHub board → surface in Issues Detected (GitHub is authoritative)
+- GitHub not available (mcp calls fail) → note degraded mode, recommend resolving GitHub connectivity
   </step>
 
 </process>
@@ -348,7 +347,7 @@ Ready to plan the next milestone.
 - [ ] Board column view shown via mcp_query_board
 - [ ] Per-phase task detail available via mcp_get_phase_progress and mcp_list_sub_issues
 - [ ] External edit detection via mcp_detect_external_edits
-- [ ] Cross-validation between local ROADMAP.md and GitHub board status
+- [ ] Cross-reference local ROADMAP.md for phase ordering (GitHub is authoritative for status)
 - [ ] Phase gaps and discrepancies detected and surfaced in Issues Detected section
 - [ ] Current position clear with visual progress
 - [ ] What's next clearly explained

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

@@ -32,15 +32,16 @@ Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `phase_found`
 </step>
 
 <step name="discover_plans">
-Find incomplete plans — skip any plan that already has a matching SUMMARY.md:
+Find incomplete plans by querying GitHub Issues (the source of truth for plans and completion status):
 
-```bash
-PLAN_INDEX=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs phase-plan-index "${PHASE_NUMBER}")
+```
+mcp_get_issue_detail(issue_number: phase_issue_number)
+mcp_list_sub_issues(issue_number: phase_issue_number)
 ```
 
-Parse JSON for: `plans[]` (each with `id`, `objective`, `files_modified`, `task_count`, `has_summary`), `incomplete`.
+Parse plan comments (`<!-- maxsim:type=plan -->`) from the phase issue. A plan is complete when all its task sub-issues are closed.
 
-**Filtering:** Skip plans where `has_summary: true`. If all plans complete: "All plans in phase already have summaries" — exit.
+**Filtering:** Skip plans where all task sub-issues are closed. If all plans complete: "All plans in phase are already complete" — exit.
 
 Report:
 ```
@@ -58,11 +59,7 @@ Report:
 </step>
 
 <step name="load_plan">
-For each incomplete plan, read the plan file and extract the ordered task list:
-
-```bash
-cat ${PHASE_DIR}/${PLAN_FILE}
-```
+For each incomplete plan, read the plan content from the GitHub Issue comment (loaded in discover_plans) and extract the ordered task list.
 
 Extract for each task:
 - **Task number** (sequential order in plan)
@@ -325,14 +322,7 @@ Display task completion:
 </step>
 
 <step name="create_summary">
-After all tasks in a plan complete, create SUMMARY.md:
-
-```bash
-# Get the summary template
-cat ~/.claude/maxsim/templates/summary.md
-```
-
-Create `{phase}-{plan}-SUMMARY.md` in the phase directory. Include:
+After all tasks in a plan complete, build the summary content in memory and post it as a GitHub comment on the phase issue. Include:
 
 **Frontmatter:** phase, plan, subsystem, tags, requires/provides/affects, tech-stack, key-files.created/modified, key-decisions, requirements-completed (copy from PLAN.md frontmatter), duration, completed date.
 
@@ -356,12 +346,19 @@ Create `{phase}-{plan}-SUMMARY.md` in the phase directory. Include:
 - Deviations (if any)
 - Issues encountered
 
-Use `node ~/.claude/maxsim/bin/maxsim-tools.cjs` for template operations as needed.
+Post summary to GitHub:
+```
+mcp_post_comment(
+  issue_number: phase_issue_number,
+  type: "summary",
+  body: {summary_content}
+)
+```
 
 Self-check:
 - Verify first 2 files from `key-files.created` exist on disk
 - Check `git log --oneline --all --grep="{phase}-{plan}"` returns commits
-- Append `## Self-Check: PASSED` or `## Self-Check: FAILED`
+- Append `## Self-Check: PASSED` or `## Self-Check: FAILED` to summary content before posting
 </step>
 
 <step name="update_state">
@@ -396,23 +393,27 @@ node ~/.claude/maxsim/bin/maxsim-tools.cjs requirements mark-complete ${REQ_IDS}
 Task code already committed per-task. Commit planning artifacts:
 
 ```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs({phase}-{plan}): complete SDD execution" --files .planning/phases/${PHASE_DIR_NAME}/${PHASE}-${PLAN}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
+node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs({phase}-{plan}): complete SDD execution" --files .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
 ```
+
+Note: No local SUMMARY.md is committed -- summary was posted to GitHub as a comment.
 </step>
 
 <step name="offer_next">
 After all plans in the phase are processed:
 
-```bash
-ls -1 .planning/phases/${PHASE_DIR_NAME}/*-PLAN.md 2>/dev/null | wc -l
-ls -1 .planning/phases/${PHASE_DIR_NAME}/*-SUMMARY.md 2>/dev/null | wc -l
+Check completion by querying the phase issue's task sub-issues:
 ```
+mcp_list_sub_issues(issue_number: phase_issue_number)
+```
+
+Count open vs closed sub-issues to determine completion.
 
 | Condition | Route | Action |
 |-----------|-------|--------|
-| summaries < plans | **A: More plans** | Find next incomplete plan. Show next plan, suggest `/maxsim:execute {phase}` (SDD mode) to continue. |
-| summaries = plans, more phases exist | **B: Phase done** | Show completion, suggest `/maxsim:execute {phase}` (verification) then `/maxsim:plan {next}`. |
-| summaries = plans, last phase | **C: Milestone done** | Show banner, suggest `/maxsim:progress` (milestone completion) + `/maxsim:execute` (verification). |
+| open sub-issues remain | **A: More plans** | Find next incomplete plan (by open sub-issues). Show next plan, suggest `/maxsim:execute {phase}` (SDD mode) to continue. |
+| all sub-issues closed, more phases exist | **B: Phase done** | Show completion, suggest `/maxsim:execute {phase}` (verification) then `/maxsim:plan {next}`. |
+| all sub-issues closed, last phase | **C: Milestone done** | Show banner, suggest `/maxsim:progress` (milestone completion) + `/maxsim:execute` (verification). |
 
 All routes: recommend `/clear` first for fresh context.
 </step>
@@ -428,5 +429,5 @@ All routes: recommend `/clear` first for fresh context.
 </failure_handling>
 
 <resumption>
-Re-run `/maxsim:execute {phase}` (SDD mode) — discover_plans finds completed SUMMARYs, skips them, resumes from first incomplete plan. Within a plan, completed tasks (those with commits matching the plan pattern) can be detected and skipped.
+Re-run `/maxsim:execute {phase}` (SDD mode) — discover_plans queries GitHub for task sub-issue status, skips plans with all sub-issues closed, resumes from first incomplete plan. Within a plan, completed tasks (those with commits matching the plan pattern) can be detected and skipped.
 </resumption>