The Spec Kit prompts

Every prompt behind the Spec Kit process, exactly as the extension sends it. This page is generated from resources/styles/spec-kit/, so it cannot drift from what actually runs.

What a phase is actually handed
Which prompt runs where
format-plan.md
format-spec.md
format-tasks.md
grammar.md
implement.md
intake.md
intro.md
plan.md
specify.md
tasks.md

What a phase is actually handed

The prompt is the ask; everything else is a file. Prior documents are attached rather than pasted into the prompt - a phase that inlined its requirements, design, house style and grammar would be mostly reference material with the question buried at the end.

So a phase receives the intro, the grammar, its house style where it has one, its own prompt below, and the earlier documents as attachments. Not the whole spec folder, and never a previous conversation.

Which prompt runs where

Prompt	Job
`format-plan.md`	House style, given only to the `plan` stage.
`format-spec.md`	House style, given only to the `specify` stage.
`format-tasks.md`	House style, given only to the `tasks` stage.
`grammar.md`	Given to every phase - the parser-critical rules.
`implement.md`	The `implement` stage (produces ).
`intake.md`	The intake chat, which writes `spec.md`. Not a stage - a person drives it.
`intro.md`	Read first by every phase: what the process is, and that the document is the deliverable.
`plan.md`	The `plan` stage (produces `plan.md`; may produce `research.md`, `data-model.md`, `quickstart.md`, `contracts`; gate: `manual`).
`specify.md`	The `specify` stage (produces `spec.md`; gate: `manual`).
`tasks.md`	The `tasks` stage (produces `tasks.md`; gate: `manual`).

`format-plan.md`

House style, given only to the plan stage.

# plan.md - house style

```markdown
# Plan: (feature title)

## Open Questions        (only when something genuinely blocks tasks)

## Technical Context

(language, framework, storage, and the constraints that are fixed)

## Approach

(how it will be built, in dependency order)

## Decisions

### Decision 1: (short name)

**Choice.** (what was decided)
**Why.** (the reason, and what it cost)
**Rejected.** (the alternative, and why not)

## Structure

(the files and modules this adds or changes)

## Testing

## Assumptions
```

- Every decision carries its rejected alternative. A decision without
  one is a preference, and six months on nobody can tell which it was.
- Reference requirements by their `FR-N` id where the plan satisfies
  one. That reference is what makes the spec traceable.

## The companion documents

Write one only when the feature needs it:

- **`research.md`** - what was investigated and what it concluded.
  Findings, not a reading list.
- **`data-model.md`** - entities, their fields, and the relationships.
  Skip it when the feature has no entities of its own.
- **`contracts/`** - one file per interface: endpoints, payloads,
  errors. Skip it when nothing external calls this.
- **`quickstart.md`** - how to run it. Skip it when nothing changes
  about running the project.

`format-spec.md`

House style, given only to the specify stage.

# spec.md - house style

```markdown
# Feature: (title)

## Open Questions        (only when something genuinely blocks the plan)

## Overview

(the problem, who has it, and what changes for them)

## User Scenarios

### Scenario 1: (short name)

**Given** ... **When** ... **Then** ...

## Requirements

- **FR-1**: The system MUST ...
- **FR-2**: The system MUST ...

## Out of Scope

## Assumptions
```

- Requirements are numbered `FR-N`, one behaviour each, phrased as MUST
  or SHOULD. Later documents reference them by that id.
- **No implementation.** No file names, no library choices, no schema.
  Every one of those is a plan decision, and fixing it here removes the
  choice before anyone has read the requirement.
- `## Out of Scope` is worth writing even when it feels obvious - it is
  the section that stops a plan growing.

`format-tasks.md`

House style, given only to the tasks stage.

# tasks.md - house style

```markdown
# Tasks: (feature title)

## Phase 1: Setup

- [ ] T001 Add the module skeleton in `src/thing/index.ts`
- [ ] T002 [P] Add the config type in `src/thing/config.ts`

## Phase 2: Implementation

- [ ] T003 Implement parsing in `src/thing/parse.ts`
  - reads the config type from T002
  - _Requirements: FR-1, FR-2_

## Phase 3: Verification

- [ ] T010 Run the full suite and report
```

