claude-config/get-shit-done/workflows/transition.md

<internal_workflow>

This is an INTERNAL workflow — NOT a user-facing command.

There is no /gsd:transition command. This workflow is invoked automatically by execute-phase during auto-advance, or inline by the orchestrator after phase verification. Users should never be told to run /gsd:transition.

Valid user commands for phase progression:

• /gsd:discuss-phase {N} — discuss a phase before planning
• /gsd:plan-phase {N} — plan a phase
• /gsd:execute-phase {N} — execute a phase
• /gsd:progress — see roadmap progress

</internal_workflow>

<required_reading>

Read these files NOW:

1. .planning/STATE.md
2. .planning/PROJECT.md
3. .planning/ROADMAP.md
4. Current phase's plan files (*-PLAN.md)
5. Current phase's summary files (*-SUMMARY.md)

</required_reading>

Mark current phase complete and advance to next. This is the natural point where progress tracking and PROJECT.md evolution happen.

"Planning next phase" = "current phase is done"

Before transition, read project state:

cat .planning/STATE.md 2>/dev/null
cat .planning/PROJECT.md 2>/dev/null

Parse current position to verify we're transitioning the right phase. Note accumulated context that may need updating after transition.

Check current phase has all plan summaries:

ls .planning/phases/XX-current/*-PLAN.md 2>/dev/null | sort
ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null | sort

Verification logic:

• Count PLAN files
• Count SUMMARY files
• If counts match: all plans complete
• If counts don't match: incomplete

cat .planning/config.json 2>/dev/null

If all plans complete:

⚡ Auto-approved: Transition Phase [X] → Phase [X+1]
Phase [X] complete — all [Y] plans finished.

Proceeding to mark done and advance...

Proceed directly to cleanup_handoff step.

Ask: "Phase [X] complete — all [Y] plans finished. Ready to mark done and move to Phase [X+1]?"

Wait for confirmation before proceeding.

If plans incomplete:

SAFETY RAIL: always_confirm_destructive applies here. Skipping incomplete plans is destructive — ALWAYS prompt regardless of mode.

Present:

Phase [X] has incomplete plans:
- {phase}-01-SUMMARY.md ✓ Complete
- {phase}-02-SUMMARY.md ✗ Missing
- {phase}-03-SUMMARY.md ✗ Missing

⚠️ Safety rail: Skipping plans requires confirmation (destructive action)

Options:
1. Continue current phase (execute remaining plans)
2. Mark complete anyway (skip remaining plans)
3. Review what's left

Wait for user decision.

Check for lingering handoffs:

ls .planning/phases/XX-current/.continue-here*.md 2>/dev/null

If found, delete them — phase is complete, handoffs are stale.

Delegate ROADMAP.md and STATE.md updates to gsd-tools:

TRANSITION=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" phase complete "${current_phase}")

The CLI handles:

• Marking the phase checkbox as [x] complete with today's date
• Updating plan count to final (e.g., "3/3 plans complete")
• Updating the Progress table (Status → Complete, adding date)
• Advancing STATE.md to next phase (Current Phase, Status → Ready to plan, Current Plan → Not started)
• Detecting if this is the last phase in the milestone

Extract from result: completed_phase, plans_executed, next_phase, next_phase_name, is_last_phase.

If prompts were generated for the phase, they stay in place. The completed/ subfolder pattern from create-meta-prompts handles archival.

Evolve PROJECT.md to reflect learnings from completed phase.

Read phase summaries:

cat .planning/phases/XX-current/*-SUMMARY.md

Assess requirement changes:

1. Requirements validated?

   • Any Active requirements shipped in this phase?
   • Move to Validated with phase reference: - ✓ [Requirement] — Phase X

2. Requirements invalidated?

   • Any Active requirements discovered to be unnecessary or wrong?
   • Move to Out of Scope with reason: - [Requirement] — [why invalidated]

3. Requirements emerged?

   • Any new requirements discovered during building?
   • Add to Active: - [ ] [New requirement]

4. Decisions to log?

   • Extract decisions from SUMMARY.md files
   • Add to Key Decisions table with outcome if known

5. "What This Is" still accurate?

   • If the product has meaningfully changed, update the description
   • Keep it current and accurate

Update PROJECT.md:

Make the edits inline. Update "Last updated" footer:

---
*Last updated: [date] after Phase [X]*

Example evolution:

Before:

### Active

- [ ] JWT authentication
- [ ] Real-time sync < 500ms
- [ ] Offline mode

### Out of Scope

- OAuth2 — complexity not needed for v1

After (Phase 2 shipped JWT auth, discovered rate limiting needed):

### Validated

- ✓ JWT authentication — Phase 2

### Active

- [ ] Real-time sync < 500ms
- [ ] Offline mode
- [ ] Rate limiting on sync endpoint

### Out of Scope

- OAuth2 — complexity not needed for v1

Step complete when:

• Phase summaries reviewed for learnings
• Validated requirements moved from Active
• Invalidated requirements moved to Out of Scope with reason
• Emerged requirements added to Active
• New decisions logged with rationale
• "What This Is" updated if product changed
• "Last updated" footer reflects this transition

Note: Basic position updates (Current Phase, Status, Current Plan, Last Activity) were already handled by gsd-tools phase complete in the update_roadmap_and_state step.

Verify the updates are correct by reading STATE.md. If the progress bar needs updating, use:

PROGRESS=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" progress bar --raw)

Update the progress bar line in STATE.md with the result.

Step complete when:

• Phase number incremented to next phase (done by phase complete)
• Plan status reset to "Not started" (done by phase complete)
• Status shows "Ready to plan" (done by phase complete)
• Progress bar reflects total completed plans

Update Project Reference section in STATE.md.

## Project Reference

See: .planning/PROJECT.md (updated [today])

**Core value:** [Current core value from PROJECT.md]
**Current focus:** [Next phase name]

Update the date and current focus to reflect the transition.

Review and update Accumulated Context section in STATE.md.

Decisions:

• Note recent decisions from this phase (3-5 max)
• Full log lives in PROJECT.md Key Decisions table

Blockers/Concerns:

• Review blockers from completed phase
• If addressed in this phase: Remove from list
• If still relevant for future: Keep with "Phase X" prefix
• Add any new concerns from completed phase's summaries

Example:

Before:

### Blockers/Concerns

- ⚠️ [Phase 1] Database schema not indexed for common queries
- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown

After (if database indexing was addressed in Phase 2):

### Blockers/Concerns

- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown

Step complete when:

• Recent decisions noted (full log in PROJECT.md)
• Resolved blockers removed from list
• Unresolved blockers kept with phase prefix
• New concerns from completed phase added

Update Session Continuity section in STATE.md to reflect transition completion.

Format:

Last session: [today]
Stopped at: Phase [X] complete, ready to plan Phase [X+1]
Resume file: None

Step complete when:

• Last session timestamp updated to current date and time
• Stopped at describes phase completion and next phase
• Resume file confirmed as None (transitions don't use resume files)

MANDATORY: Verify milestone status before presenting next steps.

Use the transition result from gsd-tools phase complete:

The is_last_phase field from the phase complete result tells you directly:

• is_last_phase: false → More phases remain → Go to Route A
• is_last_phase: true → Milestone complete → Go to Route B

The next_phase and next_phase_name fields give you the next phase details.

If you need additional context, use:

ROADMAP=$(node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap analyze)

This returns all phases with goals, disk status, and completion info.

---

Route A: More phases remain in milestone

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

Check if next phase has CONTEXT.md:

ls .planning/phases/*[X+1]*/*-CONTEXT.md 2>/dev/null

