Spec: one local RedSkills package set for the complete workstation

[filipeforattini]

Problem Statement

RedSkills is acquired, installed, cached, and refreshed differently by each AI coder and companion application. Claude Code and Codex own marketplace caches; OpenCode and RedCode consume generated trees; Pi and Hermes use skills-oriented paths; Gemini has a generated but incomplete surface; Herdr, Zellij, and the VS Code extension have separate installation routes. A single RedSkills revision is consequently cloned, copied, generated, and retained several times on the same workstation.

The first mise migration in Spec #185 established a local moving source, manifest-driven plugin entries, host refresh stamps, generator invocation, cache retention, and Directory marketplace ownership. All seven child Tickets are closed. That architecture is now insufficient: core and plugin packages still float independently, the npm runtime package is not a complete workstation distribution, a path-only refresh cannot detect in-place content changes, Gemini and Hermes cannot truthfully converge, companion integrations still bypass the canonical source, and there is no complete offline bootstrap.

An operator needs one user-global RedSkills source that every supported integration consumes, one update path through mise/red-dev, and a target-specific directory that can bootstrap a clean workstation without network access. A successful update must prove every managed surface converged without terminating active work or destroying user-owned configuration.

Solution

Introduce one coherent, versioned RedSkills package set as a single mise tool. The package set contains the complete workstation distribution: all four plugin payloads, host manifests and generators, shared runtimes, the redskilled daemon, Herdr plugin, VS Code extension, Zellij integration, and required RedSkills artifacts. Only the dev plugin is activated in the seven AI coder hosts; the remaining plugin payloads are available locally but stay inactive.

A local mise plugin acquires online revisions from one shared Git mirror, creates immutable snapshots, overlays release assets from the same commit, verifies a signed whole-set manifest and SHA-256 digests, and runs red-dev's idempotent reconciliation from a tool-level postinstall. mise upgrade red-skills and red-dev update therefore converge the same source. Development checkouts use a mise path override and explicit red-dev sync; missing same-commit assets are built into digest-keyed staging without mutating the checkout.

red-dev remains the only owner of host wiring. It installs and verifies Claude Code, Codex, OpenCode, RedCode, Gemini, Pi, and Hermes, using the richest extension mechanism each supports and skills-only fallback where richer hooks, MCP, or agent surfaces do not exist. It also installs the workstation companion applications and integrations, while preserving user configuration through dedicated includes or ownership-aware structural merges.

Add target-specific private Offline depots. A connected workstation exports mise, red-dev, the local mise plugin, exact RedSkills snapshots and assets, exact third-party installers, locks, signed manifests, checksums, and the active plus previous revisions. A clean target imports the depot into machine-owned storage with network access blocked. Initial support covers Ubuntu 24.04/26.04 x64 and a combined Windows x64 plus WSL2/Ubuntu workstation.

User Stories

