Your first spec

From a one-line piece of work to requirements, a design, an approved plan, and code — with a human decision between each. Longer than the other two pages, because most of the time is spent reading what was drafted for you.

This page needs a GitHub 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 is the one half of the extension that does not work without it.

What you are about to make
1. New Spec
2. Argue about the requirements
3. Design — and notice there is no Approve button
4. The plan
5. Implement
6. The one thing that will stop you
What you now have

What you are about to make

A folder of Markdown under .local-workflows/specs/, committed alongside your code. That is the whole artefact — no database, no service, no hidden state. Delete the extension and the documents are still there, still readable, still in your history.

You need no configuration to start. With no .local-workflows/config.yml at all you get the kiro style, specs under .local-workflows/specs, checkpoints on, and whichever model Copilot would have chosen. This page assumes exactly that.

1. New Spec

Open the Specs view and click ＋ New Spec. It asks at most two questions — what kind of spec, and where the work item comes from — then creates the folder.

The two kinds it offers come from the style, not from the engine:

	Phases
Feature	`requirements` → `design` → `tasks` → `implement`
Bug fix	`requirements` → `tasks` → `implement`

Pick Feature. A bug fix skips design, because a one-line fix does not need a design document and a process that demands one teaches people to write a paragraph of nothing to get past the gate.

2. Argue about the requirements

A Copilot chat opens and writes the first document with you. This 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. Nothing is pending, nothing is blocked — the pipeline picks up when the file lands.

The moment requirements.md appears, the spec shows up in the Specs view and the panel offers the next phase.

3. Design — and notice there is no Approve button

The panel offers design. Click it.

Starting the next phase is the approval. There is no separate approve step anywhere in the process, because a second thing to click that changes nothing is a button people learn to press without reading — and a run recording “approved” against an unread document is worse than recording nothing.

So what you are actually deciding, when you click design, is “requirements.md is good enough to build on”. That gate lives on the phase that depends on the document rather than on the phase that wrote it, because depending on it is when the judgement is real.

Two things about the session that runs:

It is a fresh session, seeded only by requirements.md. Not your intake chat, not the folder.
What crosses a phase boundary is a file on disk, never a conversation. That is what makes this 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 for them to be missing.

Read design.md when it lands. If it is wrong, this is the cheap moment.

4. The plan

Click tasks. It writes tasks.md: a numbered plan (1, 1.1) with a dependency graph between tasks expressed as ordered waves. Tasks in one wave may run at the same time; a wave begins only when every task in every earlier wave is finished and ticked.

The rule that decides where the boundaries fall is worth knowing before you read it, because it is not the obvious one:

Every task ends green. The repository builds and its tests pass at the end of each task, not just at the end of the plan. So an interface and its implementation are one task. A changed signature and every caller it breaks: one task. A behaviour and the test that proves it: one task. Splitting any of them would leave the tree red in between, and a plan you cannot stop half-way through is a script rather than a plan.

You will also see checkpoint tasks — a top-level task that runs the full test suite and confirms it passes. A checkpoint verifies; it does not ask. It never waits for a human, because whoever started the plan already asked for it to be carried out. Turn them off with checkpoints: none in .local-workflows/config.yml if you must.

5. Implement

This phase is different in a way that matters: the engine does not wait here, and it never finishes. There are no artifacts to satisfy it.

Each task launches a native Copilot chat from the panel’s implement lens, one at a time. The engine writes documents; it does not write your code. Git is the record, and a ticked checkbox in tasks.md is the definition of done.

There is no gate on this phase either — the plan was approved by starting its first task.

Whether anybody watches the session is your choice. The panel offers to open the conversation; the work is happening in your repository either way.

6. The one thing that will stop you

An ## Open Questions section in any document blocks the next phase. While it holds questions, the 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 is there because every alternative is worse: a phase that proceeds anyway invents an answer, and one that merely warns gets clicked through.

What you now have

Look at git status. Three Markdown files under .local-workflows/specs/<your-spec>/, and the process state alongside them. All of it reviewable in a pull request.

That is the part that compounds. The judgement about what was required, what the design should be, and how the work was cut up stops living in one person’s chat history and becomes a file the team inherits.

It reads other people’s specs too. Point the extension at a repository full of spec folders somebody else made and it works out which style wrote each one from the documents in it, then picks up at the right phase — there is no import step. A folder that already has requirements.md starts at design, whether that file arrived five minutes ago or in a colleague’s commit last month.

Where to go next:

Spec-driven development — the full config, the spec-kit style, and writing your own.
The Kiro style — every phase, what it is handed, and why.
Features — the rest of the extension.

Samples/HelloWorld/.local-workflows/specs/ has spec folders with their requirements already written — read them without running anything, or point the extension at one and it picks up at design.