Quick Start

The skills do the mechanical parts — scaffolding, frontmatter, index regeneration, validation — so you spend the time on the part only you can do: deciding what the thing is.

You can write every file by hand instead, and that’s a legitimate way to work. What you shouldn’t skip is _eidos/ itself.

The skills are optional. The framework is not.

The framework is what holds you to the standard. Without it on disk, the shape you’re writing to lives in your head — it drifts a little with every blueprint, and it stops being a standard the moment a second person writes one. Scaffold _eidos/ even if you never run a skill.

1. Install the skills

   Nine ship with the repository. A skill is a folder with a SKILL.md in it, so any agent that reads that format can run them.

   Claude Desktop / Web

   Customize → Plugins → + → Add marketplace from repository, and give it the repository:

   https://github.com/BuildableWorks/Eidos

   Then install eidos from that marketplace. Available on any paid plan.

   Claude Code

   The repository is a public plugin marketplace:

   /plugin marketplace add BuildableWorks/Eidos
   /plugin install eidos@eidos

   Or point at a local clone for one session:

   claude --plugin-dir /path/to/eidos

   Codex

   Codex loads skills from .agents/skills/. Copy the folders in:

   git clone https://github.com/BuildableWorks/Eidos.git
   mkdir -p .agents/skills && cp -r Eidos/skills/* .agents/skills/

   Use ~/.agents/skills/ instead to get them in every repo. No config needed — Codex picks up any folder whose SKILL.md carries name and description, which every Eidos skill does.

   Manual

   Skip this step. Copy a seed from the repository’s seeds/ into your root’s _eidos/ yourself, and follow the shapes it gives you.

   The rest of these steps name a skill for each job; each one describes what it does, so the work is the same either way.

   No build step

   Each skill is self-contained: the three that need part of the standard carry a committed copy of it, and the rest read your framework at runtime. A skill behaves the same wherever it’s installed.

2. Scaffold a root

   Run install. It asks what you’re defining, offers the three seed frameworks, and scaffolds a root around the one you pick.

   Seed	For
   software	A product, service, or system being built. The default.
   book	A book, long-form argument, or course.
   research	A question, a study, or a programme of inquiry.

   Pick the nearest one. Everything a seed gives you is reshapeable later, so “close enough” is the right answer — you are not choosing a cage.

   You’ll be asked two things that are awkward to change later:

   • The root folder name. Blueprints/ by default; it can be anything, because nothing points at it by path. A root is found by the hidden _eidos/ inside it.
   • The naming convention. kebab-case (default), TitleCase, or Title Case. One convention governs the whole root, and changing it later means renaming every file. See Naming.

   What lands on disk:

   • DirectoryBlueprints/

     • README.md the human “start here”
     • Directory_eidos/ the framework — the form

       • Directoryshapes/ body templates, one file per flavor

         • …
       • Directoryroles/ how the agent talks to each role

         • …
       • Framework.md index + config + the property Schema
       • me.md who’s in the seat (personal, gitignored)
     • Directoryframes/ the framing collection

       • …
     • Directoryspecs/ the units, grouped one level deep

       • …

3. Set who you are

   Run whoami. It offers the roles your framework installed, then calibrates the one you pick on three axes: what you own on this root, your experience with the scope, and your technical capacity.

   It writes _eidos/me.md, which is personal and gitignored. The agent reads it before acting to decide how to respond — vocabulary, depth, what to surface, and who decides what. Blank is fine; it defaults to full facilitation.

   Note

   This is a two-minute step people skip. Don’t. It’s the difference between an agent explaining things you already know and one pitched at the person actually reading.

4. Fill the frames first

   The framing collection holds the blueprints describing what the whole thing is — for the software seed: architecture, audience, criteria, market.

   Fill them before you write a single blueprint. They set what every other blueprint is judged against, which is why every framework is required to declare a framing collection at all.

   Fill what’s known and leave the rest. A frame left unwritten is a gap to surface later, not a failure now.

   More on frames →

5. Think one unit through

   If you already know exactly what the unit is, skip to the next step. If you have an idea rather than a decision — and that’s the normal case — run iterate first.

   It questions one rough idea until it holds still: what it is, what it isn’t, and where it sits among what’s already there. It writes no file. The output is an understanding you can stand behind, which the next step turns into a blueprint.

   The step that gets skipped

   A blueprint authored straight from one line of prompt reads as settled while nobody has decided anything. The cost shows up later as scope no one agreed to.

6. Write your first blueprint

   Invoke the eidos skill and talk through one unit of the thing.

   It reads your framework for the Schema, the naming convention, and the target collection’s flavors; generates frontmatter from the properties that apply; and shapes the body to the flavor you chose. Start on the light flavor (micro in the software seed) — a blueprint grows into the fuller one when the fuller sections earn their place.

   Two things decide whether the blueprint is any good:

   • Lead with the shape’s opening section. In the software seed that’s ## Intent — why this exists, and who has the problem. It is the blueprint’s stable part. If Intent changes substantially, you have a different blueprint, not an edit to this one.
   • Press hardest on the non-goals section. ## Out of Scope is the section the standard leans on most, because it’s where scope management actually happens. Write it first, not last. Why →

   The agent will not do this part for you

   By design. It formats, supplements, asks, and presses on scope — it does not invent a blueprint’s purpose or hand you a finished blueprint to rubber-stamp. When it’s unsure, it asks, and the right response is an answer rather than “you decide”.

7. Regenerate the index and commit

   Run the index skill to rebuild each collection’s index.md — the generated leaf listing its blueprints with their one-line summary.

   Then commit the whole root, _eidos/ and all. The only file that stays out is the personal me.md, which the seeded .gitignore already handles.

   git add Blueprint
   git commit -m "add product blueprints"

   Don't gitignore any of it

   Eidos relies on git history for the audit trail it deliberately does not duplicate in frontmatter. A gitignored root loses the thing that makes it trustworthy.

From here

Review the root in pull requests alongside the code it describes. When it has enough shape to be worth seeing spatially, run canvas to generate an Obsidian map of it — each collection a group, each connects_to link a directed edge.

• Writing a Blueprint — the mechanics, in detail.
• Shaping Your Framework — when a seed stops fitting.
• Skills — all nine, and when to reach for each.