MGW — My GSD Workflow

Issue in. PR out. No excuses.

GitHub-native issue-to-PR automation for Claude Code, powered by Get Shit Done.

MGW bridges GitHub Issues and the GSD planning framework into a single pipeline. Point it at an issue, and it triages, plans, executes, and opens a PR — posting structured status updates at every stage. No context switching, no tab juggling, no copy-pasting between GitHub and your terminal.

/mgw:run 42

That's it. One command takes an issue from open to PR-ready.

What It Does

MGW is a Claude Code slash command suite and standalone Node.js CLI that automates the lifecycle of a GitHub issue:

  /mgw:project               State-aware init: Vision Cycle → GSD alignment → milestone scaffold
       |
  /mgw:issue 42              Triage: scope, validity, security, conflicts
       |
  /mgw:run 42                Plan → Execute → Verify → PR (autonomous)
       |
  /mgw:milestone              Execute all issues in dependency order
       |
  PR created + status comments posted
       |
  Merge → issue auto-closes

Each step is composable. Use the full pipeline or pick individual commands. For a detailed breakdown of the pipeline stages and agent delegation model, see the Architecture Guide.

Why I Built This

I'm a solo developer. On any given day I might be writing a game server, reverse-engineering a VM, building a mobile app, or reorganizing my entire dotfiles setup for the third time this week. My brain has one mode: build. The part where you go back and update the issue, post a comment, open a PR with a nice description, cross-reference the other thing you broke — that part doesn't exist in my workflow. It's not that I don't care. It's that by the time the feature works, I've already mentally moved on to the next thing.

The result is a graveyard of GitHub issues that say "Fix auth" with zero follow-up, branches named things only I understand, and PRs that my past self apparently thought were self-documenting. They were not.

So I built MGW to be the responsible adult in the room. I point it at an issue, it does all the paperwork I was never going to do, and my GitHub history finally looks like a person who has their life together. It's the professional version of me that answers emails on time and keeps a clean desk — except it's a dozen Markdown files, a Node CLI, and Claude doing all the work.

Who This Is For

MGW is for solo developers and small teams using Claude Code who want their GitHub history to reflect the work they actually did — without spending time on project management.

You'll get the most out of MGW if you:

Use Claude Code as your primary development tool
Have a pile of GitHub issues that never get proper status updates, PR descriptions, or cross-references
Want a repeatable issue-to-PR pipeline that handles triage, planning, execution, and documentation automatically
Work across multiple projects and lose context switching between GitHub and your terminal

When to use MGW vs. Claude Code directly:

Scenario	Use
One-off code changes with no issue tracking	Claude Code directly
Issues that need triage, planning, status updates, and PRs	MGW
Executing a backlog of issues in dependency order	MGW (`/mgw:milestone`)
Scaffolding a new project from a description	MGW (`/mgw:project`)
Quick code question or file edit	Claude Code directly

Prerequisites:

Node.js >= 18
Claude Code CLI installed and working
GitHub CLI (gh) installed and authenticated (gh auth status)
Get Shit Done (GSD) installed in Claude Code
A GitHub repository with issues enabled

If you're already using Claude Code and GSD for development, MGW is the missing piece that connects your work back to GitHub. If you're not using either yet, start with Claude Code, then add GSD, then add MGW.

Commands

