Spec-driven development

A workflow whose tasks are AI-drafted documents and human decisions: requirements, design, plan, then implementation. Each phase runs a fixed prompt in a clean session, and the whole process state is committed to git.

Keys and defaults only: the cheat sheet.

What a spec is
The loop
The one hard block
Existing specs are read, not just written
Choosing a style
Configuration

What a spec is

A folder of Markdown under .local-workflows/specs/, committed alongside your code. Nothing else — no database, no service, no hidden state. Pull the repository and you have the specs; delete the extension and the documents are still there, still readable, still in your history.

Needs a Copilot sign-in. The document phases run on the ai@1 plugin with its default ghcp provider, and the implement phase launches Copilot Chat, so this half of the extension is the one part that does not work without it.

The loop

＋ New Spec asks at most two questions — what kind of spec, and where the work item comes from — then creates the folder and opens a Copilot chat to write the first document with you.

That first one is a conversation rather than a form, deliberately. It is the document worth arguing about, and a chat gets more out of a person than a set of fields does. The engine starts that session and does not wait on it — the pipeline picks up when the document lands.

The moment that file lands, the spec appears in the Specs view and the panel offers the next phase. From there each phase is one click.

There is no Approve button

Starting the next phase is the approval. One click, one decision.

A separate approve task would be a second thing to click that changes nothing — and a button people learn to press without reading is worse than no gate at all.

Each phase runs in a fresh session

A phase is seeded only by the documents before it. What crosses a phase boundary is a file on disk, never a conversation.

That is what makes the process portable: a teammate pulls the folder and carries on from exactly where you left off, because there was never any context living in your chat history that they would be missing.

The last phase is yours

The engine writes documents; it does not write your code. The implement phase starts a session and does not wait on it — the agent works, the panel offers to open the conversation, and whether anybody watches is your choice. Git is the record, and a ticked checkbox in tasks.md is the definition of done.

The one hard block

An ## Open Questions section stops the pipeline. While it holds questions, the next phase will not start, and the panel says so.

Answer them in the document, or delete the section.

It is the only hard block in the whole process, and it exists because every other way of handling an unresolved question is worse: a phase that proceeds anyway invents an answer, and one that merely warns gets clicked through.

Existing specs are read, not just written

Point the extension at a repository full of specs somebody else made and it works out which style wrote each folder from the documents in it, then picks up at the right phase. There is no import task.

This falls out of one rule: a stage whose artifacts already exist is satisfied. A spec folder that already contains requirements.md starts at design without visiting requirements — whether that file arrived from an intake chat five minutes ago or from a colleague’s commit last month.

Choosing a style

A style is the process: which phases exist, what each writes, where the gates are, and the prompts behind them.

Two ship, and they are genuinely different shapes rather than the same one renamed:

	Phases	Shape
Kiro	`requirements` → `design` → `tasks` → `implement`	three documents, a gate between each; Bug fix skips design
Spec Kit	`specify` → `plan` → `tasks` → `implement`	one phase writes several documents; a flat `T001` task list

Pick the one your team already writes. If neither, start with Kiro — three documents with a gate between each is the smaller idea, and switching later costs one line of config.

You are not limited to those two. Writing your own style is a YAML file and a folder of prompts; no code changes, and your style appears in the ＋ New Spec menu beside the built-ins.

Configuration

Everything is optional. With no configuration at all, kiro runs on whichever model Copilot would have chosen.

Create .local-workflows/config.yml to change that:

# The process. 'kiro' or 'spec-kit', or a style you wrote yourself.
style: kiro

# Where spec folders live, relative to the repository.
# Ignored when a .code-workspace is open - see below.
specRoot: .local-workflows/specs

# Where work items come from. Leave it out and New Spec asks each time.
source: ado          # manual | ado | gh

# Full-test-suite verification tasks in the plan.
checkpoints: required   # required | optional | none

ai:
  # What runs the AI phases.
  uses: ai@1

  # Which agent runtime it runs them on. The vendor is named here and
  # nowhere else.
  provider: ghcp

  # 'auto' lets the provider choose, which is the right default - a
  # pinned model name goes stale, and a team with no opinion should not
  # be made to hold one.
  model: auto

  # Per-phase, keyed by phase id. Merged over the defaults above one
  # setting at a time, so naming only 'thinking' keeps the model.
  stages:
    design:
      model: claude-opus-5
      thinking: high

Every key, its default, and every error the file can raise: config.yml.