1. As an operator, I want one RedSkills package set, so that every host consumes the same revision.
2. As an operator, I want mise upgrade red-skills to reconcile every managed integration, so that updating the source cannot leave hosts stale.
3. As an operator, I want red-dev update to invoke the same reconciliation, so that there is no second update implementation.
4. As an operator, I want one shared Git mirror and immutable snapshots, so that the same repository history is not downloaded repeatedly.
5. As an operator, I want package-set identity based on a whole-set digest and source commit, so that an in-place checkout update is visible even when its path does not change.
6. As an operator, I want all seven AI coder CLIs installed on a clean workstation, so that the workstation is complete after one bootstrap.
7. As an operator, I want only the dev plugin activated in AI coders, so that unrelated Memory, Brain, and maintainer behavior stays inactive.
8. As an operator, I want every plugin payload available locally, so that future activation does not require reacquiring the repository.
9. As an operator, I want Claude Code and Codex to read the same local Directory marketplace, so that their host caches are projections rather than independent Git clones.
10. As an operator, I want OpenCode and RedCode generated from the package set, so that both compatible hosts receive the same skills, MCP, hooks, provider, and TUI surface.
11. As an operator, I want Pi, Gemini, and Hermes to receive the richest integration each host supports, so that lack of a marketplace does not block shared skills.
12. As an operator, I want Herdr, Zellij, VS Code, the RedSkills runtimes, and redskilled installed from the same package set, so that companion surfaces do not drift from the coders.
13. As an operator, I want VS Code installed on a clean workstation and the extension updated in compatible editors already present, so that the visual surface is available without duplicate editors.
14. As an operator, I want third-party applications to remain separate mise tools, so that their publishers retain independent release cycles.
15. As an operator, I want exact third-party versions in the workstation lock, so that an offline bootstrap reproduces a tested combination.
16. As an operator, I want a private depot export command, so that I can prepare an air-gapped workstation from a connected machine.
17. As an operator, I want a depot import to copy state into managed storage, so that removing the USB drive or mount does not break RedSkills.
18. As an operator, I want a depot to contain no credentials, so that transporting installers does not transport my cloud identity.
19. As an operator, I want offline readiness to mean installed, synchronized, and verified, so that unavailable cloud authentication does not make the bootstrap falsely fail.
20. As an operator, I want signed manifests and artifact checksums, so that an offline import authenticates and verifies what it installs.
21. As an operator, I want active and previous revisions retained, so that rollback does not need network access.
22. As an operator, I want rollback to restore the complete workstation lock, so that it returns to a combination already verified together.
23. As an operator, I want obsolete host caches pruned only after successful verification, so that cleanup never destroys the last working revision.
24. As an operator, I want a failed host to make the operation fail without rolling back hosts already updated, so that partial state is visible and retryable.
25. As an operator, I want running coder sessions left alone and reported as restart needed, so that an update never interrupts active work.
26. As an operator, I want updates staged while Workers are active, so that the daemon and package set do not change under autonomous work.
27. As an operator, I want existing user configuration merged rather than replaced, so that adopting RedSkills does not erase unrelated settings.
28. As an operator, I want legacy marketplaces and caches removed only after adoption verifies, so that migration is conservative.
29. As an operator, I want the standalone installer redirected to the mise/red-dev bootstrap, so that only one acquisition and wiring architecture remains.
30. As an operator, I want stable, next, and exact version/commit channels, so that updates, prereleases, reproduction, and development share one model.
31. As a developer, I want a checkout override that stays live, so that I can test local source without publishing a release.
32. As a developer, I want missing checkout artifacts built into separate staging, so that sync never modifies package-manager-owned or source-controlled files.
33. As a maintainer, I want package-set manifests generated from canonical plugin metadata, so that host projections cannot silently disagree.
34. As a maintainer, I want Gemini and Hermes represented as required adapters, so that seven-host success cannot be reported while either is blocked.
35. As a maintainer, I want per-host ground-truth verification and ownership records, so that stamps describe observed state rather than attempted commands.
36. As a maintainer, I want offline E2E lanes with the network blocked, so that cache-warmed mocks cannot masquerade as air-gap support.
37. As a Windows operator, I want one combined Windows plus Linux depot, so that a single medium can provision the composed workstation.
38. As a Windows operator, I want AI coder CLIs, Zellij, Herdr, and the daemon in WSL while GUI applications stay native, so that each surface runs in its supported environment without duplicate coder installations.
39. As a Linux operator, I want Ubuntu 24.04 and 26.04 desktop depots, so that both supported distro targets receive the same guarantee.
40. As an operator, I want the installation to be user-global rather than system-wide, so that plugin state and credentials never leak across operating-system users.

Human Decisions

• Decision: Use a released package set by default and a local checkout only as a development override.
  Why: Releases must be reproducible and rollbackable while local development must remain possible.
  Alternatives considered: a mutable checkout as the only production source; release artifacts with no local override.

