maxsimcli 4.15.4 → 5.0.0

package/dist/assets/templates/workflows/init-existing.md

@@ -108,16 +108,16 @@ Parse init context for `has_github_remote` and `gh_authenticated`:
      ```
    - Do NOT proceed with initialization.
 
-3. Both checks passed — call `mcp_github_setup` with the project name as the milestone title:
-   ```
-   mcp_github_setup({ milestone_title: "[project name]" })
+3. Both checks passed — run `github setup` with the project name as the milestone title:
+   ```bash
+   node ~/.claude/maxsim/bin/maxsim-tools.cjs github setup --milestone-title "[project name]"
    ```
 
-4. If `mcp_github_setup` fails:
+4. If `github setup` fails:
    - STOP with the error message returned by the tool.
    - Do not fall back to local-only mode.
 
-5. Record the `project_number` and board details returned by `mcp_github_setup` for use in the Phase Issue Creation step.
+5. Record the `project_number` and board details returned by `github setup` for use in the Phase Issue Creation step.
 
 ## Step 2: Conflict Resolution
 
@@ -1174,15 +1174,12 @@ Display banner:
    - `requirements` (list of REQ-IDs mapped to this phase)
    - `success_criteria` (list of observable outcomes)
 
-2. For each phase, call `mcp_create_phase_issue`:
-   ```
-   mcp_create_phase_issue({
-     phase_number: "[phase_number]",
-     phase_name: "[phase_name]",
-     goal: "[goal]",
-     requirements: ["REQ-01", "REQ-02", ...],
-     success_criteria: ["criterion 1", "criterion 2", ...]
-   })
+2. For each phase, run `github create-phase`:
+   ```bash
+   node ~/.claude/maxsim/bin/maxsim-tools.cjs github create-phase \
+     --phase-number "[phase_number]" \
+     --phase-name "[phase_name]" \
+     --goal "[goal]"
    ```
    The tool auto-adds each issue to the project board with "To Do" status.
 
@@ -1457,7 +1454,7 @@ Print next steps:
 - [ ] Git repo initialized (if not already)
 - [ ] GitHub remote detected (gate passed)
 - [ ] GitHub CLI authenticated (gate passed)
-- [ ] `mcp_github_setup` called successfully — project_number recorded
+- [ ] `github setup` called successfully — project_number recorded
 - [ ] Conflict detection completed (merge/overwrite/cancel dialog)
 - [ ] Codebase scan completed (4 mapper agents spawned)
 - [ ] README validated against scan findings
@@ -1469,7 +1466,7 @@ Print next steps:
 - [ ] PROJECT.md created with brownfield extra sections
 - [ ] REQUIREMENTS.md created with stage-aware format
 - [ ] ROADMAP.md created with 3-5 concrete phases (no TBD)
-- [ ] `mcp_create_phase_issue` called for every phase — all issues on board with "To Do" status
+- [ ] `github create-phase` called for every phase — all issues on board with "To Do" status
 - [ ] STATE.md created with pre-populated decisions and blockers
 - [ ] config.json created with workflow settings
 - [ ] .planning/codebase/ populated with scan documents

package/dist/assets/templates/workflows/new-milestone.md

@@ -333,6 +333,26 @@ Success criteria:
 node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
 ```
 
