Shapes & Flavors

A shape is one body template

A shape is the sections a blueprint carries: in order, under set names, each with its guidance. It never describes frontmatter — that’s generated from the Schema.

One file per shape, in _eidos/shapes/, named <kind>.<flavor>.md, lowercase and dotted.

• Directory_eidos/shapes/

  • spec.full.md the specs collection, full flavor
  • spec.micro.md the specs collection, micro flavor
  • frame.architecture.md the framing collection, one file per kind of frame
  • frame.audience.md

Flavors

A collection’s shapes are variants of one family, and each variant is a flavor. A collection declares one or more and marks one default.

What flexes is which sections appear and which flavor a blueprint uses — never their order or names within a flavor.

Here is the same collection in two flavors, from the software seed:

spec.micro	spec.full
## Intent	## Intent
### Assumptions	### Assumptions
—	### Implementation Notes
## Open Questions	## Open Questions
## Behaviors & Acceptance Criteria	## Behaviors & Acceptance Criteria
—	### Functional · ### Performance · ### Design · ### External interface · ### Quality attributes
## Out of Scope	## Out of Scope
—	## Dependencies
—	## Testing
—	## Constraints & Decisions

micro is the smallest spec worth writing: why it exists, what you’re getting, and what it will not do. It’s a starting point that grows into full as the unit firms up.

Note what micro keeps even at its smallest: Intent, Open Questions, Acceptance Criteria, and Out of Scope. Those four are what a spec is. Testing and Dependencies can wait; scope cannot.

Declaring which flavor a blueprint uses

A blueprint on a non-default flavor records it in frontmatter:

flavor: micro

Absent means the collection’s default. The default is also what gets scaffolded.

A lighter flavor is not a worse blueprint

A blueprint on a lighter flavor is never faulted for the sections only a fuller one carries. Validation checks a blueprint against the flavor it names, not against the fullest one available.

Growing a blueprint

The intended path, and the reason flavors exist at all:

1. Write it as micro early, when there’s more question than answer.
2. Add the fuller flavor’s sections as they earn their place — real dependencies, a real testing story, a decision actually made.
3. Set flavor: full (or drop the property) once it has grown into it.

Don't scaffold the full shape and leave it empty

A full spec with five empty headings is worse than a micro spec that’s complete, because it implies you considered things you didn’t. It should read like someone wrote it.

Two conventions that hold shapes together

One shape family per collection

The shape is never forked per category. If half your specs need different sections, that is either a flavor or a different collection — not a second shape smuggled into the same one. This is what keeps a collection readable as a set.

A shape documents its own conventions

Section names, their order and meaning, and any labeling the shape asks for live in the shape file. The standard governs collections, shapes, flavors, and properties; it never governs a section.

That second rule is why you won’t find ## Intent or ## Out of Scope anywhere in EIDOS.md. Those are the software seed’s words. book opens a chapter differently; research opens an investigation differently again. The machinery is identical.

What a shape file looks like

_eidos/shapes/spec.micro.md

<!--
The Spec shape — micro flavor. The smallest spec worth writing: why it exists,
what you're getting, and what it will not do. Grows into spec.full.md.
Keep the order and headings; the italic prompts are guidance — delete them
as you fill each section in.
-->

# {{title}}

## Intent

_Why this exists — the problem and who has it. This is the stable part: if
Intent changes substantially, you probably have a different spec._

### Assumptions

_What you're taking as given, not yet confirmed._

## Open Questions

_What you don't yet know and still need answered. Kept high, right after
Intent, so uncertainty is seen rather than buried._

## Behaviors & Acceptance Criteria

_What it does, as observable outcomes. If a behavior isn't listed here, it
isn't promised. Label each **AC1:**, **AC2:**, … Keep each short and checkable._

- **AC1:** <!-- the first observable outcome -->

## Out of Scope

_Explicit non-goals — the section the standard leans on hardest. It's the
first thing to write, not the last._

Three things to notice, because they’re conventions worth copying into your own shapes:

• The HTML comment at the top says what the flavor is for and what it grows into. It’s guidance for whoever opens the file next.
• {{title}} is the only placeholder; everything else is real structure.
• Italic prompts are instructions to delete as you fill each section in. They are not content.

Writing inside a shape

Keep the shape’s order and names. Beyond that, write it like a person would read it — sub-headings, tables, lists, and small diagrams wherever they make the meaning clearer.

Where a shape asks for labeling (AC1:, AC2: …), follow it: keep each checkable statement short and observable, and push supporting detail into a table or sub-section that it points at.

Leave it out, don't leave it empty

Omit a section that genuinely doesn’t apply. An empty heading claims you thought about something and found nothing; an absent one is honest.

Top-level docs have no shape

A top-level doc — a Roadmap, a Vision, the generated canvas — is one-of-a-kind: filled in once and edited in place. It gets no shape, no flavors, and no validation.

A shape earns its keep by being stamped again. A document written once doesn’t need a cookie-cutter.

That’s also the one difference between a frame and a top-level doc. Both are loose prose, revised in place. But a frame is a collection blueprint — it follows a shape, carries the frontmatter contract, and is validated. More on frames →

Next

• Schema
• Shaping Your Framework — adding a flavor.