εἶδοςeidos, noun — from ἰδεῖν, to see

The form or essence of a thing.

Plato used it for the eternal Form; Aristotle for what makes matter into a particular thing. Eidos is a markdown standard for writing that form down.

One file is the complete source of truth for one unit of what you're building. Define it against an established standard, in plain Markdown files, stored on whatever system you want. You own your data and the output.

Read the documentation

Blueprints/specs/playback/resume-playback.md

---
id: resume-playback
title: Resume Playback
summary: Returns a viewer to the exact second they stopped.
status: In Progress
domain: playback
connects_to:
  - "[Watch History](../channels/watch-history.md)"
---

# Resume Playback

## Intent
A viewer who leaves mid-video should not have to
hunt for their place when they come back…

## Behaviors & Acceptance Criteria
- AC1: Position is stored per viewer, per video.

## Out of Scope
- Cross-account resume. A shared TV is one device,
  not one person.

Frontmatter is the agreement. The body is the shape. Both live in git.

Product knowledge rots

It scatters into tickets that close, wikis nobody prunes, and the heads of people who leave. Six months on, the only honest answer to “what is this thing supposed to be?” is a meeting.

One file, one unit

A single markdown file is the complete source of truth for one unit of the thing. No partial record scattered across a wiki, a ticket, and someone’s memory.

What it is, not the work

A task describes work and dies when the work ships. A blueprint describes the thing, and stays accurate across its whole life: before it exists, while it’s built, after it’s retired.

Plain markdown, in your repo

The folder sits next to the code it describes and is reviewed in pull requests. No SaaS, no lock-in, no hidden state.

The form is portable

A framework — collections, shapes, schema, roles — is the piece one team hands to another. One framework, any number of roots.

How it works

Two words carry the whole idea.

Framework: The form: the collections, shapes, roles, naming convention, and property schema that govern how you write. It lives in the hidden _eidos/ at the root, and it's the portable piece — the part one team hands to another.
Blueprint: One unit, defined completely: a single markdown file, frontmatter plus a body, that is the whole source of truth for one piece of what you're building.

Framework and blueprint, in full

Blueprints/       # the root — name it anything
  README.md       # the human "start here"
  _eidos/         # the framework — the form
    shapes/       #   body templates, one per flavor
    roles/        #   how the agent talks to each role
    Framework.md  #   index + config + schema
  frames/         # the framing collection
  specs/          # the blueprints
    index.md      #   generated leaf
    playback/
      resume-playback.md
  roadmap.md      # a top-level doc — yours

Nothing above is named by the standard

One machinery, any vocabulary.

EIDOS.md defines collections, shapes, flavors, and properties — never what any of them is called. Eidos ships three seed frameworks so you can start from the nearest one and reshape it. A framework that ends up looking like none of them is working as intended.

`software`

A product, service, or system being built.

Framing: frames — architecture, audience, criteria, market
Units: specs
Grouped by: domain
Flavors: full · micro

`book`

A book, long-form argument, or course.

Framing: frames — premise, reader, voice, market
Units: chapters
Grouped by: part
Flavors: full · sketch

`research`

A question, a study, or a programme of inquiry.

Framing: frames — question, prior work, method, ethics
Units: investigations
Grouped by: strand
Flavors: full · note

See all three, worked through

Human-first

The human authors. The agent facilitates.

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 it satisfies its own spec — everything agrees, every review passes, and nothing has been verified.

A blueprint no one thought through is worse than none.

So intent, scope, and decisions stay with a person. An agent formats, supplements, asks clarifying questions, and presses on scope. It does not author blueprints for you, and it does not set direction.

And if you're going fully autonomous — not reviewing, not deciding — then don't write blueprints at all. They'd add ceremony, not correction. When not to use Eidos →

The tooling is optional; the framework isn't. Write every file by hand if you like — but keep _eidos/ on disk, because a standard you hold in your head drifts. Where you want help, nine agent skills ship alongside it, for Claude Code, Codex, and anything else that reads a SKILL.md.

See the skills

Start with the seed that's closest.

Eidos ships three starting frameworks — one for a product, one for a book, one for a programme of inquiry. Take the nearest and reshape it until the vocabulary is yours. Everything a seed gives you is changeable later, so “close enough” is the right answer.

Quick Start Why Eidos Exists