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 the speed, switch to spec-driven mode. Shep produces a PRD, a research artifact, and a plan — each one a stop where you can read what the agent is about to do and approve, edit, or reject 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’re delegating to multiple agents in sequence and want the artifacts as a hand-off contract.
• 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    (research)   Gate 2: Plan
                                                                    │
                                                                Gate 3: Merge

What each phase produces

Analyze

Shep examines your codebase: architecture, dependencies, conventions, tech stack. The output goes to the agent as context for the rest of the pipeline.

Requirements

The agent turns your description into a structured PRD. You see:

• Goals
• User stories
• Acceptance criteria
• Out-of-scope items
• Open questions

This is Gate 1. By default Shep pauses here. Read the PRD, edit anything wrong, then approve. Use --allow-prd to auto-approve.

Research

The agent investigates the technical approach: which libraries, which patterns, which tradeoffs. Output is a research artifact you can read.

There’s no gate here by default — Shep moves on automatically.

Planning

The agent produces a tasks list — concrete steps with acceptance criteria. Each task is a unit of work the implementation phase will execute.

This is Gate 2. By default Shep pauses. Approve, edit, or reject. Use --allow-plan to auto-approve.

Implementation

The agent works through the plan task-by-task. You can watch live in the dashboard.

If agents.implementation.requireApproval is set, the agent pauses before each task. Otherwise it runs the whole plan.

Review, then PR

Same as fast mode — push, open draft PR, watch CI, auto-fix on failure.

Gate 3: Merge

Only relevant if you set --allow-merge. Shep waits for CI to pass, then merges the PR. Without that flag, the PR stays in draft and you merge manually.

Running it

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

Approve gates from the dashboard, or from the CLI:

shep feat approve <id>                  # approve current gate
shep feat reject <id> --feedback "..."  # reject and request changes
shep feat resume <id>                   # continue after providing feedback

Tuning automation

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

Artifacts

The PRD, research, and plan are stored as YAML in the worktree under specs/<feature-id>/. Each is human-readable and editable. After you edit, shep feat approve <id> continues with your edits.

What happens if the agent gets the PRD wrong

Two options:

• Reject with feedback. shep feat reject <id> --feedback "the PRD missed the mobile flow — please add it". The agent regenerates the PRD with your feedback.
• Edit and approve. Open the PRD file, fix it yourself, then shep feat approve <id>.

Same pattern for the plan.

Defaults

To make spec-driven the default for a project, set it in workflow settings:

shep settings workflow
# answer "Use fast or spec-driven?" with spec-driven

Or per-repo in .shep/config.json:

{
  "workflow": {
    "defaultMode": "spec-driven"
  }
}

(Then individual features can opt into fast mode with --fast.)