Templates & Variants

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

A collection’s templates are variants of one family. One may be the default, marked default: true, and a group may name its own with default_variant. 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 new blueprint starts from its group’s default, else the collection’s, and eidos new writes the variant into its frontmatter, variant: micro. A blueprint without the key follows the same order. With no default at either level you pick one, and a blueprint with no variant there is a gap check reports. Validation checks a blueprint against the variant it follows, so a lighter variant is never faulted for sections only a fuller one has.

variants:
  - { name: full, template: templates/spec.full.md, default: true }
  - { name: micro, template: templates/spec.micro.md }
grouping:
  label: Domains
  groups:
    - { name: ideas, description: rough ones, default_variant: micro }

Moving a blueprint to another group never changes its variant. Before Eidos 5.5.0 a collection marking no default took its first variant; eidos migrate marks it, so the root reads as it did.

Required sections

A section is either required or there for when it is wanted. A new blueprint starts with its required sections alone, and the rest are added as the work earns them: the reader draws each one the blueprint lacks greyed in its place, with a + that adds it, default content and all. Switching a blueprint to a fuller variant shows what that variant adds the same way.

Required is the CLI’s, not the standard’s. A template marks a section with an empty region of the CLI’s in the section’s own body, which the template builder’s Required switch writes:

## Intent

_Why this exists._

<!-- eidosmd:required -->
<!-- /eidosmd:required -->

A template that marks no section reads as every section required, as templates did before. A root made from a seed starts with Intent required. eidos check reports a required section the body lacks (section-missing), and a section the template only offers when the root turns it on (eidos setup --warn-missing-optional-sections on).

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.

Leave it out, don't leave it empty

A full spec with five empty headings is worse than a micro spec that is complete, because it implies you considered things you didn’t. Omit a section that does not apply.

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

.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 line under a heading is that section’s intent: what belongs there. It stays in the template, where an agent reads it; a new blueprint starts without it, and the reader shows it behind a ? beside the heading. A comment at the head of the template stays there too.

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, its required sections alone; eidos check reports a required section the body lacks.

Next

• Properties
• Shaping Your Framework