@snipcodeit/mgw 0.1.3 → 0.2.0

package/commands/init.md

@@ -1,7 +1,7 @@
 ---
 name: mgw:init
-description: Bootstrap current repo for MGW integration — creates .mgw/ state, GitHub templates, gitignore entries
-argument-hint: ""
+description: Bootstrap current repo for MGW integration — creates .mgw/ state, GitHub templates, gitignore entries, installs shell completions, and runs config wizard
+argument-hint: "[--no-config]"
 allowed-tools:
   - Bash
   - Read
@@ -12,8 +12,9 @@ allowed-tools:
 
 <objective>
 One-time setup for a repo to work with MGW. Creates the .mgw/ state directory,
-GitHub issue/PR templates, and ensures gitignore entries. Safe to re-run — skips
-anything that already exists.
+GitHub issue/PR templates, ensures gitignore entries, and runs an interactive
+config wizard for first-time setup preferences. Safe to re-run — skips anything
+that already exists. Pass --no-config to skip the wizard.
 </objective>
 
 <execution_context>
@@ -213,6 +214,109 @@ gh label create "mgw:blocked" --description "Pipeline blocked by stakeholder com
 `--force` updates existing labels without error.
 </step>
 
+<step name="install_completions">
+**Offer to install shell completions (opt-in):**
+
+Locate the completions directory bundled with the MGW package:
+```bash
+MGW_PKG_DIR=$(node -e "const path = require('path'); console.log(path.resolve(__dirname, '..', '..'))" 2>/dev/null || echo "")
+COMPLETIONS_DIR="${MGW_PKG_DIR}/completions"
+```
+
+If completions are not found (package not globally installed or completions dir absent) → skip silently, note "Shell completions not available (mgw not installed globally)" in report.
+
+If completions are found, detect the user's shell and determine the install target:
+```bash
+CURRENT_SHELL=$(basename "${SHELL:-}")
+```
+
+Shell → target directory mapping:
+- `bash` → `~/.local/share/bash-completion/completions/` (source file: `mgw.bash`)
+- `zsh`  → `~/.zsh/completions/` (source file: `mgw.zsh`)
+- `fish` → `~/.config/fish/completions/` (source file: `mgw.fish`)
+
+If shell is unrecognized or `SHELL` is unset → show all three install commands and skip auto-install.
+
+**Interactive mode (default):** Ask the user:
+```
+Shell completions are available for ${CURRENT_SHELL}.
+
+Install to ${COMPLETION_TARGET_DIR}? [Y/n]
+```
+
+If the user answers yes (or presses Enter for the default):
+```bash
+mkdir -p "${COMPLETION_TARGET_DIR}"
+cp "${COMPLETIONS_DIR}/mgw.${SHELL_EXT}" "${COMPLETION_TARGET_DIR}/mgw.${SHELL_EXT}"
+```
+
+Then show the source/activation line appropriate for the shell:
+- bash: `# Reload with: source ~/.local/share/bash-completion/completions/mgw.bash`
+  (or add to ~/.bashrc: `source ~/.local/share/bash-completion/completions/mgw.bash`)
+- zsh: Add to ~/.zshrc (required — ~/.zsh/completions is not in default $fpath):
+  ```
+  fpath=(~/.zsh/completions $fpath)
+  autoload -Uz compinit
+  compinit
+  ```
+  Then reload: `source ~/.zshrc`
+- fish: `# Completions loaded automatically from ~/.config/fish/completions/`
+
+If user answers no → skip, note "Shell completions: skipped" in report.
+
+If the completion file already exists at the target → overwrite (idempotent re-run).
+
+**Non-interactive mode** (stdin is not a TTY): Skip the prompt entirely, print the install command as a hint:
+```
+  Shell completions available. Install manually:
+    cp ${COMPLETIONS_DIR}/mgw.${SHELL_EXT} ${COMPLETION_TARGET_DIR}/mgw.${SHELL_EXT}
+```
+</step>
+
+<step name="run_config_wizard">
+**Run interactive config wizard for first-time setup (skip if --no-config or config already exists):**
+
+Check whether the wizard should run:
+```bash
+# Skip if --no-config flag is present
+# Skip if stdin is not a TTY (CI/piped context)
+# Skip if .mgw/config.json already exists
+```
+
+Use `lib/config-wizard.cjs` to determine and execute:
+```javascript
+const { runWizard, shouldRunWizard } = require('./lib/config-wizard.cjs');
+const mgwDir = path.join(REPO_ROOT, '.mgw');
+
+if (shouldRunWizard(mgwDir, process.argv)) {
+  await runWizard(mgwDir);
+} else if (fs.existsSync(path.join(mgwDir, 'config.json'))) {
+  // report: ".mgw/config.json   exists, skipping wizard"
+} else {
+  // report: ".mgw/config.json   skipped (--no-config)"
+}
+```
+
+The wizard asks the user four questions in order:
+1. **GitHub username** — auto-detected from `gh api user -q .login`; user may accept or override
+2. **Default issue state filter** — `open` (default) or `all`
+3. **Default issue limit** — `10`, `25` (default), or `50`
+4. **Default assignee filter** — `me` (default) or `all`
+
+Answers are written to `${REPO_ROOT}/.mgw/config.json`:
+```json
+{
+  "github_username": "...",
+  "default_issue_state": "open",
+  "default_issue_limit": 25,
+  "default_assignee": "me",
+  "created_at": "<ISO timestamp>"
+}
+```
+
+If the wizard errors or is interrupted, report the failure but do not abort the overall init — config is optional.
+</step>
+
 <step name="report">
 **Report setup status:**
 
