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-specVerify 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 moduleReview the extracted spec, refine it, and iterate. Now you have a spec to push against, drift-check, and evolve.
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:
| Skill | What it does | | ------------------ | ------------------------------------------------- | | /eidos:spec | Create a spec via structured Q&A | | /eidos:push | Implement code to match a spec | | /eidos:pull | Reverse-engineer a spec from existing code | | /eidos:drift | Analyse divergence between specs and code | | /eidos:sync | Bidirectional reconciliation of specs and code | | /eidos:coherence | Check specs against each other for contradictions | | /eidos:refine | Process inline comments in specs via dialogue | | /eidos:behave | Capture current behaviour as a regression net | | /eidos:weave | Discover missing wiki links, prune stale ones |
Plan and remember — procedural memory:
| Skill | What it does | | ---------------------- | -------------------------------------------- | | /eidos:plan | Persistent plan for multi-step work | | /eidos:plan-continue | Resume work on an existing plan | | /eidos:plan-review | Review a plan before implementing | | /eidos:decision | Record a decision with options and rationale | | /eidos:experiment | Log-based iterative exploration | | /eidos:observe | Capture testing issues mid-plan, update specs | | /eidos:process | Work through a structured document point by point |
Research and understand:
| Skill | What it does | | --------------------------- | --------------------------------------------- | | /eidos:research | Investigate a topic, document with sources | | /eidos:research-deep | Recursive deep research with progressive synthesis | | /eidos:research-recursive | Branching research, a file per area | | /eidos:architecture | Snapshot codebase structure for reference | | /eidos:code-review | Review code for quality and security | | /eidos:reflect | Extract learnings from a session or file | | /eidos:meta | Analyse eidos skill output for quality | | /eidos:tldr | Ultra-short summary of a topic or files |
Stay aligned — steering and shared understanding:
| Skill | What it does | | ------------------- | --------------------------------------------------- | | /eidos:align | State your understanding so the human corrects it before work | | /eidos:challenge | Constructive pushback on a proposal | | /eidos:brainstorm | Explore ideas around a topic | | /eidos:info | Request more context before proceeding | | /eidos:status | Snapshot of active plan progress | | /eidos:forgor | Re-orient fast when you lose the thread | | /eidos:pickmeup | Resurface recent activity to re-enter a project | | /eidos:next | Show actionable items to work on | | /eidos:spiral | Stop spiraling and hand off to the user |
Capture and persist — externalise:
| Skill | What it does | | ------------------ | ------------------------------------------------ | | /eidos:claim | Extract and persist a claim | | /eidos:reference | Capture external knowledge the project relies on | | /eidos:todo | Create quick task files | | /eidos:wish | Capture feature ideas not yet specced | | /eidos:missed | Log documentation gaps for later routing | | /eidos:annotate | Leave inline AI feedback for human review | | /eidos:toeidos | Route insights into specs and claims | | /eidos:toclaude | Persist behaviour corrections to CLAUDE.md | | /eidos:true-name | Find precise domain names for vague concepts | | /eidos:goodjob | Capture positive calibration with context |
Coordinate across repos — agent communication:
| Skill | What it does | | ---------------- | ----------------------------------------------- | | /eidos:inbox | Read and act on messages other repos left you | | /eidos:message | Send a request or notification to a peer repo | | /eidos:outbox | Check the status of messages you sent | | /eidos:standin | Mark and request an API a dependency should own |
Workflow and session:
| Skill | What it does | | ------------------------- | ------------------------------------------- | | /eidos:init | Bootstrap the eidos folder structure | | /eidos:config | View and toggle project settings | | /eidos:done | End a session with export and merge offer | | /eidos:compact | Pre-compact readiness check before clearing | | /eidos:archive | Move done files into archive subdirs | | /eidos:help | List all eidos skills with descriptions | | /eidos:worktree | Parallel task work via git worktrees | | /eidos:mono | Register a working subdir focus in a monorepo | | /eidos:faildetect | Verify-or-rollback execution mode | | /eidos:ping | Surface session status via an OS notification | | /eidos:debug-session-start | Print session-start context for inspection |
Content and export:
| Skill | What it does | | ---------------------- | -------------------------------------------- | | /eidos:summary | Structured summary of a file or session | | /eidos:tomd | Export the conversation to markdown | | /eidos:toscript | Export code to a script file | | /eidos:toskill | Create a new skill from the conversation | | /eidos:clip | Copy relevant content to the clipboard | | /eidos:image | Persist an image with a markdown companion | | /eidos:gid | Compress or expand text via GID notation | | /eidos:video | Generate a manim explainer video | | /eidos:me | Leave a note to yourself in the chat | | /eidos:options | Present structured choices as a numbered list | | /eidos:writing-style | Bring a file up to the house writing style |
Install
Requires Claude Code.
# Add marketplace
/plugin marketplace add agenticnotetaking/eidos
# Install plugin
/plugin install eidos@eidosThen 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/eidosThen 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
