Skip to Content
GuidesSpec-Driven Mode

Spec-Driven Mode

Shep’s default is fast mode — describe a feature, the agent codes it, you review the PR. That’s the right choice for most work.

When the change is bigger, or the approach matters more than speed, switch to spec-driven mode. Shep produces requirements, research and a plan — with stops where you read what the agent is about to do and approve it or send it back before any code is written.

When to use it

Reach for --no-fast when:

  • The feature is large enough that you want a plan before code.
  • The approach is non-obvious and you want to see the tradeoffs.
  • You want the spec files as a hand-off contract, for an agent or a teammate.
  • A teammate will review the proposal before implementation.

Stick with the default for:

  • Bug fixes.
  • Small, well-defined features (“add a /health endpoint”).
  • Anything you’d describe in one sentence.

The pipeline

Started ─▶ Analyze ─▶ Requirements ─▶ Research ─▶ Planning ─▶ Implementation ─▶ Review ─▶ Maintain │ │ │ Gate 1: PRD Gate 2: Plan Gate 3: Merge

What each phase produces

Analyze

The agent studies your codebase — structure, dependencies, conventions, tech stack — so the rest of the pipeline fits your project.

Requirements

The agent writes a PRD and turns its open questions into a short questionnaire. In the PRD Review tab each question is a decision: a few options, one marked recommended. Pick with the mouse or the number keys 1–9, or type your own answer.

The PRD Review tab: question 1 of 2, "Which Stripe integration should the cart use?", with the recommended option selected, and Reject and Approve Requirements buttons

This is Gate 1. Shep waits for you. Use --allow-prd to auto-approve.

Research

The agent investigates the technical approach: which libraries, which patterns, which tradeoffs. The result shows in the Tech Decisions tab. There’s no gate here — Shep moves on automatically.

Planning

The agent produces a plan of concrete tasks, each a unit of work the implementation will execute. You review it in the Tech Decisions tab, which holds the plan summary, the technical decisions and the Approve Plan / Reject bar.

The Tech Decisions tab during plan review: a Technical Implementation Plan Review summary, three numbered technical decisions with their rationale and other options considered, and Reject and Approve Plan buttons

This is Gate 2. Approve it, or reject with feedback. Use --allow-plan to auto-approve.

Implementation

The agent works through the plan task by task. The Plan tab shows each task’s progress.

Review and Gate 3: Merge

Same as fast mode: commit, push and open a draft PR (if they’re on), watch CI and fix failures. Then the feature waits at the merge gate. Approve it in Merge Review (or shep feat approve <id>) and Shep merges the PR. With --allow-merge, Shep merges on its own once CI is green.

Running it

shep feat new "redesign the payment system" --no-fast --pr

In the web UI, choose Spec instead of Fast in the New Feature drawer.

Review and answer gates in the feature drawer, in shep tui (a approve, r reject), or from the CLI:

shep feat review # interactive review of the waiting feature, in the terminal shep feat approve <id> # approve the current gate shep feat reject <id> --reason "…" # send it back with feedback

The ID is optional for these three when only one feature in the current repo is waiting.

Tuning automation

Mix and match approval flags to decide how much you want to be in the loop:

SetupWhat you approve
--no-fastPRD, plan, and merge.
--no-fast --allow-prdPlan and merge.
--no-fast --allow-prd --allow-planMerge only.
--no-fast --allow-allNothing — all gates auto-approved.

--allow-all covers the three gates only. Add --push / --pr (or set them as defaults) if you also want the branch pushed and a PR opened.

Artifacts

The spec lives in the worktree under specs/<NNN>-<slug>/ — spec.yaml, research.yaml, plan.yaml, tasks.yaml and feature.yaml. Each one pairs structured fields, which Shep checks after every phase and shows in the review tabs, with a Markdown content field for people. The Commit Specs toggle in the New Feature drawer (on by default) decides whether they’re committed to the branch.

What each file holds, which phase reads it, and the checks it must pass are covered in The AI-Native SDLC. Every field is listed in Spec File Schemas.

What happens if the agent gets the PRD wrong

  • Reject with feedback. shep feat reject <id> --reason "the PRD missed the mobile flow — please add it". The agent regenerates the PRD with your notes.
  • Edit and approve. Edit the spec file in the worktree (shep ide <id> opens it), then shep feat approve <id>.

Same pattern for the plan.

Each phase also leaves a git checkpoint, so you can see exactly what a phase changed with shep feat diff <id> --to plan, or roll the worktree back with shep feat restore <id> <step>.

Docs-first spaces

If your repo belongs to a space with docs-first turned on (shep space config <space> --docs-first), agents write or update the docs while planning, and the merge gate waits for a person whenever those docs are missing. See Autopilot & docs-first.

Making it the default

Spec-driven mode is optional. To make it the default for new features, go to Settings → Workflow → Default feature mode in the web UI and choose Regular. Individual features can still opt into fast mode with --fast. There’s no CLI command for this setting.

New apps created with shep app new start with a spec-driven first feature by default — see Start an app.

What’s next