@@ -223,11 +327,13 @@ gh label create "mgw:blocked" --description "Pipeline blocked by stakeholder com
 
   .mgw/                  ${created|exists}
   .mgw/cross-refs.json   ${created|exists}
+  .mgw/config.json       ${written|exists|skipped}
   .gitignore entries     ${added|exists}
   Issue templates        ${created|exists}
   PR template            ${created|exists}
   GitHub labels          synced
   MGW pipeline labels    synced (7 labels)
+  Shell completions      ${installed (bash|zsh|fish)|skipped|not available}
 
 Ready to use:
   /mgw:issues            Browse issues
@@ -242,9 +348,13 @@ Ready to use:
 - [ ] .mgw/ directory structure created
 - [ ] .mgw/ and .worktrees/ in .gitignore
 - [ ] cross-refs.json initialized
+- [ ] Config wizard run (or skipped via --no-config / pre-existing config.json)
+- [ ] .mgw/config.json written with user preferences (unless skipped)
 - [ ] Issue templates created (bug + enhancement)
 - [ ] PR template created
 - [ ] GitHub labels ensured (bug, enhancement)
 - [ ] MGW pipeline labels ensured (7 mgw:* labels)
-- [ ] Setup report shown
+- [ ] Shell completion install offered (interactive) or hint printed (non-interactive)
+- [ ] Completion install skipped gracefully if completions dir not found
+- [ ] Setup report shown with completion status line
 </success_criteria>

package/commands/issues.md

@@ -1,7 +1,7 @@
 ---
 name: mgw:issues
 description: List and filter GitHub issues, pick one to triage
-argument-hint: "[--label <label>] [--milestone <name>] [--assignee <user>] [--state open|closed|all]"
+argument-hint: "[--label <label>] [--milestone <name>] [--assignee <user>] [--state open|closed|all] [--search <query>]"
 allowed-tools:
   - Bash
   - Read
@@ -14,6 +14,10 @@ Browse GitHub issues for the current repo. Presents a scannable table filtered b
 assignment (defaults to @me), labels, milestone, or state. Pick an issue to route
 into triage via /mgw:issue.
 
+This is the Claude Code slash-command variant (table + AskUserQuestion). When running
+from the CLI (`mgw issues`), an interactive TUI browser launches instead — see
+`docs/TUI-DESIGN.md` and `lib/tui/index.cjs` for the TUI implementation.
+
 No side effects — read-only GitHub access. Safe to run anytime.
 </objective>
 
