Working with Agents

The standard's first principle

The human authors; the agent facilitates. Intent, scope, and decisions stay with the person. An agent formats, supplements, asks, and holds scope; it does not generate finished blueprints or set direction. A blueprint the owner did not think through is worse than none.

This is the most misread part of Eidos, usually as a limitation waiting to be lifted. It isn’t. It’s the constraint the rest of the standard is built on.

Why the constraint exists

Because a spec is a check on the code, and a check is only a check if it comes from somewhere else.

Let an agent write the spec and then write the code, and that independence is gone. It satisfies its own spec. Asked whether the code is right, it compares the code to the document it produced. Everything agrees, every review passes, and nothing has been verified — two outputs of the same process corroborating each other tells you nothing about either.

An agent can produce a spec that looks right. It will have an intent paragraph, plausible acceptance criteria, and a non-goals section with three reasonable entries. It will read well. And it will encode decisions nobody made.

The failure isn’t that the content is wrong — often it’s fine. The failure is that it carries the authority of being written down, committed, and reviewed, without anyone having actually decided. Six months later someone builds against AC4, and the honest answer to “who decided this?” is nobody.

A root’s value is entirely that a person stood behind it. Remove that and you have a document that looks like a source of truth and isn’t, which is worse than the meeting you were trying to avoid.

The honest corollary

If you aren’t reviewing and aren’t deciding — the agent picks the direction and you take what it builds — then don’t write blueprints at all. They add ceremony, not correction. When not to use Eidos →

What an agent does do

Plenty, and all of it real work:

Formats. Generates frontmatter from the Schema, applies the shape, keeps naming and links in convention, fixes YAML that a leading [ broke.

Supplements. Fills in what follows mechanically from what you said, and surfaces what a shape asks for that you haven’t covered.

Asks. Where you’re vague, it asks. It does not fill the gap with plausible prose. This is the behaviour to reward — the right response to a clarifying question is an answer, not “you decide”.

Presses on scope. Pushes hardest on the non-goals section, because that’s where scope is held.

Validates. Checks frontmatter against your framework’s Schema, reports missing body sections against the blueprint’s flavor, and confirms no work-tracking fields crept in.

A good session sounds like an interview

If the agent hands you a complete blueprint after two sentences of input, something is wrong. If it comes back with four questions about the boundary you left vague, it’s working.

How an agent is expected to operate

Four instructions from the standard’s own agent section, and they’re worth knowing because they tell you what to expect:

Find the framework in the root

Locate a root by its _eidos/ marker, not its folder name. Every operation reads that _eidos/. Never fall back to a hardcoded contract, and never assume a collection or section name — read what the framework declares.

If a folder has no _eidos/, offer install.

Read the actor first

_eidos/me.md, then the role file it names. Respond as that file defines the role — read it, don’t infer from its filename. A framework defines its own cast. More →

Navigate by the leaves

README.md for orientation, _eidos/Framework.md for the full index, each collection’s index.md for its blueprints. Read these instead of scraping the tree, and regenerate them when stale.

Surface, don’t block

Validation output is a review a human acts on, not a gate. A missing core property is surfaced and added with a note on why. A missing section is noted and offered. Never refuse the file.

Validating a blueprint

What a check actually does:

• Frontmatter against the framework’s Schema — id kebab-case, dates as YYYY-MM-DD, custom properties scoped to the right collection.
• Missing body sections against the blueprint’s flavor shape — a blueprint on micro is never faulted for full’s sections.
• An absent non-goals section flagged first among the missing.
• Anything skipping the labeling the shape asks for.
• No work-tracking fields.

Getting good results

Set your actor. Two minutes with whoami changes every subsequent response. Skipping it is the most common reason people find the agent pitched wrong.

Answer the questions. When it asks whether cross-account resume is in scope, the answer is yes or no, not “what do you think?”. You’re the one with the context that makes it decidable.

Bring the thinking; let it bring the structure. Talk through the unit the way you’d explain it to a colleague. Rough is fine — that’s what format exists for, reshaping a brain-dump into the shape while preserving your own words and adding nothing.

Push back when it drifts. If it produces something you didn’t say, say so. Its job is to hold your intent, not to improve on it.

The tell that something went wrong

Read the blueprint back and ask, for each claim: did I decide this? If the answer is no anywhere, that line is the agent’s, not yours — and it’s exactly the kind of line that gets built.

Next

• Roles & the Actor
• Skills