maxsimcli 4.11.0 → 4.13.0

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

@@ -1,7 +1,7 @@
 <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.
+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 posting the context decisions to GitHub.
 
 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>
@@ -11,13 +11,13 @@ You are a thinking partner, not an interviewer. The user is the visionary -- you
 </required_reading>
 
 <downstream_awareness>
-**CONTEXT.md feeds into:**
+**Context decisions (posted to GitHub) feed into:**
 
-1. **researcher** -- Reads CONTEXT.md to know WHAT to research
+1. **researcher** -- Reads context comment 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
+2. **planner** -- Reads context comment 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
 
@@ -125,7 +125,7 @@ Phase: "API documentation"
 
 ## Step 1: Initialize
 
-Phase number, name, and directory come from the orchestrator context.
+Phase number, name, directory, and GitHub issue number come from the orchestrator context.
 
 ```bash
 INIT=$(node .claude/maxsim/bin/maxsim-tools.cjs init phase-op "${PHASE}")
@@ -133,31 +133,34 @@ 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`.
 
+Also extract `phase_issue_number` passed from the orchestrator.
+
 **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
+Check if a context comment already exists on the phase GitHub Issue by calling:
+```
+mcp_get_issue_detail(issue_number={phase_issue_number})
 ```
 
-**If exists:**
+Look for a comment that contains `<!-- maxsim:type=context -->`.
+
+**If a context comment exists:**
 
 Ask the user (via natural conversation):
 ```
-Phase {phase_number} already has context. What would you like to do?
+Phase {phase_number} already has context on GitHub Issue #{phase_issue_number}. 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 "Update": Load existing context comment content, continue to Step 3.
+- If "View": Display context comment contents, then offer update/use-as-is.
 - If "Use as-is": Return control to orchestrator.
 
-**If doesn't exist:** Continue to Step 3.
+**If no context comment exists:** Continue to Step 3.
 
 ## Step 3: Analyze Phase
 
@@ -264,24 +267,14 @@ Back to [current area]: [return to current question]"
 Track deferred ideas internally.
 </process>
 
-## Step 6: Write Context
-
-Create CONTEXT.md capturing decisions made.
+## Step 6: Post Context to GitHub
 
-**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`
+Build the context content in memory, then post it as a comment on the phase GitHub Issue.
 
 **Structure the content by what was discussed:**
 
 ```markdown
+<!-- maxsim:type=context -->
 # Phase {X} Context: {Name}
 
 **Phase Goal:** {goal from ROADMAP.md}
@@ -319,20 +312,24 @@ mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
 *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"
+Post the comment to GitHub:
+```
+mcp_post_comment(
+  issue_number={phase_issue_number},
+  type="context",
+  content={context_content_above}
+)
 ```
 
+Context decisions are posted as a GitHub comment on phase issue #{phase_issue_number}. No local CONTEXT.md file is written.
+
 ## 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.
+After posting the context comment to GitHub, 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}.
+Discussion complete. Context decisions posted to GitHub Issue #{phase_issue_number}.
 ```
 
 <success_criteria>
@@ -341,7 +338,8 @@ Discussion complete. CONTEXT.md written to {path}.
 - 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
+- Context comment captures actual decisions (not vague vision) with <!-- maxsim:type=context --> marker
+- Context posted to GitHub Issue #{phase_issue_number} as a comment (no local CONTEXT.md written)
 - Deferred ideas preserved for future phases
 - Control returned to orchestrator without showing gate or next steps
 </success_criteria>

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

@@ -4,8 +4,25 @@ Before executing any step in this workflow, verify:
 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>
