Skip to Content
TutorialsGates, Decisions & Checkpoints

Gates, Decisions and Checkpoints

For a change where the approach matters, you want to read the agent’s requirements and plan before any code is written. That’s spec-driven mode. In this tutorial you run one feature through it: you answer the requirements questions, send the PRD back once, approve the plan, and then use git checkpoints to see and undo what each step changed.

Time: about 15 minutes of your own steps, plus the agent’s time. You need: Shep set up in a repository, as in From zero to a merged PR.

Spec-driven mode is optional. Fast mode, the default, is the better choice for small changes.

Start a spec-driven feature

shep feat new "Add Stripe checkout: replace the cart total with a Stripe Checkout session and an order confirmation page" --no-fast --pr --effort high
  • --no-fast runs the spec phases: analyze, requirements, research and plan, before implementation.
  • --pr pushes the branch and opens a draft PR once the code is done.
  • --effort high asks for more reasoning per turn. Only Claude Code uses it; other agents ignore it. See Models & effort.

You should see the feature start in the Requirements phase, with a spec folder in its worktree and Review: pause after every phase:

shep feat new with --no-fast: Feature created, with its ID, name Add order history page, branch feat/add-order-history-page, status Requirements, worktree and spec paths, Agent spawned, and Review: pause after every phase

Wait for the requirements gate

shep feat wait <id> shep feat status <id>

You should see blocked, Why Waiting for your approval and Phase requirements. The agent has analyzed your code, written a PRD and turned its open questions into a short questionnaire.

Answer the requirements questions

Open the feature in the browser and pick the PRD Review tab. Each question is a decision: a few options, one marked Recommended and already selected.

The PRD Review tab for Add Stripe checkout: question 1 of 2, "Which Stripe integration should the cart use?", with "Stripe Checkout (hosted page)" marked Recommended and selected, "Payment Element embedded in the cart page" as option 2, Previous and Next buttons, a box to ask the AI to refine the requirements, and Reject and Approve Requirements buttons

Pick an option with the mouse or the number keys, move with Next, or type your own answer. Prefer the terminal? shep feat review <id> walks you through the same questions and ends with approve or reject.

Don’t approve yet.

Send the PRD back once

Say the PRD missed something. Reject it with a reason:

shep feat reject <id> --reason "Also cover guest checkout, without an account"

--reason is required: it is the feedback the agent gets. In the browser, type the note in the box under the questions and click Reject.

You should see the feature go back to work in the requirements phase. Wait for it again, read the new PRD, and approve it:

shep feat wait <id> shep feat approve <id>

Review the plan

After requirements, the agent researches the approach and writes a plan. Research has no gate; the plan does.

shep feat wait <id>

You should see Phase plan. In the browser, the Tech Decisions tab shows the plan review: a summary and each technical decision with its rationale and the options the agent considered.

The Tech Decisions tab for Add dark mode toggle: a Technical Implementation Plan Review summary and three numbered technical decisions, Theme State Management, CSS Dark Mode Strategy and Persistence Layer, each with a rationale and Other Options Considered, above Reject and Approve Plan buttons

Approve it with Approve Plan, or:

shep feat approve <id>

The agent now implements the plan task by task, commits, pushes and opens a draft PR. If it hits a choice it can’t make from the code, it may ask you through the Agent Questions inbox, with a deadline after which it takes its recommended option. Background questions work with Claude Code today.

List the checkpoints

When the feature reaches the merge gate (shep feat wait <id> returns again), look at what each step did:

shep feat checkpoints <id>

You should see one row per step with when it was taken, how many files it changed and its commit, for example 0000-baseline, 0001-analyze, 0002-requirements and so on up to implement. A step that changed nothing has no checkpoint, and a step that ran twice, like the requirements you sent back, can have two.

Checkpoints live under refs/shep/checkpoints/ in your repository. They are never pushed.

Diff the steps

What did the implementation change?

shep feat diff <id> --to implement --stat

You should see one line per changed file, marked A, M, D or R, with lines added and removed. Drop --stat for the full diff. Compare any two steps with --from:

shep feat diff <id> --from plan --to implement

In the browser, the Checkpoints tab shows the same, with Per step and Compare views.

Roll back, then undo it

Try a restore while the feature waits at the gate:

shep feat restore <id> plan

Shep asks Restore the worktree to "plan"? … before it changes anything. Answer y.

You should see Worktree restored to plan and, under To undo:, a command that restores the pre-restore checkpoint Shep took first. The branch and its commits haven’t moved; only the worktree’s files changed. Run the undo command now so the implementation is back.

A restore is refused while the agent is running. A run waiting at a gate is fine.

Merge

Review the PR, then approve the merge gate:

shep feat approve <id>

What you did

  • You set the requirements and checked the plan before any code was written.
  • You sent work back with a reason instead of editing it yourself.
  • You saw exactly what each agent step changed, and rolled the worktree back and forward without touching the branch.

To skip gates you trust, add --allow-prd or --allow-plan to shep feat new. To make spec-driven the default, set Settings → Workflow → Default feature mode to Regular.

Troubleshooting

  • shep feat reject asks for --reason. The flag is required. There is no --feedback flag.
  • shep feat approve says the feature isn’t waiting for approval. The agent is still working. Run shep feat wait <id> first.
  • shep feat restore is refused. The agent is running, the worktree is gone, or the feature doesn’t use its own worktree. Wait for the next gate and try again.
  • No implement checkpoint. The implementation hasn’t finished, or it changed nothing. shep feat checkpoints <id> lists what exists.

What’s next