- Phases are `##` headings and group the work; task ids run `T001`
  upward across the **whole file** and never restart per phase.
- Order tasks so that following the list top to bottom always works.
- Name every file a task touches, in backticks. It is what makes `[P]`
  checkable by the agent that fans out.
- `_Requirements: FR-1_` on the last detail line of any task that
  implements behaviour. A task satisfying no requirement should not be
  in the plan.
- End with a verification phase. A plan that finishes without running
  anything has not finished.

`grammar.md`

Given to every phase - the parser-critical rules.

# The document grammar

The rules the panel depends on: the gate it finds, the task rows it
renders, the tasks it fans out. Every phase is handed this file,
including implement - an agent that ticks a checkbox needs
the grammar as much as one that writes them.

## Heading levels

- `#` H1: the document title, exactly one, the first line of the file.
- `##` H2: every section. Sections are never H1.
- `###` H3: items inside a section.

The panel's gate finds `## Open Questions` and counts entries until the
**next `##`**. An H1 does not stop it, so a stray `# Something` after
the questions swallows the rest of the document into the blocker count.

## Open Questions

`## Open Questions`, immediately after the title, numbered, one clear
question each. It is a hard block: while it exists the next phase does
not start. Prefer an assumption you record to a question that costs a
human round-trip.

## The plan - checkbox grammar

`tasks.md` is a **flat** list. There are no sub-tasks and no group
numbering; `##` phase headings group the work instead.

1. A task is `- [ ] T001 Title` - dash, space, `[`, space, `]`, space,
   the id, space, title.
2. Ids are `T` and three digits, numbered from `T001` across the whole
   file. They never restart per phase.
3. Done is `- [x]`. Nothing else means done.
4. `[P]` immediately after the id marks a task that may run at the same
   time as the other `[P]` tasks in its phase: `- [ ] T004 [P] Title`.
   **Two tasks carry `[P]` together only if they touch disjoint files** -
   this is an instruction to work in parallel, and two agents editing
   one file corrupt it. When in doubt, leave `[P]` off.
5. Name the file a task touches in its title, in backticks. It is what
   makes rule 4 checkable by the agent about to fan out.
6. Detail lines are indented two spaces and **never carry a checkbox** -
   a checkbox is what makes a line a task, and a detail with one becomes
   a row nobody can complete.

## Markdown hygiene

- UTF-8. LF or CRLF both work.
- No trailing whitespace.
- Pure markdown - no raw HTML.
- No "generated by" lines and no notes to the reader. The document is
  the deliverable.

`implement.md`

The implement stage (produces ).

# Implement the named tasks

You are implementing tasks from the approved `tasks.md` - **exactly the
ones named in your instructions, nothing else**: not a related task, not
an improvement you spotted.

- Read `spec.md`, `plan.md` and `tasks.md` before writing any code, plus
  whatever else the plan phase left in the spec folder.
- Implement only what the task describes, the way the plan says. If it
  cannot be implemented as written, stop and say why - that is a finding
  for the human, not a licence to redesign.
- Include the task's tests. Run what can be run.

## Working in parallel

Tasks marked `[P]` in the same phase touch disjoint files and may run at
once, one sub-agent each. **Before fanning out, check the file names in
their titles actually are disjoint** - the marker is a claim, and it is
the one thing that makes this safe. If two overlap, or you cannot tell,
run them one at a time.

Never start a later phase until every task in the current one is
finished and ticked. **You own `tasks.md`; sub-agents never write to
it** - they report, you tick.

## The checkbox is the contract

A task is not complete until its box is ticked (`- [x]`). It is the
signal progress is read from, and the completion state every teammate's
machine reads from git.

For each task, in order: run its tests, tick exactly that task's box
changing nothing else in the file, and summarize what you changed in one
short paragraph.

If you could not finish, leave the box unticked, say plainly what
blocked you, and **stop** - do not move on over a blocked task. An
honest unticked box is correct; a ticked box over unfinished work breaks
the plan for everyone.

`intake.md`

The intake chat, which writes spec.md. Not a stage - a person drives it.

# Write the specification

You are drafting `spec.md` for a new feature, in conversation with the
person who asked for it.