@@ -107,3 +111,61 @@ If invalid → re-prompt.
 - [ ] User can pick an issue number
 - [ ] Routes to /mgw:issue <number>
 </success_criteria>
+
+## TUI Mode (CLI only)
+
+When `mgw issues` runs from the CLI entry point (`bin/mgw.cjs`) in an interactive
+terminal, it launches a full TUI browser instead of a static table.
+
+**Entry point:** `lib/tui/index.cjs` — `createIssuesBrowser(options)`
+
+**CLI options:**
+```
+mgw issues [options]
+  -l, --label <label>        Filter by label
+  -m, --milestone <name>     Filter by milestone
+  -a, --assignee <user>      Assignee filter (default: @me, 'all' = no filter)
+  -s, --search <query>       Pre-populate the fuzzy search input
+  --state <state>            Issue state: open|closed|all (default: open)
+  --limit <n>                Max issues to load (default: 50)
+```
+
+**TUI keyboard shortcuts:**
+| Key | Action |
+|-----|--------|
+| `j` / `↓` | Scroll down |
+| `k` / `↑` | Scroll up |
+| `/` | Focus search input |
+| `Enter` | Select issue → prints `#N — Title` and exits |
+| `q` / `Esc` | Quit |
+| `Tab` | Cycle focus (list → detail → filter) |
+| `g` / `Home` | Jump to top |
+| `G` / `End` | Jump to bottom |
+| `?` | Toggle keyboard help |
+
+**Non-interactive fallback:**
+When stdout is not a TTY (piped, CI, `MGW_NO_TUI=1`), the static table is printed
+to stdout. Pipe-friendly — no ANSI codes, no interactive elements.
+
+```bash
+mgw issues | grep "auth"
+```
+
+**Implementation modules:**
+```
+lib/tui/
+  index.cjs      — createIssuesBrowser(options) — entry point
+  search.cjs     — FuzzySearch class — pure, no UI dependency
+  keyboard.cjs   — KeyboardHandler (EventEmitter)
+  renderer.cjs   — createRenderer() — blessed/neo-blessed adapter
+  graceful.cjs   — isInteractive(), renderStaticTable()
+```
+
+**Design document:** `docs/TUI-DESIGN.md` — library selection rationale, wireframe, full interface contracts.
+
+**Rendering library:** `neo-blessed` (optional dependency). Renderer is swappable via `lib/tui/renderer.cjs`.
+
+**Slash command vs CLI:**
+This slash command (`/mgw:issues`) uses the static table + `AskUserQuestion` pattern
+because Claude Code sessions don't have raw TTY access. The TUI is CLI-only (`mgw issues`).
+Both paths route to `/mgw:issue <number>` for triage.

package/commands/milestone.md

