Documentation

Creating provider-agnostic context

A provider-agnostic file describes intent: what the guidance is, who it is for, and when it applies — using canonical activation rather than a provider field such as applyTo or paths.

Stemma does not write this for you

You supply the knowledge. Stemma compiles its delivery. Nothing on this page is generated, summarised or rephrased by the tool.

Every canonical file needs front matter#

A canonical entity file must open with a --- block. A missing or unterminated block is a diagnostic naming the file (STEMMA2003), never a silently empty entity. This is a rule of the canonical reader, not of Markdown in general: an ordinary provider file may legitimately have none.

Present fields must have their expected type. Textual metadata is a string, enabled is a boolean, and tool lists and activation patterns are a string or a list of strings — the single-string shorthand still works. A wrong type, including null, is a blocking STEMMA1101 that names the key, the expected type and the type found. Omitting an optional field is fine; a malformed value is not read as an omission, so bad metadata can never become always-on context or quietly drop a tool restriction.

The same check applies to values imported from a provider. What it does not touch is extensions: each provider entry under it must be a mapping, and the values inside stay opaque and may be of any supported YAML type.

Always-on context#

Guidance that belongs in every request: the shape of the system, the vocabulary of the domain, the commands that build and test it.

.stemma/context/architecture.md

---title: Repository architecturekind: architectureaudience: agentactivation:  type: always---The service is a modular monolith.HTTP handlers call services; services call repositories.

kind is only assigned when there is a structural reason for it — a documented foundation filename, or an exact match in the known-headings table. Stemma never infers a kind from prose, so other is a perfectly normal value. The full set is:

producttechnologyarchitecturestructuredomainconventionssecuritytestingoperationsother

Path-scoped context#

Guidance that only matters when particular files are in scope. Patterns are repository-relative and use forward slashes.

.stemma/context/api-boundary.md

---title: API boundary validationkind: conventionsaudience: agentactivation:  type: path-scoped  include:    - src/api/**    - src/handlers/**---Validate every request body at the boundary.Return `application/problem+json` for errors.

Rules#

A rule is one actionable instruction with a priority. The body before any recognised heading is the instruction — the only part an agent ever sees. ## Rationale, ## Good examples and ## Bad examples stay for people and never cost a context token.

.stemma/rules/validate-external-input.md

---title: Validate external inputpriority: mustenabled: trueactivation:  type: path-scoped  include:    - src/api/**---Validate all external input before it reaches the domain layer.## RationaleBoundary validation keeps domain services deterministic and testable.## Good examples- Reject an invalid request before invoking a service.## Bad examples- Passing an unchecked request body into a repository.

Who sees what

Only the main instruction is necessarily agent-facing. For a context document, an audience of human keeps the whole file out of agent-facing output; for a decision record, only agentConstraints is normally projected. A test in the compiler enforces that human-only parts never leak into generated files.

Procedures, skills and agents#

Procedures are ordered, invocable workflows. Copilot has a native prompt file format for them; the other targets deliver them as skills, which is reported as adapted.
Skills are reusable on-demand capability documentation, with optional allowedTools and an invocation policy. All four implemented providers support them natively.
Specialist agents carry tools and a model preference as opaque provider metadata. Stemma never translates tool or model names between providers: crossing providers with a tool list is lossy, and STEMMA3301 asks a human to check the names.

What your files are named, and what Stemma names#

In .stemma/ the filename is the entity's slug: rule.api-validation lives at .stemma/rules/api-validation.md. In generated provider output the fallback filename is the complete canonical ID, including its type prefix — that same rule reaches Copilot as rule-api-validation.instructions.md. A filename or directory preserved from an import, or pinned in a profile, still takes precedence over it.

That is what lets two entities share a title without being merged, including entities of different types. If two mappings still resolve to one destination — or one wants a file where another wants a directory — every affected mapping is blocked with STEMMA6001 and exit code 6. Independently emitted files are never concatenated or silently overwritten.

A regenerated skill uses its directory as the front matter name, as the Agent Skills specification requires, so a changed invocation name is reported as adapted and explained in its mapping.

Keep provider syntax out of canonical prose#

Provider fields belong to generated output or to preserved provider extensions — never to the canonical file you author. Activation and paths covers the canonical alternative in full.

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