Why Eidos Exists

The problem

Ask a team what they are building and you get four answers, none of them written down in one place.

The ticket that described the feature closed eighteen months ago, and its description was written to justify a sprint, not to describe a product. The wiki page was accurate the week it was written. The decision about why you don’t support a case was made verbally, and the only person who remembers it left. The code tells you what the thing does today, but not what it is meant to be, or which of its current behaviors are promises versus accidents.

So the honest answer to “what is this thing supposed to be?” is a meeting.

Why tickets can’t hold it

The instinct is to reach for the tracker, because the tracker is where the team already lives. It doesn’t work, and the reason is structural rather than cultural.

A task describes work. It has a beginning and an end, a person assigned, an estimate, and a state that runs from open to closed. Its whole purpose is to stop being relevant. When the work ships, the ticket is done, and everything it happened to record about the product goes stale in the same instant — because nothing is watching it any more.

A blueprint describes the thing. It has no end. It is written before the work starts, corrected while the work happens, and remains the accurate description long after. Its accuracy is not tied to a state.

This is the reason Eidos forbids work-tracking fields outright. No sprint, no estimate, no assignee. The moment you add them, a blueprint becomes a task and starts rotting on the same schedule. Bridge to your tracker with a link instead.

What Eidos does about it

It keeps the authoritative answer to “what is this thing” as version-controlled markdown, in the repository, reviewed in pull requests alongside the code it describes.

That location choice does most of the work:

It’s next to the code, so it’s in front of the people who would otherwise guess.
It’s in git, so every change has an author, a date, a diff, and a reason — and Eidos leans on that history instead of inventing its own audit trail.
It’s reviewed in PRs, so a change to what the product is gets the same scrutiny as a change to what it does.
It’s plain markdown, so a human reads it in an editor, on a web page, or in an Obsidian vault, and a coding agent reads the exact same file.

That last point is not incidental. Humans and agents reading two different sources of truth is how drift starts. They read the same file here.

The self-affirming loop

This is the reason the standard is built the way it is, and it’s worth stating plainly.

A spec exists to be a check on the code. It’s the independent statement of what the thing is supposed to be, and the whole of its value is that it comes from somewhere other than the implementation.

Now let an agent write both.

It writes the spec. It writes code that satisfies the spec. Asked whether the code is right, it checks the code against the spec it wrote. Everything agrees. Every review passes. Nothing has been verified — you have two artifacts that corroborate each other, and neither was ever measured against anyone’s intent.

The failure is silent, which is what makes it expensive. A generated spec doesn’t look generated. It has an intent paragraph, plausible acceptance criteria, and a non-goals section with three reasonable entries — and no author. It reads as settled while nobody decided anything, and it carries the authority of being written down, committed, and reviewed in a pull request.

Six months later someone builds against AC4, and the honest answer to “who decided this?” is nobody.

So the human decision isn’t a nicety in Eidos, or a stage to be automated once the tooling improves. It’s the entire load-bearing element. A spec is worth exactly as much human intent as went into it, and a spec with none is worse than no spec at all — because the version in someone’s head was at least known to be unreliable.

When not to use Eidos

The corollary is blunt, and it’s more useful than another feature would be:

That isn’t a criticism of working that way. For a prototype, a throwaway, a thing whose only requirement is that it runs, it’s the right call — and the honest answer is that a spec layer would be theatre.

Eidos is for the case where someone is accountable for what the thing is. Where a person has to answer for a scope decision, defend a boundary, or explain in a year why it doesn’t handle a case someone assumes it does. If nobody is in that seat, the standard has nothing to hold.

What it is not

Not a documentation generator. Nothing is derived from your code. A blueprint is written by a person who decided something.

Not a template you fill in. The standard says it plainly: if an blueprint reads like filled-in boilerplate, reshape it until it reads like someone wrote it. The shape is a scaffold for a living document, not a form.

Not a product an agent writes for you. The human authors; the agent facilitates. See Working with Agents — this is a design constraint, not a limitation waiting to be lifted.

Not a rigid schema. Eidos names no collection, no shape, and no section. It defines the machinery — collections, shapes, flavors, properties — and your framework names everything. A framework that looks like none of the shipped seeds is working as intended.

Who holds it

One person: the Framework Owner. They hold the intent, the scope, and the decisions.

This is the least technical and most load-bearing part of Eidos. A root with no owner becomes a wiki with better formatting — everyone edits, nobody decides, and the non-goals section quietly empties out because saying no is the part that requires authority.

Quick Start — get a root on disk.
Framework & Blueprint — the two words the whole standard turns on.