How the GSD‑Build Continuation Prompt System Resumes Checkpointed Work

The GSD‑Build continuation prompt system is a file‑driven mechanism that restores project state from STATE.md and .continue‑here files to generate a single, copy‑pasteable command that resumes automation exactly where it left off.

The continuation prompt system in the gsd-build/get-shit-done repository eliminates ambiguity when returning to long‑running automations. By treating every pause as a checkpoint, the system persists enough context to reconstruct the exact project state and present the next actionable step without requiring the user to remember previous progress.

How the Continuation Prompt System Works

The architecture relies on deterministic state files and a standardized resume workflow. When a user triggers a resume, the system executes a six‑step orchestration defined in get-shit-done/workflows/resume-project.md.

Checkpoint Types and State Persistence

GSD‑Build defines three checkpoint types in get-shit-done/references/checkpoints.md:

• human‑verify — The most common (≈90 % of cases), requiring user confirmation before proceeding.
• decision — A branch point where the user must choose between alternatives.
• human‑action — Reserved for truly manual steps such as authentication gates.

These checkpoints write markers to .planning/phases/*/.continue‑here*.md files or update the Session Continuity section in .planning/STATE.md. The STATE.md file holds the current phase, plan counters, progress bars, decisions, blockers, and the resume marker, while .planning/PROJECT.md stores high‑level requirements and constraints.

The Resume Workflow Orchestration

The resume-project.md workflow executes the following sequence:

1. Initialize — Runs gsd-tools init resume to gather environment flags.
2. Load State — Parses STATE.md and PROJECT.md for project reference and position.
3. Detect Incomplete Work — Scans for .continue‑here files, missing *-SUMMARY.md files, or interrupted agents via agent-history.json.
4. Present Status — Renders a boxed status table showing phase, plan, progress, and warnings.
5. Determine Next Action — Chooses the primary step (resume agent → execute plan → transition phase).
6. Emit Continuation Prompt — Generates the standardized Continuation Format block.

Continuation Prompt Format and Structure

The canonical layout is defined in get-shit-done/references/continuation-format.md. Every continuation prompt is a markdown block containing:

• A one‑line description of the next task.
• The exact CLI command in inline backticks.
• A /clear reminder to refresh the context window.
• An Also available section listing alternative actions.

Example structure:

---

## ▶ Next Up

**02‑03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
`/gsd:execute-phase 2`
<sub>`/clear` first → fresh context window</sub>
---
Also available:
- `/gsd:list-phase-assumptions 2` — check assumptions
- `/gsd:research-phase 2` — investigate unknowns
---

This format ensures the user receives a single copy‑pasteable command with context, eliminating ambiguity about what to run next.

Detecting and Resuming Interrupted Work

The system handles three specific interruption scenarios through file‑system inspection.

Identifying Mid‑Plan Checkpoints

When a plan pauses mid‑execution, it leaves a .continue‑here*.md marker in the phase directory. The resume workflow detects these files using:

# List any mid‑plan checkpoint files

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

If found, the workflow reads the marker contents and constructs the continuation prompt around the described action, ensuring the user resumes at the exact step where the plan paused.

Handling Interrupted Sub‑Agents

Long‑running automations may spawn sub‑agents that get interrupted if the session ends. The system logs these in agent-history.json. When gsd-tools init resume returns has_interrupted_agent: true, the resume workflow inspects the JSON log to extract the agent ID and task description.

The resulting continuation prompt appears as:

---

## ▶ Next Up

**Resume interrupted agent** — Agent ID: a1b2c3 (deploying Vercel)
`/gsd:resume a1b2c3`
<sub>`/clear` first → fresh context window</sub>
---
Also available:
- `/gsd:abort a1b2c3` — abandon the agent’s work
---

This ensures no agent work is lost between sessions.

CLI Integration and Automation

The get-shit-done/bin/gsd-tools.cjs CLI utility provides the init resume command that powers the entire workflow. This command returns a JSON payload describing the current environment:

{
  "state_exists": true,
  "has_interrupted_agent": false,
  "next_command": "/gsd:execute-phase 2"
}

All subsequent resume steps consume this data. Automating the resume process in shell scripts looks like this:

# Initialise resume data (JSON printed to STDOUT)

INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init resume)

# Extract the primary next command (jq is optional)

NEXT_CMD=$(echo "$INIT" | jq -r '.next_command // "/gsd:plan-phase 1"')
echo "Run the following after clearing your chat context:"
echo "$NEXT_CMD"

This integration allows the continuation prompt system to function deterministically across different environments and sessions.

Summary

• The continuation prompt system in gsd-build/get-shit-done treats every pause as a checkpoint, storing state in STATE.md and .continue‑here files.
• Three checkpoint types (human‑verify, decision, human‑action) define how the automation pauses and what context is preserved.
• The resume workflow (resume-project.md) orchestrates state loading, incomplete work detection, and continuation prompt generation through six deterministic steps.
• The Continuation Format standardizes the user-facing prompt with a one‑line description, exact CLI command, /clear reminder, and alternative actions.
• CLI integration via gsd-tools.cjs init resume provides JSON flags that drive the entire resumption process, enabling automation and scripting.

Frequently Asked Questions

What triggers the continuation prompt system to activate?

The system activates when a user types “continue”, “resume”, or “what’s next” after a session interruption. Internally, gsd-tools init resume detects existing state via state_exists flags, scans for .continue‑here markers, and checks agent-history.json for interrupted sub‑agents. If any incomplete work is found, the resume workflow builds and displays the continuation prompt.

How does the system know exactly where to resume a project?

The system locates the resume point by reading .planning/STATE.md for the current phase and plan counters, then scanning phase directories for .continue‑here*.md files that mark mid‑plan checkpoints. For interrupted agents, it parses agent-history.json to retrieve the agent ID and task context. This multi‑layer detection ensures the next command targets the exact pending action.

What is the difference between the three checkpoint types?

human‑verify checkpoints pause automation to require user confirmation before proceeding, covering roughly 90 % of interruption scenarios. decision checkpoints present a branch where the user must select between alternative paths. human‑action checkpoints are reserved for strictly manual steps, such as completing an external authentication gate, where automation cannot proceed without human intervention.

Can the continuation prompt system be automated in CI/CD pipelines?

Yes. The gsd-tools.cjs CLI exposes init resume as a JSON‑emitting command, allowing scripts to parse state_exists, has_interrupted_agent, and next_command fields without human interaction. By chaining this with jq or similar tools, CI/CD pipelines can detect incomplete work and automatically invoke the appropriate /gsd:* command to resume phases or agents deterministically.

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