Spec File Schemas
Each feature gets a specs/<NNN>-<slug>/ folder with five YAML files. This page shows each one by example first, then lists every field.
All the examples follow one feature, “add stripe checkout to the cart page”, so you can see how the files connect. For why the files exist at all, see The AI-Native SDLC.
Watch the files fill up
Each phase reads the files on the left marked reads, and writes the one marked writes. Highlighted lines are what that phase added. Click a phase to jump to it.
- spec.yamlwrites
- research.yamltemplate
- plan.yamltemplate
- tasks.yamltemplate
- feature.yamlwrites
name: stripe-checkout number: 42 branch: feat/042-stripe-checkout oneLiner: add stripe checkout to the cart page phase: Analysis sizeEstimate: M technologies: [] openQuestions: [] content: | ## Problem Statement add stripe checkout to the cart page
- Spec folder created from templates
shep feat new "add stripe checkout to the cart page" --no-fast creates the worktree and the spec folder, with all five files from templates. Your description goes into spec.yaml.| File | Holds | Written by |
|---|---|---|
spec.yaml | The request, requirements and open questions | Shep, then Analyze and Requirements |
research.yaml | Technical decisions | Research |
plan.yaml | Ordered phases and files to change | Planning |
tasks.yaml | The task list | Planning |
feature.yaml | Run progress | Shep |
How to read the field tables
- Checked fields are validated right after the phase that writes the file. If one is missing, empty or the wrong type, Shep asks the agent to repair the file, up to 3 times, before the next phase can start.
- Fields that aren’t checked are still read by Shep and the agents. Leaving one out doesn’t stop the run.
- Every row has an example taken from the Stripe feature.
- Extra fields are ignored by the checks and kept when Shep rewrites a file.
spec.yaml
What it’s for: the feature’s requirements (the PRD). Shep creates it from your description. In spec-driven mode, Analyze rewrites it with what it learned about your codebase, and Requirements adds the requirements and the questions it wants you to answer. In fast mode it only holds your request.
Example
name: stripe-checkout # the feature slug
number: 42 # spec number, a bare integer
branch: feat/042-stripe-checkout # set when the spec is created
oneLiner: Let users pay for their cart with Stripe
userQuery: > # your words; fast mode builds from it
add stripe checkout to the cart page
summary: >
Add a checkout step that sends the cart to Stripe Checkout and records
the payment result on the order.
phase: Requirements # phase that last wrote the file
sizeEstimate: M # S, M, L or XL
technologies: # at least one
- Stripe Checkout
- Next.js route handlers
relatedFeatures: [] # other spec folders
relatedLinks:
- title: Stripe Checkout quickstart
url: https://docs.stripe.com/checkout/quickstart
openQuestions: # the PRD questionnaire (Gate 1)
- question: Which Stripe integration should the cart use?
resolved: true
options:
- option: Hosted Checkout page
description: Least code; Stripe handles card data and PCI scope
selected: true # recommended, then your pick
- option: Embedded Payment Element
description: Fully on-brand, more code to maintain
selected: false
selectionRationale: The quickest safe path for a first release
answer: Hosted Checkout page # filled in when you approve
rejectionFeedback: # added by Shep on each rejection
- iteration: 1
phase: requirements
message: The PRD missed the mobile flow. Please add it.
timestamp: 2026-11-05T09:12:44.000Z
content: | # the PRD itself, in Markdown
## 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
## Functional Requirements
- **FR-1**: A Checkout button on the cart opens Stripe CheckoutFields
| Field | Type | Checked | Description and example |
|---|---|---|---|
name | string | Yes | Feature slug. stripe-checkout |
number | integer | Yes | Spec number, unquoted. 42, not "042" |
branch | string | Yes | Set when the spec is created, as feat/<NNN>-<slug>. Shep tracks the actual git branch in its database. feat/042-stripe-checkout |
oneLiner | string | Yes | One-line description. Let users pay for their cart with Stripe |
userQuery | string | Your description, as you typed it. add stripe checkout to the cart page | |
summary | string | Yes | Two or three sentences. Add a checkout step that sends the cart to Stripe… |
phase | string | Yes | The phase that last wrote the file. Analysis, then Requirements |
sizeEstimate | string | Yes | S, M, L or XL. Anything else fails the check. M |
technologies | string[] | Yes, not empty | [Stripe Checkout, Next.js route handlers] |
relatedFeatures | string[] | Other spec folders. [031-cart-page] | |
relatedLinks | RelatedLink[] | - {title: Stripe Checkout quickstart, url: https://…} | |
openQuestions | OpenQuestion[] | See below | The questions you answer at the PRD gate. |
rejectionFeedback | RejectionFeedbackEntry[] | Written by Shep, never by agents. One entry per rejection. | |
content | string | Yes | The PRD in Markdown: problem, success criteria, requirements. |
openQuestions is checked differently by phase:
- After Analyze it must be
[]. Asking questions is the Requirements phase’s job. - After Requirements every entry needs a
question. Each one shows in the PRD Review tab, with theselectedoption pre-picked as the recommendation. When you approve, Shep setsselectedandanswerto your choice.
research.yaml
What it’s for: the technical decisions, with the alternatives that lost. The Research phase writes it after reading spec.yaml. It shows in the Tech Decisions tab, and Planning builds on it.
Example
name: stripe-checkout
summary: >
Use Stripe Checkout Sessions created from a server route, and confirm
payment through a webhook rather than the redirect.
technologies:
- Stripe Node SDK
relatedFeatures: []
relatedLinks:
- title: Stripe webhooks
url: https://docs.stripe.com/webhooks
decisions: # at least one
- title: Payment confirmation # what is being decided
chosen: Webhook on checkout.session.completed
rejected: # at least one, with why it lost
- Trusting the success redirect, which can be opened unpaid
rationale: >
The webhook is the only signal Stripe guarantees. The redirect only
shows the confirmation page.
- title: Where the session is created
chosen: A Next.js route handler at /api/checkout
rejected:
- A server action, because the cart page is a client component
rationale: Matches the existing app/api routes.
openQuestions: [] # technical questions, if any
content: | # the full write-up, in Markdown
## Technology Decisions
### 1. Payment confirmation
...Fields
| Field | Type | Checked | Description and example |
|---|---|---|---|
name | string | Yes | stripe-checkout |
summary | string | Yes | The findings in brief. Use Stripe Checkout Sessions… |
decisions | TechDecision[] | Yes, not empty | Each needs title, chosen, at least one rejected and rationale. |
technologies | string[] | [Stripe Node SDK] | |
relatedFeatures | string[] | [] | |
relatedLinks | RelatedLink[] | - {title: Stripe webhooks, url: https://…} | |
openQuestions | OpenQuestion[] | [] | |
content | string | Yes | The research write-up in Markdown. |
A decision with an empty rejected list fails the check. A choice that doesn’t name its alternatives isn’t treated as a decision.
plan.yaml
What it’s for: how the work is split and ordered. The Planning phase writes it from spec.yaml and research.yaml. It holds the strategy only; the task list goes in tasks.yaml.
Example
name: stripe-checkout
summary: >
Two phases: the payment backend first, so the UI has something to call,
then the cart UI.
phases: # run in this order; at least one
- id: phase-1 # tasks point here with phaseId
name: Payment backend
description: Checkout session route and webhook
parallel: false # tasks run one after another
- id: phase-2
name: Cart UI
description: Checkout button and confirmation page
parallel: true # tasks run at the same time
filesToCreate: # this list or the next: not empty
- app/api/checkout/route.ts
- app/api/stripe-webhook/route.ts
filesToModify:
- app/cart/page.tsx
technologies: [Stripe Node SDK]
relatedFeatures: []
relatedLinks: []
openQuestions: []
content: | # architecture, decisions, risks
## Architecture Overview
The cart page calls /api/checkout, which returns a Stripe session URL.
## Risk Mitigation
| Risk | Mitigation |
| ---- | ---------- |
| Webhook retried twice | Make the handler idempotent |Fields
| Field | Type | Checked | Description and example |
|---|---|---|---|
phases | PlanPhase[] | Yes, not empty | Each needs id, name and a true/false parallel. |
filesToCreate | string[] | Yes, see note | Repo-relative paths. [app/api/checkout/route.ts] |
filesToModify | string[] | Yes, see note | [app/cart/page.tsx] |
content | string | Yes | Architecture, decisions, strategy and risks in Markdown. |
name | string | stripe-checkout | |
summary | string | Two phases: the payment backend first… | |
technologies | string[] | [Stripe Node SDK] | |
relatedFeatures | string[] | [] | |
relatedLinks | RelatedLink[] | [] | |
openQuestions | OpenQuestion[] | Usually []. |
At least one of filesToCreate and filesToModify must be non-empty. A plan that changes no files fails the check.
tasks.yaml
What it’s for: the concrete work list. The Planning phase writes it together with plan.yaml. Implementation takes the plan’s phases in order and runs each phase’s tasks, giving each task its own instructions from these fields.
Example
name: stripe-checkout
summary: 3 tasks across 2 phases
tasks: # at least one
- id: task-1
phaseId: phase-1 # must match a phase id in plan.yaml
title: Create checkout session route
description: POST /api/checkout returns a Stripe Checkout Session
state: Todo # see TaskState below
complexity: Medium # High, Medium or Low
dependencies: [] # task ids that must finish first
acceptanceCriteria: # at least one testable condition
- Returns a session URL for a non-empty cart
- Returns 400 for an empty cart
tdd: # test-first hints for the agent
red:
- Test that an empty cart returns 400
green:
- Implement the route with the Stripe SDK
refactor:
- Move price lookup into a helper
estimatedEffort: 1h
- id: task-2
phaseId: phase-1
title: Handle checkout.session.completed webhook
description: Mark the order paid when Stripe confirms payment
state: Todo
complexity: High
dependencies: [task-1]
acceptanceCriteria:
- Rejects requests with an invalid signature
- Marks the order paid exactly once
estimatedEffort: 2h
- id: task-3
phaseId: phase-2
title: Add the Checkout button
description: Button on the cart page that redirects to the session URL
state: Todo
complexity: Low
dependencies: [task-1]
acceptanceCriteria:
- Button is disabled for an empty cart
estimatedEffort: 30min
totalEstimate: 3.5h
technologies: []
relatedFeatures: []
relatedLinks: []
openQuestions: []Fields
| Field | Type | Checked | Description and example |
|---|---|---|---|
tasks | SpecTask[] | Yes, not empty | Each needs id, title, state, at least one acceptance criterion, and a phaseId from plan.yaml. |
name | string | stripe-checkout | |
summary | string | 3 tasks across 2 phases | |
totalEstimate | string | 3.5h | |
technologies | string[] | [] | |
relatedFeatures | string[] | [] | |
relatedLinks | RelatedLink[] | [] | |
openQuestions | OpenQuestion[] | [] | |
content | string | Optional Markdown notes. |
Shep checks tasks.yaml and plan.yaml together: a phaseId of phase-3 fails if the plan only has phase-1 and phase-2.
feature.yaml
What it’s for: run progress. Shep writes and reads it; you don’t normally edit it. It has none of the common fields and no content. When a run stops and starts again, Shep skips every step listed in status.completedPhases.
Example
Midway through implementation of the Stripe feature:
feature: # identity, set at creation
id: 042-stripe-checkout # the spec folder name
name: stripe-checkout
number: 42
branch: feat/042-stripe-checkout
lifecycle: research
createdAt: '2026-11-05T09:00:00.000Z'
status:
phase: phase-2 # the plan phase now running
completedPhases: # skipped if the run restarts
- analyze
- requirements
- research
- plan
- phase-1
progress:
completed: 2 # tasks finished
total: 3
percentage: 67
currentTask: task-3
lastUpdated: '2026-11-05T09:41:10.000Z'
lastUpdatedBy: feature-agent:implement
validation:
lastRun: null
gatesPassed: []
autoFixesApplied: []
tasks:
current: null
blocked: [] # waiting on unfinished dependencies
failed: []
checkpoints: # milestones, not git checkpoints
- phase: feature-created
completedAt: '2026-11-05T09:00:00.000Z'
completedBy: feature-agent
errors:
current: null
history: []Fields
| Field | Type | Description and example |
|---|---|---|
feature.id | string | The spec folder name. 042-stripe-checkout |
feature.name | string | stripe-checkout |
feature.number | integer | 42 |
feature.branch | string | Same as branch in spec.yaml. feat/042-stripe-checkout |
feature.lifecycle | string | Stage when the file was created. research |
feature.createdAt | string | ISO timestamp. '2026-11-05T09:00:00.000Z' |
status.phase | string | The current phase; during implementation, the running plan phase. phase-2 |
status.completedPhases | string[] | Optional. Finished Shep phases and plan phase ids. [analyze, requirements, research, plan, phase-1] |
status.progress.completed | integer | 2 |
status.progress.total | integer | 3 |
status.progress.percentage | integer | 0 to 100. 67 |
status.currentTask | string or null | task-3 |
status.lastUpdated | string | ISO timestamp. |
status.lastUpdatedBy | string | feature-agent:implement |
prUrl | string | Optional. The feature agent keeps the PR in Shep’s database instead. |
mergedAt | string | Optional. ISO timestamp of the merge. |
validation.lastRun | string or null | null |
validation.gatesPassed | string[] | [] |
validation.autoFixesApplied | string[] | [] |
tasks.current | string or null | null |
tasks.blocked | string[] | [] |
tasks.failed | string[] | [task-2] if that task failed |
checkpoints | FeatureCheckpoint[] | - {phase: feature-created, completedAt: …, completedBy: feature-agent} |
errors.current | string or null | null |
errors.history | string[] | [] |
checkpoints in feature.yaml are milestone records. They are separate from git checkpoints, the worktree snapshots Shep keeps in hidden git refs.
Shared types
These appear inside the files above.
RelatedLink
A link to outside documentation.
relatedLinks:
- title: Stripe Checkout quickstart # what the link is
url: https://docs.stripe.com/checkout/quickstart| Field | Type | Description |
|---|---|---|
title | string | What the link is. |
url | string | The URL. |
OpenQuestion
A question, answered either by picking from options or with a free-text answer.
openQuestions:
# Picked from options (the PRD questionnaire)
- question: Should failed payments keep the cart?
resolved: true
options:
- option: Keep the cart
description: User can retry straight away
selected: true
- option: Empty the cart
description: Simpler, but the user starts over
selected: false
selectionRationale: Retrying is the common case
answer: Keep the cart
# Free-text answer
- question: Which Stripe API version do we pin?
resolved: true
answer: The version already set in lib/stripe.ts| Field | Type | Description |
|---|---|---|
question | string | The question. Checked in spec.yaml after Requirements. |
resolved | boolean | Whether it has been answered. |
options | QuestionOption[] | Optional. The choices. |
selectionRationale | string | Optional. Why the selected option is recommended. |
answer | string | Optional. The chosen option’s text, or a free-text answer. |
QuestionOption
One choice inside an OpenQuestion.
- option: Keep the cart # the text you see
description: User can retry straight away
selected: true # recommended, then your pick| Field | Type | Description |
|---|---|---|
option | string | The choice. |
description | string | What it means and its trade-offs. |
selected | boolean | true on exactly the option that’s picked. |
TechDecision
One decision in research.yaml. All four fields are checked.
- title: Payment confirmation
chosen: Webhook on checkout.session.completed
rejected:
- Trusting the success redirect
rationale: Only the webhook is guaranteed by Stripe.| Field | Type | Description |
|---|---|---|
title | string | What is being decided. |
chosen | string | The option chosen. |
rejected | string[] | Alternatives considered, and why they lost. At least one. |
rationale | string | Why the chosen option wins. |
PlanPhase
One phase in plan.yaml.
- id: phase-2
name: Cart UI
description: Checkout button and confirmation page
parallel: true # run its tasks at the same time
taskIds: [task-3, task-4] # optional; default: match phaseId| Field | Type | Description |
|---|---|---|
id | string | Unique id. Checked. Tasks refer to it with phaseId. |
name | string | Display name. Checked. |
description | string | Optional. What the phase does and why it’s in this position. |
parallel | boolean | Checked. true runs the phase’s tasks as concurrent agent calls; if one fails, the rest are stopped. |
taskIds | string[] | Optional. Names the phase’s tasks explicitly. Without it, the phase runs every task whose phaseId matches. |
SpecTask
One task in tasks.yaml.
- id: task-3
phaseId: phase-2
title: Add the Checkout button
description: Button on the cart page that redirects to the session URL
state: Todo
complexity: Low
dependencies: [task-1]
acceptanceCriteria:
- Button is disabled for an empty cart
tdd:
red: [Test that the button is disabled for an empty cart]
green: [Render the button and call /api/checkout on click]
refactor: [Extract the redirect into a hook]
estimatedEffort: 30min| Field | Type | Description |
|---|---|---|
id | string | Unique id. Checked. |
phaseId | string | The plan phase it belongs to. Checked against plan.yaml. |
title | string | Short title. Checked. |
description | string | What the task does and why. |
state | TaskState | Checked. Planning writes Todo. |
dependencies | string[] | Task ids that must finish first. |
acceptanceCriteria | string[] | Testable conditions for done. Checked, at least one. |
tdd | TddCycle | Optional. Test-first hints. |
estimatedEffort | string | 30min, 2h, 1d. |
complexity | TaskComplexity | Optional. With adaptive model tiers on, it picks the model for the task. |
TddCycle
Test-first hints inside a task. The agent treats them as guidance, not a script.
tdd:
red: [Test that an empty cart returns 400] # tests to write first
green: [Implement the route with Stripe] # smallest passing code
refactor: [Move price lookup into a helper] # clean-up once green| Field | Type | Description |
|---|---|---|
red | string[] | Tests to write first. |
green | string[] | The smallest implementation that passes them. |
refactor | string[] | Clean-up once tests pass. |
RejectionFeedbackEntry
Added to spec.yaml each time you reject a phase, for example with shep feat reject <id> --reason "…". The re-run must address the latest entry.
rejectionFeedback:
- iteration: 1
phase: plan
message: Split the webhook into its own phase so it ships first.
timestamp: 2026-11-05T09:30:02.000Z
attachments: [/tmp/flow-sketch.png]| Field | Type | Description |
|---|---|---|
iteration | integer | 1 for the first rejection, then counting up. |
message | string | Your feedback. |
phase | string | Optional. requirements, plan or merge. |
timestamp | string | ISO timestamp. |
attachments | string[] | Optional. Files you attached. |
FeatureCheckpoint
A milestone in feature.yaml.
- phase: feature-created
completedAt: '2026-11-05T09:00:00.000Z'
completedBy: feature-agent| Field | Type | Description |
|---|---|---|
phase | string | The milestone. |
completedAt | string | ISO timestamp. |
completedBy | string | What reached it. |
Enum values
TaskState
state: Todo| Value | Meaning |
|---|---|
Todo | Not started. Planning writes this. |
Work in Progress | Being worked on. |
Review | Being reviewed for quality and correctness. |
Done | Finished. |
TaskComplexity
complexity: High| Value | Use for | Example from the Stripe feature |
|---|---|---|
High | New design, cross-cutting changes, or work where a subtle mistake is expensive: concurrency, auth, migrations. | Idempotent payment webhook |
Medium | Ordinary work following an existing pattern. | A new API route |
Low | Mechanical, fully specified edits. | A button on an existing page |
sizeEstimate
sizeEstimate: MS, M, L or XL, in spec.yaml. Any other value fails the check.
Where the schemas are defined
The models are written in TypeSpec in the Shep repo, in tsp/domain/entities/ and tsp/domain/value-objects/spec-metadata.tsp. The checks Shep runs after each phase are in the feature agent’s nodes/schemas/.
What’s next
- The AI-Native SDLC: why the spec is YAML and how each phase reads it.
- Spec-Driven Mode: run a feature through these files with
--no-fast. - Decisions: how
openQuestionsbecomes the PRD questionnaire.