• Decision: Both mise upgrade red-skills and red-dev update must converge the package set and all managed surfaces.
  Why: Updating through either supported operator entry point must not leave host state stale.

• Decision: red-dev owns the single host-reconciliation implementation.
  Why: Host wiring is already red-dev's machine responsibility and must not be duplicated in package lifecycle scripts.
  Alternatives considered: moving reconciliation into RedSkills; requiring all hosts to consume live symlinks.

• Decision: Offline support includes warm-cache reinstall, plugin installation on a prepared machine, and a completely clean air-gapped bootstrap.
  Why: Offline installation must be a real provisioning guarantee, not an accidental cache hit.

• Decision: The transport is a local directory expanded into an Offline depot containing bootstrap binaries, dependencies, locks, and checksums.
  Why: A source checkout alone cannot install mise, red-dev, third-party CLIs, or their transitive dependencies on a clean machine.

• Decision: Package-set identity is a manifest containing version, source commit, and whole-set digest.
  Why: A path-only stamp cannot detect in-place source changes or independently moving plugin payloads.

• Decision: The managed AI coder set is Claude Code, Codex, OpenCode, RedCode, Gemini, Pi, and Hermes.
  Why: OpenCode remains a required managed host alongside RedCode rather than being retained but unmanaged.

• Decision: A clean bootstrap installs all seven coder hosts.
  Why: The workstation contract is complete provisioning, not merely making installers available.

• Decision: Only dev is activated in AI coder hosts, while all plugin payloads remain in the package set.
  Why: dev is the important global process surface; Memory, Brain, and maintainer-only behavior must not activate implicitly.

• Decision: Host parity means using every capability a host supports with a skills-only fallback, not fabricating full parity through shims.
  Why: The seven extension systems do not expose equivalent hooks, MCP, or agent APIs.
  Alternatives considered: skills-only everywhere; mandatory semantic parity through new compatibility shims.

• Decision: The package set includes every workstation integration: runtimes, daemon, Herdr, VS Code extension, Zellij, and required artifacts.
  Why: Solving only AI coder plugins would preserve separate acquisition and versioning for the rest of the RedSkills workstation.

• Decision: Workflows, containers, benchmarks, release tooling, and source-only developer applications are not workstation-installable targets.
  Why: Those artifacts have no coherent user-global installation operation.

• Decision: Install Herdr, Zellij, and a compatible editor on a clean workstation rather than only activating integrations when detected.
  Why: “Install everything” must hold on a clean-machine bootstrap.

• Decision: Install VS Code; also update the extension in compatible editors already present.
  Why: One guaranteed editor avoids installing multiple equivalent GUI applications.

• Decision: Represent RedSkills as one mise tool and external applications as separate tools under one exact depot lock.
  Why: Internal atomicity must not couple third-party release cycles to a monolithic RedSkills archive.

• Decision: Use configurable stable, next, and pinned version/commit channels.
  Why: The same model must support ordinary updates, prereleases, reproduction, and air-gapped export.

• Decision: Use a local mise plugin to acquire RedSkills from Git plus release assets.
  Why: A red-dev clone followed by mise link cannot make bare mise upgrade red-skills a complete update operation.

• Decision: Maintain one shared Git mirror and immutable snapshots per revision.
  Why: Repeated shallow clones still duplicate repository transfer and storage.

• Decision: A checkout overlays release assets from the same commit; missing assets are built locally into separate staging.
  Why: Development commits often have no published release, while using assets from another commit would create an unverified mixture.

• Decision: A depot import copies versioned state into machine-owned storage; a development checkout remains a direct path.
  Why: Development needs live edits, while production must not depend on removable media or a mounted share.

• Decision: Host caches are allowed, but revisions outside the active and previous locks are pruned only after successful sync.
  Why: Host internals cannot universally be replaced with symlinks, but unbounded derived copies recreate the original problem.

• Decision: Existing user configuration is preserved through includes or ownership-aware structural merge.
  Why: Replacing complete host configuration files would destroy user-authored state.

