Keep your context through the next migration

• Want the shortest path? Follow the v0.4.0 quick start to scan, import, review and apply.
• Moving to another agent? Follow the provider migration guide, from inventory to reviewing the destination files.
• Already using Stemma? Find daily edits, additional agents, profiles and CI.
• Starting with no existing context?Initialize a project and author your first instruction.
• Looking up a flag? The command reference covers all nine commands, prerequisites, defaults and file effects.

Stemma migrates repository context. You still review differences in provider capabilities and test the result with the destination agent. It does not transfer licenses, conversations or personal settings.

The canonical project is a directory of ordinary Markdown files with structured metadata in front matter. Entities are Markdown because almost everything in them is Markdown: holding multi-line prose inside JSON strings would make the file you are supposed to edit the least pleasant one in the repository.

.stemma/├── project.json      # name, targets, token budgets├── context/          # architecture.md, testing.md, …├── rules/            # api-validation.md, …├── procedures/├── skills/├── agents/├── decisions/├── profiles/         # <target>.json — delivery, never truth├── provenance.json   # where each entity came from└── manifest.json     # files generated, or verified at import

The file name is the entity's slug, so the filesystem mirrors the entity ids: rule.api-validation lives at .stemma/rules/api-validation.md.

Markdown entity files

One file per entity, named after its id. The body is the content a person edits; nothing about it is machine-owned.

Front matter

Structured delivery metadata in a restricted YAML subset — no tags, anchors or aliases.

provenance.json

Where every imported entity came from: source format, path, hash, byte and line span, and how it was handled.

manifest.json

What Stemma generated, with hashes, so it can tell an untouched file from one you edited.

profiles/<target>.json

Delivery decisions for one target: include or exclude, activation, destination, accepted diagnostics. Never canonical truth.

Six entity types cover what repository guidance actually contains. Each has a stable id of the form <entityType>.<slug>, an activation, provenance and provider extensions.

• Context document — durable prose guidance, with a kind and an audience of agent, human or both. A human-audience document is never projected into agent-facing output.
• Rule — a single actionable instruction with a priority of must, should or may. Only the instruction is necessarily agent-facing; rationale and examples stay for people.
• Procedure — an ordered, invocable workflow.
• Skill — reusable on-demand capability documentation.
• Specialist agent — name, description, instructions, tools and model preference, treated as opaque provider metadata. Stemma never translates tool names between providers.
• Architecture decision — normally only its agentConstraints reach an agent; the rest is human documentation.

Content Stemma refuses to interpret is preserved verbatim as an opaque block, with its provider, source path, span, hash and a human-readable reason. Unrecognised front matter keys survive as extensions.<provider>.<key> and are re-emitted when exporting back to the same provider.

• Quick startScan, import, review and compile your first canonical project.
• MigrationMigrate between supported providers, review the conversion and manage the transition.
• Command referenceEvery command, its flags, defaults, prerequisites and file effects.
• Canonical contextAuthor provider-agnostic context, rules, procedures and skills.
• Activation and pathsThe four activation types, glob syntax and what excludes cost you.
• Workflow and CIDaily edits, multiple agents, new projects, profiles, CI and conflict recovery.
• ProvidersHow canonical concepts lower into each provider, and where they lose fidelity.
• DiagnosticsProjection outcomes, diagnostic codes and how acceptance works.

Source of truth for this page: docs/canonical-model.md ↗