Composition

Composition

Personas can extend a base and mix in overlays. This lets you build focused personas and compose them into specialized variants without duplicating content.

Declaration

In persona.toml:

extends = "base-persona@^1"
mixin = ["company-style@2.x", "safety-overlay@1.x"]

• extends -- A single base persona. The root persona inherits everything from the base.
• mixin -- An ordered list of overlays applied after the base.

Resolution order

base (extends) → mixin[0] → mixin[1] → ... → root persona

Each layer adds or overrides content from the previous layer. The root persona always wins.

Conflict detection

When two layers declare a rule or skill with the same id, the composer detects the collision and emits a Conflict record. The last-write-wins policy applies (later layers override earlier ones), but the conflict is logged for audit.

Conflicts surface at install time, not at render time. You see them before anything activates.

The composer

The frameshift-compose crate implements the merge:

1. Load the root persona source.
2. Resolve extends to a local path (via LocalResolver).
3. Resolve each mixin to a local path.
4. Merge layers in order: base -> mixins -> root.
5. Detect and report conflicts.
6. Return the ComposedPersona with the merged source and conflict log.

Use cases

• Company overlay. A company-style mixin that adds your team's naming conventions, commit message format, and CI requirements to any persona.
• Safety overlay. A safety-overlay mixin that adds L1 hard constraints across all personas.
• Specialization. A rust-crypto persona that extends rust and mixes in cryptographic for Rust projects with crypto code.

Limitations

• Composition is resolved at install time, not at runtime.
• Circular extends chains are rejected.
• Mixin order matters -- later mixins override earlier ones on ID collision.