Documentation

Activation and paths

Activation is an exhaustive tagged union with four cases. The zero value is invalid on purpose: a forgotten assignment is a validation error, not an accidental "always-on".

always#

Loaded into every applicable request. It has no include or exclude patterns, and fields that do not belong to the tag must be empty.

yaml

activation:  type: always

path-scoped#

Loaded when matching files are in scope. It requires at least one include pattern; exclude is optional.

yaml

activation:  type: path-scoped  include:    - apps/web/src/**    - libs/ui/**  exclude:    - "**/*.spec.ts"

Glob patterns and what they match
Pattern	Matches
`src/api/**`	Everything under src/api, at any depth.
`src/api/*.ts`	TypeScript files directly inside src/api.
`*/.spec.ts`	Every spec file in the repository.
`apps/web/src/**`	One workspace package inside a monorepo.
`src/*/.{ts,tsx}`	Both extensions. The group is expanded into two patterns before anything else.

Patterns are repository-relative and always use forward slashes, on every operating system. A pattern that is invalid, or that would escape the repository, is a validation error (STEMMA2101).

Brace groups are expanded, not passed on#

A brace group such as {ts,tsx} is expanded into separate patterns when it is imported, and again before every projection — including patterns you write by hand in .stemma/ or in a profile. The canonical model therefore never carries a brace, and no provider has to agree with Stemma about what one means.

yaml

activation:  type: path-scoped  include:    - "src/**/*.{ts,tsx}"

src/**/*.tssrc/**/*.tsx

Braces inside a character class, such as [{], are a literal brace and are preserved.
Expansion is bounded: 1000 alternatives per pattern and 32 nested groups. Beyond either bound the import is rejected with a blocking STEMMA2102 rather than partially expanded — split the pattern into smaller groups.
A literal comma stays valid canonical input, but Copilot's comma-separated applyTo list cannot express it. That mapping is lossy with STEMMA3102 and a scope note in the file body.

Excludes are canonical, but no provider can express them

exclude belongs to the canonical model. None of the implemented providers has negative pattern syntax, so Stemma writes the exclusion as a human-readable scope note in the file body and reports STEMMA3101. It never silently widens the scope, and never calls the result exact.

on-demand#

Loaded only when explicitly invoked. Providers represent this through prompt files or skills, and Kiro through its manual and auto inclusion modes.

yaml

activation:  type: on-demand  invocationName: release-check  trigger: Use when preparing a tagged release

documentation-only#

Never emitted into agent-facing context. Useful for human rationale and decision records that should live beside the guidance without consuming a context window.

yaml

activation:  type: documentation-only

A target profile can override the activation, which makes that decision explicit and visible rather than implicit.

Do and don't#

activation:  type: path-scoped  include:    - src/api/**

Canonical activation. Every target derives its own mechanism from this.

Don't

applyTo: src/api/**paths:  - src/api/**

applyTo and paths are provider fields. They belong to generated output, or to preserved provider extensions — not to canonical prose.

What each provider does with a canonical scope is covered in provider translation.

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