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, asks, and presses on scope. It never invents a blueprint’s purpose or hands back a finished one to rubber-stamp.

This is the most misread part of Eidos, usually as a limitation waiting to be lifted. It is the constraint the rest is built on. A spec is a check on the code, and a check is only a check if it comes from somewhere else. Why →

What an agent does

• Formats. Generates frontmatter from the Properties table, applies the template, keeps names and links in convention.
• Asks. Where you are vague, it asks. It does not fill the gap with plausible prose. The right response to a clarifying question is an answer, not “you decide”.
• Presses on scope. Hardest on the non-goals.
• Validates. Frontmatter against your Properties table, sections against the blueprint’s variant, no work-tracking fields.
• Reshapes. A brain-dump into the template, keeping your words and adding nothing.
• Speaks your words. You need not know the Eidos standard. An agent places a new thing itself and tells you where, says spec or recipe rather than variant or template, starts it with the sections that are required, and adds the rest only as the work needs them.
• Logs what it decided. Where the root keeps decisions as a record type, a choice the agent made on its own while working is logged as a decision signed as itself (eidos records add <blueprint> decision … --as <alias>), waiting for you to confirm. It never confirms its own.

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 is working.

Pointing an agent at the CLI

eidos agents --write                # AGENTS.md
eidos agents --write --file CLAUDE.md

This writes a short note: before touching a blueprint or the framework, run eidos instructions overview and follow it. The guides route every mechanical step to a command and leave the decisions with you:

eidos instructions overview         # required first read
eidos instructions authoring        # before creating or editing a blueprint
eidos instructions validating       # before reviewing a blueprint or a root
eidos instructions configuring      # before changing the framework
eidos instructions init-required    # when there is no root yet

An agent that follows them reads the framework before assuming anything (eidos framework), reads who is in the seat (eidos whoami), scaffolds with eidos new instead of hand-assembling frontmatter, changes a value with eidos property set, changes the framework with eidos configure:*, validates with eidos check, and rebuilds the index with eidos index. The prose it writes in the file, with you. --json on the reading commands gives stable fields for scripts.

Letting Claude Code run eidos

Claude Code asks before every command it has no rule for, and it will not add a rule for itself. Eidos adds Bash(eidos:*) to permissions.allow for you, in two places, each showing exactly what it writes first:

• Setting up a new root in the desktop app: with Claude Code as the AI, Let Claude Code run eidos here on the AI step writes it to .claude/settings.json once the root is made.
• For the AI Agent: Allow eidos commands under Claude Code on the AI Agent plugin’s page, shown while the rule is missing, writes it to .claude/settings.local.json in the root. The AI Agent starts Claude Code in the root, and Claude Code reads its permissions from the .claude/ of the folder it starts in and no folder above, so the root is where the rule has to be. That file is local: on this computer alone, kept out of Git, and the page says which file allows the rule once one does.

The setup’s file goes at the top of the repository (outside one, beside the root). Either file is created when there is none. Every other key and rule stays as it was, a rule already there is not added twice, a file that is not valid JSON is left alone, and nothing is ever removed. The setup’s file is shared: commit it and every agent started at the top of the repository can run eidos. The rule covers a command that begins with eidos, so eidos has to be on the PATH (Help > Put eidos on the PATH in the desktop app, or npm install -g eidosmd); npx eidos, node …/cli.js, and a line such as cd docs && eidos list still ask. A setting a plugin’s page changes has an eidos command too (eidos plugin set, or the plugin’s configure: commands), so the one rule covers everything the agent does in the root. No command writes it, and eidos install never touches it, so an agent cannot widen its own permissions.

For Claude Code and Claude Desktop, a plugin of skills carries the judgment-heavy parts and calls the CLI for the rest. Claude skills →

Getting good results

• Set your me.md. Two minutes with eidos whoami changes every response after. Roles →
• Answer the questions. When it asks whether cross-account resume is in scope, the answer is yes or no.
• Bring the thinking; let it bring the structure. Talk through the unit the way you would to a colleague. Rough is fine.
• Push back when it drifts. Its job is to hold your intent, not improve on it.

The tell

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