skill lifecycle · v0.2

Try first. Adopt deliberately. Keep evidence.

Spindle replaces “install this skill and hope” with a reversible chain from intent to exact runtime behavior. Temporary use is easy; durable custody has to be earned.

A skill is more than its SKILL.md. Its effect depends on exact package bytes, the other skills a harness can see, the model actually served, available tools, policy, and whether the instructions still improve the current generation of model. Spindle keeps those facts distinct and joins them with content-addressed receipts.

inspect→ try / borrow→ compose→ bootstrap→ activate→ evaluate→ adopt / release

The harness is the front door

spindle harness setup --harness codex --here or its claude counterpart projects a minimal, versioned operator into the harness's native project-skill directory. Invoke it as $spindle in Codex or /spindle in Claude Code. The operator calls spindle harness context --here --json for the live surface lock, effective inventory, custody, blockers, hook heartbeat, authorization rule, and exact dry-run/apply commands. It does not carry a stale second copy of the lifecycle in model context.

When one harness launches another, inherited environment markers can name both. Spindle uses the nearest named harness process as stronger runtime evidence and otherwise fails closed for an explicit --harness. Installing the operator proves neither that a hook ran nor that another skill was activated, useful, or adopted.

Intent before authority

spindle inspect builds an intent card without importing or executing candidate code. It separates package facts from contextual fit, reports provenance, contents, authority requirements, context cost, and known evidence, and leaves the package inactive.

bash
$ spindle inspect ./candidate/review \
    --for "review this migration" --harness codex --here --json

$ spindle inspect \
    'github:owner/repository@0123456789abcdef0123456789abcdef01234567#review' \
    --harness claude --here --json

Temporary before durable

try

One disposable session

  • Exact content-addressed snapshot.
  • Read-only harness posture by default.
  • Startup, activation, run, and cleanup receipts.
  • No durable adoption.
borrow

One expiring lease

  • Overlays the actual incumbent blend.
  • Names permitted surface, harness, agents, and authority.
  • Rechecked on launch, resume, and compaction.
  • Released or expired without rewriting history.

Desired state beats ambient state

A surface lock names exact adopted and leased inputs. At startup, Spindle inventories repository, ancestor, user, administrator, plugin, and known system scopes; compares desired with observed state; and classifies every entry. It may repair or remove only a projection whose current path and target still match an immutable ownership receipt.

Foreign means preserve A user-managed directory, unowned symlink, plugin, or same-name collision is never silently deleted. A collision blocks strict startup until an exact, content-bound decision exists. Post-discovery repair reports restart-required instead of pretending the session is clean.
bash
$ spindle inventory --effective --harness codex --here
$ spindle bootstrap --harness codex --here --check
$ spindle hooks install --harness codex --scope repo --here --dry-run
$ spindle launch codex --here --

One package, agent-local realizations

Parent and child agents independently resolve from the model actually served, effort, role, harness build, effective tools, policy, and active blend. The package stays immutable: Spindle combines its invariant core with at most one evaluated overlay and writes a realization receipt. The adapter separately records whether that exact agent loaded it.

Harness mechanics belong in deterministic adapters, not in portable skill prose.Version checks, routing, permissions, startup, and receipt writing stay outside SKILL.md.

Evidence before promotion

Evaluation reports availability, activation, routing, authorization, behavior, and adapter conformance as separate gates. Named arms include no-skill, invariant core, candidate overlay, incumbent, and ablations. A smaller or empty overlay qualifies only when repeated held-out results clear a predeclared non-inferiority margin, hard floor, and efficiency threshold for the exact runtime coordinate.

Adoption is maintenance custody

spindle adopt promotes the exact bytes from a successful trial. Updates are new candidates tested beside the incumbent; they do not inherit old evaluation claims. Health reports source, package, cache, inventory, model, harness, toolset, and policy drift independently. Rollback creates a new exact decision without rewriting prior records.

bash
$ spindle adopt sha256:<lease-id> --here --dry-run --json
$ spindle update try review --harness codex --task-file task.md --here
$ spindle health --harness codex --here
$ spindle rollback review --harness codex --reason regression --here
$ spindle retire review --harness codex --reason obsolete --here --dry-run

Custody survives failure

Immutable records can rebuild mutable indexes after a crash. Deterministic state bundles import only absent or byte-identical files. Cache garbage collection uses an exact plan and protects all current locks, leases, and adoption history. Legacy migration audits preserve ambient state and never turn an old install into an adoption by inference.

Adapters are certified per build

Spindle's reference matrices fail closed on unobserved runtime facts. The checked evidence certifies Claude Code 2.1.220 and Codex CLI 0.146.0 with independently activated mixed-model parent and child agents. A new harness build, model, tool composition, policy, package digest, or active blend is a new coordinate—not permission to reuse an old claim.