Spec-driven development, in three sizes.

01One discipline, three sizes

The single most misunderstood thing about AFX: you don't choose between "structure" and "no structure." You choose how much — and you can change your mind later without losing anything.

All three shapes share the same bones: ### N.N task IDs, the same six-column Work Sessions log, and the same [FR-N] / [DES-*] anchor vocabulary. That's why graduation is lossless — moving up carries your tasks, checkboxes, file scopes, and history byte-for-byte.

Three shapes, one discipline. Graduate when scope grows — never rewrite. illustration

02Which one do I need?

Three questions, in order. The first "yes" is your answer.

The chooser. When in doubt: Sprint. illustration

Side by side

The one thing to remember: they share the same task IDs and history, so moving right along this table never costs you work.

Where the files land — and what they're called

This is the part that trips people up, so look closely: Dash and Sprint name the file after your feature (one file); the full spec uses four fixed names — spec.md, design.md, tasks.md, journal.md. Everything sits under the same folder.

One tree, every document type — real paths, real filenames. illustration

03Your first feature — by clicking

You don't start by memorising commands. Open the AFX panel and the moves are already on screen. This is the welcome view a fresh project greets you with — every highlighted spot is a button, not something to type.

1 2 3 4 5 6

The real welcome screen — where a new feature actually begins.

Then it's six clicks to shipped

1. Start — click Start a sprint (or the New SDD button in the Studio). Name it; the document and its journal appear.
2. Spec — the action row offers Refine. Click it, add your pushback in plain words, send. When the score looks good, click Approve.
3. Design, then Tasks — each step unlocks as you approve the one before. The buttons change to match wherever you are.
4. Code — task tiles appear. Click one and the agent builds it, with links back to the spec baked in.
5. Verify — click Verify on the tile; the evidence comes back. On the Work step, Sign Off adds your signature.

The one idea worth keeping: you approve the thinking before the agent writes the code. The buttons just make that fast.

No extension — running as skills in a terminal? The same feature, fully typed, is in the typed path.

04The journey, end to end

One feature, six stops. We'll follow room-export — "export a room's ledger as CSV" — from a sentence to shipped code, showing exactly what you type, what AFX does, and which control does it in the chat. (Sprint track; the full spec is the same journey with one file per artifact.)

05In the extension, you click — the commands come to you

Everything in the journey above can be driven without typing a single slash command. The chat watches which AFX document is active — spec, design, tasks, journal, sprint, or dash — and surfaces that document's commands as dropdowns, buttons, and suggestions. Typed commands are the headless path; in VS Code, context does the driving.

The context engine

Open or select an AFX file and the chat header picks it up: a document chip shows what's active, the doc-actions dropdown fills with the right verbs, and the stepper reflects its approval state. Switch files, and the whole surface follows.

The switcher, expanded — every entry is one of the slash commands from this guide, pre-targeted at the active document.

The dynamic strip — the row that follows you

Directly under the four pills lives the action strip. It re-resolves on every pill click and file switch — and it knows sprint from standard. Two behaviors, by design:

• Some buttons draft first. Refine, Author, Note, Capture drop their command into the composer and wait — because they're better with your context attached. Add your pushback, then send.
• Some buttons run right away. Validate, Review, Approve, Verify, Status run immediately — there's nothing to add.

The strip's header also carries the Memory menu — Session Memory (re-load the context bundle, re-orient) and Discussion actions — so continuity is one click away from wherever you are.

1 2 3 4 5 6 7

The real thing — every numbered spot is a button that runs a command for you.

Surgical commands from the previewer

The previewer doesn't just render documents — it dispatches targeted commands. Three levels of precision:

• Whole document: the header actions — Refine, Validate, Review, Approve for the doc that's open.
• One section: every Quality Pulse signal and Coach suggestion carries its own fix command, aimed at that section. "Success metrics missing → Add metrics" sends a command about that gap, not the whole file.
• One task: task rows execute individually — Code or Verify exactly 2.1, straight from the rendered checklist. Work Sessions has its own host action to approve the section.

Each dispatch chooses draft-or-send the same way the strip does — surgical and polite about your context.

Every command has a button

You never have to memorise the command line. Here's the whole map — type the left column, or click the middle one; they run the identical skill.

06The previewer — where a document comes alive

This is the surface most people fall for. It takes a plain markdown file in your repo and turns it into a working desk: it grades the document while you write, names exactly what's weak, and hands you a one-click fix — all without you typing a command. Hover the numbered spots; here's what each one is.

The same file, twice

Here's what "living document" actually means: on the left is the plain spec.md sitting in your repo — text you could write in any editor. On the right is that exact file opened in the previewer. Same bytes; one is a file, the other is a working desk.

The raw file · spec.md

--- afx: true type: SPEC status: Living owner: "@rix" version: "1.0" --- # App Workbench Canvas — Product Specification > **As-built.** Canonical canvas spec; FR/NFR/DES > anchors are stable so code @see links resolve here. ## References - **Parent spec**: App Workbench; host: Workbench Shell. - **Scope boundary**: a freeform ideation surface, not a knowledge graph (see [DES-ROLLOUT]). - **Settings owner**: 214-app-chat-settings hosts the Experimental toggle ([FR-22]). ## Problem Statement Spec-driven development has a cold-start problem: the blank spec.md front-loads…

→opened in the previewer

The previewer

Nothing proprietary on the left — delete the extension and it's still a clean markdown file. The extension just does more with it.

Now, every live part of that right-hand side

1 2 3 4 5 6 7 8 9 10

A real spec.md from the AFX repo, open in the previewer — every number is a live part of the UI.

It reads the room

The same surface adapts to whatever document you open — a design gets its [DES-…] anchors and design actions; a task list turns its rows into things you can actually run.

