refactor: remove all .planning/ writes from MGW — let GSD manage GSD files

[snipcodeit]

Problem

MGW writes to .planning/ (GSD's state directory) in 4 places, creating bidirectional coupling that breaks GSD workflows and violates the delegation boundary. MGW should derive its roadmap from GitHub state dynamically and let GSD manage all .planning/ files.

Supersedes #33 (closed — wrong approach that added MORE .planning/ writes).

Architecture Principle

MGW owns:  .mgw/  + GitHub API (milestones, issues, labels, PRs)
GSD owns:  .planning/  (ROADMAP.md, STATE.md, config.json, phases/)

MGW reads .planning/ for context. MGW never writes .planning/.
When MGW needs GSD state to exist, it invokes GSD workflows (not writes files directly).

Current Violations

1. commands/project.md — writes ROADMAP.md (line 476-484)

After creating GitHub milestones/issues, /mgw:project writes .planning/ROADMAP.md directly.

Fix: Remove the write_roadmap step entirely. /mgw:project creates GitHub infrastructure only. The user (or MGW) then invokes /gsd:new-project or /gsd:new-milestone to create the GSD scaffold from the GitHub state.

2. commands/run.md — writes config.json + ROADMAP.md (line 212-224)

When roadmap_exists = false, /mgw:run creates minimal .planning/ scaffolding before running GSD quick tasks.

Fix: If no .planning/ exists, /mgw:run should either:

• Invoke gsd:health --repair to create valid state, OR
• Prompt user to run /gsd:new-project first, OR
• Let the GSD quick init handle it (it already creates .planning/quick/ if needed)

3. commands/run.md — creates quick task directory (line 228-230)

MGW creates .planning/quick/{num}-{slug}/ directory.

Note: This is borderline — it creates the directory, but GSD agents write the actual content. Could be acceptable as "preparing the workspace for GSD agents."

4. commands/run.md — updates STATE.md (line 395)

After quick task execution, MGW updates STATE.md with a completion row.

Fix: Let the GSD executor handle STATE.md updates (it already does this in the normal GSD workflow).

MGW's Dynamic Roadmap

MGW already stores everything it needs in .mgw/project.json:

• Milestones with GitHub numbers
• Issues with phase mapping, GSD route, pipeline stage
• Dependency graph (from blocked-by labels)

MGW's roadmap IS the GitHub state. It doesn't need a separate ROADMAP.md — it derives "what's next" from:

1. Which milestone is current (project.json.current_milestone)
2. Which issues are open/closed (GitHub API)
3. Which issues are unblocked (blocked-by labels resolved)
4. Pipeline stage per issue (project.json.pipeline_stage)

Expected Behavior After Fix

/mgw:project  →  Creates GitHub milestones, issues, labels, project board
                  Writes .mgw/project.json
                  Does NOT touch .planning/
                  Suggests: "Run /gsd:new-project to set up the planning scaffold"

/mgw:run 42   →  Reads issue from GitHub, triages
                  Invokes GSD quick/milestone workflows
                  GSD creates/updates .planning/ files
                  MGW reads GSD artifacts for PR creation
                  Does NOT write .planning/ directly

/gsd:health   →  Reports HEALTHY (GSD manages its own state)

Affected Files

File	Change
commands/project.md	Remove write_roadmap step, update report/success_criteria
commands/run.md	Remove .planning/ scaffolding writes, let GSD handle state
.claude/commands/mgw/project.md	Mirror of commands/project.md
.claude/commands/mgw/run.md	Mirror of commands/run.md

Test Plan

• /mgw:project creates GitHub milestones/issues but does NOT create .planning/ROADMAP.md
• /mgw:run works when .planning/ exists (created by GSD)
• /mgw:run gracefully handles missing .planning/ (prompts for GSD init)
• GSD workflows still work correctly when invoked after /mgw:project
• .mgw/project.json contains all data MGW needs (no dependency on .planning/)

[snipcodeit]

MGW · triage-complete · 2026-02-27T00:15:29.565Z

Triage Complete

Scope	medium — 6 files across command-layer, workflow-templates, claude-command-mirrors, readme
Validity	confirmed
Security	none
Route	gsd:quick --full — medium-scope, well-defined mechanical refactoring with verification
Conflicts	#33 (superseded, closed) — same files, work from main

Work begins on branch issue/35-refactor-remove-all-planning-writes-from.

Affected Files

• commands/project.md — Remove write_roadmap step, update report/success_criteria
• commands/run.md — Remove .planning/ scaffolding writes, let GSD handle state
• .claude/commands/mgw/project.md — Mirror of commands/project.md
• .claude/commands/mgw/run.md — Mirror of commands/run.md
• .claude/commands/mgw/workflows/gsd.md — Remove .planning/ scaffolding pattern
• README.md — Update references to MGW writing ROADMAP.md

[snipcodeit]

Lets address some insights gathered that seem off.

Fix: Remove the write_roadmap step entirely. /mgw:project creates GitHub infrastructure first. then/mgw:project checks that gsd:new-project has been run, if not it should hand off to gsd:new-project to lead the user through whatever phases and tasks gsd has delegated for it's new-project (keeps us future proof). this usually involves a discussion phase, or an idea.md document, so we cannot trigger fully autonomous during this time.

Fix: If no .planning/ exists, /mgw:run should:
Invoke /gsd:health --repair to create valid state, OR
check github to see if previous milestones or issues might have been related to a project that was deleted from local disk.
if no such issues or milestones exist, instruct the user to run /mgw:project to take the user to the start of the pipeline for mgw. subsequently this will take the user into gsd:new-project so we properly hand off to gsd.

3. commands/run.md — creates quick task directory (line 228-230)
   we should move this directory into .mgw to be handled by the mgw system instead of the gsd system. if gsd sees theres no directory it should prompt back as to what it needs.

[snipcodeit]

MGW · work-started · 2026-02-27T01:47:13Z
Milestone: v1 — Pipeline Intelligence | Phase 7: Pipeline Fixes

Work Started

Issue	#35 — refactor: remove all .planning/ writes from MGW
Route	quick --full
Phase	7 of 8 — Pipeline Fixes
Milestone	v1 — Pipeline Intelligence

Milestone Progress (0/4 complete)

#	Issue	Status	PR
35	refactor: remove all .planning/ writes from MGW	◆ In Progress	—
36	feat: comment-aware pipeline	○ Pending	—
37	feat: /mgw:status — project status dashboard	○ Pending	—
38	feat: /mgw:ask — contextual question routing	○ Pending	—

[snipcodeit]

MGW · pr-ready · 2026-02-27T01:54:01Z
Milestone: v1 — Pipeline Intelligence | Phase 7: Pipeline Fixes

PR Ready

PR #39 — #39

Removed all 4 .planning/ write violations from MGW commands. 6 files changed, 44 insertions, 224 deletions.

Testing procedures posted on the PR.
This issue will auto-close when the PR is merged.

Milestone Progress (1/4 complete)

#	Issue	Status	PR
35	refactor: remove all .planning/ writes from MGW	✓ Done	#39
36	feat: comment-aware pipeline	○ Pending	—
37	feat: /mgw:status — project status dashboard	○ Pending	—
38	feat: /mgw:ask — contextual question routing	○ Pending	—

[snipcodeit]

MGW · milestone-complete · 2026-02-27T02:19:36Z

Milestone 2 Complete: v1 — Pipeline Intelligence

All 4 issues completed successfully.

#	Issue	Status	PR
35	refactor: remove all .planning/ writes from MGW	✓ Done	#39
36	feat: comment-aware pipeline	✓ Done	#40
37	feat: /mgw:status — project status dashboard	✓ Done	#41
38	feat: /mgw:ask — contextual question routing	✓ Done	#42

Milestone closed. Draft release created.
Next: Milestone 3 — v1 — NPM Publishing & Distribution