spec-driven-dev

Stars2

Forks0

UpdatedMay 13, 2026 at 18:44

Workflow for executing against a written specification — read the spec, ask clarifying questions ONLY for real ambiguity, implement, test, ship. Honors "Done when" criteria, scope boundaries, and constraint adherence. Use this skill whenever a worker is dispatched with a defined GOAL, DELIVERABLE, DONE WHEN, and CONSTRAINTS — i.e. anything spawned through subctl team templates or orchestrator-mode dispatch. Also use when reading an ADR / roadmap / RESUME.md and converting it to executable work. The skill enforces: spec is the contract, not a suggestion. Don't gold-plate. Don't ask permission for things the spec already decided. Don't leave the spec half-done.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

webdevtodayjason

webdevtodayjason/subctl

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Project Management SpecialistsBusiness and Financial Operations Occupations·SOC 13-1082

SKILL.md

readonly

More from this repository

same repository

subctl-evy

webdevtodayjason/subctl

Evy — the subctl orchestrator persona. Loaded by the Evy daemon at boot; not used by workers. Canonical spec at docs/persona/evy.md.

2026-05-242

subctl

webdevtodayjason/subctl

Subscription Central — multi-account AI subscription orchestration toolkit. Activate this skill whenever you need to: spawn or control tmux orchestrator sessions, send Telegram messages or ask the operator a question, look up cross-account session state, or read/write the rate-limit radar. Trigger phrases: "spawn an orchestrator", "send a message to the operator", "ask the user a yes/no", "what's running across all my accounts", "kill that tmux session", "what's my rate-limit status", "stats from the dashboard", "let the user know we're stuck", "fire and forget on this question". Trigger conditions: any time you would otherwise shell out to tmux for session control, OR call Telegram's API directly, OR re-read transcripts to figure out what's running on another account. subctl is the canonical surface for all of these.

2026-05-162

autonomy

webdevtodayjason/subctl

Autonomy doctrine for orchestrators and workers. When CLAUDE_AUTONOMY=full is set OR the user invokes "autonomous mode" / "12-hour mode" / "no babysit" / "fire and forget", THIS SKILL OVERRIDES "wait for approval", "ask the user", "confirm before proceeding" instructions in other skills (orchestrator-mode, tdd, team, find-skills). The orchestrator drives forward without per-step approval. Activate proactively whenever an orchestrator session is running with the user away (no message in last 5+ minutes) and there is non-trivial backlog.

2026-05-132

handoff-protocol

webdevtodayjason/subctl

How to hand off a task mid-flight — context summary, what's done, what's pending, where to find work-in-progress, and when to escalate instead. Use this skill when a worker needs to pass an unfinished task to a peer or back to the team lead — auto-compact pressure, scope shift, blocker outside the worker's tool set, end-of-shift, or running into the spawn-time context budget. Also load it when receiving a handoff so you know what shape to expect.

2026-05-132

node-conventions

webdevtodayjason/subctl

Node.js / Bun / TypeScript house style for subctl projects — runtime choice, imports, naming, errors, async patterns, testing. Load this skill whenever a worker is touching `.ts`, `.tsx`, `.js`, or `.mjs` files in a subctl-managed project. Use it instead of guessing the conventions from the surrounding code (the surrounding code may itself be drift). Defaults documented here are the operator's preferences as expressed across the v2.7.x release wave.

2026-05-132

orchestrator-mode

webdevtodayjason/subctl

Switch Claude Code into a multi-pane orchestrator + team-agent workflow. Use this skill whenever the user says "orchestrator mode", "team mode", "/team", "/orchestrator-mode", or otherwise asks Claude to coordinate multiple parallel workers in iTerm2 panes instead of writing code directly. Also trigger if the user describes a task that clearly benefits from parallel decomposition across multiple worker panes (e.g. "split this into N parallel agents", "I want to see each agent in its own pane", "use team agents"). After activation, Claude acts purely as coordinator: planning work, dispatching workers via TeamCreate + Agent (with team_name), verifying outputs, and maintaining an ORCHESTRATION.md task ledger. Workers run in their own iTerm2 panes on the right side of the window while the orchestrator pane stays on the left.

