Inside our spec-driven development framework: how we built it, and how to build yours

By Alfredo Castillejos · Dixi-Project · November 4, 2026 · 15 min read
Illustration: five colored columns resting on two horizontal bars, with a document on the left and a check mark on the right.

Our earlier posts covered individual pieces: how we classify the risk of a change, who answers for code an AI writes, and what happened over thirty days with one maintainer, one agent and 141 PRs. This post is the map that ties them together: how the spec-driven development (SDD) framework we use to build all our software is put together, why it looks the way it does, and how another company can build its own.

The framework is called AI-ASEE (AI-Assisted Software Engineering Ecosystem; internally, EIS-IA). It lives in its own repository and has shipped 20 releases since March 2026, the latest being 4.11.0 on November 5. Every new project at the company starts from it, and existing ones adopt it, including the platform that serves the page you are reading.

The core idea fits in one sentence: with AI, the bottleneck is no longer writing code but validating it. A team's speed is set by how fast it can validate, not how fast it can generate. Everything else follows from that. And it holds whether you are a development team or a single person working with agents: the framework runs both ways, with the same controls.

What we mean by SDD

In spec-driven development, the specification is in charge: code is written to satisfy it, and tests prove that it does. With AI agents this stops being a good habit and becomes a practical necessity, because an agent only knows what is written down. If it isn't in the repository, it doesn't exist for the next agent.

But an SDD framework is not a folder of documents. Our first version was exactly that, which is where the story starts.

How we got here: three versions, three lessons

Version Date What it introduced What we learned
1.0 March 2026 Numbered specification sections, four agents (architect, developer, tester, reviewer) and an operating mode Structure guarantees nothing if nobody checks it
3.0 October 2026 Rules become mechanisms that fail on their own: agent hooks, pipeline gates, signed human accountability A rule that depends on someone remembering it is not a control
4.x October–November 2026 Process proportional to each task's ambiguity and risk, profiles by project size, delegated autonomy and a work-in-progress limit Running the same ceremony for a typo and a migration is expensive and buys no quality; and with agents, what runs out is the reviewer's attention

Version 2.0 (May 2026) added what surrounds the code: a vendor-neutral guide for any agent, due diligence, a full quality strategy, and a playbook for kicking off client projects.

The model: five pillars, two axes

The AI-ASEE model: five pillars resting on two cross-cutting axes

Each pillar answers one question. Remove any of them and the ecosystem is incomplete: generating without verifying is vibe coding; verifying without operating is a green pipeline that tells you nothing about production.

Pillar The question it answers What it contains
Methods How is software thought through and specified? SDD, DDD, BDD, TDD, property-based testing, contract testing, user stories
Orchestration How do people and agents work together? A cycle of specialized agents with operating modes
Governance Who decides, who approves, who is accountable? Architecture decision records (ADRs), policies, AI usage, compliance
Verification How do we know it's correct and secure before production? A verification ladder, hooks, PR gates, security scanning, risk-based review
Operations How is it deployed, observed and recovered? Deployment chain, observability, SLOs, rollback, incidents, cost management

The two axes cut across all five pillars and make decisions survive changes of agents, models and teams:

  • Knowledge management. A decision that isn't written down doesn't exist. An agent's context is ephemeral; the repository isn't.
  • Traceability. Every line in production can be traced back to its reason: business goal → domain → module → feature → contract → test, and then task → commit → PR → artifact → deployment.

One practical rule falls out of the model: every new mechanism must state which pillar it belongs to and which axis it strengthens. If it fits neither, it probably shouldn't exist.

The pieces, one by one

1. Specifications with machine-checked traceability

The repository has 29 numbered sections, from business and domains to API contracts, data, architecture, quality, security, deployment and operations. The numbering isn't cosmetic: it sets a reading order, so an agent arriving cold knows where to start.

Traceability isn't checked by eye. A validator walks the repository and fails if a module doesn't cite its domain, a feature doesn't cite its module, or a document references one that doesn't exist. It works as a ratchet: existing debt is recorded in a baseline and the validator only fails on new findings. The baseline can only go down; it is never raised to silence an error.

2. Standard and project, kept apart

Every project starts as a copy of the framework, which forces a clear answer to "whose is this?" Each folder falls into one of four classes:

Class What it means
Standard Defined by the framework and binding on every project. Not edited in the project: changes are proposed upstream and arrive with the next release
Slot Structure each project fills with its own content: business, domains, contracts
Example A sample of a filled slot. Never copied into projects
Framework-only The framework's own state as a project. Never copied

Architecture decisions follow the same split: records 1 to 99 belong to the framework, 100 and up to each project. Deviating from the standard is allowed, but you have to write down why, in a project-level decision. The platform behind this site has several, such as the one that lets it run with a single person.

We learned this split the hard way: until version 3.0, new projects were born with the domains of the sample gym app we used as an example.

3. Orchestration: an agent cycle with frozen tests

