@snipcodeit/mgw 0.1.3 → 0.2.1

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/commands/workflows/gsd.md

@@ -374,4 +374,74 @@ and codebase to classify, then MGW presents the result and offers follow-up acti
 | Milestone pipeline | run.md, milestone.md |
 | Question classification | ask.md |
 | Model resolution | run.md |
+TB|## PR Review Pattern
+
+MGW:review has two modes:
+1. **Issue Comment Review** (default) — Classifies new comments on an issue since triage
+2. **PR Deep Review** (with --pr flag or PR URL) — Comprehensive senior engineer review
+
+The PR Deep Review pattern below is for Mode 2. This is problem-solving orchestration
+
+Used by `/mgw:review` for deep PR analysis. This is problem-solving orchestration
+(not execution orchestration) — the reviewer has high autonomy to analyze, question
+assumptions, and provide architectural guidance.
+
+```bash
+# 1. Prepare review context
+REVIEW_DIR=".mgw/reviews"
+mkdir -p "$REVIEW_DIR"
+REVIEW_ID="pr-${PR_NUMBER}-$(date +%Y%m%d-%H%M%S)"
+
+# 2. Create context file with PR details, diff, linked issue
+cat > "${REVIEW_DIR}/${REVIEW_ID}-context.md" << EOF
+# PR Review Context
+
+## PR Information
+- Number: #${PR_NUMBER}
+- Title: ${PR_TITLE}
+...
+EOF
+
+# 3. Spawn deep review agent
+Task(
+  prompt="
+    <files_to_read>
+    - ./CLAUDE.md
+    - ${REVIEW_CONTEXT_FILE}
+    </files_to_read>
+
+    You are a senior code reviewer performing comprehensive PR review.
+    Analyze across five dimensions: test, rationale, intent vs implementation,
+    impact analysis, and architectural review.
+
+    Return structured JSON with test_results, rationale, intent_vs_implementation,
+    impact_analysis, architectural_review, and overall_verdict.
+  ",
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="Deep review PR #${PR_NUMBER}"
+)
+
+# 4. Store results in .mgw/reviews/
+```
+
+**State separation:**
+- `.mgw/active/` — MGW pipeline state
+- `.mgw/reviews/` — PR review state (think tank context)
+- `.planning/` — GSD execution state
+
+This separation gives the reviewer space to handle larger context for
+mission-critical review processes without polluting pipeline or execution state.
+
+## Consumers
+
+| Pattern | Referenced By |
+|---------|---------------|
+| Standard spawn template | run.md, issue.md, pr.md, ask.md, review.md |
+| PR deep review | review.md (new) |
+| Comment classification | run.md (pre-flight) |
+| Quick pipeline | run.md |
+| Milestone pipeline | run.md, milestone.md |
+| Question classification | ask.md |
+| Model resolution | run.md |
 | Utility patterns | run.md, pr.md, issue.md, sync.md, link.md, update.md, ask.md |

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

package/completions/mgw.zsh

@@ -0,0 +1,142 @@
+#compdef mgw
+# mgw zsh completion script
+# Place in a directory on your $fpath (e.g. /usr/local/share/zsh/site-functions/_mgw)
+# or source directly: source completions/mgw.zsh
+# Generated by bin/generate-completions.cjs
+
+_mgw() {
+  local context state state_descr line
+  typeset -A opt_args
+
+  local -a global_flags
+  global_flags=(
+    '--dry-run[show what would happen without executing]'
+    '--json[output structured JSON]'
+    '(-v --verbose)'{-v,--verbose}'[show API calls and file writes]'
+    '--debug[full payloads and timings]'
+    '--model[Claude model override]:model:(claude-opus-4-5 claude-sonnet-4-5 claude-haiku-4-5)'
+  )
+
+  _arguments -C \
+    "${global_flags[@]}" \
+    '(-h --help)'{-h,--help}'[display help]' \
+    '(-V --version)'{-V,--version}'[output the version number]' \
+    '1: :_mgw_subcommands' \
+    '*:: :->subcommand_args' \
+    && return 0
+
+  case "$state" in
+    subcommand_args)
+      case "$words[1]" in
+        run)
+          _arguments \
+            "${global_flags[@]}" \
+            '--quiet[buffer output, show summary at end]' \
+            '--auto[phase chaining: discuss -> plan -> execute]' \
+            '1:issue-number:_mgw_issue_numbers' \
+            && return 0
+          ;;
+        init)
+          _arguments "${global_flags[@]}" && return 0
+          ;;
+        project)
+          _arguments "${global_flags[@]}" && return 0
+          ;;
+        milestone)
+          _arguments \
+            "${global_flags[@]}" \
+            '--interactive[pause between issues for review]' \
+            '1::milestone-number:' \
+            && return 0
+          ;;
+        next)
+          _arguments "${global_flags[@]}" && return 0
+          ;;
+        issue)
+          _arguments \
+            "${global_flags[@]}" \
+            '1:issue-number:_mgw_issue_numbers' \
+            && return 0
+          ;;
+        update)
+          _arguments \
+            "${global_flags[@]}" \
+            '1:issue-number:_mgw_issue_numbers' \
+            '2::message:' \
+            && return 0
+          ;;
+        pr)
+          _arguments \
+            "${global_flags[@]}" \
+            '--base[custom base branch]:branch:_git_branch_names' \
+            '1::issue-number:_mgw_issue_numbers' \
+            && return 0
+          ;;
+        sync)
+          _arguments "${global_flags[@]}" && return 0
+          ;;
+        issues)
+          _arguments \
+            "${global_flags[@]}" \
+            '--label[filter by label]:label:' \
+            '--milestone[filter by milestone]:milestone:' \
+            '--assignee[filter by assignee]:assignee:(all @me)' \
+            '--state[issue state]:state:(open closed all)' \
+            '(-s --search)'{-s,--search}'[pre-populate fuzzy search input]:query:' \
+            '--limit[max issues to load]:number:(10 25 50 100)' \
+            && return 0
+          ;;
+        link)
+          _arguments \
+            "${global_flags[@]}" \
+            '--quiet[no GitHub comments]' \
+            '1:ref-a:' \
+            '2:ref-b:' \
+            && return 0
+          ;;
+        help)
+          return 0
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_mgw_subcommands() {
+  local -a subcommands
+  subcommands=(
+    'run:Run the full pipeline for an issue'
+    'init:Bootstrap repo for MGW (state, templates, labels)'
+    'project:Initialize project from template (milestones, issues, ROADMAP)'
+    'milestone:Execute milestone issues in dependency order'
+    'next:Show next unblocked issue'
+    'issue:Triage issue against codebase'
+    'update:Post status comment on issue'
+    'pr:Create PR from GSD artifacts'
+    'sync:Reconcile .mgw/ state with GitHub'
+    'issues:Browse open issues'
+    'link:Cross-reference issues/PRs/branches'
+    'help:Show command reference'
+  )
+  _describe 'mgw subcommand' subcommands
+}
+
+_mgw_issue_numbers() {
+  # Attempt to complete issue numbers from active .mgw/ state
+  local -a active_issues
+  local active_dir=".mgw/active"
+  if [[ -d "$active_dir" ]]; then
+    for f in "$active_dir"/*.json; do
+      [[ -f "$f" ]] || continue
+      local num="${${f:t}%%[-_]*}"
+      [[ "$num" =~ ^[0-9]+$ ]] && active_issues+=("$num")
+    done
+  fi
+  if (( ${#active_issues[@]} > 0 )); then
+    _describe 'issue number' active_issues
+  else
+    _message 'issue number'
+  fi
+}
+
+_mgw "$@"