Skip to content
EidosDocsRegistry

Collections & Blueprints

Collections

Section titled “Collections”

A collection is a folder at the root holding blueprints of one kind that share a body template. The framework declares each one under folders with owned_by: "@eidos/collections", the one kind of folder the standard owns. Eidos names none of them: specs, chapters, investigations, decisions are all your framework’s words.

A collection is flat or grouped. Grouped, it holds its blueprints in one level of sub-folders, every one a declared group, and a group holds blueprints and nothing deeper. It may also declare a property naming the grouping (domain in the software seed). The value matches the folder name exactly; an unknown value warns rather than blocks.

  • Directoryspecs/
    • Directoryplayback/ a group
      • watch-a-video.md
      • resume-playback.md
    • Directorychannels/
      • subscribe-to-a-channel.md

A file inside a collection that is not markdown is not a blueprint. Files that blueprints link to belong in a folder of your own at the root, declared with no owner (the seeds ship one named assets), or in a folder a tool owns and keeps for you.

Blueprints

Section titled “Blueprints”

A 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 template


## Intent
…

The frontmatter is the agreement; the body is guidance. Properties are checked against the framework’s Properties table. Body sections are recommended: a missing one is noted and offered, never refused.

Frontmatter is generated from the properties that apply to the blueprint’s collection, so a new blueprint is born conforming and a property scoped to one collection never lands in another.

One blueprint, one unit

Section titled “One blueprint, one unit”

The hard question is always “is this one blueprint or two?” The test lives in the template: a template names its own stable part. In the software seed that is ## Intent. If the why changes substantially, you have a new blueprint. If only the behaviors change, you have an edit.

Blueprints are not tasks

Section titled “Blueprints are not tasks”

No work-tracking fields. No sprint, estimate, or assignee. Add them and a blueprint becomes a task and rots. Link to a tracker instead. The same holds in the body: how you mean to build a thing is intent; how far along you are is work tracking. Why →

Referencing other blueprints

Section titled “Referencing other blueprints”

Links, not bare names, in prose and properties alike. The id is the permanent identity behind the link.

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

Quote a link in YAML: a leading [ starts a list otherwise. If the target has no blueprint yet, name it plainly rather than fabricating a link.

The two ways a blueprint goes wrong

Section titled “The two ways a blueprint goes wrong”

It reads like a form. Every section present, none with a judgment in it. If a blueprint reads like filled-in boilerplate, reshape it until it reads like someone wrote it. Leave a section out when it does not apply.

It has no non-goals. ## Out of Scope is where scope is held, and the first section to go empty when nobody owns the root. Why →

In the CLI: eidos list and eidos show <id> read; eidos new <collection> "<Title>" scaffolds; eidos check reports a blueprint whose group and folder disagree.

Next

Section titled “Next”