How the Transition Workflow in gsd-build Manages Phase-to-Phase Handoffs

The transition workflow in gsd-build orchestrates deterministic phase handoffs by verifying completion through plan-to-summary file matching, atomically updating state files via CLI commands, cleaning temporary artifacts, and evolving project documentation.

The gsd-build/get-shit-done repository implements a rigorous transition workflow that ensures clean, auditable handoffs between project phases. Defined in get-shit-done/workflows/transition.md, this workflow manages the critical path from completing one phase to initializing the next, preventing state corruption through explicit verification steps and atomic state updates.

Understanding the Transition Workflow Architecture

The transition workflow operates as a deterministic state machine that reads from and writes to specific planning artifacts in the .planning/ directory. It ensures that no phase can be marked complete until all associated work items have corresponding summary files, and it guarantees that the next phase begins with a clean state free from stale temporary files.

The workflow delegates atomic state mutations to the gsd-tools.cjs CLI utility, which prevents partial updates that could leave the project in an inconsistent state between ROADMAP.md, STATE.md, and phase-specific documentation.

Step-by-Step Phase Handoff Process

The transition workflow in gsd-build executes six explicit steps to manage phase-to-phase handoffs, each defined in get-shit-done/workflows/transition.md.

Load Current Project State

The workflow begins by reading the core planning artifacts to establish the baseline for the handoff. It loads .planning/STATE.md to identify the active phase, .planning/PROJECT.md for project metadata, and .planning/ROADMAP.md to understand milestone context.

Source: lines 23-35 in get-shit-done/workflows/transition.md

Verify Phase Completion

Before allowing a handoff, the workflow enforces a safety rail by verifying that every plan file has a matching summary file (*-PLAN.md vs. *-SUMMARY.md). If any summaries are missing, the workflow pauses and presents three options: continue the current phase to finish remaining work, mark the phase complete anyway (requiring explicit confirmation due to the destructive nature of skipping work), or review what remains.

Source: lines 37-84 in get-shit-done/workflows/transition.md

Cleanup Lingering Handoffs

The workflow removes any .continue-here*.md files created by paused or interrupted phases. This cleanup step ensures that stale handoff artifacts do not pollute the next phase's working directory, preventing confusion about which tasks are actually pending.

Source: lines 109-119 in get-shit-done/workflows/transition.md

Update ROADMAP and STATE

The workflow invokes the core CLI (gsd-tools.cjs phase complete) to perform atomic updates across multiple state files. This single command:

• Marks the current phase checkbox as completed in ROADMAP.md
• Records the completion date and final plan count
• Updates the progress table
• Advances STATE.md to the next phase (setting its status to "Ready to plan")
• Detects if the completed phase was the final one in the milestone

Source: lines 121-138 in get-shit-done/workflows/transition.md

Archive Prompts

Prompt artifacts generated during the phase are preserved for auditability but moved into a completed/ subfolder by the create-meta-prompts helper. This archival step maintains history without cluttering the active plan area.

Source: lines 140-145 in get-shit-done/workflows/transition.md

Evolve PROJECT.md

After archiving, the workflow reads all *-SUMMARY.md files from the finished phase to extract validated requirements, invalidated assumptions, and new discoveries. It logs key decisions and updates .planning/PROJECT.md with the latest status, requirement lists, and a "Last updated" footer reflecting the transition timestamp.

Source: lines 147-176 in get-shit-done/workflows/transition.md

Triggering Phase Transitions Manually

While the transition workflow automates handoffs, you can manually trigger the core state update using the gsd-tools.cjs CLI. This is useful for debugging or recovering from interrupted transitions.

# Run the transition step for the currently active phase

node ~/.claude/get-shit-done/bin/gsd-tools.cjs phase complete "$(cat .planning/STATE.md | grep '^Current Phase' | cut -d' ' -f3-)"

The CLI call performs all state mutations atomically, ensuring that ROADMAP.md, STATE.md, and phase metadata remain consistent.

Handling Incomplete Plans During Transition

When the verification step detects missing summary files, the transition workflow presents a safety prompt to prevent accidental data loss:

Phase 02 has incomplete plans:
- 02-01-SUMMARY.md ✓ Complete
- 02-02-SUMMARY.md ✗ Missing
- 02-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

Choosing option 2 invokes the same gsd-tools command after explicit user confirmation, allowing the transition workflow to proceed while maintaining an audit trail of skipped work.

Summary

The transition workflow in gsd-build manages phase-to-phase handoffs through a deterministic six-step process that prioritizes data integrity and auditability:

• Verification: Enforces completion by matching every *-PLAN.md with a *-SUMMARY.md before allowing progression
• Atomic Updates: Uses gsd-tools.cjs phase complete to synchronize ROADMAP.md, STATE.md, and phase metadata in a single operation
• Cleanup: Removes stale .continue-here*.md files to prevent pollution of the next phase's workspace
• Documentation: Evolves PROJECT.md with validated requirements from phase summaries and archives prompts to completed/ subfolders

Frequently Asked Questions

What happens if I try to transition a phase with incomplete plans?

The transition workflow blocks the handoff and displays a safety prompt listing which *-SUMMARY.md files are missing compared to their corresponding plan files. You must choose to either complete the remaining work, explicitly confirm skipping the incomplete plans (which is marked as a destructive action), or review what remains. This prevents accidental loss of work during phase-to-phase handoffs.

How does the transition workflow prevent state corruption during updates?

The workflow delegates all state mutations to the gsd-tools.cjs phase complete CLI command, which performs atomic updates across ROADMAP.md, STATE.md, and phase metadata. By handling checkbox completion, date recording, progress table updates, and phase advancement in a single operation, the tool ensures the project never exists in a partially updated state where some files reflect the old phase and others the new.

What are .continue-here*.md files and why are they deleted during transition?

These are temporary handoff artifacts created when a phase is paused or interrupted mid-execution, serving as pointers to resume work. The transition workflow explicitly deletes all .continue-here*.md files during the cleanup step to ensure stale pointers do not carry over into the next phase, preventing confusion about which tasks are actually pending in the new phase workspace.

How does the transition workflow update project documentation after a phase completes?

After archiving prompts to the completed/ subfolder, the workflow reads all *-SUMMARY.md files from the finished phase to extract validated requirements, invalidated assumptions, and new discoveries. It then updates .planning/PROJECT.md with the latest status, requirement lists, and a "Last updated" footer reflecting the transition timestamp, ensuring project documentation evolves accurately with execution reality.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}