From candidate intent to verified activation.

The lifecycle record chain

No single “installed skill” record can answer where bytes came from, why they are authorized, what an agent loaded, and whether they helped. Spindle keeps those questions separate:

Composition vocabulary

The original composition nouns remain the machinery for authored, managed blends:

skill

A directory with a SKILL.md (YAML frontmatter name/description + a Markdown body). The canonical, authored-once unit. Kept small on purpose.

package

A pip-installable project that ships skills and advertises capabilities, declared with [tool.spindle.package]. Spindle discovers installed packages through that metadata.

distribution

A pip-installable bundle that groups packages (as ordinary dependencies) and carries surface-wide assets — doctrine, channels, profiles — declared with [tool.spindle.distribution].

channel

A versioned (scope × harness) manifest listing which skills a surface should receive at that scope, plus the absolutes in force and optional routing tiers.

surface

A repo or agent that consumes a blend. Carries a name, a harness, an autonomy mode, one or more app-class clusters, and a target model.

profile

A data-driven, versioned renderer. A harness profile sets dialect; a model profile sets density. Each names a transform: identity, terse, trim, or llm.

blend

The resolved skill subset for one surface — the composition — together with the absolutes in force and a record of every override (shadow). The thing that actually lands.

doctrine

The versioned first-principles set (preferences, absolutes, meta-principles) that skills are checked against. One coherent frame per distribution.

The bind composition pipeline

spindle bind <repo> --harness claude runs six stages. It is a fail-closed pipeline: if rendering drops a guardrail or the lint finds a problem, nothing is materialized (unless you pass --force).

01 · Classify

02 · Select

The surface subscribes to an ordered list of channels, least- to most-specific: (system, system), then one (cluster, <key>) per cluster, then (repo, <name>). Each resolves to a file on disk under the active distribution's source_dir:

channels/<scope>/<name>/<harness>/channel.toml

The harness is applied here: a Claude surface only ever reads the claude/ manifests. Missing manifests are simply skipped — a surface legitimately has only a system channel. A channel manifest is small:

# channels/system/system/claude/channel.toml
version = "0.1.0"
absolutes = ["A1", "A2"]        # doctrine ids in force at this scope
skills = ["clarify", "design", "tasks", "review"]

[tiers]                         # optional routing hints (advisory)
clarify = "judgment"
design  = "judgment"
tasks   = "judgment"
review  = "judgment"

03 · Resolve

Resolution merges the selected layers into one Composition. Each skill occupies a slot keyed by its command (falling back to its name); a more-specific layer overrides a less-specific one for the same slot, and every override is recorded as a shadow rather than silently dropped. Absolutes are unioned across all layers and never lost to precedence — the guardrail floor only rises. The default precedence is system → cluster → repo.

05 · Lint

With the blend assembled (and already rendered), the linter runs pure coherence checks over its metadata: no two skills may claim the same command, no skill may appear twice, and a genuinely irreversible skill must carry the matching absolute. Problems stop the bind unless forced. The linter inspects structure, not prose — which is why the guardrail check lives in rendering (below), not here.

06 · Materialize

Then it records the binding: a stable coordinate over the skills, the doctrine, and the channel versions, appended to a per-surface history so any prior coordinate is a rollback target. spindle unbind reverses it, removing exactly the links Spindle owns.

Startup and activation

Materialization is desired state, not proof of what a running harness saw. Before discovery, spindle bootstrap resolves active adoptions and leases, inventories every observable scope, compares exact content identity, and plans any ownership-safe repair. The portable spindle launch wrapper performs that work before starting Claude or Codex.

Stable native hooks then recheck session start, resume/compaction, and subagent start. Hook definitions contain no mutable pins: they invoke the same Spindle bootstrap command while desired state stays in the surface lock. The normal hook path is local and cache-only, emits one compact status marker, and keeps full findings in a startup receipt.

A pre-discovery mismatch can be repaired only when exact ownership matches. The same mismatch found after discovery returns restart-required. Foreign state is preserved in both cases.

Rendering & profiles

Selection decides which skills; rendering decides what text each one becomes for this surface. Because rendering produces new text, its output can't be a symlink — it's written to a content-addressed store and the blend is repointed at it. Two profile axes compose, dialect then density:

Profiles are tiny, versioned TOML files:

# profiles/claude/profile.toml — harness dialect
version = "1"
transform = "identity"

# profiles/models/frontier/profile.toml — model density
version = "1"
transform = "trim"
tier = "frontier"

<!-- scaffold:examples -->
Worked example a smaller model benefits from…
<!-- /scaffold -->

Doctrine

Doctrine is the coherent first-principles frame, kept as a versioned, hand-editable, machine-readable TOML artifact. It has three entry kinds:

• preferences — "favor X over Y," scoped, with a note and provenance.
• absolutes — ALWAYS/NEVER hard rules, scoped and rare; densest at system scope.
• meta-principles — rules about how the other principles are written.

# doctrine/doctrine.toml (excerpt)
version = "0.1.0"

[[preference]]
id = "P1"
scope = "system"
favor = "clear acceptance evidence"
over  = "performative process"

[[absolute]]
id = "A2"
scope = "system"
mode = "NEVER"
statement = "fabricate missing facts"

The safety floor

Two mechanisms make it structurally hard to compose away safety. First, absolutes accumulate: because resolve unions them across every layer, a narrow channel can add a guardrail but never remove one. Second, rendering verifies preservation:

Every guardrail clause in a skill's source must survive, normalized, in the rendered output — or the bind fails closed.render.verify_preserved

Guardrail clauses are lines matching ALWAYS, NEVER, MUST NOT, or DO NOT. The coherence linter reads metadata and can't catch a paraphrase that quietly drops one — so this deterministic check is the backstop, and it holds even when an llm profile ignores its instructions. A dropped clause raises an error and the binder materializes nothing.

Determinism & caching