• Decision: A host failure leaves already-converged hosts in place but returns failure until every required host succeeds.
  Why: Host plugin managers do not offer reliable cross-host transactions or rollback.

• Decision: The depot is built privately on a connected machine from official sources.
  Why: The project must not assume redistribution rights for every third-party CLI.
  Alternatives considered: publicly publishing all vendor binaries; requiring each organization to assemble a mirror manually.

• Decision: Offline success excludes cloud authentication and inference.
  Why: A clean network-isolated machine cannot validate cloud credentials or service availability.

• Decision: Initial platform support is Ubuntu 24.04/26.04 x64 and Windows x64 plus WSL2/Ubuntu.
  Why: These are red-dev's current supported platform targets.

• Decision: On Windows+WSL, install all coder CLIs, Zellij, Herdr, and redskilled only in WSL; keep GUI/editor/terminal applications on Windows.
  Why: This avoids two homes, two host cache sets, and duplicate coder reconciliation.

• Decision: The combined workstation uses one depot containing both Windows and Linux artifacts and one redskilled daemon in WSL.
  Why: A single offline medium and control plane are required for a coherent workstation.

• Decision: Retain the active and previous complete workstation locks and roll back the whole lock.
  Why: Rollback must restore a combination already verified together without unbounded retention.

• Decision: Require a signed manifest, source commit, and SHA-256 for every artifact.
  Why: Checksums prove integrity; signatures authenticate the producer during offline import.

• Decision: User-global means one operating-system user across all repositories and new sessions.
  Why: Host state and credentials must not be shared system-wide.

• Decision: Never terminate running coder sessions; report restart needed after on-disk convergence.
  Why: Plugin freshness does not justify interrupting active work.

• Decision: Active Workers cause a complete update to stage and remain pending.
  Why: The active package set and daemon must not change under autonomous work, and Workers must not be killed.

• Decision: Deprecate the standalone install.sh and redirect it to mise/red-dev.
  Why: Keeping it first-class would preserve the competing acquisition and wiring architecture this effort removes.

• Decision: Adopt and back up existing installations before removing old marketplaces and caches.
  Why: Migration must verify the new source before deleting the old working state.

• Decision: Offline E2E lanes on every initial target are required for acceptance.
  Why: Clean-machine and network-isolation claims cannot be established by unit tests or mocked host CLIs alone.

Implementation Decisions

• Define a package-set manifest schema containing revision, channel, source commit, whole-set digest, platform artifacts, per-artifact checksums, signature metadata, compatible external-tool locks, and active/previous revision relationships.
• Build a local mise plugin that lists channels/versions, maintains a shared Git mirror, creates immutable installs, overlays same-commit assets, verifies trust metadata, and invokes red-dev reconciliation through tool-level postinstall.
• Keep the stable ~/.red-skills/current consumer contract, but point it at the active immutable package-set snapshot rather than at independently resolved packages.
• Replace path-only host stamps with observed state records containing package-set digest, selected plugin set, adapter mode, generated-config digest, and reload state.
• Reconcile hosts through one adapter registry covering Claude Code, Codex, OpenCode, RedCode, Gemini, Pi, and Hermes. Every adapter must plan, apply, verify, and remove only owned state.
• Read canonical plugin metadata once and validate every generated host projection before mutating any host.
• Add Gemini installation and repair its generated hook metadata. Add an explicit Hermes adapter based on its official skills/configuration contract.
• Activate only dev in coder hosts, while making every package-set payload addressable for future explicit project/plugin activation.
• Install companion integrations from package-set artifacts: redskilled, shared runtime bundles, Herdr plugin, VS Code extension, and Zellij dashboard/layout.
• Keep host applications and third-party dependencies as individually named mise tools. Resolve them into exact target locks during online update or depot export.
• Add depot export, inspect, import, and rollback operations. Export resolves every remote dependency; import performs no network request and copies state into managed storage.
• Add a digest-keyed staging builder for development checkouts. It reuses same-commit release assets and builds only missing artifacts without modifying source.
• Add an ownership manifest and structural merge layer for user-global host/editor/terminal configuration.
• Stage updates before activation. If Workers are active, retain the active package-set pointer and expose the staged pending revision.
• Model convergence results per surface as unchanged, synced, absent, partial, blocked, failed, or restart-needed; overall success requires every mandatory surface to be synchronized or explicitly awaiting only session reload.
• Treat authentication as a separate readiness dimension. Offline bootstrap verifies binaries and local configuration without importing credentials or contacting providers.
• Migrate existing installations by inventorying and backing up managed state, installing the new package set, verifying every surface, then removing obsolete Git registrations, standalone ownership, and unneeded caches.
• Deprecate the standalone installer with a deterministic handoff to the mise/red-dev bootstrap rather than silently maintaining an alternate implementation.

