Eidos

Spec-driven development for Claude Code.

Markdown specs capture intent. Code is a downstream manifestation of that intent. The two stay in sync bidirectionally: specs shape code, code can update specs, and conflicts become human decisions.

Why

The hard part of AI-assisted development is not writing code. It is keeping human and AI on the same page.

Intent lives in ephemeral places. The chat that scrolls away. A commit message. Your head. The AI acts on a fraction of it, and each new session starts blind.

Eidos has one goal. Human and agent hold the same picture of the work, at every point. It gets there three ways:

• Capture intent as artifacts. Specs, claims, plans, decisions. Structured files, not disappearing chat.
• Keep the human steering. Surface reasoning before acting, checkpoint at decisions, so course-correction is cheap and early.
• Persist and reload. Those artifacts load back into session context automatically, so understanding compounds instead of resetting.

Specs are the flagship. They describe what a system should be, and stay in sync with the code. When the two drift, neither automatically wins. The human decides which to update.

Three folders

project/
  eidos/     # what it SHOULD be (specs, claims)
  memory/    # how we got here (plans, decisions, sessions)
  src/       # what it IS (code)

Specs describe timeless intent. Plans describe time-bound work. Code is the result.

With the agent-inbox feature enabled, a fourth folder appears: agent-inbox/. Each repo becomes an agent that coordinates with peer repos through append-only messages there. It is off by default. Turn it on with /eidos:config.

The core loop: spec ↔ code

Green-field

Write a spec for what you want: behaviour, design, verification. Do it by hand, or let /eidos:spec walk you through it.

Then push it into code:

/eidos:push my-feature-spec

Verify with tests, by hand, or both. If something is off, update the spec, commit, and push again. /eidos:push recent 1 picks up the latest spec change and its exact diff. Repeat.

Existing project

You already have the manifestation. Mine it for intent:

/eidos:pull the auth module

Review the extracted spec, refine it, and iterate. Now you have a spec to push against, drift-check, and evolve.

Workflows

The loop above is spec ↔ code. Most work starts earlier, in a vague idea.

WORKFLOWS.md shows the skills chaining end to end. Seed, research, brainstorm, design, fresh eyes, spec, plan, continue. With shorter variants for smaller work.

Externalise everything

AI "learning on the job" is just capturing ephemeral knowledge into files, then loading them into session context when they matter.

That knowledge can be anywhere. Your chat history. A coworker's head. Legacy code nobody dares touch. Eidos gives it all a place to land and a way to get loaded when it counts.

Skills

Every skill, grouped by what it is for. Run /eidos:help for the same list live inside any project.

Spec ↔ code — the core loop:

Plan and remember — procedural memory:

Research and understand:

Stay aligned — steering and shared understanding:

Capture and persist — externalise:

Coordinate across repos — agent communication:

Workflow and session:

Content and export:

Install

Requires Claude Code.

# Add marketplace
/plugin marketplace add agenticnotetaking/eidos

# Install plugin
/plugin install eidos@eidos

Then restart Claude and run /eidos:init inside any project to bootstrap the folder structure.

Alternative: clone and alias

If you'd rather run from a local checkout (easier to adjust eidos to your needs), clone the repo and add shell aliases:

git clone https://github.com/agenticnotetaking/eidos.git ~/repos/eidos

Then in your ~/.bashrc or ~/.zshrc:

export EIDOS_DIR="$HOME/repos/eidos"

eidos() {
  claude --plugin-dir "$EIDOS_DIR" "$@"
}

eidos-auto() {
  claude --dangerously-skip-permissions --plugin-dir "$EIDOS_DIR" "$@"
}

Adjust the path if you cloned elsewhere. eidos-auto skips permission prompts, so only use it in directories you trust.

The name

Eidos (εἶδος) is ancient Greek for "form" or "ideal form".

For Plato, eidos is the ideal that exists prior to any instance. /push is Platonic: start with the ideal, make it real. For Aristotle, eidos is the essence within particular things, discovered by studying concrete instances. /pull is Aristotelian: start with code, extract intent. The loop between them is dialectical refinement: spec meets reality, reality pushes back, spec evolves.

License

MIT