Skills and add-ons roadmap: complete lifecycle foundations before Librarian

[yaacovcorcos]

Goal

Build the smallest durable path from the merged Scient Skills foundation to project skills, personal skills, managed add-ons, and eventually Librarian.

PR #161 established the canonical Skills architecture. This issue owns the active sequence so implementation plans do not drift into repository scratch documents.

Architectural invariants

• A skill is immutable data, not executable authority.
• Activation and invocation remain separate.
• Built-in, personal, project, add-on, and provider-native origins remain distinct.
• Project activation uses exact release references and remains zero-write until the user acts.
• Add-ons reuse the canonical skill release, policy, session, and MCP delivery system. They must not create a parallel SkillCatalog or skill transport.
• Provider-native skills remain provider-owned compatibility surfaces.
• Running turns retain their immutable skill snapshot while later turns observe updates.
• Initial add-ons do not execute arbitrary in-process JavaScript or mount custom React surfaces.

Phase 1: project skill management

Complete the already implemented project lock and trust foundation with a compact project-facing management surface.

• Show the current .scient/skills.lock.json state.
• Add or remove exact Scient skill releases through explicit user actions.
• Review and trust the current exact lock.
• Revoke trust.
• Present invalid, changed, or untrusted lock diagnostics clearly.
• Keep provider-native and repository-discovered skills outside this Scient-managed surface.

Acceptance

• Opening a project performs no writes.
• A changed lock invalidates the previous trust receipt.
• Writes are atomic and exact-release based.
• Current turns keep their original snapshot.
• Focused server, contract, and client tests cover forward and reverse states.

Phase 2: personal skill import and authoring

Create one staged validation and installation pipeline for both user imports and agent-authored skills.

• Import valid SKILL.md or ordinary Markdown as bytes, not host paths.
• Store immutable, versioned releases in app-private storage.
• Support install, update, deactivate, delete, and recoverable removal.
• Allow optional provider-assisted conversion of ordinary Markdown after explicit consent.
• Keep authority fields, identity, version, policy, and digest Scient-owned.
• Default newly installed skills to explicit $name invocation.
• Add a separate skills:manage capability for agent installation, controlled by a default-off user setting.
• Add concise built-in Skill Authoring guidance.

Phase 3: declarative add-on lifecycle

Introduce add-ons as managed bundles of declared contributions.

• Versioned manifest with identity, compatibility, provenance, and contributions.
• Contributions may include immutable skills, tools, references, managed runtimes, and narrowly typed settings.
• Staged install, verification, activation, update, rollback, disable, and removal.
• Capability requests derived from contributions and enforced by a broker.
• First proof is a tiny skill-only add-on with no runtime or custom UI.
• Add-on-provided skills use canonical addon:{id}@{version} provenance.

Phase 4: port Librarian deliberately

Treat the existing Librarian prototype as a donor rather than a merge candidate.

1. Extract and review the provider-neutral literature package and tests.
2. Publish Librarian skills through the canonical immutable Skills system.
3. Register literature tools through add-on capabilities.
4. Add the extraction sidecar as an explicit managed-runtime contribution.
5. Add only necessary settings.
6. Verify install, update, rollback, disable, and remove end to end.

Prototype disposition

• The earlier add-ons-foundation prototype is a design donor for vocabulary, lifecycle, and contribution concepts. Its filesystem-scanning SkillCatalog and skills:activate transport are superseded.
• The Librarian mission prototype contains valuable literature clients, normalization, caching, extraction, evidence storage, skills, and tests. Its absolute-path expertise note and direct settings toggle are not the target integration.
• Neither prototype should be rebased or merged wholesale.

Deferred

• Marketplace and remote distribution
• Organization policy and collaborative skill sync
• Project-authored skill mutation
• ZIP or folder import
• Arbitrary scripts or untrusted executable add-ons
• Custom add-on UI frameworks

Each phase should land as a focused PR from latest main, update durable internal documentation with shipped behavior, and leave this issue as the sequencing record.