@@ -141,6 +141,28 @@ Display:
 Issues: ${TOTAL_ISSUES}
 Mode: ${INTERACTIVE ? "Interactive" : "Autonomous"}
 ```
+
+Then print the initial milestone progress bar (0 done, TOTAL_ISSUES total):
+```bash
+ISSUES_WITH_STAGES=$(echo "$ISSUES_JSON" | python3 -c "
+import json,sys
+issues = json.load(sys.stdin)
+result = [{'number': i['github_number'], 'pipeline_stage': i.get('pipeline_stage', 'new')} for i in issues]
+print(json.dumps(result))
+")
+
+node -e "
+const { printMilestoneProgress } = require('./lib/progress.cjs');
+const issues = JSON.parse(process.env.ISSUES_WITH_STAGES || '[]');
+const doneCount = issues.filter(i => i.pipeline_stage === 'done' || i.pipeline_stage === 'pr-created').length;
+printMilestoneProgress({
+  done: doneCount,
+  total: issues.length,
+  label: process.env.MILESTONE_NAME,
+  issues
+});
+" MILESTONE_NAME="$MILESTONE_NAME" ISSUES_WITH_STAGES="$ISSUES_WITH_STAGES"
+```
 </step>
 
 <step name="resolve_execution_order">
@@ -723,6 +745,27 @@ writeProjectState(state);
 
   ISSUES_RUN=$((ISSUES_RUN + 1))
 
+  # Update and print milestone progress bar after each issue completes
+  ISSUES_WITH_STAGES=$(node -e "
+const { loadProjectState, resolveActiveMilestoneIndex } = require('./lib/state.cjs');
+const state = loadProjectState();
+const idx = resolveActiveMilestoneIndex(state);
+if (idx < 0) { console.log('[]'); process.exit(0); }
+const issues = state.milestones[idx].issues || [];
+console.log(JSON.stringify(issues.map(i => ({ number: i.github_number, pipeline_stage: i.pipeline_stage || 'new' }))));
+" 2>/dev/null || echo "[]")
+
+  node -e "
+const { printMilestoneProgress } = require('./lib/progress.cjs');
+const issues = JSON.parse(process.env.ISSUES_WITH_STAGES || '[]');
+const doneCount = issues.filter(i => i.pipeline_stage === 'done' || i.pipeline_stage === 'pr-created').length;
+printMilestoneProgress({
+  done: doneCount,
+  total: issues.length,
+  issues
+});
+" ISSUES_WITH_STAGES="$ISSUES_WITH_STAGES"
+
   # If --interactive: pause between issues
   if [ "$INTERACTIVE" = true ]; then
     AskUserQuestion(

package/commands/status.md

@@ -1,7 +1,7 @@
 ---
 name: mgw:status
 description: Project status dashboard — milestone progress, issue pipeline stages, open PRs
-argument-hint: "[milestone_number] [--json] [--board]"
+argument-hint: "[milestone_number] [--json] [--board] [--watch [--interval N]]"
 allowed-tools:
   - Bash
   - Read
@@ -13,6 +13,11 @@ pipeline stages, open PRs, and next milestone preview. Pure read-only — no sta
 mutations, no agent spawns, no GitHub writes.
 
 Falls back gracefully when no project.json exists (lists active issues only via GitHub API).
+
+When `--watch` is passed, enters live-refresh mode: clears the terminal and redraws the
+dashboard every N seconds (default 30). Displays a "Last refreshed" timestamp. User exits
+by pressing 'q' or Ctrl+C. If both `--watch` and `--json` are supplied, print an error and
+exit 1.
 </objective>
 
 <execution_context>
@@ -35,11 +40,21 @@ Repo detected via: gh repo view --json nameWithOwner -q .nameWithOwner
 MILESTONE_NUM=""
 JSON_OUTPUT=false
 OPEN_BOARD=false
+WATCH_MODE=false
+WATCH_INTERVAL=30
+NEXT_IS_INTERVAL=false
 
 for ARG in $ARGUMENTS; do
+  if [ "$NEXT_IS_INTERVAL" = true ]; then
+    WATCH_INTERVAL="$ARG"
+    NEXT_IS_INTERVAL=false
+    continue
+  fi
   case "$ARG" in
     --json) JSON_OUTPUT=true ;;
     --board) OPEN_BOARD=true ;;
+    --watch) WATCH_MODE=true ;;
+    --interval) NEXT_IS_INTERVAL=true ;;
     [0-9]*) MILESTONE_NUM="$ARG" ;;
   esac
 done
@@ -418,6 +433,77 @@ Rendering rules:
 - If no open PRs matched to milestone, show "No open PRs for this milestone."
 - If no next milestone, show "No more milestones planned."
 - If `TARGET_MILESTONE != CURRENT_MILESTONE`, add "(viewing milestone ${TARGET_MILESTONE})" to header
+- In watch mode, append the footer: `[ Refreshing every ${WATCH_INTERVAL}s — last refreshed HH:MM:SS | press q to quit ]`
+</step>
+
+<step name="watch_mode">
+**If --watch flag: enter live-refresh loop:**
+
+`--watch` is incompatible with `--json`. If both are passed, print an error and exit 1.
+
+The watch loop is implemented as a Node.js one-shot script executed via `node -e` (or saved
+to a temp file). It wraps the full dashboard render cycle with `setInterval`, clears the
+terminal before each redraw, and uses `process.stdin.setRawMode(true)` to detect a 'q'
+keypress for clean exit.
+
+```javascript
+// watch-mode runner (pseudocode — shows the pattern)
+const { execSync } = require('child_process');
+const INTERVAL = parseInt(process.env.WATCH_INTERVAL || '30', 10) * 1000;
+const REPO_ROOT = process.env.REPO_ROOT;
+
+function renderDashboard() {
+  // Re-run all data collection and dashboard build steps synchronously
+  // (same logic as the non-watch single-shot path above, but called in a loop)
+  const output = buildDashboardOutput();  // all the python/gh calls assembled into a string
+  // Implementation note: buildDashboardOutput() is a pseudocode placeholder.
+  // The executor must refactor the full `display_dashboard` step into a reusable
+  // function that collects all GitHub and project.json data and returns the rendered
+  // dashboard string, then call it from both the single-shot path and the watch loop.
+  const now = new Date().toLocaleTimeString();
+  process.stdout.write('\x1B[2J\x1B[H');  // clear terminal, cursor home
+  process.stdout.write(output);
+  process.stdout.write(`\n[ Refreshing every ${INTERVAL / 1000}s — last refreshed ${now} | press q to quit ]\n`);
+}
+
+// Initial render
+renderDashboard();
+
+// Poll on interval
+const timer = setInterval(renderDashboard, INTERVAL);
+
+// Detect 'q' to exit
+if (process.stdin.isTTY) {
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (key) => {
+    if (key === 'q' || key === '\u0003') {  // 'q' or Ctrl+C
+      clearInterval(timer);
+      process.stdin.setRawMode(false);
+      process.stdout.write('\nWatch mode exited.\n');
+      process.exit(0);
+    }
+  });
+}
+```
+
+Implementation notes for the executor:
+- The watch runner re-executes the full data fetch on each interval tick (re-reads
+  project.json, re-calls `gh pr list`, etc.) so the display reflects live GitHub state.
+- `process.stdout.write('\x1B[2J\x1B[H')` clears the screen without spawning `clear`.
+- The footer line shows "last refreshed HH:MM:SS" only. No countdown timer.
+- SIGINT (Ctrl+C) should also trigger clean exit — the `'\u0003'` check above handles it,
+  but also register `process.on('SIGINT', ...)` as a fallback when `setRawMode` is false
+  (non-TTY or piped stdin).
+- If `--watch` and `--json` are both supplied, print the error message and exit 1 before
+  entering the watch loop.
+
+If both flags are supplied, emit:
+```
+Error: --watch and --json cannot be used together.
+```
+and exit 1.
 </step>
 
 <step name="json_output">
@@ -523,4 +609,12 @@ The JSON structure:
 - [ ] Velocity computed from .mgw/active/ and .mgw/completed/ file mtimes
 - [ ] --json output includes board_url and milestone.health object
 - [ ] Board URL line omitted when board_url is not set in project.json
+- [ ] --watch flag enters live-refresh loop, refreshing every N seconds (default 30)
+- [ ] --interval N overrides the default 30s refresh interval
+- [ ] Watch mode clears terminal before each redraw
+- [ ] Watch mode footer shows last refresh time
+- [ ] 'q' keypress exits watch mode cleanly (stdin raw mode)
+- [ ] Ctrl+C (SIGINT) exits watch mode cleanly
+- [ ] --watch and --json are mutually exclusive — error + exit 1 if both supplied
+- [ ] Watch mode re-fetches all data on each tick (live GitHub state)
 </success_criteria>

package/completions/mgw.bash

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# mgw bash completion script
+# Source this file or add to /etc/bash_completion.d/mgw
+# Generated by bin/generate-completions.cjs
+
+_mgw() {
+  local cur prev words cword
+  _init_completion 2>/dev/null || {
+    COMPREPLY=()
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+  }
+
+  local subcommands="run init project milestone next issue update pr sync issues link help"
+
+  local global_flags="--dry-run --json --verbose -v --debug --model"
+
+  case "$prev" in
+    mgw)
+      COMPREPLY=( $(compgen -W "$subcommands $global_flags" -- "$cur") )
+      return
+      ;;
+    run)
+      COMPREPLY=( $(compgen -W "--quiet --auto $global_flags" -- "$cur") )
+      return
+      ;;
+    init)
+      COMPREPLY=( $(compgen -W "$global_flags" -- "$cur") )
+      return
+      ;;
+    project)
+      COMPREPLY=( $(compgen -W "$global_flags" -- "$cur") )
+      return
+      ;;
+    milestone)
+      COMPREPLY=( $(compgen -W "--interactive $global_flags" -- "$cur") )
+      return
+      ;;
+    next)
+      COMPREPLY=( $(compgen -W "$global_flags" -- "$cur") )
+      return
+      ;;
+    issue)
+      COMPREPLY=( $(compgen -W "$global_flags" -- "$cur") )
+      return
+      ;;
+    update)
+      COMPREPLY=( $(compgen -W "$global_flags" -- "$cur") )
+      return
+      ;;
+    pr)
+      COMPREPLY=( $(compgen -W "--base $global_flags" -- "$cur") )
+      return
+      ;;
+    sync)
+      COMPREPLY=( $(compgen -W "$global_flags" -- "$cur") )
+      return
+      ;;
+    issues)
+      COMPREPLY=( $(compgen -W "--label --milestone --assignee --state --search -s --limit $global_flags" -- "$cur") )
+      return
+      ;;
+    link)
+      COMPREPLY=( $(compgen -W "--quiet $global_flags" -- "$cur") )
+      return
+      ;;
+    help)
+      COMPREPLY=()
+      return
+      ;;
+    --model)
+      # Offer common Claude model names
+      COMPREPLY=( $(compgen -W "claude-opus-4-5 claude-sonnet-4-5 claude-haiku-4-5" -- "$cur") )
+      return
+      ;;
+    --state)
+      COMPREPLY=( $(compgen -W "open closed all" -- "$cur") )
+      return
+      ;;
+    --assignee)
+      COMPREPLY=( $(compgen -W "all @me" -- "$cur") )
+      return
+      ;;
+  esac
+
+  # If cur starts with - complete flags for the current subcommand
+  if [[ "$cur" == -* ]]; then
+    # Find the subcommand in words
+    local subcmd=""
+    for word in "${words[@]}"; do
+      if [[ " $subcommands " == *" $word "* ]]; then
+        subcmd="$word"
+        break
+      fi
+    done
+
+    case "$subcmd" in
+      run)      COMPREPLY=( $(compgen -W "--quiet --auto $global_flags" -- "$cur") ) ;;
+      milestone) COMPREPLY=( $(compgen -W "--interactive $global_flags" -- "$cur") ) ;;
+      pr)       COMPREPLY=( $(compgen -W "--base $global_flags" -- "$cur") ) ;;
+      issues)   COMPREPLY=( $(compgen -W "--label --milestone --assignee --state --search -s --limit $global_flags" -- "$cur") ) ;;
+      link)     COMPREPLY=( $(compgen -W "--quiet $global_flags" -- "$cur") ) ;;
+      *)        COMPREPLY=( $(compgen -W "$global_flags" -- "$cur") ) ;;
+    esac
+    return
+  fi
+
+  # Default: suggest subcommands
+  COMPREPLY=( $(compgen -W "$subcommands" -- "$cur") )
+}
+
+complete -F _mgw mgw

package/completions/mgw.fish

@@ -0,0 +1,99 @@
+# mgw fish completion script
+# Place in ~/.config/fish/completions/mgw.fish
+# or run: fisher install (if using a fish plugin manager)
+# Generated by bin/generate-completions.cjs
+
+# Disable file completions by default for mgw
+complete -c mgw -f
+
+# ---------------------------------------------------------------------------
+# Global flags (available for all subcommands)
+# ---------------------------------------------------------------------------
+complete -c mgw -n '__fish_use_subcommand' -l dry-run  -d 'show what would happen without executing'
+complete -c mgw -n '__fish_use_subcommand' -l json     -d 'output structured JSON'
+complete -c mgw -n '__fish_use_subcommand' -s v -l verbose -d 'show API calls and file writes'
+complete -c mgw -n '__fish_use_subcommand' -l debug    -d 'full payloads and timings'
+complete -c mgw -n '__fish_use_subcommand' -l model    -d 'Claude model override' -r
+
+# ---------------------------------------------------------------------------
+# Subcommands
+# ---------------------------------------------------------------------------
+complete -c mgw -n '__fish_use_subcommand' -a run       -d 'Run the full pipeline for an issue'
+complete -c mgw -n '__fish_use_subcommand' -a init      -d 'Bootstrap repo for MGW (state, templates, labels)'
+complete -c mgw -n '__fish_use_subcommand' -a project   -d 'Initialize project from template (milestones, issues, ROADMAP)'
+complete -c mgw -n '__fish_use_subcommand' -a milestone -d 'Execute milestone issues in dependency order'
+complete -c mgw -n '__fish_use_subcommand' -a next      -d 'Show next unblocked issue'
+complete -c mgw -n '__fish_use_subcommand' -a issue     -d 'Triage issue against codebase'
+complete -c mgw -n '__fish_use_subcommand' -a update    -d 'Post status comment on issue'
+complete -c mgw -n '__fish_use_subcommand' -a pr        -d 'Create PR from GSD artifacts'
+complete -c mgw -n '__fish_use_subcommand' -a sync      -d 'Reconcile .mgw/ state with GitHub'
+complete -c mgw -n '__fish_use_subcommand' -a issues    -d 'Browse open issues'
+complete -c mgw -n '__fish_use_subcommand' -a link      -d 'Cross-reference issues/PRs/branches'
+complete -c mgw -n '__fish_use_subcommand' -a help      -d 'Show command reference'
+
+# ---------------------------------------------------------------------------
+# run <issue-number>
+# ---------------------------------------------------------------------------
+complete -c mgw -n '__fish_seen_subcommand_from run' -l quiet -d 'buffer output, show summary at end'
+complete -c mgw -n '__fish_seen_subcommand_from run' -l auto  -d 'phase chaining: discuss -> plan -> execute'
+complete -c mgw -n '__fish_seen_subcommand_from run' -l dry-run -d 'show what would happen without executing'
+complete -c mgw -n '__fish_seen_subcommand_from run' -l json    -d 'output structured JSON'
+complete -c mgw -n '__fish_seen_subcommand_from run' -s v -l verbose -d 'show API calls and file writes'
+complete -c mgw -n '__fish_seen_subcommand_from run' -l debug   -d 'full payloads and timings'
+complete -c mgw -n '__fish_seen_subcommand_from run' -l model   -d 'Claude model override' -r
+
+# ---------------------------------------------------------------------------
+# milestone [number]
+# ---------------------------------------------------------------------------
+complete -c mgw -n '__fish_seen_subcommand_from milestone' -l interactive -d 'pause between issues for review'
+complete -c mgw -n '__fish_seen_subcommand_from milestone' -l dry-run -d 'show what would happen without executing'
+complete -c mgw -n '__fish_seen_subcommand_from milestone' -l json    -d 'output structured JSON'
+complete -c mgw -n '__fish_seen_subcommand_from milestone' -s v -l verbose -d 'show API calls and file writes'
+complete -c mgw -n '__fish_seen_subcommand_from milestone' -l debug   -d 'full payloads and timings'
+complete -c mgw -n '__fish_seen_subcommand_from milestone' -l model   -d 'Claude model override' -r
+
+# ---------------------------------------------------------------------------
+# pr [number]
+# ---------------------------------------------------------------------------
+complete -c mgw -n '__fish_seen_subcommand_from pr' -l base  -d 'custom base branch' -r
+complete -c mgw -n '__fish_seen_subcommand_from pr' -l dry-run -d 'show what would happen without executing'
+complete -c mgw -n '__fish_seen_subcommand_from pr' -l json    -d 'output structured JSON'
+complete -c mgw -n '__fish_seen_subcommand_from pr' -s v -l verbose -d 'show API calls and file writes'
+complete -c mgw -n '__fish_seen_subcommand_from pr' -l debug   -d 'full payloads and timings'
+complete -c mgw -n '__fish_seen_subcommand_from pr' -l model   -d 'Claude model override' -r
+
+# ---------------------------------------------------------------------------
+# issues [filters]
+# ---------------------------------------------------------------------------
+complete -c mgw -n '__fish_seen_subcommand_from issues' -l label     -d 'filter by label' -r
+complete -c mgw -n '__fish_seen_subcommand_from issues' -l milestone -d 'filter by milestone' -r
+complete -c mgw -n '__fish_seen_subcommand_from issues' -l assignee  -d 'filter by assignee' -r -a 'all @me'
+complete -c mgw -n '__fish_seen_subcommand_from issues' -l state     -d 'issue state' -r -a 'open closed all'
+complete -c mgw -n '__fish_seen_subcommand_from issues' -s s -l search -d 'pre-populate fuzzy search input' -r
+complete -c mgw -n '__fish_seen_subcommand_from issues' -l limit     -d 'max issues to load' -r -a '10 25 50 100'
+complete -c mgw -n '__fish_seen_subcommand_from issues' -l dry-run   -d 'show what would happen without executing'
+complete -c mgw -n '__fish_seen_subcommand_from issues' -l json      -d 'output structured JSON'
+complete -c mgw -n '__fish_seen_subcommand_from issues' -s v -l verbose -d 'show API calls and file writes'
+complete -c mgw -n '__fish_seen_subcommand_from issues' -l debug     -d 'full payloads and timings'
+complete -c mgw -n '__fish_seen_subcommand_from issues' -l model     -d 'Claude model override' -r
+
+# ---------------------------------------------------------------------------
+# link <ref-a> <ref-b>
+# ---------------------------------------------------------------------------
+complete -c mgw -n '__fish_seen_subcommand_from link' -l quiet   -d 'no GitHub comments'
+complete -c mgw -n '__fish_seen_subcommand_from link' -l dry-run -d 'show what would happen without executing'
+complete -c mgw -n '__fish_seen_subcommand_from link' -l json    -d 'output structured JSON'
+complete -c mgw -n '__fish_seen_subcommand_from link' -s v -l verbose -d 'show API calls and file writes'
+complete -c mgw -n '__fish_seen_subcommand_from link' -l debug   -d 'full payloads and timings'
+complete -c mgw -n '__fish_seen_subcommand_from link' -l model   -d 'Claude model override' -r
+
+# ---------------------------------------------------------------------------
+# Subcommands that only take global flags (no subcommand-specific flags)
+# ---------------------------------------------------------------------------
+for _mgw_cmd in init project next issue update sync help
+  complete -c mgw -n "__fish_seen_subcommand_from $_mgw_cmd" -l dry-run -d 'show what would happen without executing'
+  complete -c mgw -n "__fish_seen_subcommand_from $_mgw_cmd" -l json    -d 'output structured JSON'
+  complete -c mgw -n "__fish_seen_subcommand_from $_mgw_cmd" -s v -l verbose -d 'show API calls and file writes'
+  complete -c mgw -n "__fish_seen_subcommand_from $_mgw_cmd" -l debug   -d 'full payloads and timings'
+  complete -c mgw -n "__fish_seen_subcommand_from $_mgw_cmd" -l model   -d 'Claude model override' -r
+end