+## 10b. Create Phase Tracking Issues on GitHub
+
+**This step is MANDATORY — GitHub Issues are the single source of truth for phase tracking.**
+
+For each phase in the roadmap, run `github create-phase` to create a tracking issue:
+
+```bash
+# For each phase:
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github create-phase \
+  --phase-number "[N]" \
+  --phase-name "[Phase Name]" \
+  --goal "[Phase Goal from ROADMAP.md]"
+```
+
+Track results. If any phase issue creation fails, warn and suggest manual creation.
+
+```
+✓ Created {N} phase issues on GitHub Project Board
+```
+
 ## 11. Done
 
 ```
@@ -348,8 +368,9 @@ node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: create milestone v[X.Y]
 | Research       | `.planning/research/`       |
 | Requirements   | `.planning/REQUIREMENTS.md` |
 | Roadmap        | `.planning/ROADMAP.md`      |
+| Phase Issues   | GitHub Project Board        |
 
-**[N] phases** | **[X] requirements** | Ready to build ✓
+**[N] phases** | **[X] requirements** | **[N] GitHub issues** | Ready to build ✓
 
 ## ▶ Next Up
 
@@ -375,6 +396,7 @@ Also: `/maxsim:plan [N]` — skip discussion, plan directly
 - [ ] Roadmap files written immediately (not draft)
 - [ ] User feedback incorporated (if any)
 - [ ] ROADMAP.md phases continue from previous milestone
+- [ ] `github create-phase` called for every phase — all issues on GitHub board
 - [ ] All commits made (if planning docs committed)
 - [ ] User knows next step: `/maxsim:plan [N]`
 

package/dist/assets/templates/workflows/new-project.md

@@ -100,16 +100,16 @@ Parse init context for `has_github_remote` and `gh_authenticated`:
      ```
    - Do NOT proceed with project setup.
 
-3. Both checks passed — call `mcp_github_setup` with the project name as the milestone title:
-   ```
-   mcp_github_setup({ milestone_title: "[project name]" })
+3. Both checks passed — run `github setup` with the project name as the milestone title:
+   ```bash
+   node ~/.claude/maxsim/bin/maxsim-tools.cjs github setup --milestone-title "[project name]"
    ```
 
-4. If `mcp_github_setup` fails:
+4. If `github setup` fails:
    - STOP with the error message returned by the tool.
    - Do not fall back to local-only mode.
 
-5. Record the `project_number` and board details returned by `mcp_github_setup` for use in the Phase Issue Creation step.
+5. Record the `project_number` and board details returned by `github setup` for use in the Phase Issue Creation step.
 
 ## 2. Brownfield Offer
 
@@ -1318,15 +1318,12 @@ Display banner:
    - `requirements` (list of REQ-IDs mapped to this phase)
    - `success_criteria` (list of observable outcomes)
 
-2. For each phase, call `mcp_create_phase_issue`:
-   ```
-   mcp_create_phase_issue({
-     phase_number: "[phase_number]",
-     phase_name: "[phase_name]",
-     goal: "[goal]",
-     requirements: ["REQ-01", "REQ-02", ...],
-     success_criteria: ["criterion 1", "criterion 2", ...]
-   })
+2. For each phase, run `github create-phase`:
+   ```bash
+   node ~/.claude/maxsim/bin/maxsim-tools.cjs github create-phase \
+     --phase-number "[phase_number]" \
+     --phase-name "[phase_name]" \
+     --goal "[goal]"
    ```
    The tool auto-adds each issue to the project board with "To Do" status.
 
@@ -1487,7 +1484,7 @@ Exit skill and invoke SlashCommand("/maxsim:plan 1 --auto")
 - [ ] REQUIREMENTS.md created with REQ-IDs → **committed**
 - [ ] GitHub remote detected (gate passed)
 - [ ] GitHub CLI authenticated (gate passed)
-- [ ] `mcp_github_setup` called successfully — project_number recorded
+- [ ] `github setup` called successfully — project_number recorded
 - [ ] planner (roadmap mode) spawned with context
 - [ ] Roadmap files written immediately (not draft)
 - [ ] User feedback incorporated (if any)
@@ -1496,7 +1493,7 @@ Exit skill and invoke SlashCommand("/maxsim:plan 1 --auto")
 - [ ] REQUIREMENTS.md traceability updated
 - [ ] CONVENTIONS.md generated with 4 must-have sections (Tech Stack, File Layout, Error Handling, Testing)
 - [ ] NO-GOS.md populated from confirmed no-gos during questioning
