Manifesto

A governance framework for developers working with AI agents. You set the direction, the agent executes, and every task follows the same workflow.

Devs orchestrate · Agents execute

Context

"Approving a short spec costs less than reviewing code you did not ask for."

The Spec-Driven Guide (SDG) is an AI-native governance framework. It gives every task the same workflow, so the agent starts from an agreement you approved instead of from a guess.

Code nobody recognises

Adopting AI fast, without a technical foundation, raises technical and cognitive debt. With no shared standards, the agent writes code that compiles and that nobody on the team recognises.

What the framework standardizes

Every task runs through the five-phase cycle: SPEC → PLAN → CODE → TEST → END. The agent stops for your approval at SPEC, again at PLAN, and once more before the commit. You know what it will do before it does it.

Foundations

Good software comes from a few habits, applied on every cycle.

The value of the word

Every choice, from a comment to a function name, carries intent. Naming things for what they do is what makes a system readable.

ClarityIntentionality

Healthy habits

Naming rigour and defensive coding come from practice, not from talent. Consistency is applying the same rules on the next cycle.

ConsistencyLearning

Reflection before construction

Deciding the order of the work protects the system while it grows. A plan written in ten minutes saves the rework of a change made in the wrong place.

Spec-drivenPlanning

Partnership

You lead the intent. Your agent handles the execution.

Developer (sets the direction)

You define what to build, why, and when it is good enough. Domain knowledge, priorities, and final judgement stay with you.

Agent (writes the code)

The agent proposes solutions, generates code, and applies your project's patterns. You review what it produces.

Engineering playbook

Principles that stay with you through every new project.

Security belongs to the foundation

Defensive checks and access control enter on the first draft. Bolting them on later means touching every layer again.

Code is a conversation with the team

We write for whoever maintains the system next. Often that person is you.

Resilience comes from design

Reliable systems treat failure as a planned case, not as an exception.

AI amplifies your standards

The agent repeats the pattern it finds in the project, including the ones you left loose.

Excellence by default

Open Source · Free forever

Most codebases that aged well started with one decision: take the fundamentals seriously.