Skip to content

Spec files in your repository

What a publish writes: one canonical YAML file per live artefact under the project's spec folder, a generated README.md index and one commit per task.

The layout

A publish writes one file per live artefact under the project's spec folder, .specsgraph/ unless you chose another path:

.specsgraph/Text
.specsgraph/README.md                                  generated index by group and kind
.specsgraph/subdomains/<name>.yaml
.specsgraph/bounded-contexts/<context>/context.yaml
.specsgraph/bounded-contexts/<context>/aggregates/<name>.yaml
.specsgraph/bounded-contexts/<context>/value-objects/<name>.yaml
.specsgraph/bounded-contexts/<context>/enums/<name>.yaml
.specsgraph/bounded-contexts/<context>/{use-cases,event-handlers,scheduled-jobs}/<name>.yaml
.specsgraph/bounded-contexts/<context>/{data-contracts,read-models,integration-events,terms}/<name>.yaml
.specsgraph/bounded-contexts/<context>/{decisions,constraints}/<name>.yaml
.specsgraph/{use-cases,event-handlers,scheduled-jobs,data-contracts,read-models,integration-events}/<name>.yaml
.specsgraph/features/<title>.yaml
.specsgraph/glossary/<name>.yaml                      project-wide terms
.specsgraph/roles/<name>.yaml
.specsgraph/{decisions,constraints}/<name>.yaml       project-wide decisions and constraints
  • Names become lower-case slugs.
  • Paths are fixed at the first publish. Renaming or moving the artefact keeps its file's path.
  • Archived artefacts lose their file. The file is deleted by the publish that archives it.
  • Two artefacts never share a file. The second gets a -2 suffix. If a render would still collide, the publish is blocked (render collision) and names the files.

One file per artefact

Each file is the artefact exactly as spec_get returns it from Main: spec format 1 YAML with kebab-case keys, starting with spec-format, kind and id. Members keep their ids, and references are ids.

.specsgraph/bounded-contexts/ordering/aggregates/order.yamlYAML
spec-format: 1
kind: aggregate
id: 01890000-0000-7000-8000-000000000003
name: Order
bounded-context-id: 01890000-0000-7000-8000-000000000002
summary: One order.
invariants:
  - id: 01890000-0000-7000-8000-0000000000a1
    text: Has lines.

Rendering is deterministic: the same spec gives the same bytes (UTF-8, LF line endings, one trailing newline, no timestamps), so a diff shows only what changed.

README.md

The generated README.md lists every artefact by group (Domain, Behaviour, Contracts, Product, Architecture) and kind, with links to the files, and says the folder is generated. Terms are listed under Domain, and the Interfaces group keeps the heading Contracts. Edits made to it in Git are kept as they merged.

The commit

Each publish is one commit. The body lists what changed per kind: + added, ~ changed, - removed. Trailers name the task, the workstream and the person who published it.

Commit messageText
spec: T-4 Reserve stock on checkout

Aggregates
  + Money
  ~ Order

Use cases
  + Place order

Spec-Task: T-4
Spec-Workstream: WS-2
Spec-Published-By: Kofi <kofi@example.com>
Co-authored-by: Ana <ana@example.com>

A task with a tracker key is committed as spec(KAN-43): T-4 Reserve stock on checkout with a Refs: KAN-43 trailer. The body also lists the decisions of the task's answered questions as Decision: lines; see Threads and questions.

Edits made in Git

Edit the spec in SpecsGraph, not in the folder. The folder is the output of publishing; SpecsGraph does not import changes made to it.

When a task lands, SpecsGraph notices any artefact file whose content differs from what it wrote and records it. The next publish that would overwrite that file is blocked (files changed in the repository) and names it, until an Admin chooses Overwrite. See Blocked reasons.

Next steps