The AI-Native SDLC
Shep has a firm view on how AI agents should build software. A longer prompt doesn’t make an agent reliable. A process does.
So Shep runs a feature the way a disciplined team would: requirements, research, a plan, a task list, code, review. Each step is done by an agent and leaves a structured file in the repo. The next step builds on that file, and you can read it, edit it, approve it or send it back.
This page covers that way of working and the YAML spec files behind it. For the phases and gates step by step, see SDLC Lifecycle and Spec-Driven Mode.
The principles
| Principle | What Shep does |
|---|---|
| Decide before you code. | In spec-driven mode, no code is written until the requirements and the plan exist and have passed their gates. |
| Specs are data, not prose. | Each phase writes a YAML file: structured fields Shep can check and display, plus a Markdown content field for people to read. |
| The files are the memory, not the chat. | Each phase is a separate agent run that reads the spec files from disk. Nothing depends on one long conversation staying on track. |
| Check every hand-off. | After each phase, Shep checks the file against a schema. Broken output is repaired before the next phase sees it. |
| People decide, agents do the work. | You approve the requirements, the plan and the merge. These are decisions with a recommendation attached, not individual edits. Your feedback goes into the spec, and the agent must act on it. |
| The plan is executable. | tasks.yaml is a work list with acceptance criteria and test-first hints. Shep runs it phase by phase, in parallel where the plan says so, and records progress. |
| The reasoning ships with the code. | By default the spec is committed on the feature branch, so the PR carries the requirements and decisions behind it. |
Why YAML
Shep could ask agents for Markdown documents. It asks for YAML because the spec isn’t only read by people:
- Shep reads it. The questionnaire in the PRD Review tab is the
openQuestionslist inspec.yaml. The Tech Decisions tab shows thedecisionsinresearch.yaml. The Plan tab and the SDLC board come fromplan.yamlandtasks.yaml. - Shep can check it. A required field is either present or missing.
sizeEstimatemust be one ofS,M,LorXL. Every task must belong to a phase that exists in the plan. You can’t check a paragraph that way. - The next agent finds what it needs. The implementation agent gets each task’s title, acceptance criteria and test hints as separate fields, not buried in a long document.
- Git can diff it. A changed decision or a new task shows up as a clear change in the PR and in checkpoints.
- People can still read it. Every spec file has a
contentfield holding Markdown: the problem statement, the requirements, the architecture.
So each file combines structured fields for Shep and its agents with a Markdown body for people. Here is an abridged spec.yaml after the Requirements phase:
name: stripe-checkout
number: 42
branch: feat/042-stripe-checkout
oneLiner: Let users pay for their cart with Stripe
phase: Requirements
sizeEstimate: M
technologies:
- Stripe Checkout
- Next.js route handlers
openQuestions:
- question: Which Stripe integration should the cart use?
options:
- option: Hosted Checkout page
description: Least code; Stripe handles card data and PCI scope
selected: true
- option: Embedded Payment Element
description: Fully on-brand, more code to maintain
selected: false
selectionRationale: Hosted Checkout is the quickest safe path for a first release
answer: Hosted Checkout page
content: |
## Problem Statement
Users can fill a cart but can't pay for it.
## Success Criteria
- [ ] A user can pay for their cart and lands on a confirmation page
- [ ] Failed payments return the user to the cart with an errorThe spec folder
Each feature gets a folder inside its worktree. The number is the next free one in the repo’s specs/ folder.
specs/042-stripe-checkout/
├── spec.yaml # what and why: your request, analysis, requirements, open questions, your feedback
├── research.yaml # how: technical decisions, each with the chosen option and the rejected ones
├── plan.yaml # strategy: architecture, ordered phases, files to create and change
├── tasks.yaml # work list: tasks per phase, acceptance criteria, test-first hints
└── feature.yaml # progress: completed phases, current task, errors (kept by Shep)| File | Written by | Read by |
|---|---|---|
spec.yaml | Created from your description. Analyze adds scope, technologies and a size estimate. Requirements adds the requirements and open questions. Your answers and rejection feedback are written here too. | Every later phase, and the PRD Review tab. |
research.yaml | Research | Planning and Implementation, and the Tech Decisions tab. |
plan.yaml | Planning | Implementation, the Plan tab and the SDLC board. |
tasks.yaml | Planning, together with plan.yaml | Implementation, one task at a time. |
feature.yaml | Shep | Shep, to pick up where a run stopped. |
In fast mode Shep only creates spec.yaml, which holds your request, and feature.yaml. There is no research, plan or task list: the agent implements the request directly. Exploration prototypes get only feature.yaml.
How the phases hand off
Each phase is a new run of your agent. Its input is the spec files written so far, plus your repo:
| Phase | Reads | Writes | Then |
|---|---|---|---|
| Analyze | spec.yaml (your request) and the codebase | spec.yaml | Schema check |
| Requirements | spec.yaml | spec.yaml | Schema check, then Gate 1: PRD |
| Research | spec.yaml | research.yaml | Schema check |
| Planning | spec.yaml, research.yaml | plan.yaml, tasks.yaml | Schema check, then Gate 2: Plan |
| Implementation | All four, one task at a time | Code and tests | Commit, PR, CI, then Gate 3: Merge |
Because everything a phase needs is on disk:
- A stopped run resumes cleanly. A crash, a restart or a stopped daemon doesn’t lose work. The next run reads the same files and skips phases already recorded as done in
feature.yaml. - A rejected phase re-runs with the same inputs plus your feedback. Nothing else has to be reconstructed.
- Long features don’t drift. No single conversation has to hold the whole feature in its context window.
- Project Memory stays on topic. Shep picks the Project Memory entries relevant to each phase by matching them against the spec written so far.
The spec is the agreement between you and the agent. The implementation agent is told not to edit the spec files. If the plan needs to change, that goes through a rejection or through your own edit.
Checked at every hand-off
After each phase, Shep checks the file it produced before the next phase runs:
| File | Must have |
|---|---|
spec.yaml (after Analyze) | name, number, branch, oneLiner, summary, phase and content; at least one technology; sizeEstimate of S, M, L or XL; no open questions yet, because Requirements adds them. |
spec.yaml (after Requirements) | The same, plus a question on every open question. |
research.yaml | At least one decision, each with a title, the chosen option, at least one rejected alternative and a rationale. |
plan.yaml | At least one phase with an id, a name and parallel: true or false; at least one file to create or change. |
tasks.yaml | At least one task, each with an id, title, state, at least one acceptance criterion, and a phaseId that matches a phase in plan.yaml. |
Every field of every file, including the optional ones, is listed in Spec File Schemas.
The rule on research.yaml is deliberate: a decision that doesn’t name what it rejected isn’t really a decision.
If a check fails, a repair step gets the file and the list of errors and fixes only those errors. Shep tries up to 3 repairs. If the file still fails, the run stops as Failed with the errors listed, and retrying runs the phase that wrote the file again from the start.
You decide at the gates
The gates are where your judgment goes in. Shep doesn’t ask you to approve every edit:
- At the PRD gate, each open question has options, one already selected as the recommendation, with a rationale. You confirm or change the picks, and Shep writes your choices back into
spec.yamlbefore the next phase reads it. See Decisions. - When you reject, for example with
shep feat reject <id> --reason "cover the mobile flow too", Shep adds an entry torejectionFeedbackinspec.yamlwith the phase, the iteration, your message and the time. The re-run puts your latest feedback at the top of its instructions as something it must address, with earlier feedback as context. Rejecting at the merge gate works the same way. - When it’s quicker to fix it yourself, edit the spec file in the worktree (
shep ide <id>opens it) and approve. Your edit is what the next phase reads. - When you’d rather not be asked, a supervisor can review gates for you, or the
--allow-prd,--allow-planand--allow-mergeflags skip them. The files are still written and checked either way.
The plan runs as written
plan.yaml lists the phases in order, and every task in tasks.yaml points to one of them. Implementation follows that structure:
- Phases run in order. In a phase marked
parallel: true, its tasks run as separate agent calls at the same time. If one fails, the others in that phase are stopped. - Each task gets its own instructions: title, description, acceptance criteria and red/green/refactor hints, so tests are written alongside the code.
- Progress is recorded. Each finished phase is added to
completedPhasesinfeature.yaml, and phases and tasks appear on the SDLC board (shep settings flags enable sdlcBoard). - Each step is snapshotted. Every phase leaves a git checkpoint, so
shep feat diff <id> --to planshows what one step changed, andshep feat restorerolls the worktree back.
The reasoning ships with the code
The Commit Specs toggle in the New Feature drawer is on by default, so the spec folder is committed on the feature branch. Whoever reviews the PR, or reads the history a year later, sees the requirements, the options that were considered and the plan next to the diff.
Turn it off to keep the spec local. Shep still writes the files and the agents still use them, but if an agent commits them, Shep undoes that commit and leaves the files on disk.
Shep itself is built this way. Its repository has more than 300 spec folders in this same format, one per feature, created from the same templates Shep writes into your worktree.
Choosing how much process
The approach scales down as well as up:
- Fast mode (the default) is right for bug fixes and anything you can describe in a sentence. You still get a worktree, checkpoints, the push, PR and CI flow, and a merge gate.
- Spec-driven mode (
--no-fast) is for work where the approach matters: you see the requirements, the decisions and the plan before any code exists. - Auto-approve flags let you keep the spec-driven structure, with its checked files and recorded decisions, without stopping at every gate.
What’s next
- SDLC Lifecycle: every phase and gate, and the other lifecycle states.
- Spec-Driven Mode: run a feature with
--no-fastand review each gate. - Gates, decisions and checkpoints: the same flow as a hands-on tutorial.
- Decisions: how agents ask questions with a recommended answer.
- Spec File Schemas: the full schema of every spec file.