07The documents, annotated

Each template is plain markdown you could write by hand — and every part of it powers something in the extension. Here's the map.

spec.md — anchors the extension can hold on to

spec.md — every template part, mapped to what the extension does with it. illustration

journal.md — the part everyone underestimates

journal.md — why the living docs can stay clean: history lives here, and three surfaces feed on it. illustration

The rest of the family

• design.md — the [DES-*] anatomy is annotated in the Sprint document illustration; standard mode is the same sections promoted one heading level. Every anchor is hover-able and CodeLens-linked from code.
• tasks.md — the ### N.N / checkbox / file-scope anatomy is annotated in the Dash document illustration — identical bones, which is what makes graduation lossless. In the previewer, each task row is executable.
• Sprint & Dash — single-file anatomies with their approval and escalation rails, in their own sections below.

08Dash — structure for surgical work

A bug fix deserves better than an unrecorded chat, but not a spec. Dash is Purpose + Tasks in one file — no approvals, no status, no version. Progress is the task state.

The document

Lives at docs/specs/<name>/<name>.md with type: DASH. Two sections you write, one the workflow appends:

A Dash, 1:1 — Purpose says why, Tasks say what done means, Work Sessions says what happened. illustration

The commands

09Sprint — the whole discipline, one file

Spec, Design, and Tasks as numbered sections of a single document, each behind its own approval. This is where most features should live — and the recommended starting point.

The document

docs/specs/<feature>/<feature>.md with type: SPRINT, plus a companion journal.md. The frontmatter carries the approval state per section:

A Sprint, 1:1 — the approval block in frontmatter is the state machine; sections unlock in order. illustration

The gates — how approval actually works

Working it

The rhythm is refine → approve → next section. In chat, the Spec-mode stepper shows exactly which section is live; in the previewer, Sprint documents render with the same doc actions as full specs. When all three sections are approved, code walks the tasks with the shared implementation engine, and verify demands evidence per task.

A real Sprint in the previewer — this one you can click through in the extension today.

Graduating

/afx-sprint graduate splits the one file into spec.md / design.md / tasks.md (your journal.md already exists), promotes headings one level, and retargets every @see path. FR numbers, DES anchors, and task IDs survive verbatim — code that pointed at the sprint keeps resolving.

10The full spec — four files, formal gates

For work that outlives a sitting: cross-cutting features, multi-team coordination, security boundaries, migrations. Every document gets its own file, its own lifecycle, and its own approval.

The whole machine — approval at each boundary unlocks the next artifact. illustration

spec.md — the WHAT · /afx-spec

Requirements with stable [FR-N] / [NFR-N] anchors (sequential, no gaps) that code links back to forever. The template's sections: References · Problem Statement · User Stories · Requirements (Functional / Non-Functional) · Acceptance Criteria · Non-Goals · Open Questions · Dependencies · Appendix.

Statuses: Draft → Approved → Superseded. Editing an approved spec in a way that changes scope bumps the version and reverts to Draft — downstream demotes with it.

design.md — the HOW · /afx-design

Architecture with a [DES-ID] on every ## heading — [DES-OVR], [DES-ARCH], [DES-API], [DES-SEC], and the rest — plus at least one @see spec.md [FR-X] so the design provably serves the spec.

tasks.md — the WHEN · /afx-task

The working loop. plan (gated on approved design) generates phases of ### N.N tasks; then it's pick → code → verify → complete, task after task, phase after phase.

tasks.md in the previewer — Pick, Code, and Verify are buttons here, not commands you memorise.

11Two more you'll create along the way

Specs, designs, and tasks are the spine. Two supporting documents show up as real work happens — a decision worth remembering, or a question worth investigating first.

12The assisted loop — the extension does the typing

This is why the extension exists: the ceremony is real, the typing isn't. After every action, the next sensible steps appear as clickable suggestions — you steer, AFX writes the commands.

The loop. Six places feed it suggestions — all pre-targeted at your active document. illustration

The guide that walks with you

Generated documents come with a phase-aware timeline in chat: where the feature stands, what's next, and one-click jumps to the previewer or the Studio.

The SDD guide in chat — next actions as buttons, not homework.

Next actions, ranked and clickable

/afx-next output renders as buttons in the extension — the ranked list you saw earlier becomes one-click continuations.

Real capture — the golden thread, clickable.

The cockpit view

SDD Studio shows every feature's documents in columns, with inline actions that hand off to chat with context attached — Refine spec and Code all are clicks here too.

SDD Studio — Overview, Focus, and Compare modes over the same four columns.

Tasks as tiles

When implementation starts, tasks surface as tiles — one click runs the coding engine for exactly that task.

One tile, one task, one click.

13Staying oriented

SDD's superpower isn't the documents — it's that any session, any agent, any day can pick up exactly where the last one stopped.

• /afx-next — the golden thread. Reads git state, active tasks, and session history; answers "what do I do now?" with a ranked list.
• /afx-session note / capture — capture decisions as they happen; capture stores the verbatim prompt that changed a spec, so future sessions know why.
• /afx-context save / load — bundle spec state, task progress, and open questions for a clean handoff to the next agent (or the next you).

/afx-next, 1:1 — the same ranked output in every agent; UI hosts make the list clickable. illustration

14Use cases — pick your situation

Real situations, start to finish. Copy the sequence, change the names.

15No extension? The typed path

Running AFX as skills only — in Claude Code, Codex, or Copilot? Everything in this guide works by typing. Same skills, same gates, same files; you supply the keystrokes the extension would have saved you.

Sprint, typed

The full four files, typed

—Cheat sheet

Everything above, one screen. For the terminal-first among us.

Dash

Sprint

Full spec

States

Always available