↓Skip to main content

Run a full project with GSD

Playbook
·4 mins
GSD project lifecycle: Init, Discuss, Plan, Execute, Gate checkpoint, Verify, Ship — with autonomy spectrum from Guided to Autonomous.

First big Claude Code project without scaffolding: working demo, week of cleanup—wandering files, deferred edge cases, git log that didn’t tell the story. I wanted guardrails that sped me up without ceremony for its own sake.

GSD (Get Stuff Done) is the plugin that wraps requirements → roadmap → per-phase discuss, plan, execute, verify, ship. I start at /gsd:new-project; the numbered phases and .planning/ markdown are the contract with the agent. Here’s the loop.

When I reach for this #

Any project that will take more than a single session or involves more than one phase of work. If it fits in one prompt, GSD is overhead. If it has distinct milestones, dependencies between features, or needs to survive a context reset — GSD pays for itself.

What I do #

1. Initialize the project #

/gsd:new-project

Claude asks structured questions about what I’m building, who it’s for, and what success looks like. The answers become PROJECT.md — a single-source-of-truth document that every subsequent phase references.

This step also produces a roadmap: numbered phases, each with a goal, requirements, and success criteria. The roadmap is the contract between me and the agent.

2. Discuss the first phase #

/gsd:discuss-phase

No code until this finishes. Claude asks scoped questions; typical themes:

  • Data: new database vs existing schema vs external API only
  • API shape: REST vs match legacy patterns in repo
  • Deploy: feature flags, migrations, backward compatibility

I answer in full sentences—shortcuts here become wrong assumptions in PLAN.md.

--auto skips the interview when the phase is boring and I trust the defaults.

3. Plan the phase #

/gsd:plan-phase

Output is PLAN.md:

  • Tasks with acceptance criteria
  • Dependency order
  • Files touched
  • How we’ll verify

A plan-review pass runs before I see it. If the plan can’t hit the phase goal, it revises before I spend time on an off-target plan.

4. Execute #

/gsd:execute-phase

One task → one atomic commit → descriptive message. Drift from plan gets flagged instead of silently patched.

I either watch live or review the commit stream afterward. Revert granularity stays at the task level.

5. Verify #

/gsd:verify-work

Verification asks whether the artifact matches what the phase promised; green checkboxes without the promised artifact still count as a gap.

Failure output is a concrete gap list. I fix, then rerun verify.

6. Ship #

/gsd:ship

Opens PR, runs review agent, drafts description from plan + verification.

7. Repeat for the next phase #

Advance the roadmap only on verified output. Next phase inherits a known-good base.

The autonomous mode #

For mechanical work I batch the loop:

/gsd:autonomous

Discuss → plan → execute → verify runs per phase without pausing for me. I still read verification summaries and skim commits when stakes aren’t trivial—autonomy here means the loop runs unattended, not that I skip the read-back.

/gsd:autonomous-multi-agent adds Codex or Cursor workers under the same orchestration when tasks parallelize cleanly.

What goes wrong #

  • Skipping discuss — the agent makes assumptions about the approach. Those assumptions compound across tasks. The thirty seconds of answering questions saves hours of rework
  • Plans that are too coarse — a task like “implement the API” hides ten decisions. Break it down until each task is one commit’s worth of work
  • Ignoring verification failures — marking a phase complete when verification flags gaps means the next phase builds on an unstable foundation. Fix the gaps first
  • Autonomous without checkpoints — /gsd:autonomous can burn phases if you never read verification output or skim the commit stream. I still spot-check mid-run when the domain is new
  • Stale or corrupted .planning/ — merges, manual edits, or a crashed session can leave roadmap files out of sync with the repo. If /gsd:resume-work feels wrong, I diff .planning/ against git and realign before continuing
  • PR noise — atomic commits are the point, but twenty tiny commits on one feature can swamp reviewers. I batch or squash when the story is coherent enough to read as one narrative

Notes #

GSD stores all its state in .planning/ at the project root. The roadmap, phase plans, and verification reports are all readable markdown. If a session crashes or context resets, /gsd:resume-work picks up from the last checkpoint.