@snipcodeit/mgw 0.1.0

package/commands/next.md

@@ -0,0 +1,375 @@
+---
+name: mgw:next
+description: Show next unblocked issue — what to work on now, based on declared dependencies
+argument-hint: ""
+allowed-tools:
+  - Bash
+  - Read
+  - AskUserQuestion
+---
+
+<objective>
+Surface the next unblocked issue across the current milestone based on dependency
+declarations. Local-first: reads project.json for fast answer, then does a quick
+`gh` API check to verify the issue is still open.
+
+This is a read-only command — it does NOT modify state, run pipelines, or create
+worktrees. After displaying the brief, it offers to run `/mgw:run` for the
+recommended issue.
+</objective>
+
+<execution_context>
+@~/.claude/commands/mgw/workflows/state.md
+@~/.claude/commands/mgw/workflows/github.md
+</execution_context>
+
+<process>
+
+<step name="load_state">
+**Load project.json and validate:**
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+MGW_DIR="${REPO_ROOT}/.mgw"
+
+if [ ! -f "${MGW_DIR}/project.json" ]; then
+  echo "No project initialized. Run /mgw:project first."
+  exit 1
+fi
+
+PROJECT_JSON=$(cat "${MGW_DIR}/project.json")
+
+# Resolve active milestone index using state resolution (supports both schema versions)
+ACTIVE_IDX=$(node -e "
+const { loadProjectState, resolveActiveMilestoneIndex } = require('./lib/state.cjs');
+const state = loadProjectState();
+console.log(resolveActiveMilestoneIndex(state));
+")
+
+# Get milestone data
+MILESTONE_DATA=$(echo "$PROJECT_JSON" | python3 -c "
+import json,sys
+p = json.load(sys.stdin)
+idx = ${ACTIVE_IDX}
+if idx < 0 or idx >= len(p['milestones']):
+    print(json.dumps({'error': 'No more milestones'}))
+    sys.exit(0)
+m = p['milestones'][idx]
+print(json.dumps(m))
+")
+
+MILESTONE_NAME=$(echo "$MILESTONE_DATA" | python3 -c "import json,sys; print(json.load(sys.stdin)['name'])")
+ISSUES_JSON=$(echo "$MILESTONE_DATA" | python3 -c "import json,sys; print(json.dumps(json.load(sys.stdin)['issues']))")
+TOTAL_ISSUES=$(echo "$ISSUES_JSON" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))")
+```
+</step>
+
+<step name="resolve_dependencies">
+**Compute dependency graph and ordered issue list:**
+
+```bash
+DEPENDENCY_RESULT=$(echo "$ISSUES_JSON" | python3 -c "
+import json, sys
+from collections import defaultdict
+
+issues = json.load(sys.stdin)
+
+# Build slug-to-issue and number-to-issue mappings
+slug_to_issue = {}
+num_to_issue = {}
+slug_to_num = {}
+for issue in issues:
+    title = issue.get('title', '')
+    slug = title.lower().replace(' ', '-')[:40]
+    slug_to_issue[slug] = issue
+    num_to_issue[issue['github_number']] = issue
+    slug_to_num[slug] = issue['github_number']
+
+# Build forward and reverse dependency maps
+# forward: issue -> what it depends on
+# reverse: issue -> what it unblocks
+forward_deps = {}  # slug -> [blocking_slugs]
+reverse_deps = defaultdict(list)  # slug -> [dependent_slugs]
+
+for issue in issues:
+    title = issue.get('title', '')
+    slug = title.lower().replace(' ', '-')[:40]
+    deps = issue.get('depends_on_slugs', [])
+    forward_deps[slug] = deps
+    for dep_slug in deps:
+        if dep_slug in slug_to_issue:
+            reverse_deps[dep_slug].append(slug)
+
+# Find unblocked issues:
+# - pipeline_stage == 'new' (not done, not failed, not in-progress)
+# - ALL depends_on issues have pipeline_stage == 'done'
+unblocked = []
+blocked = []
+done_count = 0
+failed_issues = []
+
+for issue in issues:
+    title = issue.get('title', '')
+    slug = title.lower().replace(' ', '-')[:40]
+    stage = issue.get('pipeline_stage', 'new')
+
+    if stage == 'done':
+        done_count += 1
+        continue
+    if stage == 'failed':
+        failed_issues.append(issue)
+        continue
+    if stage not in ('new',):
+        continue  # in-progress, skip for now
+
+    # Check if all dependencies are done
+    deps = issue.get('depends_on_slugs', [])
+    all_deps_done = True
+    blocking_info = []
+    for dep_slug in deps:
+        if dep_slug in slug_to_issue:
+            dep_issue = slug_to_issue[dep_slug]
+            if dep_issue.get('pipeline_stage') != 'done':
+                all_deps_done = False
+                blocking_info.append({
+                    'number': dep_issue['github_number'],
+                    'title': dep_issue['title'],
+                    'stage': dep_issue.get('pipeline_stage', 'new')
+                })
+
+    if all_deps_done:
+        # Compute what this issue unblocks
+        unblocks = []
+        for dep_slug in reverse_deps.get(slug, []):
+            if dep_slug in slug_to_issue:
+                dep_issue = slug_to_issue[dep_slug]
+                unblocks.append({
+                    'number': dep_issue['github_number'],
+                    'title': dep_issue['title']
+                })
+
+        # Compute resolved dependencies
+        resolved_deps = []
+        for dep_slug in deps:
+            if dep_slug in slug_to_issue:
+                dep_issue = slug_to_issue[dep_slug]
+                resolved_deps.append({
+                    'number': dep_issue['github_number'],
+                    'title': dep_issue['title']
+                })
+
+        unblocked.append({
+            'issue': issue,
+            'unblocks': unblocks,
+            'resolved_deps': resolved_deps
+        })
+    else:
+        blocked.append({
+            'issue': issue,
+            'blocked_by': blocking_info
+        })
+
+# Sort unblocked by phase_number (first = recommended)
+unblocked.sort(key=lambda x: x['issue'].get('phase_number', 999))
+
+result = {
+    'unblocked': unblocked,
+    'blocked': blocked,
+    'done_count': done_count,
+    'total': len(issues),
+    'failed': [{'number': i['github_number'], 'title': i['title']} for i in failed_issues]
+}
+print(json.dumps(result, indent=2))
+")
+```
+</step>
+
+<step name="handle_nothing_unblocked">
+**If no issues are unblocked:**
+
+Check if ALL issues are done:
+```bash
+ALL_DONE=$(echo "$DEPENDENCY_RESULT" | python3 -c "
+import json,sys
+r = json.load(sys.stdin)
+print('true' if r['done_count'] == r['total'] else 'false')
+")
+```
+
+If all done:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MGW ► ALL DONE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+All ${TOTAL_ISSUES} issues in milestone "${MILESTONE_NAME}" are complete.
+
+Run /mgw:milestone to finalize (close milestone, create release).
+```
+
+If not all done (some are blocked/failed):
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MGW ► BLOCKED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+No unblocked issues in milestone "${MILESTONE_NAME}".
+
+| Issue | Blocked By | Blocker Status |
+|-------|-----------|----------------|
+| #N title | #M title | ◆ In progress |
+| #K title | #J title | ✗ Failed |
+
+${failed_advice}
+
+Progress: ${done_count}/${total} complete
+```
+
+Where `${failed_advice}` is: "Resolve #J to unblock #K." (specific actionable advice for each failed blocker).
+</step>
+
+<step name="verify_live">
+**Quick GitHub verification for recommended issue:**
+
+```bash
+RECOMMENDED=$(echo "$DEPENDENCY_RESULT" | python3 -c "
+import json,sys
+r = json.load(sys.stdin)
+if r['unblocked']:
+    print(json.dumps(r['unblocked'][0]))
+else:
+    print('null')
+")
+```
+
+If recommended issue exists:
+```bash
+REC_NUMBER=$(echo "$RECOMMENDED" | python3 -c "import json,sys; print(json.load(sys.stdin)['issue']['github_number'])")
+
+# Quick GitHub check — verify issue is still open
+GH_CHECK=$(gh issue view ${REC_NUMBER} --json state,title,labels -q '{state: .state, title: .title}' 2>/dev/null)
+
+if [ -n "$GH_CHECK" ]; then
+  GH_STATE=$(echo "$GH_CHECK" | python3 -c "import json,sys; print(json.load(sys.stdin)['state'])")
+  if [ "$GH_STATE" != "OPEN" ]; then
+    # Issue was closed externally — skip to next unblocked
+    echo "Issue #${REC_NUMBER} is ${GH_STATE} on GitHub. Checking next..."
+    # Remove from unblocked list, try next
+  fi
+  VERIFIED="(verified)"
+else
+  VERIFIED="(GitHub state unverified)"
+fi
+```
+</step>
+
+<step name="display_brief">
+**Display full brief for recommended issue:**
+
+```bash
+REC_ISSUE=$(echo "$RECOMMENDED" | python3 -c "import json,sys; r=json.load(sys.stdin); print(json.dumps(r['issue']))")
+REC_TITLE=$(echo "$REC_ISSUE" | python3 -c "import json,sys; print(json.load(sys.stdin)['title'])")
+REC_GSD_ROUTE=$(echo "$REC_ISSUE" | python3 -c "import json,sys; print(json.load(sys.stdin).get('gsd_route','plan-phase'))")
+REC_LABELS=$(echo "$REC_ISSUE" | python3 -c "import json,sys; print(', '.join(json.load(sys.stdin).get('labels',[])))")
+REC_PHASE=$(echo "$REC_ISSUE" | python3 -c "import json,sys; print(json.load(sys.stdin).get('phase_number',''))")
+REC_PHASE_NAME=$(echo "$REC_ISSUE" | python3 -c "import json,sys; print(json.load(sys.stdin).get('phase_name',''))")
+
+DONE_COUNT=$(echo "$DEPENDENCY_RESULT" | python3 -c "import json,sys; print(json.load(sys.stdin)['done_count'])")
+```
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MGW ► NEXT UP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Issue:       #${REC_NUMBER} — ${REC_TITLE} ${VERIFIED}
+GSD Route:   ${REC_GSD_ROUTE}
+Phase:       ${REC_PHASE}: ${REC_PHASE_NAME}
+Labels:      ${REC_LABELS}
+Milestone:   ${MILESTONE_NAME} (${DONE_COUNT}/${TOTAL_ISSUES} complete)
+
+Dependencies (all done):
+  ✓ #${dep1_number} — ${dep1_title}
+  ✓ #${dep2_number} — ${dep2_title}
+  (or: None — this is an independent issue)
+
+Unblocks:
+  ○ #${next1_number} — ${next1_title}
+  ○ #${next2_number} — ${next2_title}
+  (or: None — no downstream dependencies)
+
+───────────────────────────────────────────────────────────────
+```
+
+If other unblocked alternatives exist:
+```bash
+ALT_COUNT=$(echo "$DEPENDENCY_RESULT" | python3 -c "
+import json,sys
+r = json.load(sys.stdin)
+print(len(r['unblocked']) - 1)
+")
+```
+
+If ALT_COUNT > 0:
+```
+Also unblocked:
+  #${alt1_number} — ${alt1_title} (${alt1_gsd_route})
+  #${alt2_number} — ${alt2_title} (${alt2_gsd_route})
+```
+</step>
+
+<step name="offer_run">
+**Offer to run the recommended issue:**
+
+```
+AskUserQuestion(
+  header: "Ready to Start",
+  question: "Run /mgw:run #${REC_NUMBER} now?",
+  options: [
+    { label: "Yes", description: "Start the pipeline for this issue" },
+    { label: "No", description: "Just viewing — I'll run it later" },
+    { label: "Pick different", description: "Choose a different unblocked issue" }
+  ]
+)
+```
+
+**If "Yes":** Display the command to run:
+```
+Start the pipeline:
+
+  /mgw:run ${REC_NUMBER}
+
+<sub>/clear first → fresh context window</sub>
+```
+
+Note: /mgw:next is read-only (allowed-tools don't include Task). It cannot invoke
+/mgw:run directly. It displays the command for the user to run.
+
+**If "Pick different":** Display the alternatives list and ask user to pick:
+```
+AskUserQuestion(
+  header: "Select Issue",
+  question: "Which issue do you want to work on?",
+  options: [alt_issues_as_options]
+)
+```
+
+Then re-display the brief for the selected issue.
+
+**If "No":** Exit cleanly.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] project.json loaded and current milestone identified (MLST-02)
+- [ ] Dependency graph computed from depends_on_slugs
+- [ ] Single recommended issue surfaced (dependency order, then phase order)
+- [ ] Full brief displayed: number, title, GSD route, labels, dependencies, what it unblocks, milestone context
+- [ ] Alternatives listed when multiple issues are unblocked
+- [ ] Blocking chain shown when nothing is unblocked
+- [ ] Live GitHub verification attempted for recommended issue
+- [ ] Offer to run /mgw:run displayed
+- [ ] Read-only: no state modifications, no pipeline execution
+</success_criteria>

package/commands/pr.md

@@ -0,0 +1,277 @@
+---
+name: mgw:pr
+description: Create a pull request from GSD artifacts and linked issue context
+argument-hint: "[issue-number] [--base <branch>]"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Task
+---
+
+<objective>
+Create a PR with context pulled from GSD artifacts (SUMMARY.md, VERIFICATION.md)
+and the linked GitHub issue. Builds a structured PR description with summary,
+testing procedures, and cross-references.
+
+Works in two modes:
+1. **Linked mode:** Issue number provided or found in .mgw/active/ — pulls issue
+   context, GSD artifacts, and cross-refs into the PR.
+2. **Standalone mode:** No issue — builds PR from GSD artifacts in .planning/ or
+   from the branch diff.
+</objective>
+
+<execution_context>
+@~/.claude/commands/mgw/workflows/state.md
+@~/.claude/commands/mgw/workflows/github.md
+@~/.claude/commands/mgw/workflows/gsd.md
+@~/.claude/commands/mgw/workflows/validation.md
+</execution_context>
+
+<context>
+$ARGUMENTS — optional: [issue-number] [--base <branch>]
+</context>
+
+<process>
+
+<step name="detect_mode">
+**Determine linked vs standalone mode:**
+
+If issue number in $ARGUMENTS → linked mode.
+Else if exactly one file in .mgw/active/ → linked mode with that issue.
+Else → standalone mode.
+
+Parse `--base <branch>` if provided, default to repo default branch:
+```bash
+DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
+```
+</step>
+
+<step name="gather_gsd_artifacts">
+**Gather GSD artifacts:**
+
+**Linked mode:** Read state file for gsd_artifacts.path, then:
+```bash
+# Structured summary data via gsd-tools (returns JSON with one_liner, key_files, tech_added, patterns, decisions)
+SUMMARY_DATA=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs summary-extract "${gsd_artifacts_path}/*SUMMARY*" 2>/dev/null || echo '{}')
+# Also read raw artifacts for full context
+SUMMARY_RAW=$(cat ${gsd_artifacts_path}/*SUMMARY* 2>/dev/null)
+VERIFICATION=$(cat ${gsd_artifacts_path}/*VERIFICATION* 2>/dev/null)
+# Progress table for details section
+PROGRESS_TABLE=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs progress table --raw 2>/dev/null || echo "")
+
+# Milestone/phase context for PR body
+MILESTONE_TITLE=""
+PHASE_INFO=""
+DEPENDENCY_CHAIN=""
+if [ -f "${REPO_ROOT}/.mgw/project.json" ]; then
+  MILESTONE_TITLE=$(python3 -c "
+import json
+p = json.load(open('${REPO_ROOT}/.mgw/project.json'))
+for m in p['milestones']:
+  for i in m.get('issues', []):
+    if i.get('github_number') == ${ISSUE_NUMBER}:
+      print(m['name'])
+      break
+" 2>/dev/null || echo "")
+
+  PHASE_INFO=$(python3 -c "
+import json
+p = json.load(open('${REPO_ROOT}/.mgw/project.json'))
+for m in p['milestones']:
+  for i in m.get('issues', []):
+    if i.get('github_number') == ${ISSUE_NUMBER}:
+      total = len(m.get('issues', []))
+      idx = [x['github_number'] for x in m['issues']].index(${ISSUE_NUMBER}) + 1
+      print(f\"Phase {i['phase_number']}: {i['phase_name']} (issue {idx}/{total} in milestone)\")
+      break
+" 2>/dev/null || echo "")
+
+  DEPENDENCY_CHAIN=$(python3 -c "
+import json
+p = json.load(open('${REPO_ROOT}/.mgw/project.json'))
+refs = json.load(open('${REPO_ROOT}/.mgw/cross-refs.json'))
+blockers = [l['b'].split(':')[1] for l in refs.get('links', [])
+            if l.get('type') == 'blocked-by' and l['a'] == 'issue:${ISSUE_NUMBER}']
+blocks = [l['a'].split(':')[1] for l in refs.get('links', [])
+          if l.get('type') == 'blocked-by' and l['b'] == 'issue:${ISSUE_NUMBER}']
+parts = []
+if blockers: parts.append('Blocked by: ' + ', '.join(f'#{b}' for b in blockers))
+if blocks: parts.append('Unblocks: ' + ', '.join(f'#{b}' for b in blocks))
+print(' | '.join(parts) if parts else '')
+" 2>/dev/null || echo "")
+fi
+```
+
+**Standalone mode:** Search .planning/ for recent artifacts:
+```bash
+# Check quick tasks first, then phases
+SUMMARY_PATH=$(ls -t .planning/quick/*/SUMMARY.md .planning/phases/*/SUMMARY.md 2>/dev/null | head -1)
+if [ -n "$SUMMARY_PATH" ]; then
+  SUMMARY_DATA=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs summary-extract "$SUMMARY_PATH" 2>/dev/null || echo '{}')
+  SUMMARY_RAW=$(cat "$SUMMARY_PATH" 2>/dev/null)
+fi
+```
+
+If no GSD artifacts found → fall back to `git log ${base}..HEAD --oneline` for PR content.
+</step>
+
+<step name="build_pr_body">
+**Build PR description:**
+
+Spawn task agent to compose the PR body:
+
+```
+Task(
+  prompt="
+<files_to_read>
+- ./CLAUDE.md (Project instructions — if exists, follow all guidelines)
+- .agents/skills/ (Project skills — if dir exists, list skills, read SKILL.md for each, follow relevant rules)
+</files_to_read>
+
+Build a GitHub PR description from these inputs.
+
+<issue_context>
+${issue_title_and_body_if_linked}
+Issue: #${ISSUE_NUMBER} (or 'none — standalone')
+</issue_context>
+
+<gsd_summary_structured>
+${SUMMARY_DATA}
+</gsd_summary_structured>
+
+<gsd_summary_raw>
+${SUMMARY_RAW}
+</gsd_summary_raw>
+
+<gsd_verification>
+${VERIFICATION}
+</gsd_verification>
+
+<cross_refs>
+${CROSS_REFS_FOR_THIS_ISSUE}
+</cross_refs>
+
+<commits>
+${GIT_LOG_BASE_TO_HEAD}
+</commits>
+
+<milestone_context>
+Milestone: ${MILESTONE_TITLE}
+Phase: ${PHASE_INFO}
+Dependencies: ${DEPENDENCY_CHAIN}
+</milestone_context>
+
+<output_format>
+Return EXACTLY two sections separated by ===TESTING===:
+
+SECTION 1 — PR body:
+## Summary
+- [2-4 bullet points of what changed and why]
+- [Use one_liner from gsd_summary_structured if available]
+
+${if_linked: 'Closes #${ISSUE_NUMBER}'}
+
+${if MILESTONE_TITLE non-empty:
+## Milestone Context
+- **Milestone:** ${MILESTONE_TITLE}
+- **Phase:** ${PHASE_INFO}
+- **Dependencies:** ${DEPENDENCY_CHAIN}
+}
+
+## Changes
+- [File-level changes grouped by system/module]
+- [Use key_files from gsd_summary_structured if available]
+
+## Cross-References
+${cross_ref_list_or_omit_if_none}
+
+${if PROGRESS_TABLE non-empty:
+<details>
+<summary>GSD Progress</summary>
+
+${PROGRESS_TABLE}
+
+</details>
+}
+
+===TESTING===
+
+SECTION 2 — Testing procedures comment:
+## Testing Procedures
+- [ ] [Step-by-step verification checklist]
+- [ ] [Derived from VERIFICATION.md if available]
+- [ ] [Or from the changes themselves]
+</output_format>
+",
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="Build PR description for #${ISSUE_NUMBER}"
+)
+```
+
+Split agent output on `===TESTING===` into $PR_BODY and $TESTING_COMMENT.
+</step>
+
+<step name="create_pr">
+**Create the PR:**
+
+Determine PR title:
+- Linked: from issue title, prefixed with type (fix:, feat:, etc.)
+- Standalone: from first commit message or branch name
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+gh pr create --title "${PR_TITLE}" --base "${BASE_BRANCH}" --body "${PR_BODY}"
+```
+
+Capture PR number and URL from output.
+</step>
+
+<step name="post_testing">
+**Post testing procedures as PR comment:**
+
+```bash
+gh pr comment ${PR_NUMBER} --body "${TESTING_COMMENT}"
+```
+</step>
+
+<step name="update_state">
+**Update .mgw/ state (linked mode only):**
+
+Update state file:
+- Set linked_pr to PR number
+- Set pipeline_stage to "pr-created"
+
+Add cross-ref: issue → PR link in cross-refs.json.
+</step>
+
+<step name="report">
+**Report:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MGW ► PR CREATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+PR #${PR_NUMBER}: ${PR_TITLE}
+URL: ${PR_URL}
+${if_linked: "Closes: #${ISSUE_NUMBER}"}
+Testing procedures posted as PR comment.
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Mode detected correctly (linked vs standalone)
+- [ ] GSD artifacts found and read (or fallback to git log)
+- [ ] PR body includes summary, changes, cross-refs, and Closes #N
+- [ ] PR created via gh pr create
+- [ ] Testing procedures posted as separate PR comment
+- [ ] State file updated with PR number (linked mode)
+- [ ] Cross-ref added (linked mode)
+</success_criteria>