Spec-driven delivery
In spec-driven delivery the behaviour of your product is written down before anyone builds it — not as prose, but as structured, versioned specs that a gate can check. Agents then build small slices that each prove named parts of a spec, and a change merges when every check is green. You stay in the loop where only a person can decide: before the work, not after it.
This page explains the idea from the owner’s point of view and says plainly which parts SupaCloud provides today. To set a project up, follow Run a spec-driven project.
Why decide before, rather than approve after
Section titled “Why decide before, rather than approve after”When the only definition of a feature is one sentence in an issue, an agent working alone has two choices: build a correct shell without the behaviour, or invent the behaviour. Asking you to approve every result afterwards does not fix that — approvals grow with every pull request, and a check that fires on every second change gets waved through rather than read.
Spec-driven delivery moves your judgement to the front. You answer the design questions once, in a batch, with a recommendation in front of you. From then on the spec, not the agent, defines what “correct” means, and the gates hold every change to it.
The layers
Section titled “The layers”| Layer | What it holds | Who changes it |
|---|---|---|
| Requirements | what the product must offer | you, rarely |
| Domain spec | how one area behaves: rules, parameters with approved ranges, examples, decisions, open questions | a pull request; you approve the design decisions |
| Work item | the next slice to build, naming the rules it proves | derived from an approved spec |
| Agent run | the implementation | SupaCloud |
| Evidence | proof that the change does what its rules require | the run |
| Merge | the change on your main branch | only when every check is green |
A lower layer never quietly changes a higher one. When an agent finds a gap in a spec, it asks — the gap becomes a question, and your answer becomes a recorded decision — instead of an assumption hidden in code.
The spec format knows nothing about any one product. One small file in your repository — the project profile — tells it where your requirements live, what your requirement IDs look like and which units your numbers use, so the format itself never has to be edited to fit your project. There is no fallback: without that file the checks fail and say so, rather than quietly assuming someone else’s conventions.
The decisions that stay yours
Section titled “The decisions that stay yours”Only five kinds of change need you. Everything outside the gate classes merges on green, after the automated reviews its risk class requires — you do not review every pull request.
| Class | You decide when | Examples |
|---|---|---|
| G1 Product and domain design | a spec is approved, or an approved range of a parameter changes | a pricing rule, a game mechanic, a budget corridor |
| G2 Architecture and contracts | a new architecture decision, or a breaking contract change | an API version, a data format |
| G3 First sight | the style foundation, and every new screen, flow or asset | a new settings page, a new logo — changes to screens you already approved are judged by machine against the approved version |
| G4 Sensitive content | curated content on sensitive topics | a narrative on mental health |
| G5 Release and legal | signing, store submission, licences, personal data, AI-provider obligations | a release, a data-processing change |
You also decide every change to the gate map itself — the file that says which paths fall into which class — so nothing can leave a class without you.
Security-review classes are meant to be cleared without you: a new dependency (a version bump passes), CI workflows, security tooling, secrets, and authentication or trust-boundary code go to an automated security reviewer from a different model vendor than the one that wrote the change. Its approving review of the exact commit clears the class; if it asks for changes instead, the whole pull request escalates to you and only you can clear it. This reviewer is planned; until it exists, those changes need you too.
These gates must hold however autonomously the project runs. At the top autonomy level SupaCloud’s merge ceiling is Full auto-merge, so the gates live in your repository: a required check that only the class’s approver turns green, for exactly the commit they saw — a new push is checked again. SupaCloud may narrow what that check allows, never widen it.
In the reference implementation this check exists and is required on its main branch today. Three details are worth knowing before you rely on it:
- You cannot approve your own pull request — Forgejo refuses that. So the check also accepts a
comment from you that names the commit (
/approve-gates <sha>) as your approval. It is a way around a forge rule, not an extra privilege. - An edited comment counts for nothing. Anyone with write access can edit anyone’s comment, so an edited body cannot be proven to be yours. Post a new comment instead.
- An instance admin can still force-merge past branch protection. That is your escape hatch; it is also the reason to keep admin credentials away from agents.
How decisions reach you
Section titled “How decisions reach you”Decision briefs (planned). Design decisions arrive as one brief per domain: each item with its options, a recommended option, the reasoning and drafts that make the choice concrete — tables, diagrams, before-and-after screenshots, prototypes. You answer on one page, on any device, and leave and return as you like.
The recommendation is pre-selected to save you typing, but a pre-selected answer is not an
answer until you confirm it — per item, or with Accept all open recommendations. An item you
never looked at stays open, however sensible its default. A brief cannot be handed over while a
blocking item is open, and your answers go into the spec’s decisions.yaml through a pull
request, where they stay on record with who answered, when and where.
Questions during the work (available). When an agent hits a genuine gap, it asks with
question.ask and you answer in the inbox or on the Telegram or Discord card — see
Let an agent ask a question. Parking the item while
it waits, resuming it with your answer, and writing the answer back into the spec as a decision
are planned.
What happens without you
Section titled “What happens without you”- Review depth follows the risk class. A project’s merge ladder sets it per work item: the lowest class merges once every check is green; the next adds one independent review agent; the next needs two independent reviews from different model vendors, or a person; the top class is led by a person. “Independent” means a different vendor from the one that wrote the code, because a judge tends to prefer output from its own model family.
- The spec is the test oracle. A spec’s examples come with concrete values, and the tests are generated from them. The agent that implements a rule does not also decide what proves it.
- Models are chosen by measurement. Specs and work items name a capability tier — flagship, balanced, fast, independent review — never a model. SupaCloud’s calibrator decides which model stands behind each tier from measured results.
- Readiness is a fact, not a guess. A work item is ready when the work it depends on is done,
the decisions it needs are approved and its spec is approved. That fact is published on your
issue tracker as labels —
ready,blocked,spec-ready— and SupaCloud dispatches thespec-readyitems. Exactly one system writes those labels: SupaCloud, through the forge connection your project already has. You need no bot account and no secret in your CI.
What SupaCloud does today
Section titled “What SupaCloud does today”Checked against the code on main on 2026-09-22. Planned links the design in the build brief
issue #1448.
| Part of the loop | Status | Today |
|---|---|---|
| Agents ask real questions; you or the coordinator answer | Available | question.ask with up to eight choices, answered in the inbox or on a chat card; see Let an agent ask a question |
| A waiting question parks the item and frees its slot; the answer resumes it and is written back as a decision | Planned (SC-10) | a waiting question keeps its slot and has no deadline; the answer is not written to the repository |
| Decision briefs | Planned (SC-29) | none; answer design decisions outside SupaCloud and record them in decisions.yaml by pull request |
Dispatch only spec-ready issues |
Planned (SC-2) | SupaCloud does not read labels; its classifier decides which open issue is ready |
| Readiness computed from your specs and written as labels | Planned (SC-2, SC-20) | run the reference sync from an owner session (see the how-to) |
| Merge only when your CI’s required checks are green | Planned (SC-1) | a merge follows SupaCloud’s own gates — the independent audit and, for web changes, the visual check; your repository’s checks are not read |
| Two independent reviews from different vendors | Planned (SC-4) | one review slot; a council can add a recommendation, not a gate |
| An automated security reviewer clears the security-review classes | Planned (SC-4, SC-3) | none; changes of those classes need a person |
| Work routed by capability tier | Planned (SC-3) | the calibrator maintains tier chains; an agent profile pins a model, learns one from history, or leaves it to the runner |
| Specs validated, traced and shown in the web UI | Planned (SC-20) | none; validation runs in your repository’s CI |
| Visual sign-off only for new screens, and outside web code | Planned (SC-9) | the visual gate (off, machine, human, both) triggers on web changes; see Configure visual-verify gates |