-- [ ] `mcp_create_phase_issue` called for every phase — all issues on board with "To Do" status
+- [ ] `github create-phase` called for every phase — all issues on board with "To Do" status
 - [ ] Agent dry-run validation passed (Quality Score >= 7)
 - [ ] User knows next step is `/maxsim:plan 1`
 

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

@@ -28,8 +28,8 @@ CHECKER_MODEL=$(node .claude/maxsim/bin/maxsim-tools.cjs resolve-model planner -
 ## Step 3: Check Existing Plans
 
 Query the phase GitHub Issue for existing plan comments:
-```
-mcp_get_issue_detail(issue_number={phase_issue_number})
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github get-issue $PHASE_ISSUE_NUMBER --comments
 ```
 
 Look for comments that contain `<!-- maxsim:type=plan -->`.
@@ -295,12 +295,13 @@ After verification passes (or is skipped), post each plan as a separate comment
 
 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}
-)
+```bash
+TMPFILE=$(mktemp)
+cat > "$TMPFILE" << 'BODY_EOF'
+<!-- maxsim:type=plan -->
+{plan_content}
+BODY_EOF
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github post-plan-comment --phase-issue-number $PHASE_ISSUE_NUMBER --plan-number "{plan_number}" --plan-content-file "$TMPFILE"
 ```
 
 If posting any plan comment fails:
@@ -320,16 +321,10 @@ Parse tasks from the posted plans. For each `<task>` element in the plan XML, ex
 - `title`
 - `description` / body content
 
-Call `mcp_batch_create_tasks` with the full tasks array and the phase issue number:
+Run `github 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" },
-    ...
-  ]
-)
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github batch-create-tasks --phase-number "$PHASE_NUMBER" --parent-issue-number $PHASE_ISSUE_NUMBER --tasks-json '[{"id":"1.1","title":"Task title","description":"Task body"}, ...]'
 ```
 
 Each task becomes a GitHub sub-issue linked to the phase issue.
@@ -348,11 +343,8 @@ Task sub-issues created: {task_count} tasks linked to Issue #{phase_issue_number
 
 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"
-)
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github move-issue --issue-number $PHASE_ISSUE_NUMBER --status "In Progress"
 ```
 
 Display:
@@ -379,8 +371,8 @@ Planning complete. {plan_count} plan(s) posted to GitHub Issue #{phase_issue_num
 - Checker verification loop runs (max 3 iterations) unless --skip-verify
 - 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
+- Task sub-issues created via `github batch-create-tasks` linked to phase issue
+- Phase issue moved to "In Progress" via `github 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

@@ -140,8 +140,8 @@ Also extract `phase_issue_number` passed from the orchestrator.
 ## Step 2: Check Existing Context
 
 Check if a context comment already exists on the phase GitHub Issue by calling:
-```
-mcp_get_issue_detail(issue_number={phase_issue_number})
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github get-issue $PHASE_ISSUE_NUMBER --comments
 ```
 
 Look for a comment that contains `<!-- maxsim:type=context -->`.
@@ -313,12 +313,10 @@ Build the context content in memory, then post it as a comment on the phase GitH
 ```
 
 Post the comment to GitHub:
-```
-mcp_post_comment(
-  issue_number={phase_issue_number},
-  type="context",
-  content={context_content_above}
-)
+```bash
+TMPFILE=$(mktemp)
+echo "$CONTEXT_CONTENT" > "$TMPFILE"
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github post-comment --issue-number $PHASE_ISSUE_NUMBER --body-file "$TMPFILE" --type context
 ```
 
 Context decisions are posted as a GitHub comment on phase issue #{phase_issue_number}. No local CONTEXT.md file is written.

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

@@ -117,12 +117,13 @@ Parse the researcher's return message:
   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}
