feat(ask): add capability context — command surface, open PRs, live milestones

.planning/quick/4-mgw-ask-capability-context/4-PLAN.md

@@ -0,0 +1,33 @@
+---
+phase: quick
+plan: 4
+type: quick
+must_haves:
+  - New step load_capability_context added between load_project_context and load_active_state in commands/ask.md
+  - Step builds COMMAND_SURFACE from commands/*.md front matter (name + description fields)
+  - Step fetches PR_CONTEXT via gh pr list --state open
+  - Step fetches MILESTONE_LIST via gh api repos/.../milestones
+  - <mgw_capabilities> block injected into Task() prompt after <recent_changes> and before <classification_rules>
+  - <context> block header updated to mention capability context and live state sources
+  - success_criteria updated with three new checklist items
+---
+
+# Plan: Issue #144 — mgw:ask missing capability context
+
+## Summary
+
+`mgw:ask` spawns a classification agent with milestone/issue context but no awareness of
+the MGW command surface, open PRs, or live GitHub milestones. This plan adds a
+`load_capability_context` step to gather that data and injects it into the agent prompt
+via a `<mgw_capabilities>` block.
+
+## Tasks
+
+### Task 1 — Update commands/ask.md
+
+| Field | Value |
+|-------|-------|
+| files | commands/ask.md |
+| action | (1) Insert new `load_capability_context` step between `load_project_context` and `load_active_state`. (2) Add `<mgw_capabilities>` block in the Task() prompt after `<recent_changes>` and before `<classification_rules>`. (3) Update `<context>` block header to mention capability context and live state. (4) Add three new items to `success_criteria`. |
+| verify | Read back the file and confirm: step exists in the correct position, `<mgw_capabilities>` block references all three variables, context block lists both new lines, success_criteria has three new items. |
+| done | All four edits applied; file parses as valid markdown with no broken XML structure. |

.planning/quick/4-mgw-ask-capability-context/4-SUMMARY.md

@@ -0,0 +1,45 @@
+---
+phase: quick
+plan: 4
+type: quick
+issue: 144
+---
+
+# Summary: Issue #144 — mgw:ask missing capability context
+
+## What Was Done
+
+Four edits were made to `commands/ask.md`:
+
+### 1. New step: `load_capability_context` (inserted between `load_project_context` and `load_active_state`)
+
+Collects three data sources into shell variables:
+- `COMMAND_SURFACE` — iterates `commands/*.md`, extracts `name:` and `description:` front matter fields from each file
+- `PR_CONTEXT` — runs `gh pr list --state open` with JSON output to list open PRs by number, branch, and title
+- `MILESTONE_LIST` — uses `gh api repos/.../milestones` to fetch live milestone state; falls back to a "not found" message if the API is unavailable
+
+### 2. `<mgw_capabilities>` block injected into the Task() prompt
+
+Added after `<recent_changes>` and before `<classification_rules>` in `spawn_classification_agent`. The block exposes all three variables to the classification agent so it can reason about which commands exist, which PRs are in flight, and which milestones are open — even when `project.json` is absent or stale.
+
+### 3. `<context>` block header updated
+
+Added two lines documenting the new data sources:
+- `Capability context: commands/*.md front matter (name + description per command)`
+- `Live state: open PRs via gh pr list, milestones via gh api`
+
+### 4. `success_criteria` extended
+
+Added three new checklist items:
+- `Command surface index built from commands/*.md front matter`
+- `Open PRs fetched and injected into agent context`
+- `Live GitHub milestones fetched as fallback when project.json is absent`
+
+## Files Modified
+
+- `commands/ask.md`
+
+## Files Created
+
+- `.planning/quick/4-mgw-ask-capability-context/4-PLAN.md`
+- `.planning/quick/4-mgw-ask-capability-context/4-SUMMARY.md`

commands/ask.md

@@ -32,6 +32,8 @@ Question text: $ARGUMENTS
 
 Active issues context: .mgw/active/ (current work state)
 Project context: .mgw/project.json (milestone + all issues)
+Capability context: commands/*.md front matter (name + description per command)
+Live state: open PRs via gh pr list, milestones via gh api
 </context>
 
 <process>
@@ -111,6 +113,38 @@ fi
 ```
 </step>
 
+<step name="load_capability_context">
+**Load MGW command surface, open PRs, and live milestones:**
+
+```bash
+# Extract name + description from each command's front matter
+COMMAND_SURFACE=""
+COMMANDS_DIR="${REPO_ROOT}/commands"
+for f in "${COMMANDS_DIR}"/*.md; do
+  CMD_NAME=$(grep -m1 "^name:" "$f" 2>/dev/null | sed 's/^name:[[:space:]]*//')
+  CMD_DESC=$(grep -m1 "^description:" "$f" 2>/dev/null | sed 's/^description:[[:space:]]*//')
+  if [ -n "$CMD_NAME" ]; then
+    COMMAND_SURFACE="${COMMAND_SURFACE}${CMD_NAME}: ${CMD_DESC}\n"
+  fi
+done
+
+# Fetch open PRs
+PR_CONTEXT=$(gh pr list --state open --json number,title,headRefName \
+  --jq '.[] | "#\(.number) [\(.headRefName)] \(.title)"' 2>/dev/null || echo "No open PRs")
+
+# Fetch live milestones from GitHub API
+REPO_SLUG=$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || echo "")
+MILESTONE_LIST=""
+if [ -n "$REPO_SLUG" ]; then
+  MILESTONE_LIST=$(gh api "repos/${REPO_SLUG}/milestones" \
+    --jq '.[] | "[\(.state)] \(.title)"' 2>/dev/null || echo "")
+fi
+if [ -z "$MILESTONE_LIST" ]; then
+  MILESTONE_LIST="No milestones found (or GitHub API unavailable)"
+fi
+```
+</step>
+
 <step name="load_active_state">
 **Load active issue state from .mgw/active/:**
 
@@ -216,6 +250,17 @@ ${ACTIVE_STATE}
 ${RECENT_DIFF}
 </recent_changes>
 
+<mgw_capabilities>
+## MGW Command Surface
+${COMMAND_SURFACE}
+
+## Open Pull Requests
+${PR_CONTEXT}
+
+## GitHub Milestones
+${MILESTONE_LIST}
+</mgw_capabilities>
+
 <classification_rules>
 
 Classify the question into exactly ONE of these categories:
@@ -364,5 +409,8 @@ Consider adding it to a future milestone or filing it for backlog:
 - [ ] Actionable recommendation provided
 - [ ] Follow-up action offered (file issue, post comment, etc.)
 - [ ] Delegation boundary respected: agent reads code/state, MGW presents results
+- [ ] Command surface index built from commands/*.md front matter
+- [ ] Open PRs fetched and injected into agent context
+- [ ] Live GitHub milestones fetched as fallback when project.json is absent
 </success_criteria>
 </output>