@snipcodeit/mgw 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 snipcodeit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,517 @@
+# MGW — My GSD Workflow
+
+[![npm version](https://img.shields.io/npm/v/mgw)](https://www.npmjs.com/package/mgw)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![node](https://img.shields.io/node/v/mgw)](https://nodejs.org)
+[![GitHub stars](https://img.shields.io/github/stars/snipcodeit/mgw)](https://github.com/snipcodeit/mgw)
+
+> Issue in. PR out. No excuses.
+
+**GitHub-native issue-to-PR automation for [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), powered by [Get Shit Done](https://github.com/glittercowboy/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](https://docs.anthropic.com/en/docs/claude-code/slash-commands) 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](docs/ARCHITECTURE.md).
+
+## 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](https://docs.anthropic.com/en/docs/claude-code/overview) 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](https://docs.anthropic.com/en/docs/claude-code/overview) CLI installed and working
+- [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated (`gh auth status`)
+- [Get Shit Done](https://github.com/glittercowboy/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: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](docs/USER-GUIDE.md#command-reference).
+
+## 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](docs/USER-GUIDE.md#gsd-routes-explained).
+
+## 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](docs/USER-GUIDE.md#status-comments-and-pr-descriptions).
+
+## PR Descriptions
+
+PRs follow a consistent structure with milestone context:
+
+```markdown
+## 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-draft.md      (Fresh projects) Rolling decisions from questioning loop
+  vision-brief.json    (Fresh projects) Structured Vision Brief (MoSCoW, personas, scope)
+  alignment-report.json  (GSD-Only projects) GSD state mapped for milestone backfill
+```
+
+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](docs/USER-GUIDE.md#the-mgw-directory). For how state flows through the system, see the [Architecture Guide](docs/ARCHITECTURE.md#state-management).
+
+## Requirements
+
+- [Node.js](https://nodejs.org/) >= 18
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) (CLI)
+- [Get Shit Done](https://github.com/glittercowboy/get-shit-done) (GSD) installed in Claude Code
+- [GitHub CLI](https://cli.github.com/) (`gh`) authenticated
+- A GitHub repository with issues enabled
+
+## Quick Start
+
+Try MGW without installing anything:
+
+```bash
+# See available commands
+npx mgw --help
+
+# List your open issues
+npx mgw issues
+
+# Sync local state with GitHub
+npx mgw sync
+
+# Cross-reference two issues
+npx mgw link 42 43
+```
+
+`npx 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
+
+### Full install (CLI + slash commands)
+
+```bash
+git clone https://github.com/snipcodeit/mgw.git
+cd mgw
+npm install && npm run build
+npm link
+# Slash commands are installed automatically by npm postinstall
+```
+
+### Slash commands only (no CLI)
+
+```bash
+npm install -g mgw
+# Slash commands are automatically deployed to ~/.claude/commands/mgw/
+```
+
+### Verify
+
+```bash
+# CLI (if installed)
+mgw --version
+
+# Slash commands (installed automatically by postinstall)
+ls ~/.claude/commands/mgw/
+# ask.md  board.md  help.md  init.md  issue.md  issues.md  link.md  milestone.md
+# next.md  pr.md  project.md  review.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` | Node.js >= 18, `gh` CLI, Claude Code CLI, GSD |
+
+AI-powered commands call `claude -p` under the hood and require the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/overview) to be installed and authenticated. The slash command `.md` files must also be deployed to `~/.claude/commands/mgw/` for the full pipeline to work. Use `npx mgw` to explore the CLI and verify your GitHub setup before committing to a full install.
+
+## Typical Workflow
+
+### New project (from scratch)
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+/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](docs/USER-GUIDE.md#workflow-walkthrough).
+
+## 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
+  state.cjs               .mgw/ state management (migrateProjectState, resolveActiveMilestoneIndex)
+  output.cjs              Logging and formatting
+  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
+  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
+  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](docs/ARCHITECTURE.md#directory-structure).
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Wiki](https://github.com/snipcodeit/mgw/wiki) | Comprehensive documentation hub: getting started, commands reference, workflow guide, architecture, configuration, troubleshooting |
+| [Architecture Guide](docs/ARCHITECTURE.md) | 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](docs/USER-GUIDE.md) | 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](https://github.com/glittercowboy/get-shit-done)** by [Lex Christopherson](https://github.com/glittercowboy) — 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:
+
+```bash
+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:
+
+```bash
+gh auth login --scopes repo
+```
+
+### GSD not installed
+
+```
+Error: GSD slash commands not found
+```
+
+MGW delegates planning and execution to [Get Shit Done](https://github.com/glittercowboy/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:
+
+```bash
+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:
+
+```bash
+# 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:
+
+```bash
+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:
+
+```bash
+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
+
+```bash
+# Remove CLI
+npm unlink 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](LICENSE)

package/bin/mgw-install.cjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * bin/mgw-install.cjs — Idempotent slash command installer
+ *
+ * Runs automatically via npm postinstall. Copies the commands/ source tree
+ * into ~/.claude/commands/mgw/ so Claude Code slash commands are available
+ * without any manual copy step.
+ *
+ * Behavior:
+ * - If ~/.claude/ does not exist: prints a skip message and exits 0 (non-fatal)
+ * - If ~/.claude/ exists: creates ~/.claude/commands/mgw/ and recursively
+ *   copies commands/ into it (overwriting existing files — idempotent)
+ * - Exits 0 in both cases
+ *
+ * Dependencies: Node.js built-ins only (path, fs, os)
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// Source: commands/ directory relative to this script (bin/ → ../commands/)
+const sourceDir = path.join(__dirname, '..', 'commands');
+
+// Target: ~/.claude/commands/mgw/
+const claudeDir = path.join(os.homedir(), '.claude');
+const targetDir = path.join(claudeDir, 'commands', 'mgw');
+
+// Guard: if ~/.claude/ does not exist, skip silently with a clear message
+if (!fs.existsSync(claudeDir)) {
+  console.log(
+    'mgw: ~/.claude/ not found — skipping slash command install ' +
+    '(run `node ./bin/mgw-install.cjs` after installing Claude Code)'
+  );
+  process.exit(0);
+}
+
+// Guard: ensure commands/ source exists in this package
+if (!fs.existsSync(sourceDir)) {
+  console.log('mgw: commands/ source not found — skipping slash command install');
+  process.exit(0);
+}
+
+/**
+ * Recursively copy a directory tree from src to dest.
+ * Creates dest and any subdirectories as needed.
+ * Overwrites existing files (idempotent).
+ * @param {string} src - Source directory path
+ * @param {string} dest - Destination directory path
+ * @returns {number} Number of files copied
+ */
+function copyDirRecursive(src, dest) {
+  let count = 0;
+
+  // Create destination directory if it doesn't exist
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src);
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry);
+    const destPath = path.join(dest, entry);
+
+    const stat = fs.statSync(srcPath);
+    if (stat.isDirectory()) {
+      count += copyDirRecursive(srcPath, destPath);
+    } else if (stat.isFile()) {
+      fs.copyFileSync(srcPath, destPath);
+      count++;
+    }
+  }
+
+  return count;
+}
+
+// Perform the install
+const fileCount = copyDirRecursive(sourceDir, targetDir);
+console.log(`mgw: installed ${fileCount} slash commands to ${targetDir}`);