-  )
+  ```bash
+  TMPFILE=$(mktemp)
+  cat > "$TMPFILE" << 'BODY_EOF'
+  <!-- maxsim:type=research -->
+  {research_findings_document}
+  BODY_EOF
+  node ~/.claude/maxsim/bin/maxsim-tools.cjs github post-comment --issue-number $PHASE_ISSUE_NUMBER --body-file "$TMPFILE" --type research
   ```
 
   Research findings are posted as a GitHub comment on phase issue #{phase_issue_number}. No local RESEARCH.md file is written.

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

@@ -45,9 +45,9 @@ Detect planning stage by querying the phase GitHub Issue:
 
 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).
+   - Run `node ~/.claude/maxsim/bin/maxsim-tools.cjs github create-phase --phase-number "$PHASE_NUMBER" --phase-name "$PHASE_NAME" --goal "$GOAL" --requirements "$REQUIREMENTS" --success-criteria "$SUCCESS_CRITERIA"` 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.
+3. Run `node ~/.claude/maxsim/bin/maxsim-tools.cjs github get-issue $PHASE_ISSUE_NUMBER --comments` 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
@@ -104,8 +104,8 @@ Pass context: `phase_number`, `phase_name`, `phase_dir`, `padded_phase`, `phase_
 **After discussion completes (context posted as GitHub comment):**
 
 Re-query the phase issue to verify the `type=context` comment now exists:
-```
-mcp_get_issue_detail(issue_number={phase_issue_number})
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github get-issue $PHASE_ISSUE_NUMBER --comments
 ```
 
 Show gate:
@@ -139,8 +139,8 @@ Pass context: `phase_number`, `phase_name`, `phase_dir`, `padded_phase`, `phase_
 **After research completes (research posted as GitHub comment or already exists):**
 
 Re-query the phase issue to verify the `type=research` comment now exists:
-```
-mcp_get_issue_detail(issue_number={phase_issue_number})
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github get-issue $PHASE_ISSUE_NUMBER --comments
 ```
 
 Show gate:
@@ -171,8 +171,8 @@ Pass context: `phase_number`, `phase_name`, `phase_dir`, `padded_phase`, `phase_
 **After planning completes (plans posted as GitHub comments and task sub-issues created):**
 
 Re-query the phase issue to verify `type=plan` comments exist:
-```
-mcp_get_issue_detail(issue_number={phase_issue_number})
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github get-issue $PHASE_ISSUE_NUMBER --comments
 ```
 
 Show final gate:
@@ -200,12 +200,19 @@ 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:
-```
-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}"
-)
+```bash
+TMPFILE=$(mktemp)
+cat > "$TMPFILE" << 'BODY_EOF'
+## MAXSIM Checkpoint
+
+**Command:** /maxsim:plan
+**Stage:** {current_stage} ({stage_num}/3)
+**Completed:**
+{list of completed stages with summaries}
+**Resume from:** {next_stage}
+**Timestamp:** {ISO timestamp}
+BODY_EOF
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github post-comment --issue-number $PHASE_ISSUE_NUMBER --body-file "$TMPFILE" --type checkpoint
 ```
 
 2. Display checkpoint recommendation:

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

@@ -54,10 +54,13 @@ This minimizes orchestrator context usage.
 <step name="live_github_phase_overview">
 **Get live phase status from GitHub (primary source — always-live, no cached state):**
 
