Coroid uses specification-driven development: the specification stays with a piece of work from planning through testing and review, so every stage works from the same definition of success.
Instead of starting from a sentence and deciding the details while writing code, Coroid turns the request into explicit scope, exclusions and acceptance criteria. That document becomes the source of truth for the plan, implementation, tests and final review.
What is specification-driven development?
Specification-driven development is a way of building software from an agreed, testable description of the outcome. The specification says what will change, what will not change, which constraints apply and how a reviewer can tell the work succeeded.
It separates two decisions that are easy to blur together:
- The specification defines what success means.
- The implementation plan defines how to achieve it.
That separation lets you correct scope before code exists without prescribing an implementation too early. In Coroid, you can also enable the optional SDLC workflow when you want to approve the intent and specification before planning starts.
How the workflow works in Coroid
- Describe the outcome. Give Coroid the result you need, the relevant context and any constraints or non-goals.
- Review the specification. Check the scope, exclusions and acceptance criteria on the task's Specification tab.
- Approve the plan. The architect turns the agreed outcome into ordered implementation steps.
- Build and verify. Developer and QA agents use the same criteria to implement the change and prove each promised behavior.
- Review the pull request. The delivered change carries the plan, test results, findings and evidence back to the original specification.
The result is traceability from product intent to the code and evidence a human reviewer sees. See How a task becomes a pull request for the full execution path.
Why the extra step
An instruction like "add caching to the user lookup" has at least four reasonable implementations and no definition of done. An agent will pick one. Whether it picks yours is luck.
The specification makes that choice explicit before implementation begins, at the point where changing your mind is cheapest.
It also gives verification something to test against. Without acceptance criteria, "did this work?" collapses into "do the tests still pass?", which is a much weaker question.
What a specification contains
| Part | What it answers |
|---|---|
| Scope | What will change |
| Out of scope | What deliberately will not, so the change does not sprawl |
| Acceptance criteria | How anyone can tell it worked |
| Context | Constraints, conventions, and prior decisions that apply |
You can read and edit it on the task's Specification tab before execution starts. For the work description and supporting context that feed this process, see Describing what you need.
Worked example: from brief to testable specification
Suppose the original brief is:
Add caching to the user lookup so repeated requests are faster.That states the desired outcome, but it leaves important choices unresolved. A useful specification turns those choices into boundaries and checks:
Scope
- Cache successful user lookups by user id for 60 seconds.
- Invalidate the cached entry when the user record is updated.
Out of scope
- Do not cache failed lookups.
- Do not change the public signature of getUser.
Acceptance criteria
- Two lookups for the same user id within 60 seconds call the data source once.
- Updating that user invalidates the existing cache entry.
- A cache miss preserves the current result and error behavior.The plan can now choose an implementation, QA can turn the criteria into tests, and the reviewer can compare the pull request with the promised behavior.
What makes acceptance criteria good
They must be checkable by someone who was not in the conversation.
Weak:
Caching works correctly and performance is improved.Strong:
- Repeated lookups for the same user id within 60s hit the cache, verified
by a test asserting the data source is called once across two lookups.
- Cache entries are invalidated when the user record is updated.
- A cache miss behaves identically to today, including error handling.
- No change to the public signature of `getUser`.The second version tells the developer agent what to build, tells the QA agent what to test, and tells you what to check on the pull request. The first leaves each of those decisions open.
Scope lines matter as much as criteria
The most common cause of an oversized pull request is not an agent exceeding its brief — it is a specification that never said where the brief ended.
If you do not want the surrounding module refactored while it is in there, say so. "Do not change the call sites" is a legitimate and useful line.
Common specification mistakes
| Mistake | Better approach |
|---|---|
| Describing the implementation instead of the outcome | State the behavior and constraints, then let the plan choose the implementation |
| Using words such as “fast”, “secure” or “works correctly” | Replace them with an observable threshold, behavior or test |
| Omitting non-goals | Name adjacent code, interfaces or behaviors that must remain unchanged |
| Combining unrelated outcomes | Split the work so one task ends in one reviewable pull request |
| Copying a ticket without checking assumptions | Add the context and decisions the repository cannot reveal |
When you disagree with it
Edit it. The specification is a working document up until execution begins, and correcting it is far cheaper than correcting the code that would have come from it.
If the specification reveals that the work is really two pieces of work, split it into two tasks. One task should end in one pull request that one person can review in one sitting.
Where it goes next
For anything beyond a small change the specification becomes a plan. See Tasks, plans, sprints and lanes, which explains how the work is divided and approved before code is written.
Frequently asked questions
Is a specification the same as a technical design?
No. A specification defines the required outcome and boundaries. A technical design or implementation plan explains the architecture and steps used to reach that outcome.
Does every change need a long specification?
No. A small, unambiguous change may need only a few scope lines and acceptance criteria. The specification should remove meaningful uncertainty, not add ceremony.
Who should approve the specification?
The person accountable for the outcome should confirm that the scope and criteria match what the team needs. Technical, security or compliance approvers can participate when their constraints affect success.
Can a specification change after work starts?
It can, but the change should create a new version and trigger a review of the dependent plan and work. Silent scope changes break the evidence chain between the request and the delivered pull request.