Spec Workflow

When AI writes code from a vague prompt, the decisions are in nobody's head. The code is an artifact of a conversation that happened between one engineer and a model, and that conversation disappears when the chat window closes. Spec-driven development fixes this by moving the real decisions upstream into specs and designs that the whole team reviews before any code is generated. The spec becomes the source of truth. The tasks become the contract. The code becomes a derived artifact — generated from a plan that everyone has already agreed on.

For small, well-understood changes. Bug fixes, config updates, simple refactors — anything where the scope is obvious and the risk is low. An engineer describes what needs to happen, and the AI generates a focused implementation brief. No stage progression, no approvals, no ceremony. Vibe coding has a real place in the workflow. Not everything needs a spec. The mistake teams make is applying this approach to everything — including work that is too ambiguous or too large for it.

For standard features. Work that would normally take a few days to a week, involves real decisions, and benefits from team alignment before implementation starts. The process has four stages with a team review between each: 1. Requirements — Plain-language description of what you're building and why. Written in EARS notation (WHEN [condition] THE SYSTEM SHALL [behavior]) for testable, unambiguous criteria. 2. Tech Spec — Technical specification generated from the approved requirements. Architecture, data models, API design, error handling. 3. System Design — Detailed design with component responsibilities, database design, infrastructure, implementation phases. 4. Task Specs — N parallel task specs, one per engineer, each with scope, acceptance criteria, and dependencies. The team collectively reviews and approves each stage before moving to the next. This is the whole point. If you skip the reviews, you have built an expensive vibe coding pipeline with more steps.

After the team has reviewed the spec and the design, every engineer knows what's being built, why it's being built that way, and what the tasks are. No surprises in code review. Code reviews get dramatically simpler too. When the reviewer already knows the spec, the design, and the task breakdown, they're not trying to figure out what the code is supposed to do. They're checking that it did what was already agreed on. Reviews that used to take an hour now take fifteen minutes. Configure how many approvals each stage requires in Admin > Spec Workflow Settings.

Requirements are most useful when they're testable and unambiguous. EARS (Easy Approach to Requirements Syntax) provides five patterns that originated in aerospace engineering at Rolls-Royce: - Ubiquitous: THE SYSTEM SHALL log all authentication events. - Event-driven: WHEN a user submits the form THE SYSTEM SHALL validate all fields. - State-driven: WHILE offline THE SYSTEM SHALL queue writes locally. - Unwanted behavior: IF payment processing fails THEN THE SYSTEM SHALL display an error and retry. - Optional: WHERE dark mode is enabled THE SYSTEM SHALL use the dark color scheme. The EARS builder on the requirements stage lets you add structured criteria that carry through to the task specs.

For larger features. Work that touches multiple services, spans several weeks, and needs several engineers working simultaneously. The design is hand-written (with AI assistance), decomposed into independent blocks, and each block gets its own mini-spec prompt. Multiple engineers build separate blocks in parallel against well-defined interfaces. Instead of one engineer working through a long sequential task list, you have three or four engineers each with their own block and their own AI tooling, working simultaneously. The blocks integrate cleanly because the hand-written design already defined the interfaces between them. This workflow is coming soon.

Start with the spec-driven workflow. Pick one upcoming feature. Write a one-page requirements doc before anyone starts coding. Have the team review it together — this is where changing direction is free. Then write the tech spec. Review it. Break it into tasks. Review those. Then build. Once spec-driven development feels natural, your team will be amazed at how much faster they move when everyone is aligned before the first line is written.