2026-05-132

name	spec-driven-dev
description	Workflow for executing against a written specification — read the spec, ask clarifying questions ONLY for real ambiguity, implement, test, ship. Honors "Done when" criteria, scope boundaries, and constraint adherence. Use this skill whenever a worker is dispatched with a defined GOAL, DELIVERABLE, DONE WHEN, and CONSTRAINTS — i.e. anything spawned through subctl team templates or orchestrator-mode dispatch. Also use when reading an ADR / roadmap / RESUME.md and converting it to executable work. The skill enforces: spec is the contract, not a suggestion. Don't gold-plate. Don't ask permission for things the spec already decided. Don't leave the spec half-done.
scope	dev-team
loaded_by_default	[]
created_at	2026-05-10
created_by	operator

Spec-Driven Development

A worker dispatched by a team lead receives a spec, not an open-ended ask. The spec — whether it's the original Agent prompt, a planning doc, an ADR, or a RESUME.md handoff — is the contract. This skill codifies how to execute against one without drifting.

The v2.7.x release wave on 2026-05-13 was built this way: each PR shipped from a spec that named GOAL, files to touch, files NOT to touch, DONE-WHEN criteria, and a constraint list. The pattern works at production scale; this skill captures it.

1. The spec contract

Every spec a worker receives MUST resolve to these six fields. If any are missing, surface the gap to the lead BEFORE writing code:

Field	Question it answers
GOAL	What's the one-sentence outcome?
CONTEXT	What prior decisions or files do I need to know about?
DELIVERABLE	What artifacts come out (files, diffs, branch, SHA)?
DONE WHEN	What specific check tells me to stop?
REPORT BACK	What do I `SendMessage` to the lead when finished?
CONSTRAINTS	What am I forbidden to touch (other workers' scopes)?

A spec without DONE WHEN is the most common failure mode — it leads to gold-plating ("I added one more feature while I was in there") and merge conflicts. If the spec is missing DONE WHEN, ask one question:

"What's the verifiable criterion that tells me this task is finished?"

Get the answer, then start.

2. The workflow — five steps

Step 1. Read the spec twice

First read: skim for shape. Second read: extract the contract fields above and write them down in a scratch note (./SPEC.md at the repo root if the task is large; an internal note otherwise). Re-reading is cheap; restarting from a misread is expensive.

If the spec references files, read those files before doing anything else. Especially ADRs, prior CHANGELOG entries, and the docs/master.md section the spec lives under. The spec is the tip; the supporting docs are the rest of the iceberg.

Step 2. Ask clarifying questions — only for real ambiguity

Ask ONE clarifying question only if both are true:

The spec is genuinely ambiguous (two reasonable interpretations would lead to different code), AND
The wrong interpretation cannot be cheaply reverted.

Do NOT ask:

"Should I add tests?" — yes, always, unless the spec says otherwise
"Should I update the CHANGELOG?" — yes, if the spec mentions VERSION
"Should I use library X or Y?" — pick the one already imported in the file; if neither, pick the one the ecosystem conventions skill prefers
"Is it OK if I touch file Z?" — only if Z is on the CONSTRAINTS list, in which case the answer is no

Five clarifying questions before writing code = you didn't read the spec twice. Go back to step 1.

Step 3. Implement

The implementation order that minimizes rework:

Smallest verifiable slice first. Write the type signatures or stub functions. Run the type checker. Confirm the shape is right.
Tests for the contract. What does DONE WHEN actually mean in code? Write the test that asserts it.
Fill in the bodies. Tests pass.
Polish. Error messages, doc comments, edge cases not in the test.

Touch only files the spec mentions or files those files naturally drag in (import targets, sibling tests). Anything else is gold-plating.

Step 4. Verify against DONE WHEN

Run the verification check the spec named. Examples from real v2.7.x PRs:

"Tests pass: bun test components/master/__tests__/foo.test.ts"
"Endpoint responds: curl localhost:3737/api/foo returns {ok: true}"
"Dashboard pill renders: open localhost:3737, check Profile tab"
"No regressions: bun test whole suite green"

Do NOT mark done if any of these are red. Loop back to step 3.

Step 5. Report back

Send one SendMessage to the lead with:

Branch name + SHA
Files touched (list, not diff — lead pulls diff themselves)
DONE WHEN verification evidence (test output, curl response, screenshot path)
Anything the lead should know about (deviations from spec, decisions made, follow-up TODOs)

Then enter idle state. Do not start the next task without an assignment.

3. Scope boundaries

The CONSTRAINTS list in the spec names files the worker may NOT touch. Reasons it exists:

A sibling worker is editing them in parallel — conflicts on merge
They're owned by a different roadmap phase
They contain secrets / generated code / vendored deps

If you find yourself wanting to edit a constrained file:

STOP. Do not edit it "just a little."
Ask the lead: is the constraint a hard wall, or can it be relaxed?
If hard wall: re-design your change to live within your scope.
If relaxed: get explicit confirmation in writing before editing.

The cost of asking is one message. The cost of an out-of-scope edit is a merge conflict, a reverted PR, and your work potentially landing under a sibling worker's commit.

4. Anti-patterns — the spec-violation hall of fame

"While I was in there..."

You opened a file to fix one thing, noticed unrelated lint issues, and fixed those too. NO. The lead's verification pass now has to diff your noise from your signal. Open a follow-up issue; don't bundle.

"I refactored the helper since it was ugly"

The spec said "add field X to function foo." It didn't say "redesign the module." Even if your redesign is better, it's not what you were dispatched to do. Surface the refactor as a follow-up; do not ship it in this PR.

"The spec didn't say not to..."

If a spec has CONSTRAINTS, treat unmentioned-but-related files as implicitly constrained. The lead can't enumerate every file; they listed the ones they thought you'd touch. If in doubt, ask.

"I added a flag in case we need it later"

Don't. Speculative flexibility creates dead code that confuses the next reader. Add the flag when the use case lands.

"Skipped tests to ship faster"

The spec's DONE WHEN included tests. You didn't ship; you bypassed verification.

"Added a TODO for a thing the spec required"

If the spec named it, you ship it. TODOs are for follow-ups, not core scope.

5. Exemplars — the v2.7.X PR pattern

Tonight's release wave (v2.7.18 through v2.7.31) is the canonical reference. Each PR followed the same shape:

Spec source: an ADR or roadmap line + a SendMessage brief from the team lead naming exact files
Branch: v2.7.<N>-<scope>, branched from origin/main
VERSION + CHANGELOG: bumped in the same commit that lands the feature
Docs: the relevant docs/master.md section updated in the same PR
Tests: new test file under components/<scope>/__tests__/
REPORT BACK: one message to team-lead with branch, SHA, files touched, test output, deviations

Pattern recognition over invention: if you're not sure how to structure your deliverable, find the closest v2.7.X PR and mirror it.

6. Spec-driven for unfamiliar specs

Sometimes the spec is an ADR you didn't write or a roadmap entry from before your spawn. Two extra steps:

Find the predecessor. What was the last shipped feature in this area? Read its CHANGELOG entry, its files, its tests. The patterns there are the patterns the operator expects.
Check for canonical refs. ADRs in docs/adr/ are load-bearing decisions; the spec inherits their constraints whether they're cited explicitly or not.

7. Related skills

subctl-team-protocol — how the spec arrived (dispatch + REPORT BACK mechanics)
handoff-protocol — if you can't finish the spec, how to pass it on
node-conventions / python-conventions / rust-conventions — the ecosystem-specific defaults the spec doesn't have to spell out