AGENTS/.pi/gsd/workflows/progress.md

Context (pre-injected)

Roadmap:

State:

Check project progress, summarize recent work and what's ahead, then intelligently route to the next action - either executing an existing plan or creating the next one. Provides situational awareness before continuing work.

<required_reading> Read all files referenced by the invoking prompt's execution_context before starting. </required_reading>

**Load progress context (paths only):**

Extract from init JSON: project_exists, roadmap_exists, state_exists, phases, current_phase, next_phase, milestone_version, completed_count, phase_count, paused_at, state_path, roadmap_path, project_path, config_path.

DISCUSS_MODE=$(pi-gsd-tools config-get workflow.discuss_mode 2>/dev/null || echo "discuss")

If project_exists is false (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.

**Use structured extraction from gsd-tools:**

Instead of reading full files, use targeted tools to get only the data needed for the report:

• ROADMAP=$(pi-gsd-tools roadmap analyze)
• STATE=$(pi-gsd-tools state-snapshot)

This minimizes orchestrator context usage.

**Get comprehensive roadmap analysis (replaces manual parsing):**

ROADMAP=$(pi-gsd-tools roadmap analyze)

This returns structured JSON with:

• All phases with disk status (complete/partial/planned/empty/no_directory)
• Goal and dependencies per phase
• Plan and summary counts per phase
• Aggregated stats: total plans, summaries, progress percent
• Current and next phase identification

Use this instead of manually reading/parsing ROADMAP.md.

**Gather recent work context:**

• Find the 2-3 most recent SUMMARY.md files
• Use summary-extract for efficient parsing:

  pi-gsd-tools summary-extract <path> --fields one_liner
  

• This shows "what we've been working on"

**Parse current position from init context and roadmap analysis:**

• Use current_phase and next_phase from $ROADMAP
• Note paused_at if work was paused (from $STATE)
• Count pending todos: use init todos or list-todos
• Check for active debug sessions: (ls .planning/debug/*.md 2>/dev/null || true) | grep -v resolved | wc -l

**Generate progress bar from gsd-tools, then present rich status report:**

# Get formatted progress bar
PROGRESS_BAR=$(pi-gsd-tools progress bar --raw)

Present:

# [Project Name]

**Progress:** {PROGRESS_BAR}
**Profile:** [quality/balanced/budget/inherit]
**Discuss mode:** {DISCUSS_MODE}

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

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

## Key Decisions Made
- [extract from $STATE.decisions[]]
- [e.g. jq -r '.decisions[].decision' from state-snapshot]

## Blockers/Concerns
- [extract from $STATE.blockers[]]
- [e.g. jq -r '.blockers[].text' from state-snapshot]

## 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 analyze]

**Determine next action based on verified counts.**

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 || true) | wc -l
(ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null || true) | wc -l
(ls -1 .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null || true) | 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 or partial (incomplete) testing
grep -l "status: diagnosed\|status: partial" .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null || true

Track:

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

Step 1.6: Cross-phase health check

Scan ALL phases in the current milestone for outstanding verification debt using the CLI (which respects milestone boundaries via getMilestonePhaseFilter):

DEBT=$(pi-gsd-tools audit-uat --raw 2>/dev/null)

Parse JSON for summary.total_items and summary.total_files.

Track: outstanding_debt - summary.total_items from the audit.

If outstanding_debt > 0: Add a warning section to the progress report output (in the report step), placed between "## What's Next" and the route suggestion:

## Verification Debt ({N} files across prior phases)

| Phase   | File       | Issue                                                                     |
| ------- | ---------- | ------------------------------------------------------------------------- |
| {phase} | {filename} | {pending_count} pending, {skipped_count} skipped, {blocked_count} blocked |
| {phase} | {filename} | human_needed - {count} items                                              |

Review: `/gsd-audit-uat ${GSD_WS}` - full cross-phase audit
Resume testing: `/gsd-verify-work {phase} ${GSD_WS}` - retest specific phase

This is a WARNING, not a blocker - routing proceeds normally. The debt is visible so the user can make an informed choice.

Step 2: Route based on counts

Condition	Meaning	Action
uat_partial > 0	UAT testing incomplete	Go to Route E.2
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.

---

## ▶ Next Up

**{phase}-{plan}: [Plan Name]** - [objective summary from PLAN.md]

`/gsd-execute-phase {phase} ${GSD_WS}`

<sub>`/new` first → fresh context window</sub>

---

---

Route B: Phase needs planning

Check if {phase_num}-CONTEXT.md exists in phase directory.

Check if current phase has UI indicators:

PHASE_SECTION=$(pi-gsd-tools roadmap get-phase "${CURRENT_PHASE}" 2>/dev/null)
PHASE_HAS_UI=$(echo "$PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" || echo "false")

If CONTEXT.md exists:

---

## ▶ Next Up

**Phase {N}: {Name}** - {Goal from ROADMAP.md}
<sub>✓ Context gathered, ready to plan</sub>

`/gsd-plan-phase {phase-number} ${GSD_WS}`

<sub>`/new` first → fresh context window</sub>

---

If CONTEXT.md does NOT exist AND phase has UI (PHASE_HAS_UI is true):

---

## ▶ Next Up

**Phase {N}: {Name}** - {Goal from ROADMAP.md}

`/gsd-discuss-phase {phase}` - gather context and clarify approach

<sub>`/new` first → fresh context window</sub>

---

**Also available:**
- `/gsd-ui-phase {phase}` - generate UI design contract (recommended for frontend phases)
- `/gsd-plan-phase {phase}` - skip discussion, plan directly
- `/gsd-list-phase-assumptions {phase}` - see the agent's assumptions

---

If CONTEXT.md does NOT exist AND phase has no UI:

---

## ▶ Next Up

**Phase {N}: {Name}** - {Goal from ROADMAP.md}

`/gsd-discuss-phase {phase} ${GSD_WS}` - gather context and clarify approach

<sub>`/new` first → fresh context window</sub>

---

**Also available:**
- `/gsd-plan-phase {phase} ${GSD_WS}` - skip discussion, plan directly
- `/gsd-list-phase-assumptions {phase} ${GSD_WS}` - see the agent's assumptions

---

---

Route E: UAT gaps need fix plans

UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.

---

## ⚠ UAT Gaps Found

**{phase_num}-UAT.md** has {N} gaps requiring fixes.

`/gsd-plan-phase {phase} --gaps ${GSD_WS}`

<sub>`/new` first → fresh context window</sub>

---

**Also available:**
- `/gsd-execute-phase {phase} ${GSD_WS}` - execute phase plans
- `/gsd-verify-work {phase} ${GSD_WS}` - run more UAT testing

---

---

Route E.2: UAT testing incomplete (partial)

UAT.md exists with status: partial - testing session ended before all items resolved.

---

## Incomplete UAT Testing

**{phase_num}-UAT.md** has {N} unresolved tests (pending, blocked, or skipped).

`/gsd-verify-work {phase} ${GSD_WS}` - resume testing from where you left off

<sub>`/new` first → fresh context window</sub>

---

**Also available:**
- `/gsd-audit-uat ${GSD_WS}` - full cross-phase UAT audit
- `/gsd-execute-phase {phase} ${GSD_WS}` - execute phase plans

---

---

Step 3: Check milestone status (only when phase complete)

Read ROADMAP.md and identify:

1. Current phase number
2. All phase numbers in the current milestone section

Count total phases and identify the highest phase number.

State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."

Route based on milestone status:

Condition	Meaning	Action
current phase < highest phase	More phases remain	Go to Route C
current phase = highest phase	Milestone complete	Go to Route D

---

Route C: Phase complete, more phases remain

Read ROADMAP.md to get the next phase's name and goal.

Check if next phase has UI indicators:

NEXT_PHASE_SECTION=$(pi-gsd-tools roadmap get-phase "$((Z+1))" 2>/dev/null)
NEXT_HAS_UI=$(echo "$NEXT_PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true" || echo "false")

If next phase has UI (NEXT_HAS_UI is true):

---

## ✓ Phase {Z} Complete

## ▶ Next Up

**Phase {Z+1}: {Name}** - {Goal from ROADMAP.md}

`/gsd-discuss-phase {Z+1}` - gather context and clarify approach

<sub>`/new` first → fresh context window</sub>

---

**Also available:**
- `/gsd-ui-phase {Z+1}` - generate UI design contract (recommended for frontend phases)
- `/gsd-plan-phase {Z+1}` - skip discussion, plan directly
- `/gsd-verify-work {Z}` - user acceptance test before continuing

---

If next phase has no UI:

---

## ✓ Phase {Z} Complete

## ▶ Next Up

**Phase {Z+1}: {Name}** - {Goal from ROADMAP.md}

`/gsd-discuss-phase {Z+1} ${GSD_WS}` - gather context and clarify approach

<sub>`/new` first → fresh context window</sub>

---

**Also available:**
- `/gsd-plan-phase {Z+1} ${GSD_WS}` - skip discussion, plan directly
- `/gsd-verify-work {Z} ${GSD_WS}` - user acceptance test before continuing

---

---

Route D: Milestone complete

---

## 🎉 Milestone Complete

All {N} phases finished!

## ▶ Next Up

**Complete Milestone** - archive and prepare for next

`/gsd-complete-milestone ${GSD_WS}`

<sub>`/new` first → fresh context window</sub>

---

**Also available:**
- `/gsd-verify-work ${GSD_WS}` - user acceptance test before completing milestone

---

---

Route F: Between milestones (ROADMAP.md missing, PROJECT.md exists)

A milestone was completed and archived. Ready to start the next milestone cycle.

Read MILESTONES.md to find the last completed milestone version.

---

## ✓ Milestone v{X.Y} Complete

Ready to plan the next milestone.

## ▶ Next Up

**Start Next Milestone** - questioning → research → requirements → roadmap

`/gsd-new-milestone ${GSD_WS}`

<sub>`/new` first → fresh context window</sub>

---

**Handle edge cases:**

• Phase complete but next phase not planned → offer /gsd-plan-phase [next] ${GSD_WS}
• All work complete → offer milestone completion
• Blockers present → highlight before offering to continue
• Handoff file exists → mention it, offer /gsd-resume-work ${GSD_WS}

<success_criteria>

• Rich context provided (recent work, decisions, issues)
• Current position clear with visual progress
• What's next clearly explained
• Smart routing: /gsd-execute-phase if plans exist, /gsd-plan-phase if not
• User confirms before any action
• Seamless handoff to appropriate gsd command </success_criteria>