maxsimcli 4.12.0 → 4.14.0

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

@@ -25,7 +25,7 @@ INIT=$(node .claude/maxsim/bin/maxsim-tools.cjs init execute-phase "$PHASE")
 
 Parse `$ARGUMENTS` for: phase number (required), `--worktrees` (force worktree mode), `--no-worktrees` (force standard mode), `--auto` (auto-advance), `--gaps-only` (gap plans only).
 
-Parse JSON for: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `has_verification`, `commit_docs`, `executor_model`, `verifier_model`, `parallelization`, `state_path`, `roadmap_path`, `requirements_path`, `phase_req_ids`.
+Parse JSON for: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `has_verification`, `commit_docs`, `executor_model`, `verifier_model`, `parallelization`, `state_path`, `roadmap_path`, `requirements_path`, `phase_req_ids`, `phase_issue_number`, `task_mappings`.
 
 All flags from `$ARGUMENTS` are passed through to the execute-phase workflow steps so they are available for execution mode decision and auto-advance detection.
 
@@ -37,7 +37,16 @@ Use /maxsim:progress to see available phases.
 ```
 Exit workflow.
 
-**If `plan_count` is 0:**
+**If `plan_count` is 0 (GitHub check):**
+
+When GitHub integration is active (phase_issue_number is set), check for plan comments on the phase issue before reporting no plans:
+
+```
+mcp_get_issue_detail(issue_number: phase_issue_number)
+```
+
+Parse the response to find comments with `<!-- maxsim:type=plan -->` markers or `## Plan NN` headings. If no plan comments are found:
+
 ```
 No plans found for Phase {phase_number}.
 
@@ -47,6 +56,58 @@ Exit workflow.
 
 ## 2. Detect State
 
+### 2a. Load Plan Inventory from GitHub
+
+When GitHub integration is active (`phase_issue_number` is set):
+
+1. Fetch the phase issue and its comments:
+   ```
+   mcp_get_issue_detail(issue_number: phase_issue_number)
+   ```
+
+2. Parse issue comments to identify plan comments. A plan comment is one that contains either:
+   - A `<!-- maxsim:type=plan -->` HTML comment marker, OR
+   - A heading matching `## Plan NN` (where NN is a number)
+
+3. For each plan comment found:
+   - Extract the plan number (from the `## Plan NN` heading or frontmatter)
+   - Parse YAML frontmatter from the comment body for: `wave`, `dependencies`, `autonomous`, `objective`, `gap_closure`
+   - Store plan content in memory as `PLAN_COMMENTS[]`
+
+4. Check completion status for each plan by calling:
+   ```
+   mcp_list_sub_issues(issue_number: phase_issue_number)
+   ```
+   A plan is considered complete when ALL of its task sub-issues are closed (state: closed).
+   Additionally, check for `<!-- maxsim:type=summary -->` comments on the phase issue as a secondary completion signal.
+
+5. Build `plan_inventory` from GitHub data:
+   - `plans[]`: each with `id`, `wave`, `autonomous`, `objective`, `has_summary` (derived from sub-issue closure)
+   - `incomplete_plans[]`: plans where not all task sub-issues are closed
+   - `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}")
+```
+
+### 2b. Check for External Edits (WIRE-06)
+
+If phase_issue_number is set, optionally detect whether the phase issue was externally modified since last read:
+
+```
+mcp_detect_external_edits(issue_number: phase_issue_number)
+```
+
+If external edits are detected: warn the user before proceeding.
+```
+⚠️  Phase issue #{phase_issue_number} was modified externally since last check.
+Review the changes before continuing? (yes/no)
+```
+
+### 2c. Determine Execution State
+
 Determine where to start based on phase artifacts:
 
 | Condition | State | Action |
@@ -72,20 +133,20 @@ Display:
 
 **Plans:** {plan_count} plan(s) -- all complete
 **Verification:** Passed
-**Phase directory:** {phase_dir}
+**Phase issue:** #{phase_issue_number} (if GitHub active)
 
 **Options:**
