feat: planning improvements — PRD express path, interface-first planning, living retrospective (#644)

Cherry-pick from @smledbetter with conflict resolution and project-specific reference removed.

Co-Authored-By: Stevo <smledbetter@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

agents/gsd-planner.md

@@ -200,6 +200,16 @@ Each task: **15-60 minutes** Claude execution time.
 
 **Combine signals:** One task sets up for the next, separate tasks touch same file, neither meaningful alone.
 
+## Interface-First Task Ordering
+
+When a plan creates new interfaces consumed by subsequent tasks:
+
+1. **First task: Define contracts** — Create type files, interfaces, exports
+2. **Middle tasks: Implement** — Build against the defined contracts
+3. **Last task: Wire** — Connect implementations to consumers
+
+This prevents the "scavenger hunt" anti-pattern where executors explore the codebase to understand contracts. They receive the contracts in the plan itself.
+
 ## Specificity Examples
 
 | TOO VAGUE | JUST RIGHT |
@@ -445,6 +455,69 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 
 Wave numbers are pre-computed during planning. Execute-phase reads `wave` directly from frontmatter.
 
+## Interface Context for Executors
+
+**Key insight:** "The difference between handing a contractor blueprints versus telling them 'build me a house.'"
+
+When creating plans that depend on existing code or create new interfaces consumed by other plans:
+
+### For plans that USE existing code:
+After determining `files_modified`, extract the key interfaces/types/exports from the codebase that executors will need:
+
+```bash
+# Extract type definitions, interfaces, and exports from relevant files
+grep -n "export\|interface\|type\|class\|function" {relevant_source_files} 2>/dev/null | head -50
+```
+
+Embed these in the plan's `<context>` section as an `<interfaces>` block:
+
+```xml
+<interfaces>
+<!-- Key types and contracts the executor needs. Extracted from codebase. -->
+<!-- Executor should use these directly — no codebase exploration needed. -->
+
+From src/types/user.ts:
+```typescript
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  createdAt: Date;
+}
+```
+
+From src/api/auth.ts:
+```typescript
+export function validateToken(token: string): Promise<User | null>;
+export function createSession(user: User): Promise<SessionToken>;
+```
+</interfaces>
+```
+
+### For plans that CREATE new interfaces:
+If this plan creates types/interfaces that later plans depend on, include a "Wave 0" skeleton step:
+
+```xml
+<task type="auto">
+  <name>Task 0: Write interface contracts</name>
+  <files>src/types/newFeature.ts</files>
+  <action>Create type definitions that downstream plans will implement against. These are the contracts — implementation comes in later tasks.</action>
+  <verify>File exists with exported types, no implementation</verify>
+  <done>Interface file committed, types exported</done>
+</task>
+```
+
+### When to include interfaces:
+- Plan touches files that import from other modules → extract those module's exports
+- Plan creates a new API endpoint → extract the request/response types
+- Plan modifies a component → extract its props interface
+- Plan depends on a previous plan's output → extract the types from that plan's files_modified
+
+### When to skip:
+- Plan is self-contained (creates everything from scratch, no imports)
+- Plan is pure configuration (no code interfaces involved)
+- Level 0 discovery (all patterns already established)
+
 ## Context Section Rules
 
 Only include prior plan SUMMARY references if genuinely needed (uses types/exports from prior plan, or prior plan made decision affecting this one).
@@ -954,6 +1027,16 @@ For phases not selected, retain from digest:
 - `patterns`: Conventions to follow
 
 **From STATE.md:** Decisions → constrain approach. Pending todos → candidates.
+
+**From RETROSPECTIVE.md (if exists):**
+```bash
+cat .planning/RETROSPECTIVE.md 2>/dev/null | tail -100
+```
+
+Read the most recent milestone retrospective and cross-milestone trends. Extract:
+- **Patterns to follow** from "What Worked" and "Patterns Established"
+- **Patterns to avoid** from "What Was Inefficient" and "Key Lessons"
+- **Cost patterns** to inform model selection and agent strategy
 </step>
 
 <step name="gather_phase_context">

commands/gsd/plan-phase.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:plan-phase
 description: Create detailed phase plan (PLAN.md) with verification loop
-argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify]"
+argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd <file>]"
 agent: gsd-planner
 allowed-tools:
   - Read
