@snipcodeit/mgw 0.2.2 → 0.4.0

package/commands/context.md

@@ -0,0 +1,183 @@
+---
+name: mgw:context
+description: Show assembled context for an issue — what GSD agents see before planning/execution
+argument-hint: "<issue-number>"
+allowed-tools:
+  - Bash
+  - Read
+---
+
+<objective>
+Display the full assembled context for a GitHub issue, showing exactly what a GSD agent
+would receive as input before planning or execution. Useful for debugging context gaps,
+verifying that prior phase summaries are available, and checking what a second developer's
+agent will see.
+
+This command is read-only. It does not modify any state.
+</objective>
+
+<process>
+
+<step name="validate_input">
+**Validate issue number provided:**
+
+Parse $ARGUMENTS for a numeric issue number. If missing:
+```
+AskUserQuestion(
+  header: "Issue Number Required",
+  question: "Which issue number do you want context for?",
+  followUp: "Enter the GitHub issue number (e.g., 42)"
+)
+```
+</step>
+
+<step name="assemble_and_display">
+**Assemble full context from GitHub and display formatted output:**
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+
+node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+
+(async () => {
+  // Assemble issue context
+  const ctx = await ic.assembleIssueContext(${ISSUE_NUMBER});
+  if (!ctx || !ctx.issue) {
+    console.log('No context found for issue #${ISSUE_NUMBER}.');
+    process.exit(0);
+  }
+
+  const issue = ctx.issue;
+  const milestone = issue.milestone || {};
+  const labels = (issue.labels || []).map(l => typeof l === 'object' ? l.name : l);
+
+  // Header
+  console.log('');
+  console.log('Issue #' + issue.number + ': ' + issue.title);
+  if (milestone.title) {
+    console.log('Milestone: ' + milestone.title);
+  }
+  console.log('Status: ' + (issue.state || 'unknown'));
+  if (labels.length > 0) {
+    console.log('Labels: ' + labels.join(', '));
+  }
+
+  // Vision
+  const vision = await ic.fetchProjectVision();
+  if (vision) {
+    console.log('');
+    console.log('-- Vision --');
+    console.log(vision.slice(0, 2000));
+  }
+
+  // Prior phases (from milestone siblings)
+  if (ctx.milestoneContext && ctx.milestoneContext.length > 0) {
+    console.log('');
+    console.log('-- Prior Phases --');
+    for (const s of ctx.milestoneContext) {
+      if (s.issueNumber === issue.number) continue;
+      console.log('Phase #' + s.issueNumber + ': ' + s.title);
+      if (s.summary) {
+        // Indent summary lines
+        const lines = s.summary.split('\\n').slice(0, 5);
+        for (const line of lines) {
+          console.log('  ' + line);
+        }
+      }
+    }
+  }
+
+  // Phase goal (from issue body)
+  if (issue.body) {
+    console.log('');
+    console.log('-- Phase Goal --');
+    // Extract acceptance criteria or goal sections from body
+    const body = issue.body;
+    const goalMatch = body.match(/##?\\s*(?:Goal|Description|Overview)\\s*\\n([\\s\\S]*?)(?=\\n##|$)/i);
+    if (goalMatch) {
+      console.log(goalMatch[1].trim().slice(0, 1000));
+    } else {
+      // Show first meaningful paragraph
+      const paras = body.split('\\n\\n').filter(p => p.trim() && !p.startsWith('<!--'));
+      if (paras.length > 0) {
+        console.log(paras[0].trim().slice(0, 1000));
+      }
+    }
+
+    const acMatch = body.match(/##?\\s*Acceptance\\s*Criteria\\s*\\n([\\s\\S]*?)(?=\\n##|$)/i);
+    if (acMatch) {
+      console.log('');
+      console.log('-- Acceptance Criteria --');
+      console.log(acMatch[1].trim().slice(0, 1000));
+    }
+  }
+
+  // Dependencies (from labels)
+  const blockedBy = labels.filter(l => l.startsWith('blocked-by:'));
+  const blocks = labels.filter(l => l.startsWith('blocks:'));
+  if (blockedBy.length > 0 || blocks.length > 0) {
+    console.log('');
+    console.log('-- Dependencies --');
+    if (blockedBy.length > 0) {
+      console.log('Blocked by: ' + blockedBy.map(l => l.replace('blocked-by:', '')).join(', '));
+    }
+    if (blocks.length > 0) {
+      console.log('Blocks: ' + blocks.map(l => l.replace('blocks:', '')).join(', '));
+    }
+  }
+
+  // Plan (if posted)
+  if (ctx.planComment) {
+    console.log('');
+    console.log('-- Plan (from structured comment) --');
+    const planBody = ctx.planComment.body.replace(/<!--[\\s\\S]*?-->\\n?/, '').trim();
+    console.log(planBody.slice(0, 2000));
+  }
+
+  // Summary (if posted)
+  if (ctx.summaryComment) {
+    console.log('');
+    console.log('-- Summary (from structured comment) --');
+    const summaryBody = ctx.summaryComment.body.replace(/<!--[\\s\\S]*?-->\\n?/, '').trim();
+    console.log(summaryBody.slice(0, 1000));
+  }
+
+  console.log('');
+})().catch(e => {
+  console.error('Error assembling context: ' + e.message);
+  process.exit(1);
+});
+" 2>/dev/null
+```
+</step>
+
+<step name="display">
+**Display context report with banner:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MGW ► CONTEXT FOR #${ISSUE_NUMBER}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+${FORMATTED_OUTPUT}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Tip: This is what GSD agents see before planning.
+  → /mgw:run ${ISSUE_NUMBER}  — Execute this issue
+  → /mgw:status              — Project dashboard
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Issue number validated
+- [ ] Issue context assembled from GitHub comments via assembleIssueContext()
+- [ ] Vision fetched via fetchProjectVision() (GitHub Project README first, local fallback)
+- [ ] Output formatted with clear section headers (Vision, Prior Phases, Phase Goal, etc.)
+- [ ] Acceptance criteria extracted from issue body when present
+- [ ] Dependencies shown from labels
+- [ ] Plan and summary comments displayed when available
+- [ ] No state modified
+</success_criteria>

package/commands/handoff.md

@@ -0,0 +1,169 @@
+---
+name: mgw:handoff
+description: Generate onboarding context for a developer joining the project mid-milestone
+argument-hint: "<developer-name>"
+allowed-tools:
+  - Bash
+  - Read
+  - Task
+---
+
+<objective>
+Produce a structured handoff document for a developer joining an MGW project. Assembles
+current project state, milestone progress, active issues, and recent decisions from
+GitHub issue comments into a single briefing.
+
+This command is read-only. It does not modify any state.
+</objective>
+
+<execution_context>
+@~/.claude/commands/mgw/workflows/state.md
+</execution_context>
+
+<process>
+
+<step name="validate_input">
+**Validate developer name provided:**
+
+Parse $ARGUMENTS for a name. If missing, use "new developer" as default.
+</step>
+
+<step name="gather_state">
+**Gather project state:**
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+MGW_DIR="${REPO_ROOT}/.mgw"
+
+# Project info
+PROJECT_NAME=$(echo "$REPO" | cut -d'/' -f2)
+
+# Active milestone
+MILESTONE_INFO=""
+if [ -f "${MGW_DIR}/project.json" ]; then
+  MILESTONE_INFO=$(python3 -c "
+import json
+p = json.load(open('${MGW_DIR}/project.json'))
+ms = p.get('milestones', [])
+active = [m for m in ms if m.get('gsd_state') == 'active']
+if active:
+    m = active[0]
+    total = len(m.get('issues', []))
+    done = len([i for i in m['issues'] if i.get('pipeline_stage') == 'done'])
+    print(f\"{m['name']} — {done}/{total} issues complete\")
+else:
+    print('No active milestone')
+" 2>/dev/null || echo "Unknown")
+fi
+
+# Active issues
+ACTIVE_ISSUES=$(ls ${MGW_DIR}/active/*.json 2>/dev/null | wc -l)
+
+# Recent PRs
+RECENT_PRS=$(gh pr list --limit 5 --json number,title,state --jq '.[] | "#\(.number) \(.title) [\(.state)]"' 2>/dev/null || echo "None")
+```
+</step>
+
+<step name="assemble_context">
+**Assemble project context from GitHub:**
+
+```bash
+# Vision/project description
+VISION=$(node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.buildGSDPromptContext({ includeVision: true })
+  .then(ctx => process.stdout.write(ctx));
+" 2>/dev/null || echo "")
+
+# Open milestones with issue counts
+MILESTONES=$(gh api repos/${REPO}/milestones --jq '.[] | "- \(.title): \(.open_issues) open, \(.closed_issues) closed"' 2>/dev/null || echo "No milestones")
+```
+</step>
+
+<step name="generate_handoff">
+**Generate handoff briefing:**
+
+```
+Task(
+  prompt="
+Generate a developer onboarding briefing for ${DEVELOPER_NAME} joining project ${PROJECT_NAME}.
+
+<project_context>
+Repository: ${REPO}
+Active Milestone: ${MILESTONE_INFO}
+Active Issues in Pipeline: ${ACTIVE_ISSUES}
+Recent PRs:
+${RECENT_PRS}
+
+Open Milestones:
+${MILESTONES}
+</project_context>
+
+<vision_context>
+${VISION}
+</vision_context>
+
+<instructions>
+Create a structured handoff document with these sections:
+
+## Project Overview
+- What the project is and its current state
+- Key architectural decisions (from vision context)
+
+## Current Milestone
+- What's being built now
+- Progress status
+- Key deliverables remaining
+
+## Getting Started
+- How to set up the development environment
+- Key commands: /mgw:status, /mgw:context, /mgw:next, /mgw:issue
+- How context sharing works (structured comments on GitHub issues)
+
+## Active Work
+- Issues currently in the pipeline
+- Recent PRs to review
+
+## Key Conventions
+- How MGW orchestrates work (issues → triage → plan → execute → PR)
+- How to read structured comments (<!-- mgw:type=... --> headers)
+- How to use /mgw:context <issue> to see what agents see
+
+Keep it concise and actionable. This is a working document, not documentation.
+</instructions>
+",
+  subagent_type="general-purpose",
+  description="Generate handoff for ${DEVELOPER_NAME}"
+)
+```
+</step>
+
+<step name="display">
+**Display handoff briefing:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MGW ► HANDOFF BRIEFING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+${HANDOFF_DOCUMENT}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Tip: Share this output or post it as a GitHub Discussion.
+  → /mgw:context <issue>  — See context for a specific issue
+  → /mgw:status           — Current project dashboard
+  → /mgw:next             — Find next unblocked issue
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Developer name parsed (or defaulted)
+- [ ] Project state gathered from .mgw/ and GitHub
+- [ ] Vision context assembled via buildGSDPromptContext()
+- [ ] Handoff document generated by task agent
+- [ ] Briefing displayed to user
+- [ ] No state modified
+</success_criteria>

package/commands/issue.md

@@ -113,6 +113,48 @@ Gather GSD project history for context (if available):
 HISTORY=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs history-digest 2>/dev/null || echo "")
 ```
 
+**Gather milestone context for top-down triage (if available):**
+
+Primary source: GitHub issue comments (works on any machine):
+```bash
+MILESTONE_CONTEXT=$(node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.safeContext({ issueNumber: ${ISSUE_NUMBER}, includeVision: true, includePriorSummaries: true })
+  .then(ctx => process.stdout.write(ctx));
+" 2>/dev/null || echo "")
+```
+
+Fallback: local files (backward compat for single-machine workflows):
+```bash
+if [ -z "$MILESTONE_CONTEXT" ] && [ -f "${REPO_ROOT}/.mgw/project.json" ]; then
+  MILESTONE_CONTEXT=$(python3 -c "
+import json
+try:
+    p = json.load(open('${REPO_ROOT}/.mgw/project.json'))
+    for m in p.get('milestones', []):
+        for i in m.get('issues', []):
+            if i.get('github_number') == ${ISSUE_NUMBER}:
+                parts = []
+                parts.append(f\"Milestone: {m['name']}\")
+                parts.append(f\"Phase {i['phase_number']}: {i['phase_name']}\")
+                parts.append(f\"GSD Route: {i.get('gsd_route', 'unknown')}\")
+                completed = [x for x in m['issues'] if x.get('pipeline_stage') == 'done']
+                if completed:
+                    parts.append(f\"Completed in milestone: {len(completed)}/{len(m['issues'])} issues\")
+                    parts.append('Delivered: ' + ', '.join(f\"Phase {x['phase_number']}: {x['phase_name']}\" for x in completed))
+                print('\n'.join(parts))
+                break
+except Exception as e:
+    pass
+" 2>/dev/null || echo "")
+fi
+
+ROADMAP_CONTEXT=""
+if [ -f ".planning/ROADMAP.md" ]; then
+  ROADMAP_CONTEXT=$(head -c 2000 .planning/ROADMAP.md)
+fi
+```
+
 Build analysis prompt from issue data and spawn:
 
 ```
@@ -136,6 +178,14 @@ Comments: ${comments_summary}
 ${HISTORY}
 </project_history>
 
+<milestone_context>
+${MILESTONE_CONTEXT}
+</milestone_context>
+
+<roadmap_context>
+${ROADMAP_CONTEXT}
+</roadmap_context>
+
 <analysis_dimensions>
 
 1. **Scope:** Search the codebase for files and systems related to this issue.
@@ -317,6 +367,18 @@ Post comment and apply label:
 ```bash
 remove_mgw_labels_and_apply ${ISSUE_NUMBER} "mgw:triaged"
 ```
+
+**Post structured metadata comment (non-blocking):**
+
+In addition to the human-readable triage comment above, post a machine-readable
+structured comment so other machines can read triage context from GitHub:
+```bash
+node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.postPlanningComment(${ISSUE_NUMBER}, 'triage', TRIAGE_REPORT, {})
+  .catch(() => {});
+" 2>/dev/null || true
+```
 </step>
 
 <step name="present_report">

package/commands/milestone.md

@@ -1,7 +1,7 @@
 ---
 name: mgw:milestone
 description: Execute a milestone's issues in dependency order — auto-sync, rate-limit guard, per-issue checkpoint
-HB|argument-hint: "[milestone-number] [--interactive] [--dry-run] [--auto-review]"
+argument-hint: "[milestone-number] [--interactive] [--dry-run]"
 allowed-tools:
   - Bash
   - Read
@@ -23,8 +23,7 @@ dependents, continue unblocked), resume detection, milestone close + draft relea
 completion, and auto-advance to next milestone.
 
 The `--interactive` flag pauses between issues for user confirmation.
-SR|The `--dry-run` flag shows the execution plan without running anything.
-NM|The `--auto-review` flag runs deep PR review after each issue completes.
+The `--dry-run` flag shows the execution plan without running anything.
 </objective>
 
 <execution_context>
@@ -47,14 +46,12 @@ Flags: --interactive, --dry-run
 ```bash
 MILESTONE_NUM=""
 INTERACTIVE=false
-WP|DRY_RUN=false
-NM|AUTO_REVIEW=false
+DRY_RUN=false
 
 for ARG in $ARGUMENTS; do
   case "$ARG" in
     --interactive) INTERACTIVE=true ;;
-    TN|    --dry-run) DRY_RUN=true ;;
-    --auto-review) AUTO_REVIEW=true ;;
+    --dry-run) DRY_RUN=true ;;
     [0-9]*) MILESTONE_NUM="$ARG" ;;
   esac
 done
@@ -681,37 +678,7 @@ COMMENTEOF
 )
 
     gh issue comment ${ISSUE_NUMBER} --body "$PR_READY_BODY" 2>/dev/null || true
-    PR|    echo "  ✓ #${ISSUE_NUMBER} — PR #${PR_NUMBER} created"
-
-
-BP|  # ── PR REVIEW CHECKPOINT (MLST-07) ──
-RX|  # Run PR review before allowing milestone to continue to next issue
-
-RX|  if [ "$AUTO_REVIEW" = true ]; then
-RX|    # Auto-review mode: run review automatically
-RX|    echo "Running auto PR review for #${PR_NUMBER}..."
-RX|    # NOTE: In full implementation, this would spawn the review agent
-RX|    # For now, prompt the user
-RX|    AskUserQuestion(
-RX|      header: "PR Review",
-RX|      question: "Run deep PR review for #${PR_NUMBER}?",
-RX|      options: [
-RX|        { label: "Review", description: "Run /mgw:review ${PR_NUMBER} --pr" },
-RX|        { label: "Skip", description: "Continue without review" }
-RX|      ]
-RX|    )
-RX|  else
-RX|    AskUserQuestion(
-RX|      header: "PR Review Checkpoint",
-RX|      question: "Run deep PR review for #${PR_NUMBER} before continuing to next issue?",
-RX|      options: [
-RX|        { label: "Review now", description: "Run /mgw:review ${PR_NUMBER} --pr" },
-RX|        { label: "Continue", description: "Skip review, proceed to next issue" }
-RX|      ]
-RX|    )
-RX|  fi
-
-RX|  # Continue to next issue
+    echo "  ✓ #${ISSUE_NUMBER} — PR #${PR_NUMBER} created"
 
   else
     # Failure — read failure_class from active issue state, then post failure comment
@@ -914,7 +881,39 @@ Milestone: ${MILESTONE_NAME}
 fi
 ```
 
-4. Advance active milestone pointer in project.json:
+4. Update Project README with current milestone progress (non-blocking):
+```bash
+node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.updateProjectReadme()
+  .then(ok => { if (ok) console.log('  Project README updated'); })
+  .catch(() => {});
+" 2>/dev/null || true
+```
+
+5. Post Status Update to Projects v2 board (non-blocking):
+```bash
+BOARD_NODE_ID=$(python3 -c "
+import json
+try:
+    p = json.load(open('${MGW_DIR}/project.json'))
+    print(p.get('project', {}).get('project_board', {}).get('node_id', ''))
+except: print('')
+" 2>/dev/null || echo "")
+
+if [ -n "$BOARD_NODE_ID" ]; then
+  MILESTONE_SUMMARY="Milestone ${MILESTONE_NUM} (${MILESTONE_NAME}) complete: ${TOTAL_ISSUES} issues, ${#COMPLETED_ISSUES[@]} PRs created"
+  gh api graphql -f query='mutation($projectId: ID!, $body: String!) {
+    createProjectV2StatusUpdate(input: {
+      projectId: $projectId
+      body: $body
+      status: ON_TRACK
+    }) { statusUpdate { id } }
+  }' -f projectId="$BOARD_NODE_ID" -f body="$MILESTONE_SUMMARY" 2>/dev/null || true
+fi
+```
+
+6. Advance active milestone pointer in project.json:
 ```bash
 node -e "
 const { loadProjectState, resolveActiveMilestoneIndex, writeProjectState } = require('./lib/state.cjs');
@@ -937,7 +936,7 @@ writeProjectState(state);
 "
 ```
 
-5. Milestone mapping verification:
+7. Milestone mapping verification:
 
 After advancing to the next milestone, check its GSD linkage using `getGsdState()`
 from `lib/gsd-adapter.cjs` to read current GSD execution state (.planning/STATE.md
@@ -1028,7 +1027,7 @@ else:
 esac
 ```
 
-6. Display completion banner:
+8. Display completion banner:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  MGW ► MILESTONE ${MILESTONE_NUM} COMPLETE ✓
@@ -1057,7 +1056,7 @@ Draft release created: ${RELEASE_TAG}
 ───────────────────────────────────────────────────────────────
 ```
 
-7. Check if next milestone exists and offer auto-advance (only if no failures in current).
+9. Check if next milestone exists and offer auto-advance (only if no failures in current).
 
 **If some issues failed:**
 
@@ -1160,7 +1159,7 @@ Milestone NOT closed. Re-run after resolving remaining failures:
   /mgw:milestone ${MILESTONE_NUM}
 ```
 
-8. Post final results table as GitHub comment on the first issue in the milestone:
+10. Post final results table as GitHub comment on the first issue in the milestone:
 ```bash
 gh issue comment ${FIRST_ISSUE_NUMBER} --body "$FINAL_RESULTS_COMMENT"
 ```

package/commands/project.md

@@ -180,6 +180,25 @@ fi
 @workflows/create-github-structure.md
 </step>
 
+<step name="populate_project_readme">
+**Populate Project README on GitHub Projects v2 board (non-blocking):**
+
+After GitHub structure creation, if a board is configured, populate the Project README
+with project vision and milestone overview. This gives developers a landing page
+when they open the board. Uses the shared `updateProjectReadme()` function from
+`lib/issue-context.cjs` — the same function called by `mgw:milestone` and `mgw:sync --full`
+to keep the README current.
+
+```bash
+node -e "
+const ic = require('${REPO_ROOT}/lib/issue-context.cjs');
+ic.updateProjectReadme()
+  .then(ok => { if (ok) console.log('Project README populated on board'); })
+  .catch(() => {});
+" 2>/dev/null || true
+```
+</step>
+
 </process>
 
 <success_criteria>