-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).
+[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>

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

@@ -1,7 +1,7 @@
 <purpose>
-Research stage sub-workflow for /maxsim:plan. Spawns the researcher agent with phase context to produce RESEARCH.md.
+Research stage sub-workflow for /maxsim:plan. Spawns the researcher agent with phase context to produce research findings, then posts them to GitHub as a comment on the phase issue.
 
-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 research and validating the output.
+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 research and posting the output to GitHub.
 </purpose>
 
 <process>
@@ -12,9 +12,10 @@ The orchestrator provides phase context. Verify we have what we need:
 
 - `phase_number`, `phase_name`, `phase_dir`, `padded_phase`, `phase_slug`
 - `researcher_model`, `research_enabled`
-- `has_research` (whether RESEARCH.md already exists)
+- `has_research` (whether a research comment already exists on the phase issue)
 - `state_path`, `roadmap_path`, `requirements_path`, `context_path`
 - `phase_req_ids` (requirement IDs that this phase must address)
+- `phase_issue_number` (GitHub Issue number for the phase)
 - `--force-research` flag presence
 
 ## Step 2: Resolve Researcher Model
@@ -25,18 +26,20 @@ RESEARCHER_MODEL=$(node .claude/maxsim/bin/maxsim-tools.cjs resolve-model resear
 
 ## Step 3: Check Existing Research
 
+Determine whether a research comment already exists on the phase GitHub Issue by checking for a comment containing `<!-- maxsim:type=research -->`. This is reflected in the `has_research` flag passed from the orchestrator (which performs the GitHub query).
+
 **If `has_research` is true AND `--force-research` is NOT set:**
 
-Research already exists. Display:
+Research already exists as a GitHub comment on Issue #{phase_issue_number}. Display:
 ```
-Using existing research from: {research_path}
+Using existing research from GitHub Issue #{phase_issue_number}.
 ```
 
 Return control to orchestrator -- no need to re-research.
 
 **If `has_research` is true AND `--force-research` IS set:**
 
-Continue to Step 4 (re-research will overwrite existing RESEARCH.md).
+Continue to Step 4 (re-research will post a new research comment, replacing the old one).
 
 **If `has_research` is false:**
 
@@ -67,7 +70,7 @@ Display:
 Researching Phase {phase_number}: {phase_name}...
 ```
 
-Construct the research prompt:
+Construct the research prompt. The researcher must return its findings as a structured markdown document (not write to a local file -- the orchestrator will post findings to GitHub):
 
 ```markdown
 <objective>
@@ -76,7 +79,7 @@ Answer: "What do I need to know to PLAN this phase well?"
 </objective>
 
 <files_to_read>
-- {context_path} (USER DECISIONS -- locked choices that constrain research)
+- GitHub Issue #{phase_issue_number} context comment (USER DECISIONS -- locked choices that constrain research)
 - {requirements_path} (Project requirements)
 - {state_path} (Project decisions and history)
 </files_to_read>
@@ -90,7 +93,8 @@ Answer: "What do I need to know to PLAN this phase well?"
 </additional_context>
 
 <output>
-Write to: {phase_dir}/{padded_phase}-RESEARCH.md
+Return findings as a structured markdown document in your response.
+Do NOT write to a local file -- findings will be posted to GitHub by the orchestrator.
 </output>
 ```
 
@@ -110,30 +114,25 @@ Task(
 Parse the researcher's return message:
 
 - **`## RESEARCH COMPLETE`:**
-  Validate RESEARCH.md was created:
-  ```bash
-  test -f "${phase_dir}/${padded_phase}-RESEARCH.md" && echo "FOUND" || echo "MISSING"
+  Extract the research findings document from the researcher's response.
+
+  Post research findings to GitHub:
+  ```
+  mcp_post_comment(
+    issue_number={phase_issue_number},
+    type="research",
+    content="<!-- maxsim:type=research -->\n" + {research_findings_document}
+  )
+  ```
+
+  Research findings are posted as a GitHub comment on phase issue #{phase_issue_number}. No local RESEARCH.md file is written.
+
+  Display confirmation:
+  ```
+  Research complete. Findings posted to GitHub Issue #{phase_issue_number}.
   ```
 
-  If FOUND:
-  - If `commit_docs` is true:
-    ```bash
-    node .claude/maxsim/bin/maxsim-tools.cjs commit "docs(${padded_phase}): research phase domain" --files "${phase_dir}/${padded_phase}-RESEARCH.md"
-    ```
-  - Display confirmation:
-    ```
-    Research complete. RESEARCH.md written to {path}.
-    ```
-  - Return control to orchestrator.
-
-  If MISSING:
-  - Error: "Researcher reported complete but RESEARCH.md not found at expected path."
-  - Check for alternative paths:
-    ```bash
-    ls "${phase_dir}"/*RESEARCH* 2>/dev/null
-    ```
-  - If found elsewhere, note the actual path and continue.
-  - If truly missing, offer: retry or skip research.
+  Return control to orchestrator.
 
 - **`## RESEARCH BLOCKED`:**
   Display the blocker reason. Offer options:
@@ -147,7 +146,7 @@ Parse the researcher's return message:
   Wait for user choice.
 
   - If "Provide context": Get additional info, re-spawn researcher with augmented prompt.
-  - If "Skip": Return to orchestrator without RESEARCH.md.
+  - If "Skip": Return to orchestrator without posting research comment.
   - If "Abort": Exit workflow.
 
 - **`## RESEARCH INCONCLUSIVE`:**
@@ -163,15 +162,16 @@ Parse the researcher's return message:
 
 ## Step 7: Return to Orchestrator
 
-After RESEARCH.md is validated (or research is skipped), return control to the plan.md orchestrator. Do NOT show gate confirmation or next steps -- the orchestrator handles the gate between Research and Planning.
+After research is posted to GitHub (or research is skipped), return control to the plan.md orchestrator. Do NOT show gate confirmation or next steps -- the orchestrator handles the gate between Research and Planning.
 
 </process>
 
 <success_criteria>
 - Researcher model resolved from config
-- Existing research detected and reused (unless --force-research)
-- researcher agent spawned with full context (CONTEXT.md, requirements, state)
-- RESEARCH.md created and validated
+- Existing research detected from GitHub Issue comment (<!-- maxsim:type=research --> marker) and reused unless --force-research
+- researcher agent spawned with full context (GitHub context comment, requirements, state)
+- Research findings returned from researcher as document, then posted as GitHub comment on Issue #{phase_issue_number}
+- No local RESEARCH.md file written
 - Blocked/inconclusive scenarios handled with user options
 - Control returned to orchestrator without showing gate or next steps
 </success_criteria>

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

@@ -23,7 +23,7 @@ Load phase state in one call:
 INIT=$(node .claude/maxsim/bin/maxsim-tools.cjs init plan-phase "$PHASE")
 ```
 
-Parse JSON for: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_context`, `has_research`, `has_plans`, `plan_count`, `plans`, `commit_docs`, `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `phase_req_ids`.
+Parse JSON for: `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_context`, `has_research`, `has_plans`, `plan_count`, `plans`, `commit_docs`, `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `phase_req_ids`, `phase_issue_number`.
 
 **If `phase_found` is false:**
 ```
@@ -39,46 +39,57 @@ Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`-
 
 **If no phase number:** Detect next unplanned phase from roadmap using the `plans` and `has_context`/`has_research` fields.
 
-## 3. Detect Current Stage
+## 3. Stage Detection (GitHub-First)
 
-Determine where to start based on artifacts that already exist:
+Detect planning stage by querying the phase GitHub Issue:
 
-| Condition | Stage | Action |
-|-----------|-------|--------|
-| `plan_count > 0` | Already planned | Go to **Re-entry flow** (step 4) |
-| `has_research == true` AND `plan_count == 0` | Planning | Start at **Planning stage** (step 7) |
-| `has_context == true` AND `has_research == false` | Research | Start at **Research stage** (step 6) |
-| None of the above | Discussion | Start at **Discussion stage** (step 5) |
+1. Get `phase_issue_number` from the init context parsed above.
+2. **If no `phase_issue_number` exists:** The phase has not been set up on GitHub yet.
+   - Call `mcp_create_phase_issue` to create the issue (uses roadmap data).
+   - Store the returned issue number as `phase_issue_number`.
+3. Call `mcp_get_issue_detail` with `phase_issue_number` to read the phase issue body and comments.
+4. Check issue comments for existing artifacts using HTML marker comments:
+   - Has a comment containing `<!-- maxsim:type=context -->`? → Discussion stage complete
+   - Has a comment containing `<!-- maxsim:type=research -->`? → Research stage complete
+   - Has a comment containing `<!-- maxsim:type=plan -->`? → Planning stage complete
+5. Determine next stage from the GitHub state:
+
+| GitHub Issue State | Stage | Action |
+|--------------------|-------|--------|
+| Has `type=plan` comment | Already planned | Go to **Re-entry flow** (step 4) |
+| Has `type=research`, no `type=plan` | Planning | Start at **Planning stage** (step 7) |
+| Has `type=context`, no `type=research` | Research | Start at **Research stage** (step 6) |
+| No marker comments | Discussion | Start at **Discussion stage** (step 5) |
 
 Display detected stage:
 ```
 Phase {phase_number}: {phase_name}
+GitHub Issue: #{phase_issue_number}
 Current stage: {Discussion | Research | Planning | Already planned}
 ```
 
 ## 4. Re-entry Flow (Already Planned)
 
-When `plan_count > 0`, the phase has existing plans. Show status and offer options.
+When a `type=plan` comment exists on the phase issue, the phase has been planned. Show status and offer options.
 
 Display:
 ```
 ## Phase {phase_number} Already Planned
 
-**Plans:** {plan_count} plan(s)
-**Plan files:** {list of plan filenames from `plans` array}
-**Phase directory:** {phase_dir}
+**Plans:** posted as comment(s) on GitHub Issue #{phase_issue_number}
+**Phase Issue:** https://github.com/{owner}/{repo}/issues/{phase_issue_number}
 
 **Options:**
 1. View existing plans
-2. Re-plan from scratch (deletes existing plans, restarts from Discussion)
+2. Re-plan from scratch (deletes plan comments, restarts from Discussion)
 3. Execute phase -- run /maxsim:execute {phase_number}
 4. Done (exit)
 ```
 
 Wait for user choice via natural conversation.
 
-- **View:** Display contents of each PLAN.md file, then re-show options.
-- **Re-plan:** Delete existing PLAN.md files, reset to Discussion stage (step 5).
+- **View:** Display contents of each `type=plan` comment from the issue, then re-show options.
+- **Re-plan:** Delete existing plan/context/research comments from the phase issue, reset to Discussion stage (step 5).
 - **Execute:** Display `/maxsim:execute {phase_number}` and exit.
 - **Done:** Exit workflow.
 
@@ -88,13 +99,13 @@ Delegate to the discussion sub-workflow for full discussion logic:
 
 @./workflows/plan-discuss.md
 
-Pass context: `phase_number`, `phase_name`, `phase_dir`, `padded_phase`, `phase_slug`, `commit_docs`, `roadmap_path`, `state_path`.
+Pass context: `phase_number`, `phase_name`, `phase_dir`, `padded_phase`, `phase_slug`, `commit_docs`, `roadmap_path`, `state_path`, `phase_issue_number`.
 
-**After discussion completes (CONTEXT.md written):**
+**After discussion completes (context posted as GitHub comment):**
 
-Refresh state to pick up the newly created CONTEXT.md:
-```bash
-INIT=$(node .claude/maxsim/bin/maxsim-tools.cjs init plan-phase "$PHASE")
+Re-query the phase issue to verify the `type=context` comment now exists:
+```
+mcp_get_issue_detail(issue_number={phase_issue_number})
 ```
 
 Show gate:
@@ -103,10 +114,10 @@ Show gate:
 
 **Captured:** {N} decisions across {M} areas
 **Locked decisions:**
-{bullet list of key decisions from CONTEXT.md}
+{bullet list of key decisions from context comment}
 
 **Claude's discretion:** {list of areas where Claude decides}
-**Context file:** {path to CONTEXT.md}
+**GitHub Issue:** #{phase_issue_number} (context posted as comment)
 
 Continue to research? [Yes / Review context / Re-discuss area]
 ```
@@ -114,7 +125,7 @@ Continue to research? [Yes / Review context / Re-discuss area]
 Wait for user response via natural conversation (not AskUserQuestion).
 
 - **Yes:** Advance to Research stage (step 6).
-- **Review context:** Display CONTEXT.md contents, then re-show gate.
+- **Review context:** Display context comment contents, then re-show gate.
 - **Re-discuss area:** Loop back to discussion sub-workflow with the area to re-discuss.
 
 ## 6. Research Stage
@@ -123,22 +134,22 @@ Delegate to the research sub-workflow:
 
 @./workflows/plan-research.md
 
-Pass context: `phase_number`, `phase_name`, `phase_dir`, `padded_phase`, `phase_slug`, `commit_docs`, `researcher_model`, `research_enabled`, `has_research`, `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `phase_req_ids`. Also pass the `--force-research` flag if present in $ARGUMENTS.
+Pass context: `phase_number`, `phase_name`, `phase_dir`, `padded_phase`, `phase_slug`, `commit_docs`, `researcher_model`, `research_enabled`, `has_research`, `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `phase_req_ids`, `phase_issue_number`. Also pass the `--force-research` flag if present in $ARGUMENTS.
 
-**After research completes (RESEARCH.md written or already exists):**
+**After research completes (research posted as GitHub comment or already exists):**
 
-Refresh state:
-```bash
-INIT=$(node .claude/maxsim/bin/maxsim-tools.cjs init plan-phase "$PHASE")
+Re-query the phase issue to verify the `type=research` comment now exists:
+```
+mcp_get_issue_detail(issue_number={phase_issue_number})
 ```
 
 Show gate:
 ```
 ## Gate: Research Complete
 
-**Key findings:** {3-5 bullet summary from RESEARCH.md}
-**Confidence:** {HIGH/MEDIUM/LOW from RESEARCH.md metadata}
-**File:** {path to RESEARCH.md}
+**Key findings:** {3-5 bullet summary from research comment}
+**Confidence:** {HIGH/MEDIUM/LOW from research content}
+**GitHub Issue:** #{phase_issue_number} (research posted as comment)
 
 Continue to planning? [Yes / Review research / Re-research]
 ```
@@ -146,7 +157,7 @@ Continue to planning? [Yes / Review research / Re-research]
 Wait for user response via natural conversation.
 
 - **Yes:** Advance to Planning stage (step 7).
-- **Review research:** Display RESEARCH.md contents, then re-show gate.
+- **Review research:** Display research comment contents, then re-show gate.
 - **Re-research:** Loop back to research sub-workflow with `--force-research`.
 
 ## 7. Planning Stage
@@ -155,13 +166,13 @@ Delegate to the planning sub-workflow:
 
 @./workflows/plan-create.md
 
-Pass context: `phase_number`, `phase_name`, `phase_dir`, `padded_phase`, `phase_slug`, `commit_docs`, `planner_model`, `checker_model`, `plan_checker_enabled`, `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `phase_req_ids`. Also pass the `--skip-verify` flag if present in $ARGUMENTS.
+Pass context: `phase_number`, `phase_name`, `phase_dir`, `padded_phase`, `phase_slug`, `commit_docs`, `planner_model`, `checker_model`, `plan_checker_enabled`, `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`, `phase_req_ids`, `phase_issue_number`. Also pass the `--skip-verify` flag if present in $ARGUMENTS.
 
-**After planning completes (PLAN.md files created):**
+**After planning completes (plans posted as GitHub comments and task sub-issues created):**
 
-Refresh state:
-```bash
-INIT=$(node .claude/maxsim/bin/maxsim-tools.cjs init plan-phase "$PHASE")
+Re-query the phase issue to verify `type=plan` comments exist:
+```
+mcp_get_issue_detail(issue_number={phase_issue_number})
 ```
 
 Show final gate:
@@ -172,9 +183,11 @@ Show final gate:
 **Wave structure:**
 | Wave | Plans | What it builds |
 |------|-------|----------------|
-{wave summary from plan frontmatter}
+{wave summary from plan comment frontmatter}
 
-**Plan files:** {list of PLAN.md paths}
+**GitHub Issue:** #{phase_issue_number} (plans posted as comments)
+**Task sub-issues:** {task_count} tasks created as linked sub-issues
+**Board status:** Phase moved to "In Progress"
 
 Ready to execute? Run `/maxsim:execute {phase_number}`
 ```
@@ -186,13 +199,12 @@ This is the final gate -- no confirmation needed. The user's next action is to r
 At any point during the workflow, if context is getting full (conversation is long, many tool calls made), recommend checkpointing before `/clear`.
 
 **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:plan\n**Stage:** {current_stage} ({stage_num}/3)\n**Completed:**\n{list of completed stages with summaries}\n**Resume from:** {next_stage}\n**Timestamp:** {ISO timestamp}"
+1. Post a checkpoint comment to the phase's GitHub Issue:
+```
+mcp_post_comment(
+  issue_number={phase_issue_number},
+  type="checkpoint",
+  content="## MAXSIM Checkpoint\n\n**Command:** /maxsim:plan\n**Stage:** {current_stage} ({stage_num}/3)\n**Completed:**\n{list of completed stages with summaries}\n**Resume from:** {next_stage}\n**Timestamp:** {ISO timestamp}"
 )
 ```
 
@@ -200,10 +212,10 @@ mcp_post_plan_comment(
 ```
 Context is filling up. Recommended: save progress and /clear.
 
-Your progress has been checkpointed. Re-run `/maxsim:plan {phase_number}` after /clear -- it will detect completed stages and resume from {next_stage}.
+Your progress has been checkpointed on GitHub Issue #{phase_issue_number}. Re-run `/maxsim:plan {phase_number}` after /clear -- it will detect completed stages from GitHub and resume from {next_stage}.
 ```
 
-The stage detection in step 3 handles resume automatically -- completed stages produce artifacts (CONTEXT.md, RESEARCH.md, PLAN.md) that are detected on re-entry.
+The stage detection in step 3 handles resume automatically -- completed stages produce marker comments (`<!-- maxsim:type=context -->`, `<!-- maxsim:type=research -->`, `<!-- maxsim:type=plan -->`) that are detected on re-entry.
 
 ## 9. Update State
 
@@ -212,20 +224,22 @@ After all stages complete, update STATE.md:
 ```bash
 node .claude/maxsim/bin/maxsim-tools.cjs state record-session \
   --stopped-at "Phase ${PHASE} planned" \
-  --resume-file "${phase_dir}"
+  --resume-file "GitHub Issue #${phase_issue_number}"
 ```
 
 </process>
 
 <success_criteria>
 - [ ] Phase validated against roadmap
-- [ ] Current stage correctly detected from artifacts
-- [ ] Re-entry flow works for already-planned phases
+- [ ] Phase GitHub Issue created if it does not exist
+- [ ] Current stage correctly detected from GitHub Issue comments (not local files)
+- [ ] Re-entry flow works for already-planned phases (reads plan comments from GitHub)
 - [ ] Discussion stage delegates to plan-discuss.md sub-workflow
 - [ ] Research stage delegates to plan-research.md sub-workflow
 - [ ] Planning stage delegates to plan-create.md sub-workflow
 - [ ] Gate confirmation shown after each stage transition
 - [ ] User confirms before advancing to next stage
-- [ ] Checkpoint-before-clear pattern available
+- [ ] Checkpoint-before-clear posts to GitHub Issue and resumes via GitHub detection
 - [ ] No stage-specific logic inline -- all delegated to sub-workflows
 </success_criteria>
+</output>