Collections & Blueprints

Collections

A collection is a top-level folder of repeated blueprints that share a body shape. A framework declares each one in Framework.md, and Eidos names none of them — specs, chapters, investigations, decisions are all your framework’s words.

Every framework must declare a framing collection first — the loose docs saying what the whole thing is — and then at least one collection of units.

Required as a declaration, never as a gate

A framework that declares no framing collection is incomplete, and a check says so. But a declared frame left unwritten is a gap to surface, not a failure. Eidos surfaces; it doesn’t refuse. More on frames →

Grouping

A collection may group its blueprints in one level of sub-folders, and no more. It may also declare a property naming that grouping — domain in the software seed, part in book, strand in research.

When it does, three things follow:

• The property’s value matches the folder name exactly, in the framework’s naming convention.
• An unknown value warns rather than blocking. Groupings accrue; the validator is not the place to fight about them.
• The standard never names the grouping for you. It’s the collection’s own.

• Directoryspecs/

  • index.md generated — never hand-edit
  • Directoryplayback/ a group

    • watch-a-video.md
    • resume-playback.md
  • Directorychannels/ another group

    • subscribe-to-a-channel.md

The generated leaf

Each collection carries an index.md listing its blueprints, rebuilt wholesale by index. Each line is that blueprint’s summary, verbatim — a blueprint with none is flagged, never invented. More on generated leaves →

Blueprints

An blueprint is one markdown file defining one unit completely. Two parts:

---
id: resume-playback            ← frontmatter: the agreement
title: Resume Playback
summary: Returns a viewer to the exact second they stopped.
status: In Progress
domain: playback
---

# Resume Playback                ← body: the shape

## Intent
…

The frontmatter is the agreement; the body is guidance. That one line sets what happens when something is wrong. Properties are checked against the framework’s Schema. Body sections are recommended structure — a missing one is noted and offered, never refused.

Frontmatter is generated, not typed

It’s generated per blueprint from the properties that apply to that blueprint’s collection. A new blueprint is born conforming, and a property scoped to one collection never lands in another where it makes no sense.

One blueprint, one unit

The hard question is always “is this one blueprint or two?” Eidos gives you a test, and it lives in the shape rather than the standard:

A shape names its own stable part

Every shape has a part that holds still and a part that moves, and says which is which. If the stable part changes substantially, ask whether this is a different blueprint.

In the software seed the stable part is ## Intent. So: if the why changes, you have a new spec. If only the behaviors change, you have an edit. That’s a concrete test you can apply in a code review, which is the point.

Blueprints are not tasks

The convention people most often try to work around:

No work-tracking fields. No sprint, estimate, or assignee — the moment you add them, a blueprint becomes a task and rots.

Bridge to a tracker with a link. The same holds in the body: a section describing how you mean to build a thing captures intent; a section describing how far along you are is work tracking, and dies on the same schedule as the ticket. Why this matters →

Referencing other blueprints

Reference other blueprints with links, not bare names — in prose and in properties alike. The id is still the permanent identity, sitting behind the link.

depends_on:
  - "[Watch a Video](../playback/watch-a-video.md)"

Quote them in YAML: a leading [ starts a list otherwise. And only a Title Case root carries %20 — the other two conventions are space-free.

If a target has no blueprint yet, name it plainly rather than fabricating a link.

The two ways a blueprint can go wrong

Both are worth naming, because they fail differently.

It reads like a form. Every section present, every section empty of judgement. The standard is explicit about this: if a blueprint reads like filled-in boilerplate, reshape it until it reads like someone wrote it. Leave a section out when it genuinely doesn’t apply rather than leaving it filled with nothing.

It has no non-goals. The Out of Scope section is the one the standard leans on hardest, because it’s where scope is actually held — and it’s the first section to quietly go empty when nobody owns the root. Why →

Next

• Shapes & Flavors — the body template.
• Schema — the frontmatter contract.
• Writing a Blueprint — start to finish.