@@ -34,6 +34,7 @@ Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omit
 - `--skip-research` — Skip research, go straight to planning
 - `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
 - `--skip-verify` — Skip verification loop
+- `--prd <file>` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely.
 
 Normalize phase input in step 2 before any directory lookups.
 </context>

get-shit-done/templates/retrospective.md

@@ -0,0 +1,54 @@
+# Project Retrospective
+
+*A living document updated after each milestone. Lessons feed forward into future planning.*
+
+## Milestone: v{version} — {name}
+
+**Shipped:** {date}
+**Phases:** {count} | **Plans:** {count} | **Sessions:** {count}
+
+### What Was Built
+- {Key deliverable 1}
+- {Key deliverable 2}
+- {Key deliverable 3}
+
+### What Worked
+- {Efficiency win or successful pattern}
+- {What went smoothly}
+
+### What Was Inefficient
+- {Missed opportunity}
+- {What took longer than expected}
+
+### Patterns Established
+- {New pattern or convention that should persist}
+
+### Key Lessons
+1. {Specific, actionable lesson}
+2. {Another lesson}
+
+### Cost Observations
+- Model mix: {X}% opus, {Y}% sonnet, {Z}% haiku
+- Sessions: {count}
+- Notable: {efficiency observation}
+
+---
+
+## Cross-Milestone Trends
+
+### Process Evolution
+
+| Milestone | Sessions | Phases | Key Change |
+|-----------|----------|--------|------------|
+| v{X} | {N} | {M} | {What changed in process} |
+
+### Cumulative Quality
+
+| Milestone | Tests | Coverage | Zero-Dep Additions |
+|-----------|-------|----------|-------------------|
+| v{X} | {N} | {Y}% | {count} |
+
+### Top Lessons (Verified Across Milestones)
+
+1. {Lesson verified by multiple milestones}
+2. {Another cross-validated lesson}

get-shit-done/workflows/complete-milestone.md

@@ -438,6 +438,67 @@ rm .planning/REQUIREMENTS.md
 
 </step>
 
+<step name="write_retrospective">
+
+**Append to living retrospective:**
+
+Check for existing retrospective:
+```bash
+ls .planning/RETROSPECTIVE.md 2>/dev/null
+```
+
+**If exists:** Read the file, append new milestone section before the "## Cross-Milestone Trends" section.
+
+**If doesn't exist:** Create from template at `~/.claude/get-shit-done/templates/retrospective.md`.
+
+**Gather retrospective data:**
+
+1. From SUMMARY.md files: Extract key deliverables, one-liners, tech decisions
+2. From VERIFICATION.md files: Extract verification scores, gaps found
+3. From UAT.md files: Extract test results, issues found
+4. From git log: Count commits, calculate timeline
+5. From the milestone work: Reflect on what worked and what didn't
+
+**Write the milestone section:**
+
+```markdown
+## Milestone: v{version} — {name}
+
+**Shipped:** {date}
+**Phases:** {phase_count} | **Plans:** {plan_count}
+
+### What Was Built
+{Extract from SUMMARY.md one-liners}
+
+### What Worked
+{Patterns that led to smooth execution}
+
+### What Was Inefficient
+{Missed opportunities, rework, bottlenecks}
+
+### Patterns Established
+{New conventions discovered during this milestone}
+
+### Key Lessons
+{Specific, actionable takeaways}
+
+### Cost Observations
+- Model mix: {X}% opus, {Y}% sonnet, {Z}% haiku
+- Sessions: {count}
+- Notable: {efficiency observation}
+```
+
+**Update cross-milestone trends:**
+
+If the "## Cross-Milestone Trends" section exists, update the tables with new data from this milestone.
+
+**Commit:**
+```bash
+node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs: update retrospective for v${VERSION}" --files .planning/RETROSPECTIVE.md
+```
+
+</step>
+
 <step name="update_state">
 
 Most STATE.md updates were handled by `milestone complete`, but verify and update remaining fields:
@@ -695,6 +756,8 @@ Milestone completion is successful when:
 - [ ] Requirements completion checked against REQUIREMENTS.md traceability table
 - [ ] Incomplete requirements surfaced with proceed/audit/abort options
 - [ ] Known gaps recorded in MILESTONES.md if user proceeded with incomplete requirements
+- [ ] RETROSPECTIVE.md updated with milestone section
+- [ ] Cross-milestone trends updated
 - [ ] User knows next step (/gsd:new-milestone)
 
 </success_criteria>

get-shit-done/workflows/discuss-phase.md

@@ -107,6 +107,8 @@ Phase: "API documentation"
 
 <process>
 
+**Express path available:** If you already have a PRD or acceptance criteria document, use `/gsd:plan-phase {phase} --prd path/to/prd.md` to skip this discussion and go straight to planning.
+
 <step name="initialize" priority="first">
 Phase number from argument (required).
 

get-shit-done/workflows/execute-plan.md

@@ -118,6 +118,8 @@ Pattern B only (verify-only checkpoints). Skip for A/C.
 cat .planning/phases/XX-name/{phase}-{plan}-PLAN.md
 ```
 This IS the execution instructions. Follow exactly. If plan references CONTEXT.md: honor user's vision throughout.
