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: MergeUse 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: MergeUse 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
| State | Meaning | What to do |
|---|---|---|
Pending | Created 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. |
Blocked | A child feature (--parent) waiting for its parent’s work to land. | Nothing — it starts once the parent reaches Maintain. |
Exploring | An exploration prototype session. | shep feat feedback <id> "…", then shep feat promote <id>. |
AwaitingUpstream | The 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. |
Deleting | shep feat del is cleaning up the worktree, branches and PR. | — |
Archived | Hidden 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:
| 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 three gates auto-approved. |
--fast (default) | Merge only. |
--fast --allow-merge | Nothing — 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 featureshep 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
- The AI-Native SDLC — the YAML spec files each phase writes and reads, and why.
- Spec-Driven Mode — deeper dive on
--no-fast. - Decisions — how agents ask and how you answer.
- Agent activity & states — working, needs you, waiting, done, failed.
- Git checkpoints — diff or roll back any step.
- CI Watch & Auto-Fix — what happens after the PR is open.