What This Buys You
The argument for adopting it, written for whoever signs off rather than whoever builds — plus a one-page reference to all seven commands.
The operating-model version of this argument is in the business view — FIGURE B3 for what changes about an ordinary morning, FIGURE B4 for where the effort goes and when it crosses over. What follows is the same case made for whoever signs off.
Three moments, each of which arrives eventually.
The day somebody asks why. An editor notices that two syndicating sites both got a story through, and asks how de-duplication is supposed to work. Without the method the answer is "let me read the workflow and try to reconstruct it." With it, the answer is in research.md: de-duplicate on canonical URL, with title and feed GUID both considered and both rejected for stated reasons. The conversation takes two minutes and does not reopen a settled decision.
The day the person who built it is unavailable. The pipeline stops producing drafts on a Tuesday. The person who wrote the prompts has left. What the new engineer inherits is not a codebase to reverse-engineer, but a specification saying what it is meant to do, a plan saying why it was built this way — including what was rejected — and a task list saying what each file is for.
The day the requirements change. Not "add a source" — a real change: the team now wants one article per source rather than one synthesis. Ad-hoc, this is a re-explanation of the whole system to an agent with no memory of the original conversation. Spec-driven, it is an edit to FR-004, a regenerated plan, and a task list that tells you exactly which four nodes are affected.
What it costs to get there. An hour on the constitution, an hour or two on the specification and clarification, and the willingness to amend the specification rather than the workflow. That is the entire overhead, and it is front-loaded.
What it does not buy you. It does not make the articles good — that is the writer's prompt and your house style, and it takes a fortnight of review to tune. It does not remove the need for someone who can read the code and judge whether it is any good. It does not prevent bad decisions; it only guarantees that bad decisions are visible, attributed and dated, which turns out to be most of what you need.
The recommendation. Adopt spec-kit for this pipeline. It meets both of the tests in section 1.7 — it touches a live public website, and it will outlive whoever builds it. Do not adopt it for one-line changes to workflows that already exist; the overhead is real and applying it indiscriminately is how a good method gets a bad name.
Appendix A — The seven commands at a glance
| Command | Reads | Writes | Refuses to |
|---|---|---|---|
/speckit.constitution | your principles, in prose | .specify/memory/constitution.md | build anything |
/speckit.specify | a feature description | spec.md, checklists/requirements.md | name a technology |
/speckit.clarify (optional) | spec.md | spec.md + a Clarifications section | ask more than 5 questions |
/speckit.plan | spec.md, the constitution | plan.md, research.md, data-model.md, contracts/, quickstart.md | write tasks.md |
/speckit.tasks | plan.md, spec.md | tasks.md | accept a task with no file path |
/speckit.analyze (optional) | spec.md, plan.md, tasks.md, the constitution | nothing — a report | modify any file |
/speckit.implement | tasks.md, plan.md, contracts/ | your source code; tasks.md marked [X] | start with an incomplete checklist, without asking |
Also available, outside the core sequence: /speckit.checklist (quality checklists — "unit tests for requirements writing"), /speckit.converge (append remaining work after the fact), /speckit.taskstoissues (push the task list to GitHub issues; needs the GitHub MCP server).
Version. This document is written against spec-kit v0.15.1. Several things differ from earlier write-ups still in circulation: the install flag is --integration, not --ai; Git branching is an opt-in extension rather than core; the constitution lives at .specify/memory/constitution.md; and the active feature is tracked in .specify/feature.json rather than by the checked-out branch.
How is this guide?
Last updated on