-1. View results -- show SUMMARY.md files and verification report
-2. Re-execute from scratch -- delete SUMMARYs, restart execution
-3. View verification -- show VERIFICATION.md
+1. View results -- show plan summaries from GitHub comments
+2. Re-execute from scratch -- reopen task sub-issues and restart execution
+3. View verification -- show verification comment on phase issue
 4. Done (exit)
 ```
 
 Wait for user choice via natural conversation.
 
-- **View results:** Display contents of each SUMMARY.md file, then re-show options.
-- **Re-execute:** Delete existing SUMMARY.md files, restart from Execute Plans (step 4).
-- **View verification:** Display VERIFICATION.md contents, then re-show options.
+- **View results:** Fetch and display summary comments (`<!-- maxsim:type=summary -->`) from the phase issue, then re-show options.
+- **Re-execute:** Reopen task sub-issues via `mcp_reopen_issue` for each task sub-issue, restart from Execute Plans (step 4).
+- **View verification:** Fetch and display the verification comment (`<!-- maxsim:type=verification -->`) from the phase issue, then re-show options.
 - **Done:** Exit workflow.
 
 ## 4. Execute Plans
@@ -94,13 +155,7 @@ Execute all plans in wave order, delegating each plan to a subagent via execute-
 
 ### 4.1 Discover and Group Plans
 
-Load plan inventory with wave grouping:
-
-```bash
-PLAN_INDEX=$(node .claude/maxsim/bin/maxsim-tools.cjs phase-plan-index "${PHASE_NUMBER}")
-```
-
-Parse JSON for: `plans[]` (each with `id`, `wave`, `autonomous`, `objective`, `has_summary`), `waves` (map of wave number to plan IDs), `incomplete`.
+Use the plan inventory built in step 2 (from GitHub comments or local files).
 
 Skip plans where `has_summary: true` (already complete -- supports resume).
 
@@ -141,7 +196,7 @@ Execute each wave in sequence. Within a wave: parallel if `parallelization` is t
 
 2. **Spawn executor agents:**
 
-   Pass paths only -- executors read files themselves with their fresh 200k context.
+   Pass plan content and GitHub context -- executors read the plan from GitHub comment content passed in the prompt.
 
    ```
    Task(
@@ -150,7 +205,8 @@ Execute each wave in sequence. Within a wave: parallel if `parallelization` is t
      prompt="
        <objective>
        Execute plan {plan_number} of phase {phase_number}-{phase_name}.
-       Commit each task atomically. Create SUMMARY.md. Update STATE.md and ROADMAP.md.
+       Commit each task atomically. Post SUMMARY as GitHub comment. Update STATE.md and ROADMAP.md.
+       Move task sub-issues on the board as you work (In Progress → Done per task).
        </objective>
 
        <execution_context>
@@ -160,9 +216,14 @@ Execute each wave in sequence. Within a wave: parallel if `parallelization` is t
        @./references/tdd.md
        </execution_context>
 
+       <github_context>
+       Phase issue number: {phase_issue_number}
+       Plan comment: {plan_comment_body}
+       Task mappings: {task_mappings_for_this_plan}
+       </github_context>
+
        <files_to_read>
        Read these files at execution start using the Read tool:
-       - {phase_dir}/{plan_file} (Plan)
        - .planning/STATE.md (State)
        - .planning/config.json (Config, if exists)
        - ./CLAUDE.md (Project instructions, if exists)
@@ -171,7 +232,8 @@ Execute each wave in sequence. Within a wave: parallel if `parallelization` is t
        <success_criteria>
        - [ ] All tasks executed
        - [ ] Each task committed individually
-       - [ ] SUMMARY.md created in plan directory
+       - [ ] Summary posted as GitHub comment (mcp_post_comment with type=summary) on phase issue
+       - [ ] Task sub-issues moved: In Progress when started, Done when completed
        - [ ] STATE.md updated with position and decisions
        - [ ] ROADMAP.md updated with plan progress
        </success_criteria>
@@ -183,11 +245,12 @@ Execute each wave in sequence. Within a wave: parallel if `parallelization` is t
 
 4. **Spot-check results:**
 
-   For each completed plan's SUMMARY.md:
-   - Verify first 2 files from key-files exist on disk
+   For each completed plan:
+   - Check that a `<!-- maxsim:type=summary -->` comment exists on the phase issue for this plan
    - Check `git log --oneline --all --grep="{phase}-{plan}"` returns at least 1 commit
-   - Check for `## Self-Check: FAILED` marker
-   - Check for `## Review Cycle` section -- verify both Spec and Code stages show PASS
+   - Verify task sub-issues for this plan are all closed
+   - Check for `## Self-Check: FAILED` in the summary comment body
+   - Check for `## Review Cycle` section in summary -- verify both Spec and Code stages show PASS
 
    If ANY spot-check fails: report which plan failed, ask "Retry plan?" or "Continue with remaining waves?"
 
@@ -198,7 +261,7 @@ Execute each wave in sequence. Within a wave: parallel if `parallelization` is t
    ## Wave {N} Complete
 
    **{Plan ID}: {Plan Name}**
-   {What was built -- from SUMMARY.md}
+   {What was built -- from summary comment}
    {Notable deviations, if any}
 
    {If more waves: what this enables for next wave}
@@ -218,7 +281,7 @@ After all waves complete:
 
 **Plans executed:** {completed}/{total}
 **Waves:** {wave_count}
-**Commits:** {list of commit summaries from SUMMARY.md files}
+**Commits:** {list of commit summaries from summary comments}
 
 Proceeding to verification...
 ```
@@ -241,11 +304,13 @@ VERIFIER_MODEL=$(node .claude/maxsim/bin/maxsim-tools.cjs resolve-model verifier
 Task(
   prompt="Verify phase {phase_number} goal achievement.
 Phase directory: {phase_dir}
+Phase issue: #{phase_issue_number}
 Phase goal: {goal from ROADMAP.md}
 Phase requirement IDs: {phase_req_ids}
 Check must_haves against actual codebase.
-Cross-reference requirement IDs from PLAN frontmatter against REQUIREMENTS.md.
-Create VERIFICATION.md.",
+Cross-reference requirement IDs from plan frontmatter against REQUIREMENTS.md.
+Post verification results as a GitHub comment (mcp_post_comment with type=verification) on the phase issue.
+Also write VERIFICATION.md to the phase directory for local reference.",
   subagent_type="verifier",
   model="{verifier_model}"
 )
@@ -253,7 +318,15 @@ Create VERIFICATION.md.",
 
 ### 5.2 Parse Verifier Result
 
-Read verification status:
+Read verification status from the verification comment on the phase issue:
+
+```
+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 ' '
 ```
@@ -264,11 +337,25 @@ grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
 ## Gate: Verification Passed
 
 **Status:** All must-haves verified
-**Evidence:** {summary from VERIFICATION.md}
+**Evidence:** {summary from verification comment}
 
 Phase {phase_number} complete!
 ```
 
+Move phase issue to "Done" status:
+```
+mcp_move_issue(issue_number: phase_issue_number, status: "Done")
+```
+
+Post phase completion comment:
+```
+mcp_post_comment(
+  issue_number: phase_issue_number,
+  type: "phase-complete",
+  body: "## Phase {phase_number} Complete\n\nAll plans executed and verified.\n\n**Plans:** {completed}/{total}\n**Waves:** {wave_count}\n**Verification:** Passed"
+)
+```
+
 Mark phase complete:
 ```bash
 COMPLETION=$(node .claude/maxsim/bin/maxsim-tools.cjs phase complete "${PHASE_NUMBER}")
@@ -279,7 +366,15 @@ Update tracking files:
 node .claude/maxsim/bin/maxsim-tools.cjs commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md
 ```
 
-**If `gaps_found`:** Proceed to Retry Loop (step 6).
+**If `gaps_found`:** Post a gaps comment on the phase issue, then proceed to Retry Loop (step 6).
+
+```
+mcp_post_comment(
+  issue_number: phase_issue_number,
+  type: "verification-gaps",
+  body: "## Verification Gaps Found\n\n{gap summaries from verification result}"
+)
+```
 
 **If `human_needed`:** Present items for human testing, get approval or feedback. If approved, treat as passed. If issues reported, proceed to Retry Loop.
 
@@ -299,7 +394,7 @@ If `attempt_count > 2`:
 **Attempts:** 3 (initial + 2 retries)
 
 ### What Failed
-{List of unresolved gaps from VERIFICATION.md with evidence}
+{List of unresolved gaps from verification comment with evidence}
 
 ### Options
 1. Fix manually and re-run `/maxsim:execute {phase_number}`
@@ -332,6 +427,7 @@ Task(
 <downstream_consumer>
 Output consumed by /maxsim:execute.
 Plans must be executable prompts.
+Post gap-closure plans as comments on phase issue #{phase_issue_number} using mcp_post_comment with type=plan.
 </downstream_consumer>
 ",
   subagent_type="planner",
@@ -341,7 +437,7 @@ Plans must be executable prompts.
 
 ### 6.3 Execute Gap Plans
 
-Execute the newly created gap-closure plans using the same wave execution logic from step 4. Only execute plans with `gap_closure: true` in frontmatter.
+After the planner posts gap-closure plan comments on the phase issue, re-read the phase issue to discover the new plan comments. Execute the newly created gap-closure plans using the same wave execution logic from step 4. Only execute plans with `gap_closure: true` in frontmatter.
 
 ### 6.4 Re-verify
 
@@ -356,12 +452,11 @@ At any point during the workflow, if context is getting full (conversation is lo
 
 **Checkpoint protocol:**
 1. Post a checkpoint comment to the phase's GitHub Issue (if issue tracking is active):
-```bash
-# Use MCP tool to post checkpoint
-mcp_post_plan_comment(
-  phase_issue_number={issue_number},
-  plan_number="checkpoint",
-  plan_content="## MAXSIM Checkpoint\n\n**Command:** /maxsim:execute\n**Stage:** {current_stage}\n**Plans completed:** {completed_count}/{total_count}\n**Verification attempts:** {attempt_count}/3\n**Resume from:** {next_action}\n**Timestamp:** {ISO timestamp}"
+```
+mcp_post_comment(
+  issue_number: phase_issue_number,
+  type: "checkpoint",
+  body: "## MAXSIM Checkpoint\n\n**Command:** /maxsim:execute\n**Stage:** {current_stage}\n**Plans completed:** {completed_count}/{total_count}\n**Verification attempts:** {attempt_count}/3\n**Resume from:** {next_action}\n**Timestamp:** {ISO timestamp}"
 )
 ```
 
@@ -369,10 +464,10 @@ mcp_post_plan_comment(
 ```
 Context is filling up. Recommended: save progress and /clear.
 
-Your progress has been checkpointed. Re-run `/maxsim:execute {phase_number}` after /clear -- it will detect completed plans and resume from where it left off.
+Your progress has been checkpointed on GitHub issue #{phase_issue_number}. Re-run `/maxsim:execute {phase_number}` after /clear -- it will detect completed plans (via closed task sub-issues) and resume from where it left off.
 ```
 
-The state detection in step 2 handles resume automatically -- completed plans have SUMMARY.md files that are detected on re-entry.
+The state detection in step 2 handles resume automatically -- completed plans have all their task sub-issues closed, which is detected on re-entry.
 
 ## 8. Update State
 
@@ -394,10 +489,11 @@ Display final results:
 **Plans:** {completed}/{total} complete
 **Waves:** {wave_count}
 **Verification:** Passed (attempt {attempt_count}/3)
+**Phase issue:** #{phase_issue_number} (closed)
 
 ### Plan Details
-1. **{plan_id}**: {one-liner from SUMMARY.md}
-2. **{plan_id}**: {one-liner from SUMMARY.md}
+1. **{plan_id}**: {one-liner from summary comment}
+2. **{plan_id}**: {one-liner from summary comment}
 
 ### Next Steps
 - `/maxsim:plan {next_phase}` -- Plan next phase
@@ -408,14 +504,17 @@ Display final results:
 
 <success_criteria>
 - [ ] Phase validated against roadmap
-- [ ] Current state correctly detected from artifacts
+- [ ] Plan inventory loaded from GitHub issue comments (falling back to local files if no GitHub integration)
+- [ ] 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
-- [ ] Plans discovered and grouped by wave
-- [ ] Per-plan execution delegates to execute-plan.md sub-workflow via Task
-- [ ] Spot-check of SUMMARY.md after each wave
+- [ ] Plans discovered from GitHub comments and grouped by wave
+- [ ] Per-plan execution delegates to execute-plan.md sub-workflow via Task with GitHub context
+- [ ] Spot-check reads summary comments and checks sub-issue closure instead of local SUMMARY.md
 - [ ] Gate confirmation shown after execution completes
-- [ ] Auto-verification spawns verifier agent
+- [ ] Auto-verification spawns verifier agent that posts to GitHub
+- [ ] Phase issue moved to Done on verification pass
 - [ ] Retry loop with gap closure (max 2 retries, 3 total attempts)
-- [ ] Checkpoint-before-clear pattern available
-- [ ] No references to old commands (execute-phase, verify-work)
+- [ ] Checkpoint-before-clear posts to GitHub issue
+- [ ] No references to old SUMMARY.md local file checks for completion detection
 </success_criteria>

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

@@ -1,5 +1,5 @@
 <purpose>
-Auto-detect project state through deep context gathering, surface problems proactively, and dispatch to the appropriate MAXSIM command. Uses the Show + Act pattern: display detection reasoning first, then act immediately.
+Auto-detect project state through live GitHub queries, surface problems proactively, and dispatch to the appropriate MAXSIM command. Uses the Show + Act pattern: display detection reasoning first, then act immediately.
 </purpose>
 
 <required_reading>
@@ -30,19 +30,24 @@ PLANNING_EXISTS=$(test -d .planning && echo "true" || echo "false")
 
 If `.planning/` does not exist, skip all other checks and go directly to the decision tree (Rule 1: No project found).
 
-**2. Load project state (if .planning/ exists):**
+**2. Load local project context (always from local files per WIRE-02):**
 ```bash
-# State snapshot
+# State snapshot (local)
 STATE=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs state-snapshot 2>/dev/null || echo "{}")
-
-# Roadmap analysis
-ROADMAP=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap analyze 2>/dev/null || echo "{}")
 ```
 
-**3. Read key files (if they exist):**
-- `.planning/PROJECT.md` -- project name and vision
-- `.planning/STATE.md` -- blockers, decisions, session continuity
-- `.planning/ROADMAP.md` -- phase structure and progress
+Read local files for project context:
+- `.planning/STATE.md` — blockers, decisions, session continuity
+- `.planning/ROADMAP.md` — phase structure and phase ordering
+
+**3. Live GitHub state (primary source — always-live, no cached state):**
+
+Call `mcp_get_all_progress` to get current state of all phases from GitHub. Returns:
+- `phase_number`, `title`, `issue_number`
+- `total_tasks`, `completed_tasks`, `remaining_tasks`
+- `status` (GitHub board column: To Do / In Progress / In Review / Done)
+
+Call `mcp_detect_interrupted` to check for any phases that were interrupted mid-execution (e.g., agent was stopped while a task was marked in-flight).
 
 **4. Git context:**
 ```bash
@@ -52,20 +57,12 @@ GIT_STATUS=$(git status --porcelain 2>/dev/null | head -20)
 # Recent commits
 RECENT_COMMITS=$(git log --oneline -5 2>/dev/null)
 ```
-
-**5. Phase directory scan:**
-```bash
-# List phase directories and their contents
-ls -1 .planning/phases/ 2>/dev/null
-```
-
-For each phase directory, check for PLAN.md, SUMMARY.md, CONTEXT.md, RESEARCH.md files to determine phase state.
 </step>
 
 <step name="problem_detection">
 **Phase 2: Problem Detection**
 
-Check for problems BEFORE suggesting any action. All problems are blocking -- no severity tiers.
+Check for problems BEFORE suggesting any action. All problems are blocking — no severity tiers.
 
 **Check each of these in order:**
 
@@ -78,7 +75,7 @@ If uncommitted changes exist in `.planning/`:
 ## Problem Detected
 
 **Issue:** Uncommitted changes in .planning/ directory
-**Impact:** State drift -- local planning files may diverge from team or lose work
+**Impact:** State drift — local planning files may diverge from team or lose work
 **Resolution:** Commit planning changes to preserve state
 
 **Files with changes:**
@@ -110,22 +107,18 @@ Resolve this before continuing. Options:
 
 Block until user responds.
 
-**3. Failed verification**
-Check for VERIFICATION.md in the current/latest phase with FAIL status:
-```bash
-grep -l "FAIL\|status: failed" .planning/phases/*/VERIFICATION.md 2>/dev/null | tail -1
-```
-If found:
+**3. Failed verification on GitHub**
+Check if any phase issue has a verification comment with FAIL status (from live GitHub data via `mcp_get_all_progress` — look for phases stuck in "In Review" with a known failure, or check recent comments via `mcp_get_issue_detail` for the current phase issue):
 ```
 ## Problem Detected
 
 **Issue:** Phase verification failed
-**Phase:** {phase number and name}
-**Impact:** Phase is not verified as complete -- may have gaps
+**Phase:** {phase number and name} (GitHub Issue #{issue_number})
+**Impact:** Phase is not verified as complete — may have gaps
 **Resolution:** Re-run verification or fix identified issues
 
 Resolve this before continuing. Options:
-1. View verification results
+1. View verification results (check GitHub issue comments)
 2. Re-execute to fix issues
 3. Skip and continue anyway
 ```
@@ -142,6 +135,8 @@ Block until user responds.
 
 Apply rules in strict precedence order. The FIRST matching rule determines the action.
 
+Use live GitHub data from `mcp_get_all_progress` and `mcp_detect_interrupted` (gathered in Phase 1) as the primary source of truth for phase state. Use local ROADMAP.md for phase ordering only.
+
 ```
 Rule 1: No .planning/ directory?
   -> Action: /maxsim:init
@@ -151,31 +146,35 @@ Rule 2: Has blockers in STATE.md? (not cleared in problem detection)
   -> Action: Surface blocker, suggest resolution
   -> Reasoning: "BLOCKED: {blocker text}"
 
-Rule 3: Active phase has plans but not all executed?
-  -> Check: summaries < plans in current phase directory
+Rule 3: Interrupted phase detected (from mcp_detect_interrupted)?
+  -> Action: /maxsim:execute {N}
+  -> Reasoning: "Phase {N} ({name}) was interrupted. Resuming execution."
+
+Rule 4: Phase "In Progress" on GitHub board with incomplete tasks?
+  -> Check: mcp_get_all_progress returns a phase with status="In Progress" and remaining_tasks > 0
   -> Action: /maxsim:execute {N}
-  -> Reasoning: "Phase {N} ({name}) has {X} plans, {Y} executed. Ready to continue."
+  -> Reasoning: "Phase {N} ({name}) has {remaining} tasks remaining. Ready to continue."
 
-Rule 4: Active phase needs planning? (no PLAN.md files)
-  -> Check: no PLAN.md files in current phase directory
+Rule 5: Phase "To Do" on GitHub board (not yet started)?
+  -> Check: mcp_get_all_progress returns the next unstarted phase (status="To Do")
   -> Action: /maxsim:plan {N}
   -> Reasoning: "Phase {N} ({name}) needs planning."
 
-  Sub-check: Does CONTEXT.md exist?
+  Sub-check: Does local CONTEXT.md exist?
   -> If yes: "Discussion complete, ready for research + planning."
   -> If no: "Starting from discussion stage."
 
-Rule 5: Current phase complete, next phase exists?
-  -> Check: all plans have summaries AND next phase exists in roadmap
-  -> Action: /maxsim:plan {N+1}
-  -> Reasoning: "Phase {N} complete. Next: Phase {N+1} ({name})."
+Rule 6: Current phase "In Review" on GitHub board?
+  -> Check: mcp_get_all_progress returns a phase with status="In Review"
+  -> Action: /maxsim:verify {N}
+  -> Reasoning: "Phase {N} ({name}) is awaiting verification."
 
-Rule 6: All phases complete?
-  -> Check: all phases in roadmap have all plans executed
+Rule 7: All phases "Done" on GitHub board?
+  -> Check: mcp_get_all_progress — all phases have status="Done"
   -> Action: /maxsim:progress
   -> Reasoning: "All phases complete. Milestone ready for review."
 
-Rule 7: None of the above?
+Rule 8: None of the above?
   -> Action: Show interactive menu
   -> Reasoning: "Project state is ambiguous. Here are your options."
 ```
@@ -186,53 +185,55 @@ Rule 7: None of the above?
 
 Once a rule matches, display detection reasoning FIRST, then act immediately.
 
-**Format for auto-dispatch (Rules 1-6):**
+**Format for auto-dispatch (Rules 1-7):**
 
 ```
 ## Detected: {summary of what was found}
 
 **Project:** {project name from PROJECT.md, or "New project"}
 **Milestone:** {milestone from ROADMAP.md, or "Not started"}
-**Current phase:** {phase N - name, or "None"}
-**Status:** {description of current state}
+**Current phase:** {phase N - name, or "None"} (GitHub Issue #{issue_number})
+**GitHub Status:** {board column from live mcp_get_all_progress data}
+**Tasks:** {completed}/{total} complete
 
 **Action:** Running /maxsim:{command} {args}...
 ```
 
 Then immediately dispatch the command using the SlashCommand tool. The user can Ctrl+C if the detection is wrong.
 
-**Important:** Show the detection block, then dispatch. Do not ask for confirmation -- this is Show + Act, not Show + Ask.
+**Important:** Show the detection block, then dispatch. Do not ask for confirmation — this is Show + Act, not Show + Ask.
 </step>
 
 <step name="interactive_menu">
-**Phase 5: Interactive Menu (Rule 7 -- no obvious action)**
+**Phase 5: Interactive Menu (Rule 8 — no obvious action)**
 
-When no clear action is detected, show a contextual menu. The menu items are NOT static -- filter based on what makes sense for the current project state.
+When no clear action is detected, show a contextual menu. The menu items are NOT static — filter based on what makes sense for the current project state (use live GitHub data from mcp_get_all_progress).
 
 ```
 ## Project Status
 
 **Project:** {project name}
 **Milestone:** {milestone}
-**Progress:** {X}/{Y} phases complete
+**GitHub Progress:** {X}/{Y} phases Done on board
 
 What would you like to do?
 
-1. /maxsim:plan {next_phase} -- Plan next phase
-2. /maxsim:quick -- Quick ad-hoc task
-3. /maxsim:progress -- View detailed progress
-4. /maxsim:debug -- Debug an issue
+1. /maxsim:plan {next_phase} — Plan next phase
+2. /maxsim:quick — Quick ad-hoc task
+3. /maxsim:progress — View detailed progress
+4. /maxsim:debug — Debug an issue
 
 Or describe what you'd like to do:
 ```
 
 **Contextual filtering rules:**
-- If phases are planned but not executed: show execute options prominently
-- If all phases are done: show `/maxsim:progress` (offers milestone completion)
+- If phases are "In Progress" on GitHub: show execute options prominently
+- If all phases are "Done" on GitHub: show `/maxsim:progress` (offers milestone completion)
 - If recent git activity suggests debugging: show `/maxsim:debug` prominently
-- If no phases exist: show `/maxsim:plan` prominently
+- 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
 
 Wait for user selection, then dispatch the chosen command.
 </step>
@@ -242,9 +243,12 @@ Wait for user selection, then dispatch the chosen command.
 <constraints>
 - Never ask for confirmation before dispatching (Show + Act, not Show + Ask)
 - Always surface problems BEFORE suggesting actions
-- All problems block -- no severity tiers, no "warnings"
-- No arguments accepted -- this is pure auto-detection
+- All problems block — no severity tiers, no "warnings"
+- No arguments accepted — this is pure auto-detection
 - No mention of old commands (plan-phase, execute-phase, etc.)
-- Keep initial feedback fast -- show "Analyzing..." before heavy operations
+- Keep initial feedback fast — show "Analyzing..." before heavy operations
+- Primary source for phase state: live GitHub (mcp_get_all_progress, mcp_detect_interrupted)
+- Local reads: STATE.md for blockers/decisions, ROADMAP.md for phase ordering only
 - If context gathering fails (tools not available, etc.), fall back to the interactive menu
 </constraints>
+</output>