Command	What it does
`/mgw:project`	State-aware project init — detects Fresh/Aligned/Diverged/GSD-Only state and routes to the right flow (Vision Cycle, alignment backfill, drift reconciliation, or extend)
`/mgw:init`	Bootstrap repo for MGW — creates .mgw/ state, GitHub templates, gitignore entries
`/mgw:issues`	Browse and filter your GitHub issues
`/mgw:issue <n>`	Deep triage — scope analysis, security review, GSD route recommendation
`/mgw:next`	Show next unblocked issue based on dependency order
`/mgw:run <n>`	Full autonomous pipeline: triage through PR creation; enforces cross-milestone consistency
`/mgw:milestone [n]`	Execute a milestone's issues in dependency order with checkpointing and failed-issue recovery
`/mgw:update <n>`	Post structured status comments on issues
`/mgw:pr [n]`	Create PR from GSD artifacts with phase context and plan traceability
`/mgw:ask <question>`	Route a question or observation — classify as in-scope, adjacent, separate, duplicate, or out-of-scope
`/mgw:review <n>`	Review and classify new comments on an issue since last triage
`/mgw:link <ref> <ref>`	Cross-reference issues, PRs, and branches (including milestone ↔ GSD milestone maps-to links)
`/mgw:status [n]`	Project dashboard — milestone progress, issue stages, open PRs
`/mgw:roadmap [--set-dates] [--post-discussion]`	Render project milestones as a roadmap table; optionally set GitHub due dates or post as a Discussion
`/mgw:assign <n> [user]`	Claim or reassign an issue; resolves GitHub noreply co-author tag
`/mgw:board [--sync]`	Create, configure, and sync a GitHub Projects v2 board
`/mgw:sync`	Reconcile local state with GitHub; verifies GSD milestone consistency
`/mgw:help`	Command reference

For detailed usage of every command including flags, examples, and edge cases, see the User Guide.

How Triage Works

/mgw:issue spawns an analysis agent that reads your codebase and evaluates the issue across five dimensions:

Scope — which files and systems are affected, estimated size
Validity — can the issue be confirmed by reading the code?
Purpose — who benefits, what's the impact of inaction?
Security — does it touch auth, user data, external APIs?
Conflicts — does it overlap with other in-progress work?

Based on scope, MGW recommends a GSD route:

Issue Size	GSD Route	What Happens
Small (1-2 files)	`gsd:quick`	Single-pass plan + execute
Medium (3-8 files)	`gsd:quick --full`	Plan with verification loop
Large (9+ files)	`gsd:new-milestone`	Full milestone with phased execution
Bug (unclear root cause)	`gsd:diagnose-issues`	Debug agent investigates root cause first, then routes to quick fix

For a deeper explanation of how GSD routes work, including dependency ordering and how MGW selects the right route, see the User Guide.

Status Comments

Every pipeline step posts a structured comment on the issue so you (and your team) can follow along on GitHub without touching the terminal:

> MGW · `work-started` · 2026-02-26T03:31:00Z
> Milestone: v1.0 — Auth & Data Layer | Phase 1: Database Schema

### Work Started

| | |
|---|---|
| **Issue** | #71 — Implement user registration |
| **Route** | `plan-phase` |
| **Phase** | 1 of 6 — Database Schema |
| **Milestone** | v1.0 — Auth & Data Layer |

<details>
<summary>Milestone Progress (1/6 complete)</summary>
| # | Issue | Status | PR |
|---|-------|--------|----|
| 70 | Design SQLite schema | ✓ Done | #85 |
| **71** | **User registration** | ◆ In Progress | — |
| 72 | JWT middleware | ○ Pending | — |
</details>

Comments are posted for: work-started, triage-complete, execution-complete, pr-ready, and pipeline-failed. The milestone orchestrator handles all comment posting directly (not delegated to sub-agents), guaranteeing every stage is logged. For the full list of comment formats and customization options, see the User Guide.

PR Descriptions

PRs follow a consistent structure with milestone context:

## Summary
- 2-4 bullets of what was built and why

Closes #71

## Milestone Context
- **Milestone:** v1.0 — Auth & Data Layer
- **Phase:** 1 — Database Schema
- **Issue:** 2 of 6 in milestone

## Changes
- File-level changes grouped by module

## Test Plan
- Verification checklist

State Management

MGW tracks pipeline state in a local .mgw/ directory (gitignored, per-developer):

.mgw/
  project.json         Milestones, issues, phases, pipeline stages, GSD milestone links
  config.json          User prefs (GitHub username, default filters)
  active/              In-progress issue pipelines
    42-fix-auth.json   Issue state: triage results, pipeline stage, artifacts
  completed/           Archived after PR merge
  cross-refs.json      Bidirectional issue/PR/branch/milestone links
  vision-research.json   (Fresh projects) Domain research from vision-researcher agent
  vision-draft.md        (Fresh projects) Rolling decisions from questioning loop
  vision-brief.json      (Fresh projects) Structured Vision Brief (MoSCoW, personas, scope)
  vision-handoff.md      (Fresh projects) Condensed brief handed off to gsd:new-project
  alignment-report.json  (GSD-Only projects) GSD state mapped for milestone backfill
  drift-report.json      (Diverged projects) Reconciliation table from drift-analyzer agent