If next phase exists:

If CONTEXT.md exists:

Phase [X] marked complete.

Next: Phase [X+1] — [Name]

⚡ Auto-continuing: Plan Phase [X+1] in detail

Exit skill and invoke SlashCommand("/gsd:plan-phase [X+1] --auto")

If CONTEXT.md does NOT exist:

Phase [X] marked complete.

Next: Phase [X+1] — [Name]

⚡ Auto-continuing: Discuss Phase [X+1] first

Exit skill and invoke SlashCommand("/gsd:discuss-phase [X+1] --auto")

If CONTEXT.md does NOT exist:

## ✓ Phase [X] Complete

---

## ▶ Next Up

**Phase [X+1]: [Name]** — [Goal from ROADMAP.md]

`/gsd:discuss-phase [X+1]` — gather context and clarify approach

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

---

**Also available:**
- `/gsd:plan-phase [X+1]` — skip discussion, plan directly
- `/gsd:research-phase [X+1]` — investigate unknowns

---

If CONTEXT.md exists:

## ✓ Phase [X] Complete

---

## ▶ Next Up

**Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
<sub>✓ Context gathered, ready to plan</sub>

`/gsd:plan-phase [X+1]`

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

---

**Also available:**
- `/gsd:discuss-phase [X+1]` — revisit context
- `/gsd:research-phase [X+1]` — investigate unknowns

---

---

Route B: Milestone complete (all phases done)

Clear auto-advance chain flag — milestone boundary is the natural stopping point:

node "C:/Users/yaoji/.claude/get-shit-done/bin/gsd-tools.cjs" config-set workflow._auto_chain_active false

Phase {X} marked complete.

🎉 Milestone {version} is 100% complete — all {N} phases finished!

⚡ Auto-continuing: Complete milestone and archive

Exit skill and invoke SlashCommand("/gsd:complete-milestone {version}")

## ✓ Phase {X}: {Phase Name} Complete

🎉 Milestone {version} is 100% complete — all {N} phases finished!

---

## ▶ Next Up

**Complete Milestone {version}** — archive and prepare for next

`/gsd:complete-milestone {version}`

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

---

**Also available:**
- Review accomplishments before archiving

---

<implicit_tracking> Progress tracking is IMPLICIT: planning phase N implies phases 1-(N-1) complete. No separate progress step—forward motion IS progress. </implicit_tracking>

<partial_completion>

If user wants to move on but phase isn't fully complete:

Phase [X] has incomplete plans:
- {phase}-02-PLAN.md (not executed)
- {phase}-03-PLAN.md (not executed)

Options:
1. Mark complete anyway (plans weren't needed)
2. Defer work to later phase
3. Stay and finish current phase

Respect user judgment — they know if work matters.

If marking complete with incomplete plans:

• Update ROADMAP: "2/3 plans complete" (not "3/3")
• Note in transition message which plans were skipped

</partial_completion>

<success_criteria>

Transition is complete when:

• Current phase plan summaries verified (all exist or user chose to skip)
• Any stale handoffs deleted
• ROADMAP.md updated with completion status and plan count
• PROJECT.md evolved (requirements, decisions, description if needed)
• STATE.md updated (position, project reference, context, session)
• Progress table updated
• User knows next steps

</success_criteria>