Skip to Content
Core ConceptsSDLC Lifecycle

SDLC Lifecycle

Every feature in Shep moves through a series of phases. In fast mode (the default) you get the short path. In spec-driven mode (--no-fast) you get the full pipeline with approval gates.

Fast mode (default)

Started ─▶ Implementation ─▶ Review ─▶ Maintain

Use this for most work. The agent receives your description and implements it in one go. It’s fast, has the lowest overhead, and produces good results when the change is well-defined.

Spec-driven mode (--no-fast)

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

                                              ◀── Blocked (from any phase)

Use this when you want a plan you can review before any code is written. Most useful for larger features where the approach matters more than speed.

What each phase does

Started

The feature exists. Shep is provisioning the worktree and branch.

Analyze

Shep reads your codebase to understand architecture, dependencies, and conventions. This context goes to the agent so its output fits the rest of your project.

Requirements

The agent turns your description into a structured PRD. You can read and edit the PRD before Shep continues.

This is Gate 1. By default Shep pauses here so you can approve. Use --allow-prd to auto-approve.

Research

The agent investigates: which libraries to use, which patterns already exist in your repo, what tradeoffs to make. This stops the agent from jumping into code with a bad plan.

Planning

Shep produces a tasks list — concrete steps with acceptance criteria. You can read it in the dashboard, edit it, or send it back for revision.

This is Gate 2. By default Shep pauses. Use --allow-plan to auto-approve.

Implementation

The agent executes the work. In spec-driven mode it follows the plan task by task. In fast mode it just codes.

You can watch live in the dashboard’s logs view, or follow with shep feat logs <id>.

Review

Shep checks that requirements are met, tests run, and the code is ready for human review. If --push is set, Shep pushes the branch. If --pr is set, Shep opens a draft PR.

If --allow-merge is set, this is Gate 3 — Shep waits for CI to pass and then merges. Without that flag the PR stays in draft for you to review and merge yourself.

Maintain

The feature is merged or marked done. Shep keeps the record so you can refer back to it.

Blocked

A feature can enter Blocked from any phase. This happens when Shep needs your input — a merge conflict it can’t resolve, a test failure it can’t fix after the configured retry count, or a question the agent has flagged.

Blocked features are highlighted in the dashboard. Provide feedback, then shep feat resume <id> to continue.

Approval gates in detail

Gates are how you control automation level. From most controlled to least:

SetupWhat you approve
--no-fast (no allow flags)PRD, plan, and merge — all manual.
--no-fast --allow-prdPRD auto-approved. Plan and merge manual.
--no-fast --allow-prd --allow-planPRD and plan auto-approved. Manual merge.
--no-fast --allow-allEverything automated end-to-end.
--fast (default)No gates — straight to coding. Manual merge.
--fast --allow-mergeCoding then auto-merge after CI.
--allow-allPush, PR, gates auto-approved, auto-merge.

You can also set defaults so you stop typing flags. See Configuration.

Watching progress

shep feat ls                    # all features and current phase
shep feat show <id>             # current phase, plan, recent activity
shep feat logs <id>             # tail logs as the agent works

The dashboard shows every feature’s current phase plus a visual progress indicator.

What’s next

Features & TasksParallel Execution & Worktrees