Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification. Default flow: Research (if needed) -> Plan -> Verify -> Done. Orchestrates gsd-phase-researcher, gsd-planner, and gsd-plan-checker agents with a revision loop (max 3 iterations).
Read all files referenced by the invoking prompt's execution_context before starting.
@~/.claude/get-shit-done/references/ui-brand.md
## 1. Validate Environment and Resolve Model Profile
```bash
PLANNING_EXISTS=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning --raw)
echo "$PLANNING_EXISTS"
```
**If not found:** Error — run `/gsd:new-project` first.
**Resolve models:**
```bash
RESEARCHER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-phase-researcher --raw)
PLANNER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-planner --raw)
CHECKER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.js resolve-model gsd-plan-checker --raw)
```
## 2. Parse and Normalize Arguments
Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`).
**If no phase number:** Detect next unplanned phase from roadmap.
**Find phase directory:**
```bash
PHASE_INFO=$(node ~/.claude/get-shit-done/bin/gsd-tools.js find-phase "$PHASE")
PHASE_DIR=$(echo "$PHASE_INFO" | grep -o '"directory":"[^"]*"' | cut -d'"' -f4)
```
If `found` is false, validate phase exists in ROADMAP.md. If valid, create the directory:
```bash
PHASE_NAME=$(grep "Phase ${PHASE}:" .planning/ROADMAP.md | sed 's/.*Phase [0-9]*: //')
PHASE_SLUG=$(node ~/.claude/get-shit-done/bin/gsd-tools.js generate-slug "$PHASE_NAME" --raw)
PADDED=$(node ~/.claude/get-shit-done/bin/gsd-tools.js find-phase "$PHASE" --raw | grep -o '^[0-9]*' || printf "%02d" "$PHASE")
mkdir -p ".planning/phases/${PADDED}-${PHASE_SLUG}"
PHASE_DIR=".planning/phases/${PADDED}-${PHASE_SLUG}"
```
**Check for existing research and plans:**
```bash
ls ${PHASE_DIR}/*-RESEARCH.md 2>/dev/null
ls ${PHASE_DIR}/*-PLAN.md 2>/dev/null
```
## 3. Validate Phase
```bash
grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null
```
**If not found:** Error with available phases. **If found:** Extract phase number, name, description.
## 4. Load CONTEXT.md
```bash
CONTEXT_CONTENT=$(cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null)
```
**CRITICAL:** Store `CONTEXT_CONTENT` now — pass to researcher, planner, checker, and revision agents.
If CONTEXT.md exists, display: `Using phase context from: ${PHASE_DIR}/*-CONTEXT.md`
## 5. Handle Research
**Skip if:** `--gaps` flag, `--skip-research` flag, or config `workflow.research=false` (without `--research` override).
```bash
WORKFLOW_RESEARCH=$(node ~/.claude/get-shit-done/bin/gsd-tools.js state load --raw | grep '^research=' | cut -d= -f2)
```
**If RESEARCH.md exists AND no `--research` flag:** Use existing, skip to step 6.
**If RESEARCH.md missing OR `--research` flag:**
Display banner:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► RESEARCHING PHASE {X}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
◆ Spawning researcher...
```
### Spawn gsd-phase-researcher
```bash
PHASE_DESC=$(grep -A3 "Phase ${PHASE}:" .planning/ROADMAP.md)
REQUIREMENTS=$(cat .planning/REQUIREMENTS.md 2>/dev/null | grep -A100 "## Requirements" | head -50)
DECISIONS=$(grep -A20 "### Decisions Made" .planning/STATE.md 2>/dev/null)
```
Research prompt:
```markdown
Research how to implement Phase {phase_number}: {phase_name}
Answer: "What do I need to know to PLAN this phase well?"
IMPORTANT: If CONTEXT.md exists below, it contains user decisions from /gsd:discuss-phase.
- **Decisions** = Locked — research THESE deeply, no alternatives
- **Claude's Discretion** = Freedom areas — research options, recommend
- **Deferred Ideas** = Out of scope — ignore
{context_content}
**Phase description:** {phase_description}
**Requirements:** {requirements}
**Prior decisions:** {decisions}
```
```
Task(
prompt="First, read ~/.claude/agents/gsd-phase-researcher.md for your role and instructions.\n\n" + research_prompt,
subagent_type="general-purpose",
model="{researcher_model}",
description="Research Phase {phase}"
)
```
### Handle Researcher Return
- **`## RESEARCH COMPLETE`:** Display confirmation, continue to step 6
- **`## RESEARCH BLOCKED`:** Display blocker, offer: 1) Provide context, 2) Skip research, 3) Abort
## 6. Check Existing Plans
```bash
ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null
```
**If exists:** Offer: 1) Add more plans, 2) View existing, 3) Replan from scratch.
## 7. Read Context Files
Read and store for planner agent (`@` syntax doesn't work across Task() boundaries):
```bash
STATE_CONTENT=$(cat .planning/STATE.md)
ROADMAP_CONTENT=$(cat .planning/ROADMAP.md)
REQUIREMENTS_CONTENT=$(cat .planning/REQUIREMENTS.md 2>/dev/null)
RESEARCH_CONTENT=$(cat "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null)
VERIFICATION_CONTENT=$(cat "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null)
UAT_CONTENT=$(cat "${PHASE_DIR}"/*-UAT.md 2>/dev/null)
```
## 8. Spawn gsd-planner Agent
Display banner:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► PLANNING PHASE {X}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
◆ Spawning planner...
```
Planner prompt:
```markdown
**Phase:** {phase_number}
**Mode:** {standard | gap_closure}
**Project State:** {state_content}
**Roadmap:** {roadmap_content}
**Requirements:** {requirements_content}
**Phase Context:**
IMPORTANT: If context exists below, it contains USER DECISIONS from /gsd:discuss-phase.
- **Decisions** = LOCKED — honor exactly, do not revisit
- **Claude's Discretion** = Freedom — make implementation choices
- **Deferred Ideas** = Out of scope — do NOT include
{context_content}
**Research:** {research_content}
**Gap Closure (if --gaps):** {verification_content} {uat_content}
Output consumed by /gsd:execute-phase. Plans need:
- Frontmatter (wave, depends_on, files_modified, autonomous)
- Tasks in XML format
- Verification criteria
- must_haves for goal-backward verification
- [ ] PLAN.md files created in phase directory
- [ ] Each plan has valid frontmatter
- [ ] Tasks are specific and actionable
- [ ] Dependencies correctly identified
- [ ] Waves assigned for parallel execution
- [ ] must_haves derived from phase goal
```
```
Task(
prompt="First, read ~/.claude/agents/gsd-planner.md for your role and instructions.\n\n" + filled_prompt,
subagent_type="general-purpose",
model="{planner_model}",
description="Plan Phase {phase}"
)
```
## 9. Handle Planner Return
- **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or config `workflow.plan_check=false`: skip to step 13. Otherwise: step 10.
```bash
WORKFLOW_PLAN_CHECK=$(node ~/.claude/get-shit-done/bin/gsd-tools.js state load --raw | grep '^plan_checker=' | cut -d= -f2)
```
- **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
- **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
## 10. Spawn gsd-plan-checker Agent
Display banner:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► VERIFYING PLANS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
◆ Spawning plan checker...
```
```bash
PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
```
Checker prompt:
```markdown
**Phase:** {phase_number}
**Phase Goal:** {goal from ROADMAP}
**Plans to verify:** {plans_content}
**Requirements:** {requirements_content}
**Phase Context:**
IMPORTANT: Plans MUST honor user decisions. Flag as issue if plans contradict.
- **Decisions** = LOCKED — plans must implement exactly
- **Claude's Discretion** = Freedom areas — plans can choose approach
- **Deferred Ideas** = Out of scope — plans must NOT include
{context_content}
- ## VERIFICATION PASSED — all checks pass
- ## ISSUES FOUND — structured issue list
```
```
Task(
prompt=checker_prompt,
subagent_type="gsd-plan-checker",
model="{checker_model}",
description="Verify Phase {phase} plans"
)
```
## 11. Handle Checker Return
- **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 13.
- **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
## 12. Revision Loop (Max 3 Iterations)
Track `iteration_count` (starts at 1 after initial plan + check).
**If iteration_count < 3:**
Display: `Sending back to planner for revision... (iteration {N}/3)`
```bash
PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
```
Revision prompt:
```markdown
**Phase:** {phase_number}
**Mode:** revision
**Existing plans:** {plans_content}
**Checker issues:** {structured_issues_from_checker}
**Phase Context:**
Revisions MUST still honor user decisions.
{context_content}
Make targeted updates to address checker issues.
Do NOT replan from scratch unless issues are fundamental.
Return what changed.
```
```
Task(
prompt="First, read ~/.claude/agents/gsd-planner.md for your role and instructions.\n\n" + revision_prompt,
subagent_type="general-purpose",
model="{planner_model}",
description="Revise Phase {phase} plans"
)
```
After planner returns -> spawn checker again (step 10), increment iteration_count.
**If iteration_count >= 3:**
Display: `Max iterations reached. {N} issues remain:` + issue list
Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
## 13. Present Final Status
Route to ``.
Output this markdown directly (not as a code block):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► PHASE {X} PLANNED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**Phase {X}: {Name}** — {N} plan(s) in {M} wave(s)
| Wave | Plans | What it builds |
|------|-------|----------------|
| 1 | 01, 02 | [objectives] |
| 2 | 03 | [objective] |
Research: {Completed | Used existing | Skipped}
Verification: {Passed | Passed with override | Skipped}
───────────────────────────────────────────────────────────────
## ▶ Next Up
**Execute Phase {X}** — run all {N} plans
/gsd:execute-phase {X}
/clear first → fresh context window
───────────────────────────────────────────────────────────────
**Also available:**
- cat .planning/phases/{phase-dir}/*-PLAN.md — review plans
- /gsd:plan-phase {X} --research — re-research first
───────────────────────────────────────────────────────────────
- [ ] .planning/ directory validated
- [ ] Phase validated against roadmap
- [ ] Phase directory created if needed
- [ ] CONTEXT.md loaded early (step 4) and passed to ALL agents
- [ ] Research completed (unless --skip-research or --gaps or exists)
- [ ] gsd-phase-researcher spawned with CONTEXT.md
- [ ] Existing plans checked
- [ ] gsd-planner spawned with CONTEXT.md + RESEARCH.md
- [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled)
- [ ] gsd-plan-checker spawned with CONTEXT.md
- [ ] Verification passed OR user override OR max iterations with user decision
- [ ] User sees status between agent spawns
- [ ] User knows next steps