Nothing in "build a waitlist with referrals" stops a mail scanner from confirming every signup on your list.
Spec-driven development means the decisions, the constraints and the acceptance checks for a feature are written before an agent writes code, and the document is kept after the chat ends. The five-word prompt "build a waitlist with referrals" names a feature and stops there. This page puts that prompt next to juno/waitlist version 0.1.2, and marks each decision the prompt left to the model. By the end you should be able to say what the practice is, when it is worth it, and how to pull a spec that already exists.
The Prompt Gap
PROMPT
build a waitlist with referrals
26 decisions this prompt leaves to the model
An agent given only the five words matched the spec on 5 of 26. It asked no questions.
A fresh Cursor cloud agent, in an empty repo, on 18 November 2026. It ran about an hour. The code was checked against each row.
R1. Join (8)
duplicate emails: allowed?
No — addresses are trimmed and lowercased first.
AgentSame
a plus-tag: a new person?
No — a plus-tag is ignored. sam+a@example.com is sam@example.com.
AgentNot handled
dots in Gmail: a new person?
No — Gmail dots are ignored. s.a.m@gmail.com is sam@gmail.com.
AgentNot handled
mail goes where they typed?
Yes — mail goes to the address they gave, trimmed and in lowercase, not to the key.
AgentNot handled
can someone test who is on the list?
No — the answer is the same whether the address is new or already on the list.
AgentDifferent: says already listed
lost the link: a way back?
Yes — a person already on the list is sent their status link again.
AgentDifferent: shows place and link
bots: stopped?
Yes — a hidden field; a request that fills it in looks like success, and nothing is stored.
AgentNot handled
joins from one address: how many?
Five times an hour from one IP address.
AgentNot handled
R2. Confirm (5)
joining: confirmed?
Yes — joining sends a link that confirms the address.
AgentNot handled
a confirm link: how long?
48 hours.
AgentNot handled
unconfirmed: a place in line?
No — only confirmed entries have a place in line, count as referrals, or can be invited.
AgentNot handled
a mail scanner opens it: confirmed?
No — the link shows a page with one button. Opening the link confirms nothing.
AgentNot handled
never confirmed: kept?
No — an entry not confirmed in 48 hours is deleted.
AgentNot handled
R3. Referrals (7)
the share code: guessable?
It's a code of 8 letters and digits.
AgentDifferent: 6 lowercase letters
a join through the link: one referral?
Yes — it counts as one referral for the link's owner, after they confirm.
AgentSame
refer your own address: allowed?
No — referring an address that is the same as yours (by the rule in R1) does not count.
AgentDifferent: exact email only
the same network: a referral?
No — joining from the same IP as the referrer does not count.
AgentNot handled
referrals from one address: how many?
Five referred entries from one IP in a day. More than that do not count.
AgentNot handled
a referral that does not count: still joined?
Yes — it is still a normal entry.
AgentSame
which referrals counted: told?
No — nobody is told which referrals counted.
AgentDifferent: a public feed names them
R4. The line (3)
joined first: ahead?
No — the score starts from time of confirming, and the line is ordered by score, lowest first.
AgentDifferent: ordered by join time
places per referral: how many?
referral_boost places for each referral that counts.
AgentSame
a tie: who is ahead?
Whoever confirmed first.
AgentDifferent: earlier join wins
R5. Status page (3)
a guessed status link: does it work?
No — the link carries a signed token, so guessing doesn't work.
AgentDifferent: looked up by share code
their place: shown?
When Show a person their place is on, the page shows their place and how many are ahead.
AgentSame
leaving the list: how?
'Take me off the list,' after one confirmation.
AgentNot handled
R1. Join
- A person gives an email address. It is trimmed and lowercased.
- For telling whether someone already joined, a tag after a plus sign is ignored, and for Gmail addresses so are full stops:
sam+a@example.comissam@example.com, ands.a.m@gmail.comissam@gmail.com. Email is still sent to the address they gave, trimmed and in lowercase, not to the key. - The answer is the same whether the address is new or already on the list. A person already on it is sent their status link again.
- The form has a field people cannot see. A request that fills it in is answered as if it worked and nothing is stored.
- One IP address can join 5 times an hour.
Accept when: Sam+x@Example.com and sam@example.com are one entry, the answer to both requests is the same, and the sixth join from an address in an hour is refused.
R2. Confirm
- Joining sends a link that confirms the address. It works for 48 hours.
- Only confirmed entries have a place in line, count as referrals, or can be invited.
- The link shows a page with one button, and the button confirms. A mail scanner that opens the link confirms nothing.
Accept when: fetching the link with GET alone confirms nothing, pressing the button does, and an entry not confirmed in 48 hours is deleted.
R3. Referrals
Only if referrals is on.
- Each confirmed entry has a link to share, with a code of 8 letters and digits.
- A person who joins through the link and then confirms counts as one referral for its owner.
- These do not count: a person referring an address that is the same as theirs by the rule in R1; a referred entry that joined from the same IP address as its referrer; and more than 5 referred entries from one IP address in a day, whoever referred them.
- A referral that does not count is still a normal entry. Nobody is told which referrals counted.
Accept when: each of the three rules has a test, and a referral counts only after the referred person confirms.
Not built when Referrals is off
R4. The line
- A person's score is their place by time of confirming, minus
referral_boostfor each referral that counts. - The line is ordered by score, lowest first. Equal scores go by who confirmed first.
- A person's place is their position in that order, starting at 1.
Accept when: the table in design.md is reproduced exactly.
R5. Status page
- Every email holds a link to the person's own status page. The link carries a signed token, so nobody can read another person's page by guessing.
- The page shows, if
show_positionis on, the person's place and how many are ahead(Not shown when Show a person their place is off); and ifreferralsis on, their link to share and how many referrals have counted(Not built when Referrals is off). - "Take me off the list" deletes the entry after one confirmation.
Accept when: a changed token is refused, and after "Take me off the list" the address is in no table.
Try the dedupe rule
R1's key is the address trimmed and lowercased, with a tag after a plus sign removed, and with full stops removed for Gmail. The published design says googlemail.com counts as Gmail. Nothing you type is sent or stored.
What spec-driven development is
A spec, in this sense, is a decision you can check. It says what the feature does, what it refuses, and the sentence that tells you the build is done. The agent writes the code. The spec is what you argue with, and what the next person reads when the chat is gone.
The five-word prompt feels finished because a waitlist with referrals is a familiar thing. The familiar thing is where the unstated rules hide: which addresses are the same person, what a mail program does when it opens a link, whether someone can refer themselves. The spec writes those down. The prompt does not.
IBM's What is Spec-Driven Development? describes three levels. Spec-first: the spec is written before the code, and it may not be maintained. Spec-anchored: the spec evolves alongside the software, and tests in CI keep them in sync. Spec-as-source: a change to the spec triggers the code change, and people do not edit the code directly.
Diving Into Spec-Driven Development With GitHub Spec Kit (Den Delimarsky, Microsoft for Developers, 15 September 2025) frames spec-driven development as making technical decisions explicit, reviewable and evolvable.
Spec-driven development isn't writing docs before code. It's taking back the decisions a prompt quietly hands to the model, and because most features work the same everywhere, most of those decisions are already written down.
An agent that can open a page can fetch the spec and build from it. The line that starts "Accept when" is the check: a condition, not a feeling. A later model that guesses better still was not there when the number of places, or the life of a confirm link, was chosen. Those choices stay in the spec, at one address, whether or not the chat was saved.
Anatomy of a spec
juno/waitlist is a manifest plus the three files that manifest lists. Nothing below is a blank template. The lines are from the published spec at version 0.1.2.
spekkr.json
The manifest names the spec and what a person may change. The published one says the id is juno/waitlist and the version is 0.1.2. It lists three files, in its own words: spec.md, "Requirements and acceptance criteria."; design.md, "Data model, rules and flows."; tasks.md, "Build tasks in order, each with a check."
The choices on this page are the ones that manifest publishes. Referrals is an option, on by default. Show a person their place is an option, on by default. Database is a swap, postgres or sqlite, default postgres. It also publishes two settings this page does not switch: the app name, default Acme, and places gained per referral, default 3.
spec.md
Requirements, each with an id. R1 to R5 are above, in the published wording. The line that turns a requirement into a check is "Accept when". R1 ends with this one:
Accept when:
Sam+x@Example.comandsam@example.comare one entry, the answer to both requests is the same, and the sixth join from an address in an hour is refused.
design.md
The published design says it fixes the parts that are easy to get wrong. It gives the score as this line:
score = confirm_order - boost * (number of entries that count as its referrals)
It also says, under "Named here":
googlemail.comcounts as Gmail.
And it shows the tie the ordering rule is about: cho and fay both score 3. cho confirmed first, so cho is ahead.
tasks.md
The build, in order, each step with a check. This page does not reprint that file. The listing describes it as "Build tasks in order, each with a check."
The spec is listed as an app part.
When not to bother
The case against, stated as fairly as it can be: for small changes the overhead isn't worth it, it can feel like waterfall written in Markdown, and models keep getting better at guessing.
That holds for a one-line fix, a sentence of copy, a colour. Writing a spec for it costs more than the change. A model that has seen a great many waitlists will often guess a reasonable one. The guess is only a problem when the reasonable one is not yours.
Write a spec when there's an abuse case, a money path, or a second person who will touch it.
A better model still can't guess your choices, such as 3 places per referral or a 48-hour confirm link.
Three places per referral is this spec's default for referral_boost, and the confirm link works for 48 hours. Either number could have been a different one. A second person, or you in a month, cannot recover it from a chat that was not saved. A money path has the same shape: who is charged, and when, is a choice. An abuse case is the mail scanner, the plus-address, the shared network. The prompt does not mention them, because the person who typed it was thinking about the feature, not about the way it gets cheated.
The in-repo tools
Three tools keep a spec in the repository with the code. They are named here so the shape is visible. This is not a ranking, and it is not a bake-off.
Spec Kit is GitHub's toolkit. It keeps a spec, a plan and tasks in the repo and walks an agent from those files into an implementation. Its documentation and its repository are the places to read it.
Kiro writes requirements, a design and tasks into the project, under a .kiro/specs folder, and implements from those files.
OpenSpec keeps the spec in the repo as well. A change holds a proposal, the spec edits, a design and tasks. An agent applies the change and archives it back into the spec. The repository holds the same project.
A hosted spec is a different arrangement: one address, the choices on the page, any agent that can fetch. How that compares with Spec Kit is the third part of this series.
Don't write the waitlist twice
The same waitlist should not be specified once in a chat, again in a repo, and again for the next agent. juno/waitlist is already written. It has a stable address, and the choices are part of the spec rather than part of the prompt.
Referrals starts on. Turn it off and requirement R3, above, dims, and so does the half of the status page that shows a link to share and how many referrals counted. The dimmed part says it is not built, and the lines stay on the page. Show a person their place starts on. Turn it off and the half of the status page that shows a place, and how many people are ahead, dims. Database starts at postgres. Choosing sqlite changes the pull call at the end of this page, and nothing else.
An agent fetches the call below from the MCP address. Search, get and pull need no sign-in. The spec it receives is the one this page shows, with those choices filled in.
It isn't only for software
It isn't only for software. nova/falling-sand is a published spec whose listing says: "A cellular workshop where sand, water, fire, plant and fuse interact, and a known scene hashes after N ticks."
Pull it
Connect https://spekkr.com/mcp in your agent. Search, get and pull need no account. Questions: support@spekkr.com.
pull_spec {"id": "juno/waitlist", "choices": {"referrals": true, "show_position": true, "database": "postgres"}}
The call uses the choices currently set above. Paste it to an agent that has the address connected. Publishing a spec of your own is a different step, and it needs sign-in: how to publish.
FAQ
What is spec-driven development?
Writing the decisions, constraints and acceptance checks for a feature before an agent builds it, and keeping that document as the source of truth.
Do I need Spec Kit to do it?
No. Spec Kit is one in-repo process. A spec can also be a hosted document an agent fetches.
Do I need an account to pull a Spekkr spec?
No. Search, get and pull need no sign-in. Publishing needs sign-in with an emailed code.
Is a spec worth it for a one-line fix?
Usually not. Use the rule of thumb above.