git-project-xray-mcp: Command for Claude Code

Provides situational awareness before continuing work.

Use Bash (not Glob) to check—Glob respects .gitignore but .planning/ is often gitignored:

test -d .planning && echo "exists" || echo "missing"

If no .planning/ directory:

No planning structure found.

Run /gsd:new-project to start a new project.

Exit.

If missing STATE.md: suggest /gsd:new-project.

If ROADMAP.md missing but PROJECT.md exists:

This means a milestone was completed and archived. Go to Route F (between milestones).

If missing both ROADMAP.md and PROJECT.md: suggest /gsd:new-project.

• Read .planning/STATE.md for living memory (position, decisions, issues)
• Read .planning/ROADMAP.md for phase structure and objectives
• Read .planning/PROJECT.md for current state (What This Is, Core Value, Requirements)
• Read .planning/config.json for settings (model_profile, workflow toggles)

• Find the 2-3 most recent SUMMARY.md files
• Extract from each: what was accomplished, key decisions, any issues logged
• This shows "what we've been working on"

• From STATE.md: current phase, plan number, status
• Calculate: total plans, completed plans, remaining plans
• Note any blockers or concerns
• Check for CONTEXT.md: For phases without PLAN.md files, check if {phase}-CONTEXT.md exists in phase directory
• Count pending todos: ls .planning/todos/pending/*.md 2>/dev/null | wc -l
• Check for active debug sessions: ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l

# [Project Name]

**Progress:** [████████░░] 8/10 plans complete
**Profile:** [quality/balanced/budget]

## Recent Work
- [Phase X, Plan Y]: [what was accomplished - 1 line]
- [Phase X, Plan Z]: [what was accomplished - 1 line]

## Current Position
Phase [N] of [total]: [phase-name]
Plan [M] of [phase-total]: [status]
CONTEXT: [✓ if CONTEXT.md exists | - if not]

## Key Decisions Made
- [decision 1 from STATE.md]
- [decision 2]

## Blockers/Concerns
- [any blockers or concerns from STATE.md]

## Pending Todos
- [count] pending — /gsd:check-todos to review

## Active Debug Sessions
- [count] active — /gsd:debug to continue
(Only show this section if count > 0)

## What's Next
[Next phase/plan objective from ROADMAP]

Step 1: Count plans, summaries, and issues in current phase

List files in the current phase directory:

ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l
ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
ls -1 .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null | wc -l

State: "This phase has {X} plans, {Y} summaries."

Step 1.5: Check for unaddressed UAT gaps

Check for UAT.md files with status "diagnosed" (has gaps needing fixes).

# Check for diagnosed UAT with gaps
grep -l "status: diagnosed" .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null

Track:

• uat_with_gaps: UAT.md files with status "diagnosed" (gaps need fixing)

Step 2: Route based on counts

Condition	Meaning	Action
uat_with_gaps > 0	UAT gaps need fix plans	Go to Route E
summaries < plans	Unexecuted plans exist	Go to Route A
summaries = plans AND plans > 0	Phase complete	Go to Step 3
plans = 0	Phase not yet planned	Go to Route B

---

Route A: Unexecuted plan exists

Find the first PLAN.md without matching SUMMARY.md. Read its <objective> section.