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: MergeWhat 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.

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.

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 --prIn 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 feedbackThe 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:
| Setup | What you approve |
|---|---|
--no-fast | PRD, plan, and merge. |
--no-fast --allow-prd | Plan and merge. |
--no-fast --allow-prd --allow-plan | Merge only. |
--no-fast --allow-all | Nothing — 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), thenshep 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
- The AI-Native SDLC — why Shep works this way, and how the YAML spec files connect the phases.
- Gates, decisions and checkpoints — a hands-on tutorial of this flow.
- Decisions — how the PRD questionnaire and agent questions work.
- CI Watch & Auto-Fix — what Shep does after the PR opens.
- Web Dashboard — review and approve gates from the browser.