maxsimcli 4.11.0 → 4.12.0

package/dist/assets/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [4.11.0](https://github.com/maystudios/maxsimcli/compare/v4.10.0...v4.11.0) (2026-03-11)
+
+
+### Features
+
+* **workflows:** wire mcp_github_setup and phase issue creation into init workflows ([fe30a97](https://github.com/maystudios/maxsimcli/commit/fe30a979957e9a480fc6e98bc9e60d51d2f428e2))
+
 # [4.10.0](https://github.com/maystudios/maxsimcli/compare/v4.9.0...v4.10.0) (2026-03-11)
 
 

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

@@ -1,7 +1,7 @@
 <purpose>
-Planning stage sub-workflow for /maxsim:plan. Spawns the planner agent to create PLAN.md files, then optionally spawns the planner (in plan-checking mode) for verification with a revision loop.
+Planning stage sub-workflow for /maxsim:plan. Spawns the planner agent to create plan content, posts plans to GitHub as comments on the phase issue, creates task sub-issues, and moves the phase board card to "In Progress". Optionally spawns the planner (in plan-checking mode) for verification with a revision loop.
 
-This file is loaded by the plan.md orchestrator. It does NOT handle gate confirmations or stage routing -- the orchestrator handles that. This sub-workflow focuses ONLY on creating and verifying plans.
+This file is loaded by the plan.md orchestrator. It does NOT handle gate confirmations or stage routing -- the orchestrator handles that. This sub-workflow focuses ONLY on creating, verifying, and publishing plans to GitHub.
 </purpose>
 
 <process>
@@ -15,6 +15,7 @@ The orchestrator provides phase context. Verify we have what we need:
 - `commit_docs`
 - `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`
 - `phase_req_ids` (requirement IDs that this phase must address)
+- `phase_issue_number` (GitHub Issue number for the phase)
 - `--skip-verify` flag presence
 
 ## Step 2: Resolve Models
@@ -26,38 +27,40 @@ CHECKER_MODEL=$(node .claude/maxsim/bin/maxsim-tools.cjs resolve-model planner -
 
 ## Step 3: Check Existing Plans
 
-```bash
-ls "${phase_dir}"/*-PLAN.md 2>/dev/null
+Query the phase GitHub Issue for existing plan comments:
+```
+mcp_get_issue_detail(issue_number={phase_issue_number})
 ```
 
-**If plans exist:** Offer options via natural conversation:
+Look for comments that contain `<!-- maxsim:type=plan -->`.
+
+**If plan comment(s) exist:** Offer options via natural conversation:
 ```
-Phase {phase_number} already has plan(s):
-{list of existing plan files}
+Phase {phase_number} already has plan(s) on GitHub Issue #{phase_issue_number}.
 
 1. Add more plans (keep existing)
 2. View existing plans
-3. Re-plan from scratch (deletes existing plans)
+3. Re-plan from scratch (deletes existing plan comments)
 ```
 
 - If "Add more": Continue to Step 4 with existing plans preserved.
-- If "View": Display plan files, then re-offer options.
-- If "Re-plan": Delete existing PLAN.md files, continue to Step 4.
+- If "View": Display plan comment contents, then re-offer options.
+- If "Re-plan": Delete existing plan comments from the issue, continue to Step 4.
 
-**If no plans exist:** Continue to Step 4.
+**If no plan comments exist:** Continue to Step 4.
 
 ## Step 4: Gather Context Paths
 
-Extract file paths from the orchestrator context (provided via init JSON):
+Extract file paths and GitHub context from the orchestrator context (provided via init JSON):
 
 ```bash
 STATE_PATH=$(echo "$INIT" | jq -r '.state_path // empty')
 ROADMAP_PATH=$(echo "$INIT" | jq -r '.roadmap_path // empty')
 REQUIREMENTS_PATH=$(echo "$INIT" | jq -r '.requirements_path // empty')
-RESEARCH_PATH=$(echo "$INIT" | jq -r '.research_path // empty')
-CONTEXT_PATH=$(echo "$INIT" | jq -r '.context_path // empty')
 ```
 
+Context and research content will be read from GitHub Issue #{phase_issue_number} comments (identified by `<!-- maxsim:type=context -->` and `<!-- maxsim:type=research -->` markers) rather than from local files.
+
 ## Step 5: Spawn Planner
 
 Display:
@@ -65,20 +68,20 @@ Display:
 Planning Phase {phase_number}: {phase_name}...
 ```
 
-Construct the planner prompt:
+Construct the planner prompt. The planner must return plan content as structured markdown in its response (not write local files):
 
 ```markdown
 <planning_context>
 **Phase:** {phase_number}
 **Mode:** standard
 
-<files_to_read>
+<context_sources>
+- GitHub Issue #{phase_issue_number} context comment (USER DECISIONS -- locked choices from discussion stage)
+- GitHub Issue #{phase_issue_number} research comment (Technical Research findings)
 - {state_path} (Project State)
 - {roadmap_path} (Roadmap)
 - {requirements_path} (Requirements)
-- {context_path} (USER DECISIONS from discussion stage)
-- {research_path} (Technical Research)
-</files_to_read>
+</context_sources>
 
 **Phase requirement IDs (every ID MUST appear in a plan's `requirements` field):** {phase_req_ids}
 
@@ -87,16 +90,31 @@ Construct the planner prompt:
 </planning_context>
 
 <downstream_consumer>
-Output consumed by /maxsim:execute. Plans need:
+Output consumed by /maxsim:execute via GitHub Issue comments. Plans need:
 - Frontmatter (wave, depends_on, files_modified, autonomous)
 - Tasks in XML format
 - Verification criteria
 - must_haves for goal-backward verification
 </downstream_consumer>
 
+<output_format>
+Return each plan as a separate fenced code block with a plan number header.
+Do NOT write local PLAN.md files -- plans will be posted to GitHub by the orchestrator.
+
+Example structure:
+## Plan 01
+
+```yaml
+# frontmatter here
+```
+
+<tasks>
+...
+</tasks>
+</output_format>
+
 <quality_gate>
-- [ ] PLAN.md files created in phase directory
-- [ ] Each plan has valid frontmatter
+- [ ] Each plan returned in response with valid frontmatter
 - [ ] Tasks are specific and actionable
 - [ ] Dependencies correctly identified
 - [ ] Waves assigned for parallel execution
@@ -120,18 +138,16 @@ Task(
 Parse the planner's return message:
 
 - **`## PLANNING COMPLETE`:**
-  Validate PLAN.md files were created:
-  ```bash
-  ls "${phase_dir}"/*-PLAN.md 2>/dev/null | wc -l
-  ```
+  Extract the plan content from the planner's response. Parse out individual plans (each is a separate fenced block with a plan number header).
 
-  If plans found:
-  - Display plan count and filenames.
+  If plans found in response:
+  - Display plan count.
+  - Store plans in memory as `plans_content` array.
   - If `--skip-verify` flag is set OR `plan_checker_enabled` is false: skip to Step 9.
   - Otherwise: continue to Step 7 (verification).
 
-  If no plans found:
-  - Error: "Planner reported complete but no PLAN.md files found."
+  If no plans in response:
+  - Error: "Planner reported complete but returned no plan content."
   - Offer: retry or abort.
 
 - **`## CHECKPOINT REACHED`:**
@@ -157,20 +173,23 @@ Display:
 Verifying plans...
 ```
 
-Construct the checker prompt:
+Construct the checker prompt. Pass the in-memory `plans_content` directly:
 
 ```markdown
 <verification_context>
 **Phase:** {phase_number}
 **Phase Goal:** {goal from ROADMAP}
 
-<files_to_read>
-- {phase_dir}/*-PLAN.md (Plans to verify)
+<plans_to_verify>
+{plans_content -- the plan(s) returned by the planner in step 5}
+</plans_to_verify>
+
+<context_sources>
+- GitHub Issue #{phase_issue_number} context comment (USER DECISIONS)
+- GitHub Issue #{phase_issue_number} research comment (Technical Research)
 - {roadmap_path} (Roadmap)
 - {requirements_path} (Requirements)
-- {context_path} (USER DECISIONS from discussion stage)
-- {research_path} (Technical Research)
-</files_to_read>
+</context_sources>
 
 **Phase requirement IDs (MUST ALL be covered):** {phase_req_ids}
 
@@ -214,17 +233,20 @@ Task(
   Sending plans back for revision... (iteration {iteration_count}/3)
   ```
 
-  Construct revision prompt:
+  Construct revision prompt. Pass the current in-memory `plans_content` directly:
 
   ```markdown
   <revision_context>
   **Phase:** {phase_number}
   **Mode:** revision
 
-  <files_to_read>
-  - {phase_dir}/*-PLAN.md (Existing plans)
-  - {context_path} (USER DECISIONS from discussion stage)
-  </files_to_read>
+  <existing_plans>
+  {plans_content -- current in-memory plan content}
+  </existing_plans>
+
+  <context_sources>
+  - GitHub Issue #{phase_issue_number} context comment (USER DECISIONS)
+  </context_sources>
 
   **Checker issues:** {structured_issues_from_checker}
   </revision_context>
@@ -232,7 +254,7 @@ Task(
   <instructions>
   Make targeted updates to address checker issues.
   Do NOT replan from scratch unless issues are fundamental.
-  Return what changed.
+  Return the full revised plan content (same format as original -- one fenced block per plan).
   </instructions>
   ```
 
@@ -267,32 +289,98 @@ Task(
   - If "Provide guidance": Get user input, re-spawn planner with user guidance, reset iteration_count, go to Step 7.
   - If "Abort": Exit workflow.
 
-## Step 9: Commit Plans
+## Step 9: Post Plans to GitHub
 
-If `commit_docs` is true:
+After verification passes (or is skipped), post each plan as a separate comment on the phase GitHub Issue.
 
-```bash
-node .claude/maxsim/bin/maxsim-tools.cjs commit "docs(${padded_phase}): create phase plan" --files "${phase_dir}"
+For each plan in `plans_content`:
+
+```
+mcp_post_plan_comment(
+  phase_issue_number={phase_issue_number},
+  plan_number={plan_number},  // e.g. "01", "02"
+  plan_content="<!-- maxsim:type=plan -->\n" + {plan_content}
+)
+```
+
+If posting any plan comment fails:
+- Report which plans failed to post.
+- Offer retry for failed plans.
+- Do not proceed to task creation until all plans are successfully posted.
+
+Display:
+```
+Plans posted to GitHub Issue #{phase_issue_number}: {plan_count} plan(s).
+```
+
+## Step 10: Create Task Sub-Issues
+
+Parse tasks from the posted plans. For each `<task>` element in the plan XML, extract:
+- `id` (e.g. "1.1", "1.2")
+- `title`
+- `description` / body content
+
+Call `mcp_batch_create_tasks` with the full tasks array and the phase issue number:
+
+```
+mcp_batch_create_tasks(
+  phase_issue_number={phase_issue_number},
+  tasks=[
+    { id: "1.1", title: "Task title", description: "Task body" },
+    ...
+  ]
+)
+```
+
+Each task becomes a GitHub sub-issue linked to the phase issue.
+
+**If batch creation fails (partial or total):**
+- Report which task IDs failed to create.
+- Offer: retry failed tasks, skip and continue, or abort.
+- Do not proceed to board transition until task creation succeeds or user accepts partial failure.
+
+Display:
+```
+Task sub-issues created: {task_count} tasks linked to Issue #{phase_issue_number}.
+```
+
+## Step 11: Move Phase to In Progress
+
+After all plans are posted and task sub-issues are created, move the phase issue to "In Progress" on the project board:
+
+```
+mcp_move_issue(
+  issue_number={phase_issue_number},
+  status="In Progress"
+)
+```
+
+Display:
+```
+Phase #{phase_issue_number} moved to "In Progress" on the board.
 ```
 
-## Step 10: Return to Orchestrator
+## Step 12: Return to Orchestrator
 
-After plans are created and optionally verified, return control to the plan.md orchestrator. Do NOT show gate confirmation or next steps -- the orchestrator handles the final gate.
+After plans are posted, task sub-issues created, and the phase moved to "In Progress", return control to the plan.md orchestrator. Do NOT show gate confirmation or next steps -- the orchestrator handles the final gate.
 
 Display a brief completion message:
 ```
-Planning complete. {plan_count} plan(s) created in {phase_dir}.
+Planning complete. {plan_count} plan(s) posted to GitHub Issue #{phase_issue_number}. {task_count} task sub-issues created.
 ```
 
 </process>
 
 <success_criteria>
 - Planner and checker models resolved from config
-- Existing plans detected and handled (add/view/replan options)
-- Planner agent spawned with full context (STATE.md, ROADMAP.md, REQUIREMENTS.md, CONTEXT.md, RESEARCH.md)
-- PLAN.md files created and validated
+- Existing plans detected from GitHub Issue comments and handled (add/view/replan options)
+- Planner agent spawned with context from GitHub Issue comments (context + research) and local files (state, roadmap, requirements)
+- Plan content returned from planner as in-memory document (no local PLAN.md files written)
 - Checker verification loop runs (max 3 iterations) unless --skip-verify
-- Revision loop sends issues back to planner for targeted fixes
-- Plan files committed if commit_docs is true
+- Revision loop passes in-memory plan content to planner for targeted fixes
+- Plans posted to GitHub Issue #{phase_issue_number} as comments with <!-- maxsim:type=plan --> markers
+- Task sub-issues created via mcp_batch_create_tasks linked to phase issue
+- Phase issue moved to "In Progress" via mcp_move_issue
+- Failed task creation surfaced with retry option (WIRE-07)
 - Control returned to orchestrator without showing gate or next steps
 </success_criteria>

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>

package/package.json

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