Testing Decisions

A good test asserts operator-visible convergence, trust, offline behavior, ownership, and rollback. It does not assert private helper call order or duplicate host implementation details.

• Extend the pure mise projection and manifest seams to test one RedSkills tool, separate external tools, exact locks, deterministic serialization, channel selection, and target filtering.
• Add pure package-set identity tests proving that any source, plugin, generated artifact, or lock change changes the whole-set digest while path changes alone do not.
• Add trust fixtures for valid signatures/checksums, corrupt artifacts, wrong source commits, missing assets, expired or unknown signing identities, and cross-target artifact substitution.
• Extend the existing host adapter harness with fake CLIs for all seven coders. Pin plan/apply/verify results, selected dev activation, restart-needed reporting, retries, and no success stamp for blocked or partial hosts.
• Extend companion artifact tests to cover Herdr, VS Code, Zellij, daemon/runtime artifacts, offline local sources, and exact commit correlation.
• Add configuration ownership fixtures showing includes/merges preserve unrelated user values and uninstall removes only owned state.
• Add migration fixtures for standalone trees, Git marketplaces, Directory marketplaces, copied OpenCode/RedCode state, Pi registrations, host caches, and interrupted adoption. Prove cleanup happens only after verification and a second run has zero drift.
• Add update-state tests for active Workers, staged revisions, session reload requirements, host failure without rollback, full-lock rollback, and active/previous retention.
• Add a high-level converge test that starts from the current Spec Spec: red-dev owns RedSkills wiring and mise owns its version (ADR 0008) #185 layout and reaches the new package-set layout without reacquiring a repository per host.
• Add network-denied E2E lanes for Ubuntu 24.04 x64, Ubuntu 26.04 x64, and Windows x64 plus WSL2/Ubuntu. Each lane performs clean import, second converge with zero drift, N-1 to current update, pending update with an active Worker, full-lock rollback, and uninstall/ownership verification.
• Use the existing project gates as mandatory local/CI seams: bun run typecheck, bun test, and bun run build.

Acceptance Criteria

