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 extra requirements and planning phases with their own approval gates.

Fast mode (default)

Started ─▶ Implementation ─▶ Review ─▶ Maintain │ Gate: Merge

Use this for most work. The agent receives your description and implements it in one go. The merge gate still applies: the feature waits in Review for you to approve the merge, unless you passed --allow-merge.

Spec-driven mode (--no-fast)

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

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. Each phase writes a YAML spec file that the next phase reads — see The AI-Native SDLC.

What each phase does

Started

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

Analyze

Spec-driven only. The agent studies your codebase — structure, dependencies, conventions — so the requirements and plan fit the rest of your project.

Requirements

Spec-driven only. The agent turns your description into a PRD, and asks you its open questions as a questionnaire of decisions, each with a recommended answer.

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

Research

Spec-driven only. The agent investigates the technical approach: which libraries, which patterns already exist in your repo, what tradeoffs to make. There is no gate here.

Planning

Spec-driven only. Shep produces a plan of concrete tasks. Read it in the Plan tab, approve it, or send it back with feedback.

This is Gate 2. Use --allow-plan to auto-approve.

Implementation

The agent does the work. In spec-driven mode it follows the plan task by task; in fast mode it implements the prompt directly. Watch it in the web UI’s Log tab, in shep tui, or with shep feat logs <id> -f.

Review

Shep commits, then — if push and PR are on — pushes the branch, opens a draft PR and watches CI, fixing failures as they come.

Then the feature waits at the merge gate (Gate 3 in spec-driven mode). It shows as Needs you · merge. Approve it in the Merge Review tab, with shep feat approve <id>, or with a in shep tui, and Shep merges the PR (squash). With --allow-merge, Shep merges on its own once CI is green.

Shep still stops for a person, even with --allow-merge, when CI couldn’t be verified, or when a docs-first space is missing its docs.

Maintain

The feature is merged or done. Shep keeps the record, and archives it from the canvas after 10 minutes (configurable in Settings → Workflow).

Other lifecycle states

StateMeaningWhat to do
PendingCreated with --pending, or waiting in the queue for a free slot under the parallel limit.shep feat start <id> (add --force to skip the limit), or wait — queued features start automatically.
BlockedA child feature (--parent) waiting for its parent’s work to land.Nothing — it starts once the parent reaches Maintain.
ExploringAn exploration prototype session.shep feat feedback <id> "…", then shep feat promote <id>.
AwaitingUpstreamThe PR was opened from a fork (--remote on a repo you can’t push to) and waits on the upstream project.Follow up on the upstream PR.
Deletingshep feat del is cleaning up the worktree, branches and PR.—
ArchivedHidden from the canvas.shep feat unarchive <id> to bring it back.

Blocked is about parent features only. When a feature needs you — a gate to approve, a question to answer — that’s its agent state, not its phase: the web UI and shep feat status show it as Needs you. When a run fails (for example, CI is still red after every fix attempt), the agent state is Failed. See Agent activity & states.

Approval gates in detail

Gates are how you control how much runs without you:

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 three gates auto-approved.
--fast (default)Merge only.
--fast --allow-mergeNothing — Shep merges once CI is green.

--allow-all only covers the gates. Whether Shep pushes and opens a PR is still up to --push / --pr or your workflow defaults. Set defaults with shep settings workflow — see Configuration.

To review a waiting feature in the terminal, run shep feat review. To reject with feedback, run shep feat reject <id> --reason "…"; the agent re-runs that phase with your notes.

Questions during a run

Agents don’t only stop at gates. A background agent can ask you a decision mid-run: a question with options, one of them recommended, and a deadline (30 minutes by default, set in Settings → Workflow). If nobody answers in time, the agent proceeds with its recommended option and notes that in the activity log.

Watching progress

shep feat ls # every feature and its phase shep feat show <id> # phase, settings, PR, worktree shep feat status <id> # what the agent is doing and why (--json for scripts) shep feat wait <id> # block until it needs you, finishes or fails shep feat logs <id> -f # follow the agent's log shep tui # live console of every feature

shep feat wait exits 0 when the state is reached, 1 if the feature isn’t found, 2 on --timeout, 3 if the ID prefix is ambiguous and 130 if interrupted — handy in scripts.

In the browser, the Control Center canvas shows every feature’s phase, the Agent activity page lists what needs you, and each feature’s Checkpoints tab lets you diff or restore any step — see Git checkpoints. A Kanban-style SDLC board also exists but is off by default; turn it on with shep settings flags enable sdlcBoard.

What’s next