Skip to content
EidosDocsRegistry

Templates & Variants

A template is the body

Section titled “A template is the body”

A template is the sections a blueprint carries: in order, under set names, each with guidance. Body only; frontmatter is generated from the Properties table, and a template that carries any is a fault.

One file per template in .eidos/templates/, named <unit>.<variant>.md: the word for one of the collection’s blueprints, then the variant.

  • Directory.eidos/templates/
    • spec.full.md
    • spec.micro.md
    • frame.architecture.md
    • frame.audience.md

Variants

Section titled “Variants”

A collection’s templates are variants of one family. One is the default. What flexes between them is which sections appear, never their order or names.

The software seed’s two spec variants:

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 are getting, what it will not do. Testing and dependencies can wait; scope cannot.

A blueprint on a non-default variant says so in frontmatter, variant: micro. Absent means the default. Validation checks a blueprint against the variant it names, so a lighter variant is never faulted for sections only a fuller one has.

Growing a blueprint

Section titled “Growing a blueprint”
  1. Write it as micro early, when there is more question than answer.
  2. Add the fuller sections as they earn their place: a real dependency, a decision actually made.
  3. Set variant: full (or drop the property) once it has grown into it.

Two conventions

Section titled “Two conventions”

One template family per collection. If half your specs need different sections, that is a variant or a different collection, never a second template smuggled into the same one.

A template documents its own conventions. Section names, their order, and any labelling live in the template file. The standard governs collections, templates, variants, and properties; it never governs a section. That is why ## Intent appears nowhere in EIDOS.md: it is the software seed’s word.

What a template file looks like

Section titled “What a template file looks like”
.eidos/templates/spec.micro.md
# {{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._


## Behaviors & Acceptance Criteria


_What it does, as observable outcomes. Label each **AC1:**, **AC2:**, …_


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


## Out of Scope


_Explicit non-goals. The first thing to write, not the last._

{{title}} is the only placeholder. The italic lines are guidance to delete as you fill each section in.

Top-level docs have no template

Section titled “Top-level docs have no template”

A top-level doc (a Vision, a Roadmap) is one of a kind: written once, revised in place. No template, no variants, no validation. A template earns its keep by being stamped again.

In the CLI: eidos new --variant <name> renders the body from that template; eidos check reports the sections it declares and the body lacks.

Next

Section titled “Next”