-Call `mcp_get_all_progress` to get progress for all phases. This returns live data from GitHub Issues:
-- `phase_number`, `title`, `issue_number`
-- `total_tasks`, `completed_tasks`, `remaining_tasks`
-- `status` (the GitHub board column: To Do / In Progress / In Review / Done)
+Run `github all-progress` to get progress for all phases. This returns live data from GitHub Issues:
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github all-progress
+```
+
+Returns: `phase_number`, `title`, `issue_number`, `total_tasks`, `completed_tasks`, `remaining_tasks`, `status` (the GitHub board column: To Do / In Progress / In Review / Done)
 
 Display as formatted table:
 
@@ -72,7 +75,11 @@ Display as formatted table:
 
 **Also get board column view:**
 
-Call `mcp_query_board` with the project number (from init context / config). Group items by status column (To Do, In Progress, In Review, Done). Display column counts and issue details:
+Run `github query-board` with the project number (from init context / config). Group items by status column (To Do, In Progress, In Review, Done). Display column counts and issue details:
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github query-board --project-number PROJECT_NUMBER
+```
 
 ```
 ## Board Status (Live)
@@ -85,23 +92,31 @@ Call `mcp_query_board` with the project number (from init context / config). Gro
 | Done        | 3     | #9, #10, #11 |
 ```
 
-**Cross-validate with local ROADMAP.md:**
-- Run `ROADMAP=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap analyze)` to get local phase data
-- Compare local completion status against GitHub board status
-- Highlight any discrepancies between local and GitHub state in the Issues Detected section
+**Cross-reference with local ROADMAP.md (for phase ordering only -- GitHub is authoritative for status):**
+- Run `ROADMAP=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap analyze)` to get local phase ordering data
+- If local ROADMAP phase list differs from GitHub Issues, note in Issues Detected section (GitHub is the source of truth)
 </step>
 
 <step name="live_github_detail">
 **Per-phase detail (when user requests or for current phase):**
 
 For the current active phase (or any phase requested by user):
-- Call `mcp_get_phase_progress` with the phase issue number to get task-level progress
-- Call `mcp_list_sub_issues` to get individual task status with sub-issue details
+- Run `github phase-progress` with the phase issue number to get task-level progress
+- Run `github list-sub-issues` to get individual task status with sub-issue details
 - Display task breakdown with status indicators (✓ done / ⏳ in progress / ○ to do)
 
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github phase-progress --phase-issue-number N
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github list-sub-issues N
+```
+
 **Detect external edits:**
 
-After reading phase data from GitHub, call `mcp_detect_external_edits` for each phase with the stored `body_hash`. Warn in the Issues Detected section if modifications were detected outside the normal workflow.
+After reading phase data from GitHub, run `github detect-external-edits` for each phase with the stored `body_hash`. Warn in the Issues Detected section if modifications were detected outside the normal workflow.
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github detect-external-edits --phase-number "XX"
+```
 </step>
 
 <step name="position">
@@ -109,8 +124,13 @@ After reading phase data from GitHub, call `mcp_detect_external_edits` for each
 
 - Use `current_phase` and `next_phase` from `$ROADMAP` (local) cross-referenced with GitHub board status
 - Note `paused_at` if work was paused (from `$STATE`)
-- Count pending todos: use `mcp_list_todos` for live todo count
-- Check for interrupted phases via `mcp_detect_interrupted`
+- Count pending todos: run `github list-todos` for live todo count
+- Check for interrupted phases via `github detect-interrupted`
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github list-todos --status pending
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github detect-interrupted --phase-issue-number N
+```
 </step>
 
 <step name="report">
@@ -130,10 +150,10 @@ Present (GitHub Issues is the primary progress source; local ROADMAP is cross-va
 **Profile:** [quality/balanced/budget]
 
 ## GitHub Issues Progress (Live)
-[formatted table from mcp_get_all_progress — see live_github_phase_overview step]
+[formatted table from github all-progress — see live_github_phase_overview step]
 
 ## Board Status (Live)
-[column view from mcp_query_board — see live_github_phase_overview step]
+[column view from github query-board — see live_github_phase_overview step]
 
 ## Current Position
 Phase [N] of [total]: [phase-name]
@@ -175,14 +195,18 @@ When displaying the performance metrics table from STATE.md (the `## Performance
 
 **Step 1: Get live phase state from GitHub**
 