+
+**If plan contains `<interfaces>` block:** These are pre-extracted type definitions and contracts. Use them directly — do NOT re-read the source files to discover types. The planner already extracted what you need.
 </step>
 
 <step name="previous_phase_check">

get-shit-done/workflows/help.md

@@ -99,6 +99,8 @@ Create detailed execution plan for a specific phase.
 Usage: `/gsd:plan-phase 1`
 Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
 
+**PRD Express Path:** Pass `--prd path/to/requirements.md` to skip discuss-phase entirely. Your PRD becomes locked decisions in CONTEXT.md. Useful when you already have clear acceptance criteria.
+
 ### Execution
 
 **`/gsd:execute-phase <phase-number>`**
@@ -351,6 +353,7 @@ Usage: `/gsd:join-discord`
 ├── PROJECT.md            # Project vision
 ├── ROADMAP.md            # Current phase breakdown
 ├── STATE.md              # Project memory & context
+├── RETROSPECTIVE.md      # Living retrospective (updated per milestone)
 ├── config.json           # Workflow mode & gates
 ├── todos/                # Captured ideas and tasks
 │   ├── pending/          # Todos waiting to be worked on

get-shit-done/workflows/plan-phase.md

@@ -26,7 +26,9 @@ Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_
 
 ## 2. Parse and Normalize Arguments
 
-Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`).
+Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`, `--prd <filepath>`).
+
+Extract `--prd <filepath>` from $ARGUMENTS. If present, set PRD_FILE to the filepath.
 
 **If no phase number:** Detect next unplanned phase from roadmap.
 
@@ -45,8 +47,98 @@ PHASE_INFO=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "$
 
 **If `found` is false:** Error with available phases. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
 
+## 3.5. Handle PRD Express Path
+
+**Skip if:** No `--prd` flag in arguments.
+
+**If `--prd <filepath>` provided:**
+
+1. Read the PRD file:
+```bash
+PRD_CONTENT=$(cat "$PRD_FILE" 2>/dev/null)
+if [ -z "$PRD_CONTENT" ]; then
+  echo "Error: PRD file not found: $PRD_FILE"
+  exit 1
+fi
+```
+
+2. Display banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► PRD EXPRESS PATH
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Using PRD: {PRD_FILE}
+Generating CONTEXT.md from requirements...
+```
+
+3. Parse the PRD content and generate CONTEXT.md. The orchestrator should:
+   - Extract all requirements, user stories, acceptance criteria, and constraints from the PRD
+   - Map each to a locked decision (everything in the PRD is treated as a locked decision)
+   - Identify any areas the PRD doesn't cover and mark as "Claude's Discretion"
+   - Create CONTEXT.md in the phase directory
+
+4. Write CONTEXT.md:
+```markdown
+# Phase [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+**Source:** PRD Express Path ({PRD_FILE})
+
+<domain>
+## Phase Boundary
+
+[Extracted from PRD — what this phase delivers]
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+{For each requirement/story/criterion in the PRD:}
+### [Category derived from content]
+- [Requirement as locked decision]
+
+### Claude's Discretion
+[Areas not covered by PRD — implementation details, technical choices]
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+[Any specific references, examples, or concrete requirements from PRD]
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+[Items in PRD explicitly marked as future/v2/out-of-scope]
+[If none: "None — PRD covers phase scope"]
+
+</deferred>
+
+---
+
+*Phase: XX-name*
+*Context gathered: [date] via PRD Express Path*
+```
+
+5. Commit:
+```bash
+node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs(${padded_phase}): generate context from PRD" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+
+6. Set `context_content` to the generated CONTEXT.md content and continue to step 5 (Handle Research).
+
+**Effect:** This completely bypasses step 4 (Load CONTEXT.md) since we just created it. The rest of the workflow (research, planning, verification) proceeds normally with the PRD-derived context.
+
 ## 4. Load CONTEXT.md
 
+**Skip if:** PRD express path was used (CONTEXT.md already created in step 3.5).
+
 Check `context_path` from init JSON.
 
 If `context_path` is not null, display: `Using phase context from: ${context_path}`