Pipeline stages flow: new → triaged → planning → executing → verifying → pr-created → done (or failed/blocked). Bugs routed to gsd:diagnose-issues pass through diagnosing before planning.

The /mgw:sync command reconciles local state with GitHub reality — archiving completed work, flagging stale branches, and catching drift. For the complete state schema and configuration reference, see the User Guide. For how state flows through the system, see the Architecture Guide.

Requirements

Node.js >= 18
Claude Code (CLI)
Get Shit Done (GSD) installed in Claude Code
GitHub CLI (gh) authenticated
A GitHub repository with issues enabled

Quick Start

Try MGW without installing anything:

# See available commands
npx @snipcodeit/mgw --help

# List your open issues
npx @snipcodeit/mgw issues

# Sync local state with GitHub
npx @snipcodeit/mgw sync

# Cross-reference two issues
npx @snipcodeit/mgw link 42 43

npx @snipcodeit/mgw gives you the full CLI subset that works without Claude Code. For the AI-powered pipeline commands (run, issue, project, milestone, etc.), do a full install below.

Installation

npm (recommended)

npm install -g @snipcodeit/mgw
# Slash commands are automatically deployed to ~/.claude/commands/mgw/

From source

git clone https://github.com/snipcodeit/mgw.git
cd mgw
npm install && npm run build
npm install -g . --prefix ~/.npm-global
# Slash commands are installed automatically by npm postinstall

Verify

# CLI (if installed)
mgw --version

# Slash commands (installed automatically by postinstall)
ls ~/.claude/commands/mgw/
# ask.md  assign.md  board.md  help.md  init.md  issue.md  issues.md  link.md
# milestone.md  next.md  pr.md  project.md  review.md  roadmap.md  run.md
# status.md  sync.md  update.md  workflows/

Then in Claude Code:

/mgw:help

npx vs full install

Not all commands work via npx. The CLI has two tiers:

Tier	Commands	Requirements
CLI-only (works with npx)	`issues`, `sync`, `link`, `help`, `--help`, `--version`	Node.js >= 18, `gh` CLI
AI-powered (requires full install)	`run`, `init`, `project`, `milestone`, `next`, `issue`, `update`, `pr`, `ask`, `review`, `assign`, `board`, `roadmap`, `status`	Node.js >= 18, `gh` CLI, Claude Code CLI, GSD

AI-powered commands call claude -p under the hood and require the Claude Code CLI to be installed and authenticated. The slash command .md files must also be deployed to ~/.claude/commands/mgw/ for the full pipeline to work — this happens automatically via postinstall. Use npx @snipcodeit/mgw to explore the CLI and verify your GitHub setup before committing to a full install.

Typical Workflow

New project (from scratch)

# 1. Run the project initializer (state-aware — safe to run on any repo)
/mgw:project
# On a fresh repo: launches a 6-stage Vision Collaboration Cycle
#   → Intake (describe your idea)
#   → Domain research (AI expands your concept)
#   → Structured questioning (8–15 rounds)
#   → Vision synthesis (structured brief: MoSCoW features, personas, scope)
#   → Review + condense
#   → Spawns gsd:new-project → creates GitHub milestones/issues automatically
#
# On a repo with GSD state but no GitHub structure:
#   → Backfills GitHub milestones/issues from existing ROADMAP.md
#
# On an already-configured repo (Aligned state):
#   → Shows status + offers to add new milestones

# 2. Execute the first milestone (issues run in dependency order)
/mgw:milestone

# 3. Review PRs as they're created, merge when ready

Existing issues

# 1. See what's assigned to you
/mgw:issues

# 2. Pick the next unblocked issue
/mgw:next