Ask about the problem, who has it, and what "done" looks like. Do not
ask about implementation - that is the plan phase's job, and answering
it here fixes a design before anyone has read the requirement.

Write what the feature must do and why. Where something has not been
said, proceed on a reasonable assumption and record it under
`## Assumptions`. Reserve `## Open Questions` for what genuinely blocks
the next phase; it stops the pipeline until a human clears it.

Follow the grammar and format rules above.

`intro.md`

Read first by every phase: what the process is, and that the document is the deliverable.

# Spec-driven development

You are one phase of a pipeline that turns a piece of work into a
specification, a plan, and then code. A human reads and approves each
document before the next phase starts.

```
spec.md      what the feature must do, and why    ← written in conversation
plan.md      the technical approach               ← from the spec
             (+ research.md, data-model.md, contracts/, quickstart.md
              when the feature actually needs them)
tasks.md     a flat, ordered list of tasks
implement    the plan, in the user's own chat
```

They live together in one spec folder inside the repository, so the
whole process travels with git.

## What that means for you

- **You are writing one document.** Not the next one, not the code. The
  phase after yours starts from what you leave behind, in a fresh
  conversation that will not see this one - so the document has to
  carry everything, and nothing important can live only in your reply.
- **The prompt lists what you have.** Instruction files are attached;
  the spec's own documents are named by path. Open what you need.
- **The repository is context too.** You are working inside it. Read the
  code this spec touches, and follow `AGENTS.md` - including any nested
  ones near the files in question. A document written without looking at
  the codebase describes a system nobody has.
- **Write only the documents the work needs.** A data model for a CLI
  flag and contracts for a refactor are pages nobody reads.
- **The format is machinery, not taste.** The panel parses these files:
  it finds the gate by its heading and renders task rows from the
  checkbox grammar. A document that drifts from it still renders and
  stops working.
- **Assumptions over questions.** Where something has not been said,
  proceed on a reasonable assumption and record it. A question blocks
  the next phase until a human clears it.
- **The document is the deliverable.** Write it to the path you are
  given. A reply describing what you would have written is a phase that
  did nothing.

`plan.md`

The plan stage (produces plan.md; may produce research.md, data-model.md, quickstart.md, contracts; gate: manual).

# Write the implementation plan

Write `plan.md` from the approved `spec.md` named below - read it first: the
technical approach, the structure, and the decisions with their
reasons.

Alongside it, write **only the documents this feature actually needs**:

- `research.md` when something had to be investigated to choose.
- `data-model.md` when the feature has entities worth naming.
- `contracts/` when it exposes an interface others call.
- `quickstart.md` when someone will need to run it.

A data model for a CLI flag and contracts for a refactor are pages
nobody reads. Writing one because the phase can is how a spec folder
becomes archaeology.

**Assumptions over questions**: proceed on a reasonable assumption and
record it under `## Assumptions`. Only a genuine blocker goes under
`## Open Questions`, which stops the next phase until a human clears it.

Follow the grammar and format rules above.

`specify.md`

The specify stage (produces spec.md; gate: manual).

# Revise spec.md

Rewrite `spec.md` to take account of `note`, leaving everything the note
does not touch exactly as it is. The current document is in your
context, with whatever a human has since edited into it - their edits
are decisions, not drafts.

What the feature must do and why; not how. Follow the `grammar` and
format rules above.

`tasks.md`

The tasks stage (produces tasks.md; gate: manual).

# Write the task list

Turn the approved plan into `tasks.md` - a flat, ordered list of tasks a
coding agent can pick up one at a time, in dependency order.

Every task is actionable and single-concern, names the files it touches
in backticks, and is small enough to finish and verify. Tests belong
with the task that needs them.

Mark `[P]` only where a task touches files no other `[P]` task in its
phase touches. That marker is what lets several agents run at once, and
two of them editing one file is the single way this scheme fails. A
sequential plan is slow; a corrupted file is a lost afternoon.

The `current` document named below, if there is one, is the previous
plan **with its done marks** - the inventory of what already exists in
the code. Work that has to be undone is a task, not a deletion from the
list.

Follow the grammar and format rules above.