Skip to Content
Spec File Schemas

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
specs/042-stripe-checkout/spec.yaml
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
1. Create. 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.
FileHoldsWritten by
spec.yamlThe request, requirements and open questionsShep, then Analyze and Requirements
research.yamlTechnical decisionsResearch
plan.yamlOrdered phases and files to changePlanning
tasks.yamlThe task listPlanning
feature.yamlRun progressShep

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 Checkout

Fields

FieldTypeCheckedDescription and example
namestringYesFeature slug. stripe-checkout
numberintegerYesSpec number, unquoted. 42, not "042"
branchstringYesSet when the spec is created, as feat/<NNN>-<slug>. Shep tracks the actual git branch in its database. feat/042-stripe-checkout
oneLinerstringYesOne-line description. Let users pay for their cart with Stripe
userQuerystringYour description, as you typed it. add stripe checkout to the cart page
summarystringYesTwo or three sentences. Add a checkout step that sends the cart to Stripe…
phasestringYesThe phase that last wrote the file. Analysis, then Requirements
sizeEstimatestringYesS, M, L or XL. Anything else fails the check. M
technologiesstring[]Yes, not empty[Stripe Checkout, Next.js route handlers]
relatedFeaturesstring[]Other spec folders. [031-cart-page]
relatedLinksRelatedLink[]- {title: Stripe Checkout quickstart, url: https://…}
openQuestionsOpenQuestion[]See belowThe questions you answer at the PRD gate.
rejectionFeedbackRejectionFeedbackEntry[]Written by Shep, never by agents. One entry per rejection.
contentstringYesThe 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 the selected option pre-picked as the recommendation. When you approve, Shep sets selected and answer to 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

FieldTypeCheckedDescription and example
namestringYesstripe-checkout
summarystringYesThe findings in brief. Use Stripe Checkout Sessions…
decisionsTechDecision[]Yes, not emptyEach needs title, chosen, at least one rejected and rationale.
technologiesstring[][Stripe Node SDK]
relatedFeaturesstring[][]
relatedLinksRelatedLink[]- {title: Stripe webhooks, url: https://…}
openQuestionsOpenQuestion[][]
contentstringYesThe 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

FieldTypeCheckedDescription and example
phasesPlanPhase[]Yes, not emptyEach needs id, name and a true/false parallel.
filesToCreatestring[]Yes, see noteRepo-relative paths. [app/api/checkout/route.ts]
filesToModifystring[]Yes, see note[app/cart/page.tsx]
contentstringYesArchitecture, decisions, strategy and risks in Markdown.
namestringstripe-checkout
summarystringTwo phases: the payment backend first…
technologiesstring[][Stripe Node SDK]
relatedFeaturesstring[][]
relatedLinksRelatedLink[][]
openQuestionsOpenQuestion[]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

FieldTypeCheckedDescription and example
tasksSpecTask[]Yes, not emptyEach needs id, title, state, at least one acceptance criterion, and a phaseId from plan.yaml.
namestringstripe-checkout
summarystring3 tasks across 2 phases
totalEstimatestring3.5h
technologiesstring[][]
relatedFeaturesstring[][]
relatedLinksRelatedLink[][]
openQuestionsOpenQuestion[][]
contentstringOptional 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

FieldTypeDescription and example
feature.idstringThe spec folder name. 042-stripe-checkout
feature.namestringstripe-checkout
feature.numberinteger42
feature.branchstringSame as branch in spec.yaml. feat/042-stripe-checkout
feature.lifecyclestringStage when the file was created. research
feature.createdAtstringISO timestamp. '2026-11-05T09:00:00.000Z'
status.phasestringThe current phase; during implementation, the running plan phase. phase-2
status.completedPhasesstring[]Optional. Finished Shep phases and plan phase ids. [analyze, requirements, research, plan, phase-1]
status.progress.completedinteger2
status.progress.totalinteger3
status.progress.percentageinteger0 to 100. 67
status.currentTaskstring or nulltask-3
status.lastUpdatedstringISO timestamp.
status.lastUpdatedBystringfeature-agent:implement
prUrlstringOptional. The feature agent keeps the PR in Shep’s database instead.
mergedAtstringOptional. ISO timestamp of the merge.
validation.lastRunstring or nullnull
validation.gatesPassedstring[][]
validation.autoFixesAppliedstring[][]
tasks.currentstring or nullnull
tasks.blockedstring[][]
tasks.failedstring[][task-2] if that task failed
checkpointsFeatureCheckpoint[]- {phase: feature-created, completedAt: …, completedBy: feature-agent}
errors.currentstring or nullnull
errors.historystring[][]

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.

A link to outside documentation.

relatedLinks: - title: Stripe Checkout quickstart # what the link is url: https://docs.stripe.com/checkout/quickstart
FieldTypeDescription
titlestringWhat the link is.
urlstringThe 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
FieldTypeDescription
questionstringThe question. Checked in spec.yaml after Requirements.
resolvedbooleanWhether it has been answered.
optionsQuestionOption[]Optional. The choices.
selectionRationalestringOptional. Why the selected option is recommended.
answerstringOptional. 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
FieldTypeDescription
optionstringThe choice.
descriptionstringWhat it means and its trade-offs.
selectedbooleantrue 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.
FieldTypeDescription
titlestringWhat is being decided.
chosenstringThe option chosen.
rejectedstring[]Alternatives considered, and why they lost. At least one.
rationalestringWhy 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
FieldTypeDescription
idstringUnique id. Checked. Tasks refer to it with phaseId.
namestringDisplay name. Checked.
descriptionstringOptional. What the phase does and why it’s in this position.
parallelbooleanChecked. true runs the phase’s tasks as concurrent agent calls; if one fails, the rest are stopped.
taskIdsstring[]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
FieldTypeDescription
idstringUnique id. Checked.
phaseIdstringThe plan phase it belongs to. Checked against plan.yaml.
titlestringShort title. Checked.
descriptionstringWhat the task does and why.
stateTaskStateChecked. Planning writes Todo.
dependenciesstring[]Task ids that must finish first.
acceptanceCriteriastring[]Testable conditions for done. Checked, at least one.
tddTddCycleOptional. Test-first hints.
estimatedEffortstring30min, 2h, 1d.
complexityTaskComplexityOptional. 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
FieldTypeDescription
redstring[]Tests to write first.
greenstring[]The smallest implementation that passes them.
refactorstring[]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]
FieldTypeDescription
iterationinteger1 for the first rejection, then counting up.
messagestringYour feedback.
phasestringOptional. requirements, plan or merge.
timestampstringISO timestamp.
attachmentsstring[]Optional. Files you attached.

FeatureCheckpoint

A milestone in feature.yaml.

- phase: feature-created completedAt: '2026-11-05T09:00:00.000Z' completedBy: feature-agent
FieldTypeDescription
phasestringThe milestone.
completedAtstringISO timestamp.
completedBystringWhat reached it.

Enum values

TaskState

state: Todo
ValueMeaning
TodoNot started. Planning writes this.
Work in ProgressBeing worked on.
ReviewBeing reviewed for quality and correctness.
DoneFinished.

TaskComplexity

complexity: High
ValueUse forExample from the Stripe feature
HighNew design, cross-cutting changes, or work where a subtle mistake is expensive: concurrency, auth, migrations.Idempotent payment webhook
MediumOrdinary work following an existing pattern.A new API route
LowMechanical, fully specified edits.A button on an existing page

sizeEstimate

sizeEstimate: M

S, 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