# 3. Run the full pipeline
/mgw:run 42
# → Creates branch, triages (if needed), plans via GSD, executes,
#   verifies, opens PR, posts status comments on the issue

# 4. Review the PR, merge when ready

Manual control

/mgw:issue 42                          # Triage
/mgw:link 42 #43                       # Cross-reference related issue
/mgw:update 42 "blocked on #43"        # Post custom status
/mgw:pr 42 --base develop              # Create PR to specific base
/mgw:sync                              # Clean up stale state

For step-by-step walkthroughs of common scenarios including failure recovery, see the User Guide.

Project Structure

bin/
  mgw.cjs                 CLI entry point (Commander.js)
lib/
  index.cjs               Barrel export
  claude.cjs              Claude Code invocation helpers
  github.cjs              GitHub CLI wrappers (issues, PRs, milestones, Projects v2)
  gsd.cjs                 GSD integration
  gsd-adapter.cjs         GSD route adapter (maps triage results to GSD spawn args)
  state.cjs               .mgw/ state management (migrateProjectState, resolveActiveMilestoneIndex)
  output.cjs              Logging and formatting
  retry.cjs               Retry logic for GitHub API calls
  templates.cjs           Template system
  template-loader.cjs     Output validation (JSON Schema) + parseRoadmap()
commands/                  Slash command source files (deployed to ~/.claude/commands/mgw/ at install time)
  ask.md                  Contextual question routing during milestone execution
  assign.md               Claim/reassign issues; resolves GitHub noreply co-author tag
  board.md                GitHub Projects v2 board management
  help.md                 Command reference display
  init.md                 One-time repo bootstrap (state, templates, labels)
  project.md              State-aware project init (Vision Cycle, alignment, drift, extend)
  issues.md               Issue browser with filters
  issue.md                Deep triage with agent analysis
  next.md                 Next unblocked issue picker (surfaces failed issues as advisory)
  review.md               Comment review and classification since last triage
  roadmap.md              Milestone roadmap table; optional GitHub due-date setter and Discussion post
  run.md                  Autonomous pipeline orchestrator (cross-milestone enforcement)
  milestone.md            Milestone execution with dependency ordering and failed-issue recovery
  update.md               Structured GitHub comment templates
  pr.md                   PR creation from GSD artifacts with phase context + plan traceability
  link.md                 Cross-referencing system (incl. maps-to milestone links)
  status.md               Project status dashboard and milestone progress query
  sync.md                 State reconciliation (GSD milestone consistency check)
  workflows/
    state.md              Shared state schema and initialization
    github.md             Shared GitHub CLI patterns
    gsd.md                GSD agent spawn templates
    validation.md         Delegation boundary rules
    board-sync.md         Board sync utilities (update_board_status, sync_pr_to_board)
templates/
  schema.json             JSON Schema for project output validation
  vision-brief-schema.json  JSON Schema for Vision Brief output from vision-synthesizer

For a detailed walkthrough of the directory structure, slash command anatomy, and CLI architecture, see the Architecture Guide.

Documentation

Document	Description
Wiki	Comprehensive documentation hub: getting started, commands reference, workflow guide, architecture, configuration, troubleshooting
Architecture Guide	System design: the two-layer model (MGW orchestrates, GSD executes), delegation boundary, pipeline data flow, state schema, agent model, and slash command anatomy
User Guide	Practical usage: configuration reference, full command reference with examples, workflow walkthroughs, GSD route explanations, dependency ordering, failure recovery, and FAQ

Acknowledgments

MGW wouldn't exist without Get Shit Done by Lex Christopherson — a structured project management framework for Claude Code that handles planning, execution, and verification. GSD does the heavy lifting; MGW just connects it to GitHub so the rest of the world can see what you actually accomplished.

Seriously, if you're using Claude Code for development, go install GSD. MGW is just the GitHub layer on top.

Troubleshooting

GitHub CLI not authenticated

Error: gh: not logged in

Run gh auth status to check. If not authenticated:

gh auth login
# Select GitHub.com, HTTPS, and authenticate via browser

MGW requires the repo scope. If you're authenticated but getting permission errors, re-authenticate with the correct scopes:

gh auth login --scopes repo

GSD not installed

Error: GSD slash commands not found

MGW delegates planning and execution to Get Shit Done. Install it following the GSD README, then verify the commands are available in Claude Code:

/gsd:quick --help

State file issues (.mgw/ directory)

State drift — Local .mgw/ state can fall out of sync with GitHub if you merge PRs from the web UI, close issues manually, or work from a different machine. Run sync to reconcile:

/mgw:sync

Corrupted state — If .mgw/ gets into a bad state, you can safely delete it and re-initialize:

rm -rf .mgw/
/mgw:init

This won't affect anything on GitHub. The .mgw/ directory is local-only and gitignored.

Missing .mgw/ directory — If you cloned a repo that uses MGW but don't have a .mgw/ directory, run init:

/mgw:init

Worktree cleanup

MGW creates git worktrees in .worktrees/ for each issue pipeline. If a pipeline fails mid-execution, stale worktrees can accumulate:

# List active worktrees
git worktree list

# Remove a specific stale worktree
git worktree remove .worktrees/issue/42-fix-auth

# Prune all stale worktree references
git worktree prune

The associated branches are not deleted automatically. Clean them up after removing the worktree:

git branch -d issue/42-fix-auth

Rate limiting

MGW posts comments on GitHub issues at each pipeline stage. If you're executing many issues in quick succession (e.g., via /mgw:milestone), you may hit GitHub's API rate limits:

Error: API rate limit exceeded

Check your current rate limit status:

gh api rate_limit --jq '.resources.core'

If rate-limited, wait for the reset window (usually under an hour) or reduce the number of concurrent pipelines. Authenticated requests get 5,000 requests per hour — plenty for normal use, but milestone-level execution with many issues can approach the limit.

Common errors

Error	Cause	Fix
`Issue #N not found`	Issue doesn't exist or is in a different repo	Check the issue number and ensure you're in the correct repo
`Branch already exists`	A previous pipeline run created the branch	Delete the branch (`git branch -D issue/N-...`) or use the existing one
`No GSD route determined`	Triage couldn't determine issue scope	Run `/mgw:issue N` manually to inspect the triage output
`Merge conflict in worktree`	Main branch diverged during execution	Resolve conflicts in the worktree, then resume with `/mgw:run N`
`Permission denied`	GitHub token lacks required scopes	Re-authenticate: `gh auth login --scopes repo`

Uninstalling

# Remove CLI
npm uninstall -g @snipcodeit/mgw

# Remove slash commands
rm -rf ~/.claude/commands/mgw/

# Remove local state (per-repo, if initialized)
rm -rf .mgw/

Contributing

MGW is young and there's plenty of room to make it better:

Multi-repo support — monorepo and cross-repo issue tracking
GitHub Actions integration — trigger MGW from CI events
Review cycle automation — handle PR review comments → fix → re-request
Dashboard — terminal UI for pipeline visualization
Webhook support — react to issue assignments and label changes in real-time

The slash commands are plain Markdown with a simple frontmatter + process structure. The CLI is a lightweight Node.js wrapper (bin/mgw.cjs) that delegates AI work to Claude and handles non-AI commands (sync, issues, link) directly. If any of the above interests you, open an issue or submit a PR. I promise MGW will keep mine updated even if I won't.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 254 Commits
.github		.github
.planning		.planning
bin		bin
commands		commands
completions		completions
docs		docs
lib		lib
templates		templates
test		test
wiki		wiki
workflows		workflows
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODEOWNERS		CODEOWNERS
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

MGW — My GSD Workflow

What It Does

Why I Built This

Who This Is For

Commands

How Triage Works

Status Comments

PR Descriptions

State Management

Requirements

Quick Start

Installation

npm (recommended)

From source

Verify

npx vs full install

Typical Workflow

New project (from scratch)

Existing issues

Manual control

Project Structure

Documentation

Acknowledgments

Troubleshooting

GitHub CLI not authenticated

GSD not installed

State file issues (.mgw/ directory)

Worktree cleanup

Rate limiting

Common errors

Uninstalling

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages