Working with Specs
How the Spec Agent interviews you, tracks gaps and decisions, scores readiness, and produces a builder-ready specification.
The Spec Agent is a conversation, not a form. You describe the app you want; it drafts an initial specification and then interviews you to fill it out until it's complete enough to build.
Describe, then iterate#
Start with a short description — one or two sentences is enough. The agent produces a first draft: functional requirements (FRs), non-functional requirements (NFRs), acceptance criteria (ACs), and a capability graph that maps how the pieces fit together. It then asks targeted questions to close what's missing.
Ask for changes the way you'd tell a colleague — "split requirement 3 into sub-requirements," "add an audit trail," "the warehouse is Databricks Unity Catalog." The agent applies each change to the spec in place, and you can revise as many times as you need.
Every functional requirement carries a testable acceptance criterion, so the Build Agent — and the live compliance matrix — can verify it objectively. A single requirement looks like this:
{
"id": "FR-3",
"title": "Export the current report as a PDF",
"acceptance_criteria": [
"A user can download the current report as a PDF in under 5 seconds",
"The PDF preserves table formatting and the company header"
],
"capability_nodes": ["report-export-service"]
}The capability_nodes a requirement lists are nodes in the capability
graph — the structured map of components (and their dependencies) the Build
Agent implements. FR-3's node, with its data dependency, looks like:
{
"nodes": [
{
"id": "report-export-service",
"kind": "service",
"implements": ["FR-3"],
"reads": ["report-store"]
}
],
"edges": [
{ "from": "report-export-service", "to": "report-store", "relation": "reads" }
]
}Gaps and decision points#
As it works, the agent surfaces two kinds of open items. The distinction matters because only one of them blocks you from locking the spec:
A critical gap is a genuine decision with no reasonable default — the agent can't finish the requirement without your answer (for example, "which transactions count toward the fraud threshold?"). A spec can't be routed for signature until every critical gap is resolved.
A config gap is a build- or deploy-time detail with a sensible default — an auth mode, a library choice, a tenant setting. The agent records the default, flags it "confirm at build," and keeps going. Config gaps never hold up the lock.
A decision point is a fork where you choose between options the agent lays out — for instance, which identity provider to use. Answer gaps and decision points in the chat; the agent writes your answer into the right part of the spec and resolves the item.
Grounding in your own documents#
Attach files to the spec's knowledge base and the agent reads them, cites them by name, and turns the relevant details into real requirements — so the spec reflects your data and your policies, not a generic template.
PDF, Word, Excel, CSV, JSON, Markdown, and plain text. You can also attach a Git repository as reference material — the agent reverse-engineers its structure and drafts requirements from the code.
The spec lifecycle#
A spec moves from a rough draft to a locked, buildable artifact by looping through the interview until readiness reports it complete:
The readiness view is live: which requirements are specified, which acceptance criteria are measurable, and whether any critical gaps remain. When it reports the spec complete, you Route for E-Signature to lock it. A locked, approved spec is what the Build Agent builds from.