A build task goes through five steps, each handled by a specialized agent:

  1. Architect reads the specs and proposes a plan.
  2. Tester writes tests that must fail, and they are frozen in their own commit.
  3. Developer writes code until they pass, without touching them.
  4. Tester verifies the whole.
  5. Reviewer checks the result against the spec and the risks.

Step 2 is the linchpin. An approved test is an executable specification, and the agent cannot edit it: a hook blocks it. If a test looks wrong, the agent stops and explains why; a person changes it. Without that rule, the shortest path to green would be adjusting the test.

When does the agent ask? This is where delegated autonomy comes in: inside its branch, the agent moves on its own and stops only at the boundaries, a closed list of cases. For example: breaking a published contract, deleting data, touching permissions or secrets, adding an unapproved dependency, finding two specs that contradict each other, or a frozen test that looks wrong. Outside that list it decides, and records every assumption in the PR, along with the alternative it rejected, so review can check it. A missing assumption counts as a review finding. Each project can tune what it delegates in a file of its own, such as which dependencies the agent may add without asking, but only to add boundaries, never to remove them. That way, the person isn't spending the day approving one-off decisions, which is the fastest route to approving without reading.

4. Controls that fail on their own

The standard has 20 non-negotiable rules, and each declares three things: the rule, where it is written, and which mechanism enforces it, with an honest status: fails on its own, partial, or pending.

The cheapest mechanisms protect the most. Five hooks inspect every agent action before it happens:

Hook What it prevents
Operating mode Catastrophic commands, pushing to deployable branches, merging or deploying by hand
Secrets Reading environment files, keys or cloud secrets
Attestation Signing commits or ticking the PR's accountability box
Tests Editing a test that has already been committed
Verify on stop Declaring a task done while local verification is red

They cost next to nothing in time or tokens, and they don't depend on anyone remembering. The hooks have tests of their own: a matrix of cases that must be allowed and cases that must be blocked.

5. A person answers for every change

The AI doesn't sign, attest, approve or merge. The agent prepares the PR; the person signs each commit, ticks the box that says "I reviewed this and I answer for it," and merges it. A pipeline gate checks after the merge that all of that happened: the commit came from a PR, it is signed, the attestation is ticked, and the change is within the size limit.

Signing and merging are two commands only the person can run: they ask for confirmation in their terminal and refuse to run when an agent launches them. The merge command also refuses if any required check isn't green, the box is unticked, or a commit is unsigned, and it always merges with a merge commit so the signatures survive.

We go deeper in Who answers for AI-written code?.

6. A single deployment chain

PR → CodePipeline → CodeBuild → deployment, with two independent human gates: PR review (is the change correct?) and manual approval before production (should this artifact go to production now?). The artifact is built once, tagged with its commit, and the same one moves through every stage. Rolling back means redeploying the previous artifact, not building a new one.

Two rules that look minor and aren't: PR checks get no cloud credentials, not even temporary ones; and after the merge, the cloud runs everything: infrastructure, migrations and rollback. Nobody operates production from a laptop.

7. Process proportional to ambiguity and risk

This was the big change in version 4. Previously every task went through the full agent cycle, with each agent re-reading the same specs to reach a plan that, for a small fix, was already obvious. Now each task is classified up front:

Level Kind of work Process
0, fix Cause and solution understood Failing test if behavior changes, change, verify. No agents
1, clear rules Bounded feature, no business questions Short ticket, failing tests, code, verify
2, ambiguous Open business, scope or design questions Full user story validated by a person, full cycle
3, structural Architecture, contracts, data or migrations Plus a written architecture decision and a multi-PR plan

Two rules keep this from becoming a way to skip the process:

  • Risk sets a floor. If the task touches money, permissions, personal data, security or infrastructure, it is level 2 at minimum. If it touches contracts or persistent data, level 3.
  • Levels go up, never down. The agent proposes the level; a person can raise it. If a business question surfaces midway, the agent stops and reclassifies.

What never changes at any level: mandatory PR, green verification, frozen tests, secrets out of the agent's reach, human sign-off, and the deployment chain. The savings come from ceremony, not from controls.

8. Profiles: a landing page is not a platform

This piece answers a fair complaint: a content site shouldn't carry the same load as a platform that handles payments.

Profile What it is
S, site Landing page or content site with no backend of its own
A, application A few deployable pieces: site, admin panel, API, one database
P, platform Multiple services, events, several apps or teams
+R, regulated Added to any profile: payments, health, sensitive data or enterprise clients

The profile is chosen with a six-axis questionnaire (components, data and money, users, budget, team and expected lifespan), and the highest axis wins. The agent proposes it; a person confirms it.

Two guarantees keep it safe. There is a core no profile can drop: the deployment chain, agent controls, human accountability, the internationalization policy, and the five hooks. And profiles only go up: the validator looks for signs of a larger profile, such as migrations in a site or events in an application, and fails if it finds them.

9. One person or a team: the same framework