• bun run typecheck, bun test, and bun run build pass with the complete package-set implementation.
• A focused package-set manifest test proves one RedSkills mise tool contains all workstation payloads while external applications remain separate exact-version tools.
• A focused digest test proves modifying any plugin payload, generated projection, companion artifact, source commit, or external-tool lock changes the package-set identity.
• A trust test refuses a corrupt artifact, an invalid signature, a source/asset commit mismatch, and a target-mismatched artifact before host state changes.
• mise upgrade red-skills from N-1 advances the immutable package-set snapshot, invokes red-dev reconciliation once, and leaves all mandatory surfaces at the new digest.
• red-dev update reaches the same final digest and a second run issues no host or companion writes.
• A development path: checkout with no matching release builds missing assets into digest-keyed staging and leaves the checkout byte-for-byte unchanged.
• Host adapter tests verify Claude Code, Codex, OpenCode, RedCode, Gemini, Pi, and Hermes install only dev, consume the selected local package set, and record success only after observable verification.
• Gemini generated manifests reference only existing artifacts and its installation succeeds from a local source with network access denied.
• Hermes receives a verified skills integration from the local source and reports richer unsupported capabilities explicitly rather than reporting false parity.
• Companion tests install and verify redskilled, Herdr, VS Code extension, and Zellij from package-set-local artifacts without GitHub/npm access during reconciliation.
• A clean bootstrap installs all seven coder CLIs, Herdr, Zellij, VS Code, red-dev, mise, and required runtimes from the target depot without network access.
• The Windows+WSL E2E lane installs coder CLIs, Herdr, Zellij, and one redskilled daemon in WSL; installs GUI/editor/terminal surfaces on Windows; and uses one combined depot.
• Ubuntu 24.04 and 26.04 E2E lanes complete import, verification, and a second zero-drift converge with all network egress blocked.
• Offline bootstrap succeeds without credentials and reports cloud authentication as unconfigured rather than failed installation.
• An active Worker causes an update to stage without moving current or restarting the daemon; completing the Worker allows the same staged revision to activate without reacquisition.
• Running coder sessions are not terminated; affected hosts report restart needed, and a new session observes the new plugin revision.
• A forced failure in one host returns overall failure, leaves successful hosts converged, records no success for the failed host, and succeeds on retry.
• Rollback restores RedSkills and every external tool to the previous complete lock while retaining no package-set revision older than active plus previous.
• Existing user configuration survives install, update, rollback, and uninstall; ownership tests prove unrelated keys and files remain byte-identical.
• Migration from the current Spec Spec: red-dev owns RedSkills wiring and mise owns its version (ADR 0008) #185 layout adopts and verifies the new package set before removing standalone trees, Git registrations, or obsolete caches; interruption before verification leaves the prior source usable.
• The deprecated standalone installer prints and executes the mise/red-dev handoff and does not create an independently owned RedSkills tree.
• red-dev doctor --json reports active digest, source commit, channel, lock identity, per-host state, companion state, pending revision, reload requirements, retained revisions, and offline trust verdict.
• The depot manifest lists exactly the artifacts needed by its target, carries active plus previous revisions, contains no recognized credential material, and verifies successfully after transport.

Out of Scope

• Activating memory, brain, or internal globally in AI coder hosts.
• macOS, ARM architectures, generic non-Ubuntu Linux distributions, and Windows without WSL2.
• System-wide installation shared by multiple operating-system users.
• Exporting, importing, or validating cloud-provider credentials.
• Offline model inference or cloud-agent functionality without network access.
• Publishing a public depot containing third-party vendor binaries.
• Full hooks/MCP/agent semantic parity on hosts that do not expose equivalent extension APIs.
• Automatically terminating or reloading running coder sessions.
• GitHub Actions workflows, AFK container images, benchmarks, release-maintainer tooling, and source-only developer applications as workstation install targets.
• Reimplementing completed Spec Spec: red-dev owns RedSkills wiring and mise owns its version (ADR 0008) #185 behavior unless it must change to support the atomic package-set contract.

Further Notes

This Spec implements ADR 0010 and supersedes the remaining architectural assumptions of Spec #185 and ADR 0008. Spec #185's child Tickets #186 through #192 are complete and define the migration baseline: mise-backed core layout, manifest-derived plugins, retention, version-gated refresh, published VSIX/Herdr artifacts, generator invocation, and Directory-source arbitration.

The current RedSkills npm package carries runtime bundles and shims, not the complete workstation source/manifests/assets required here. The current installed checkout also lacks the complete release output. The new package-set release contract is therefore a prerequisite, not a relabeling of the existing npm tarball.

Gemini currently has dangling generated hook paths and no universal installer path. Hermes has no RedSkills host adapter. Both are mandatory blockers because this Spec installs all seven coder hosts and does not permit a blocked host to be stamped successful.