-Call `mcp_get_all_progress` (already fetched above). Identify:
+Use `github all-progress` output (already fetched above). Identify:
 - Phases with status "In Progress" that have remaining tasks
 - Phases with status "To Do" (not yet started)
 - Phases with status "Done"
 
 **Step 1.5: Check for interrupted or external edit issues**
 
-Call `mcp_detect_interrupted` to check for any phases that were interrupted mid-execution. If any are found, note them — they take priority over new work.
+Run `github detect-interrupted` to check for any phases that were interrupted mid-execution. If any are found, note them — they take priority over new work.
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github detect-interrupted --phase-issue-number N
+```
 
 **Step 2: Route based on live GitHub status**
 
@@ -197,7 +221,7 @@ Call `mcp_detect_interrupted` to check for any phases that were interrupted mid-
 
 **Route A: Phase in progress or interrupted — continue execution**
 
-Identify the in-progress or interrupted phase (from `mcp_get_all_progress` or `mcp_detect_interrupted`).
+Identify the in-progress or interrupted phase (from `github all-progress` or `github detect-interrupted`).
 
 ```
 ---
@@ -217,9 +241,9 @@ Identify the in-progress or interrupted phase (from `mcp_get_all_progress` or `m
 
 **Route B: Phase needs planning**
 
-Check if `{phase_num}-CONTEXT.md` exists in phase directory.
+Check if a `<!-- maxsim:type=context -->` comment exists on the phase GitHub Issue.
 
-**If CONTEXT.md exists:**
+**If context comment exists:**
 
 ```
 ---
@@ -236,7 +260,7 @@ Check if `{phase_num}-CONTEXT.md` exists in phase directory.
 ---
 ```
 
-**If CONTEXT.md does NOT exist:**
+**If no context comment exists:**
 
 ```
 ---
@@ -244,7 +268,7 @@ Check if `{phase_num}-CONTEXT.md` exists in phase directory.
 ## ▶ Next Up
 
 **Phase {N}: {Name}** — {Goal from ROADMAP.md}
-<sub>No context yet — /maxsim:plan will start with discussion</sub>
+<sub>No context comment yet — /maxsim:plan will start with discussion</sub>
 
 `/maxsim:plan {phase}`
 
@@ -335,8 +359,8 @@ Ready to plan the next milestone.
 - All work complete → offer milestone completion via `/maxsim:init`
 - Blockers present → highlight before offering to continue
 - External edits detected → surface in Issues Detected section before routing
-- Discrepancy between local ROADMAP and GitHub board → surface in Issues Detected, ask user to reconcile
-- GitHub not available (mcp calls fail) → fall back to local ROADMAP analysis and note degraded mode
+- Discrepancy between local ROADMAP and GitHub board → surface in Issues Detected (GitHub is authoritative)
+- GitHub not available (CLI calls fail) → show error: "GitHub integration required for progress tracking. Run `/maxsim:init` to configure GitHub." Do NOT fall back to local file scanning.
   </step>
 
 </process>
@@ -344,11 +368,11 @@ Ready to plan the next milestone.
 <success_criteria>
 
 - [ ] Rich context provided (decisions, blockers, issues)
-- [ ] GitHub Issues progress shown as primary source (always-live reads via mcp_get_all_progress)
-- [ ] Board column view shown via mcp_query_board
-- [ ] Per-phase task detail available via mcp_get_phase_progress and mcp_list_sub_issues
-- [ ] External edit detection via mcp_detect_external_edits
-- [ ] Cross-validation between local ROADMAP.md and GitHub board status
+- [ ] GitHub Issues progress shown as primary source (always-live reads via `github all-progress`)
+- [ ] Board column view shown via `github query-board`
+- [ ] Per-phase task detail available via `github phase-progress` and `github list-sub-issues`
+- [ ] External edit detection via `github detect-external-edits`
+- [ ] Cross-reference local ROADMAP.md for phase ordering (GitHub is authoritative for status)
 - [ ] Phase gaps and discrepancies detected and surfaced in Issues Detected section
 - [ ] Current position clear with visual progress
 - [ ] What's next clearly explained

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

@@ -5,13 +5,13 @@ Before executing any step in this workflow, verify:
 </sanity_check>
 
 <purpose>
-Execute small, ad-hoc tasks with MAXSIM guarantees (atomic commits, STATE.md tracking). Also supports "save for later" todo capture -- managing ideas as local todos with best-effort GitHub Issue creation.
+Execute small, ad-hoc tasks with MAXSIM guarantees (atomic commits, STATE.md tracking). Also supports "save for later" todo capture via GitHub Issues.
 
-Quick mode spawns planner (quick mode) + executor(s), tracks tasks in `.planning/quick/`, and updates STATE.md's "Quick Tasks Completed" table.
+Quick mode spawns planner (quick mode) + executor(s), tracks tasks as GitHub Issues (label: "quick"), and updates STATE.md's "Quick Tasks Completed" table.
 
 With `--full` flag: enables plan-checking (max 2 iterations) and post-execution verification for quality guarantees without full milestone ceremony.
 
-With `--todo` flag (or trigger words): enters Todo Mode for listing, capturing, completing, and triaging todos.
+With `--todo` flag (or trigger words): enters Todo Mode for listing, capturing, completing, and triaging todos via GitHub Issues.
 </purpose>
 
 <required_reading>
@@ -668,11 +668,16 @@ files: []
 TBD
 ```
 
-5. Best-effort GitHub Issue creation:
-   - Always attempt: `node ~/.claude/maxsim/bin/maxsim-tools.cjs todos add "$TITLE" "$PRIORITY" 2>/dev/null || true`
-   - If `github_ready` is true in init context: also call `mcp_create_todo_issue` with title, priority, area, and description to create a tracked GitHub Issue linked to the todo file
-6. Commit: `node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: capture todo - ${TITLE}" --files .planning/todos/pending/${date}-${slug}.md`
-7. Confirm: "Saved: ${TITLE} (priority: ${PRIORITY})"
+5. GitHub Issue creation (primary):
+   - Run `github add-todo` with title, priority, area, and description to create a tracked GitHub Issue (label: "todo")
+   - If GitHub is unavailable, fall back to local file only and warn user: "Todo saved locally. Run `/maxsim:init` to enable GitHub tracking."
+
+   ```bash
+   node ~/.claude/maxsim/bin/maxsim-tools.cjs github add-todo --title "${TITLE}" --description "${DESCRIPTION}" --area "${AREA}"
+   ```
+6. Local file cache: also create the local todo file for offline access
+7. Commit: `node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: capture todo - ${TITLE}" --files .planning/todos/pending/${date}-${slug}.md`
+8. Confirm: "Saved: ${TITLE} (priority: ${PRIORITY}) — GitHub Issue #{number}"
 
 Exit after confirm.
 
@@ -683,11 +688,14 @@ Exit after confirm.
 If user references an existing todo to complete:
 
 1. Parse identifier (number from list, or title fragment)
-2. Find matching todo in `.planning/todos/pending/`
-3. Move to done: `mv ".planning/todos/pending/[filename]" ".planning/todos/done/"`
-4. Best-effort: close corresponding GitHub Issue
-5. Commit: `node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: complete todo - ${TITLE}" --files .planning/todos/done/${filename}`
-6. Confirm: "Completed: ${TITLE}"
+2. Close the corresponding GitHub Issue (primary): run `github close-issue` with the todo's issue number
+
+   ```bash
+   node ~/.claude/maxsim/bin/maxsim-tools.cjs github close-issue N
+   ```
+3. Move local cache file: `mv ".planning/todos/pending/[filename]" ".planning/todos/done/"`
+4. Commit: `node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: complete todo - ${TITLE}" --files .planning/todos/done/${filename}`
+5. Confirm: "Completed: ${TITLE} — GitHub Issue closed"
 
 Exit after confirm.