The framework works the same for a development team as for a single person. The only thing that changes is who performs the second review; signing, attestation, tests, verification and the deployment chain are identical in both cases.

Team Single person
Who writes the change A person with their agents A person with their agents
Second review Another person approves the latest commit; two approvals for high risk. Authors never approve their own work An independent reviewer agent reviews the latest commit and the author gives an explicit final confirmation
Changes to the control system itself Reviewed by another person Mandatory wait after the last change, for a cold review
Signing, attestation, tests, deployment Same Same

Single-person mode ships switched off in every new project: turning it on is an explicit day-one decision. And it switches itself off as soon as a second person gets write access to the repository. Nobody has to remember to disable it: the day the second person joins, the project starts running as a team.

This matters for adoption. A small company can start with one person and agents, with the same controls it will have once it grows, and moving to a team doesn't require redoing anything.

10. The reviewer sets the pace

The last piece goes back to the premise. With agents, opening PRs is nearly free; reviewing them isn't. Left unchecked, the review queue grows faster than a person can read, and review turns into a rubber stamp.

So there is a work-in-progress limit: three open PRs per person, counting those opened by the agents they launched, and drafts. The agent checks it before starting a new task, not when it opens the PR. If the limit is reached, it doesn't start another one: it addresses review comments, fixes red checks and, if nothing is left, hands the person the list of what is waiting on them. Only an incident blocking production can exceed the limit, by one, and the person declares it, not the agent.

The control fails open: if the counter itself breaks, it warns and lets work continue. Its job is to set the pace, not to become one more blocker.

How to build your own

If your company wants its own SDD framework, this is the order we would follow knowing what we know today:

  1. Start from the premise, not the folders. Write down the problem the framework solves. Ours is "validation is the bottleneck"; every piece is justified against that.
  2. Draw your model and give every pillar an owner. A pillar without an owner is a gap, and it shows in the first audit.
  3. Write the short list of what is non-negotiable. One rule per line, with its source and its mechanism. Be honest about which ones fail on their own and which still depend on a person. If a rule isn't on the list, it is guidance, not a standard.
  4. Turn rules into mechanisms, cheapest first. A hook that blocks reading secrets is worth more than a policy that forbids it. Agent ceremony is the expensive part; controls aren't.
  5. Make traceability verifiable, with a ratchet. That lets you adopt the framework on top of existing debt without freezing work, and debt only goes down.
  6. Separate the standard from the project, and version the standard. Use semantic versioning and a migration guide for every major release. Deviations get written down.
  7. Put a named person behind every change. AI can prepare everything, but someone signs and answers for it. Decide early how the second review works while you are a single person, so that moving to a team happens on its own, without redesigning the process.
  8. Make the process proportional from day one. We added it later, and paid for ceremony that bought no quality along the way.
  9. Limit work in progress. Cap open PRs per person before the review queue caps them for you.
  10. Measure. PR size, lead time, rework and defects that reach production. Without metrics you can't tell whether you are better or just faster.

What went wrong along the way

  • Uniform ceremony was expensive. Running the full agent cycle for every task cost time and tokens without improving small fixes. That is where proportional process came from.
  • Twelve checks were too many. In version 4.0 we grouped them into three, with the same controls. A documentation-only PR went from about fifteen CI jobs to five.
  • Examples leaked into projects. Until we separated standard, slot and example.
  • The size limit was too strict. We started at 400 lines of code per PR, and tests counted. With tests written first, tests were half the change: the limit punished exactly what we wanted to encourage. Today it is 1,500 lines excluding tests, which are shown separately and reviewed first.
  • Merging with a button skipped the controls. On a single day, seven PRs were merged with at least one red check, from UI buttons that wait for nothing. That is where the merge command that refuses red checks came from.
  • Controls trail incidents by a step. Several were born from a real problem, as we described in the single-maintainer post.

What is implemented and what isn't

Piece Status
Machine-checked traceability with a ratchet Implemented
Agent hooks with their test matrix Implemented
Human signing and attestation checked in the pipeline Implemented
Signing and merging through commands only the person can run Implemented
Proportional process and project profiles Implemented in the framework; each project picks them up when it upgrades
Delegated autonomy: the agent decides inside the branch, the person at the boundaries Implemented in the framework; we still need to measure how many pauses it saves
Work-in-progress limit: three open PRs per person Implemented in the framework
Second review by task level, and a single PR for several small fixes Pending
Single-person mode Implemented. Our own repository runs this way; the control that requires another person's approval is in warning mode until January 2027
Automatic check for untranslated text Pending

What this post does not claim

  • It doesn't claim this is the only correct SDD framework. It is the one that works for our size and our stack, and it changes every few weeks.
  • It doesn't claim mechanisms replace judgment. They guarantee the process was followed; whether the change is the right one is still decided by a person.
  • It doesn't claim the framework is finished. The table above says so: some pieces are still pending.

Sources

ShareLinkedInXWhatsApp