The Worked Example
One real automation walked through the first four phases — the principles, the specification, and the four questions it turns out to leave open.
Everything from here is a worked example. It shows what each phase would produce for one specific automation. The artifacts below are written as they would be generated — this is a proposed design, and none of it has been built.
2.1 The automation we are building
A pipeline that watches a set of source websites you choose, has an AI agent write a complete article from what it finds, and files that article on your WordPress site — with as little manual work as possible, and with one deliberate exception to "as little as possible."
FIGURE 5 — The same seven boxes, now filled in for this project. Nothing about the sequence changes. Only the content of each box is specific to the content pipeline.
Compare that figure with FIGURE 1. The geometry is identical, and that is the argument for the method in a single image: the process does not bend to accommodate the project.
Here is the shape of what comes out of the far end.
FIGURE 6 — What actually gets built: source sites to a draft awaiting approval. Each box is a job the system does, not a component. How each one is built is decided in section 2.5, and by the coding agent rather than by this document.
On the one deliberate exception. The brief for this pipeline asked for articles to publish "straight to WordPress." The design above files them as drafts instead, and a person approves each one before it is public. This is a change from the brief and it is the right one: it is what makes the constitution in the next section enforceable rather than decorative, and it is what lets this pipeline be defended to an editor. If you want fully autonomous publication, it is one decision to reverse — but it should be reversed knowingly, in the specification, rather than by omission.
Note — the companion document AI-Native Content Automation Pipeline describes one implementation of this same specification, built on a visual workflow platform. It is worth reading alongside this one, and the comparison is the point rather than a distraction: the same user stories, the same five principles and the same article contract produced a different build, because the technology is chosen at the plan phase and everything above that phase is unaffected by the choice. This document covers the process by which a design is arrived at; that one covers one design in depth. (Cross-reference URLs to be added once that document is published.)
2.2 /speckit.constitution — the principles, locked first
Before anything is specified, five principles are agreed. This is a conversation with you, not a technical exercise, and it takes about an hour.
These same five principles appear in the business view as FIGURE B5, written as the risks they exist to prevent rather than as rules. If you are presenting this to a risk or compliance reviewer, that is the version to show them; this is the version the tooling acts on.
What we would type:
/speckit.constitution
Create principles for an automated content pipeline that publishes to a
live company website. Cover editorial control, source attribution,
configuration explicitness, safe deployment, and credential scope.Comes back: .specify/memory/constitution.md, along with a summary of what changed and which downstream templates it affects. Abridged:
# Content Automation Pipeline Constitution
## Core Principles
### I. Human Approval Before Publication (NON-NEGOTIABLE)
No article generated by this pipeline MUST ever become publicly visible
without an identified person having read it and chosen to publish it.
Automated steps MUST terminate at a draft state. Rationale: an incorrect
or defamatory article published automatically is not recoverable by
deleting it afterwards.
### II. Every Claim Is Attributed
Every generated article MUST carry the source URLs it was derived from.
An article the pipeline cannot attribute MUST NOT be created.
### III. Configuration Is Explicit
Every setting MUST be stated explicitly, including those matching the
current default. Rationale: a default that changes in a later release of
a dependency changes behaviour silently.
### IV. Nothing Touches A Live System Until It Validates
Nothing MUST be deployed to a production system before passing its
checks, and nothing MUST be put on a schedule before one successful
manual execution has been reviewed by a person.
### V. Least-Privilege Credentials Only
The pipeline MUST authenticate with a dedicated service account holding
only the permissions it needs. Shared or administrator credentials MUST
NOT be used.
## Governance
Amendments require agreement from the client's editorial owner.
Version: 1.0.0 | Ratified: [DATE] | Last Amended: [DATE]A principle that changes nothing downstream is decoration. These five do not.
FIGURE 7 — Where each principle actually bites. Amber marks the one principle that cannot be traded away.
Why this is first. From here on, every command reads this file live, on every run — not as a copy taken once. Amend a principle and the next /speckit.plan already knows. This is why "we should have thought about that earlier" stops being a category of problem.
2.3 /speckit.specify — what it does, and why
What we would type:
/speckit.specify
An automation that watches a set of source websites we choose, drafts a
complete article from what it finds using an AI writer, and files that
article on our WordPress site for a member of the editorial team to
review and publish. It should run on a schedule without anyone starting
it, and it should not show us the same story twice.Note what is absent: no platform, no language, no model, no mention of RSS. Naming a technology here is the single most common way to get a bad specification, because it settles the how before anyone has agreed the what.
Comes back: specs/001-content-pipeline/spec.md. Abridged:
# Feature Specification: Automated Content Drafting Pipeline
## User Scenarios & Testing
### User Story 1 - Sources are watched without anyone remembering to look (P1)
As a member of the editorial team, I want new items from our chosen
sources to be found automatically, so that nothing is missed because
someone was busy.
**Independent Test**: Run the pipeline against one source with one new
item. The item is found. No other part of the pipeline is required for
this to be useful — a list of new items is already worth having.
**Acceptance Scenarios**
1. Given a source has published a new item since the last run,
when the pipeline runs, then that item is collected.
2. Given an item was already collected in an earlier run,
when the pipeline runs again, then it is not collected twice.
### User Story 2 - A finished draft, not a summary (P2)
As an editor, I want the pipeline to produce a complete article rather
than notes, so that my job is correcting rather than writing.
**Independent Test**: Given a collected item, the pipeline produces an
article with a headline, body and suggested tags. A person reads it and
judges whether it is closer to publishable than to a blank page.
**Acceptance Scenarios**
1. Given one or more collected items, when the writer runs, then it
produces a headline, a body of the agreed target length, suggested
tags, and the source URLs used.
2. Given the writer cannot attribute a claim to a source, when it
produces the article, then that claim is omitted.
### User Story 3 - It arrives where the team already works (P3)
As an editor, I want drafts to appear in WordPress rather than in an
email or a spreadsheet, so that reviewing one is the job I already know
how to do.
**Independent Test**: A generated article appears under Posts, with
status Draft, authored by the pipeline's service account.
**Acceptance Scenarios**
1. Given a finished article, when it is filed, then it appears in
WordPress with status Draft and is not publicly visible.
2. Given the filing step fails, when the run ends, then a person is
notified; the run does not fail silently.
### Edge Cases
- A source is unreachable for one run.
- A source publishes nothing between runs.
- Two sources syndicate the same story under different URLs.
- The AI writer returns a malformed or empty article.
## Requirements
### Functional Requirements
- FR-001: System MUST check every configured source on a fixed schedule
without human initiation.
- FR-002: System MUST collect items published since the previous run.
- FR-003: System MUST discard an item that was already seen in an
earlier run.
- FR-004: System MUST produce one article per run from the collected
items.
- FR-005: System MUST produce a headline, body and suggested tags as
distinct fields, not as one block of text.
- FR-006: System MUST record the source URLs each article was derived
from.
- FR-007: System MUST create the article in the content management
system in an unpublished state.
- FR-008: System MUST NOT make any article publicly visible.
- FR-009: System MUST notify a person when a run fails.
### Key Entities
- **Source**: a site being watched. Identity, address, whether it
publishes a feed.
- **Item**: one thing found at a source. Canonical URL, title, published
date, extracted text.
- **Article**: what the writer produces. Headline, body, tags, sources.
- **Seen record**: the identifiers of items collected in earlier runs.
## Success Criteria
- SC-001: A new item at a monitored source results in a reviewable draft
within one scheduled cycle of its publication.
- SC-002: Across a two-week trial, no item is presented to reviewers
twice.
- SC-003: An editor can take a generated draft to publishable in less
time than writing the same article from scratch.
- SC-004: No article becomes publicly visible without a person
publishing it. Target: 100%.
- SC-005: A failed run is noticed by a person on the day it fails.
## Assumptions
- One article per run, not one per source item.
- Reviewers already have WordPress accounts.
- Sources permit their content being read by an automated agent.Two things to notice.
Every success criterion is technology-agnostic. SC-001 says "within one scheduled cycle", not "the HTTP node returns within 200ms." You can verify SC-001 without knowing what was built. That means you can agree it before anything is built.
FR-008 is the constitution showing up as a requirement. Principle I is not repeated as prose — it becomes a numbered, testable requirement, which is what makes it enforceable further down.
2.4 /speckit.clarify — the questions this spec actually triggers
The specification above is decent and still ambiguous in four places. /speckit.clarify finds them and asks, one at a time, with a recommendation attached. Its cap is five questions.
Comes back: a ## Clarifications section appended to spec.md:
## Clarifications
### Session [DATE]
- Q: FR-007 says "unpublished state". Should articles ever be published
automatically once confidence is established?
(A) Never — always draft (B) After a trial period (C) Per-source
→ A: Never. Draft only. This is Principle I; it is not a setting.
- Q: FR-003 requires discarding items already seen. What identifies an
item uniquely?
(A) Canonical URL (B) Title (C) Feed GUID (D) Content hash
→ A: Canonical URL. Titles change after publication; feed GUIDs are
not universal across sources.
- Q: FR-004 produces one article per run. If a run collects fifteen
items across six sources, what is the article about?
(A) The single most significant item (B) A synthesis of all of
them (C) One article per item
→ A: A synthesis. The editorial value is in the connection between
stories, not in restating each one.
- Q: SC-001 references "one scheduled cycle". What is the cycle?
(A) Hourly (B) Daily (C) Weekly
→ A: Daily, at 06:00, so drafts are waiting at the start of the
working day.The first question is the important one. "Draft or live" reads like a configuration detail and is in fact the decision that determines whether this system is a tool your editors use or a system that can publish something wrong before anyone reads it. Asked here, it costs a sentence. Discovered after the build, it costs a rebuild of the final stage and an uncomfortable conversation.
Assumption — the answers above are the ones this design assumes. Each is a single change if you disagree, and each would be changed in
spec.mdrather than in the thing that was built.
These four answers are the bottom half of the decision register in FIGURE B6, alongside the four inputs from the summary. That figure is the one to read if you want the whole list of what is settled, what is proposed, and what still needs you — with the cost of disagreeing stated for each.
How is this guide?
Last updated on
Setting It Up
Installing spec-kit, choosing your coding agent, what lands on disk and who owns it — and an honest account of when the method is not worth the overhead.
The Plan and the Task List
Where the coding agent acts as architect. It proposes a technical approach, defends it in writing, and the numbered build steps fall out of it.