@snipcodeit/mgw 0.3.0 → 0.6.0

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

@@ -881,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');
@@ -904,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
@@ -995,7 +1027,7 @@ else:
 esac
 ```
 
-6. Display completion banner:
+8. Display completion banner:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  MGW ► MILESTONE ${MILESTONE_NUM} COMPLETE ✓
@@ -1024,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:**
 
@@ -1127,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>