feat(huginn): independent multi-component releases and crates.io/npm/Docker distribution #278

Objective

Introduce independently versioned and independently distributable Cortex products, using the multi-component Release Please pattern already established in dallay/profiletailors.com.

The current products are Rook (model gateway) and Huginn (coding agent, once #315 is merged). Future products, such as Muninn, must be addable without creating a global Cortex release version or changing existing product identities.

A code change limited to one product MUST NOT cause an unrelated product release. Each product owns its SemVer, changelog, release PR, tag, GitHub Release, artifacts and distribution jobs.

Hard blockers and sequencing

Do not activate Huginn Release Please or publicly publish Huginn until all applicable gates pass.

1. Merge refactor(huginn): rename personal coding agent from agent to huginn #315 (rename agent to huginn) into main; target apps/huginn, crates/huginn/{core,runtime}, binary huginn and canonical HUGINN_* names only after the rename lands. Do not bind the new release component to provisional apps/agent paths.
2. Complete the personal MVP acceptance milestone and stabilize the public binary/config contracts.
3. Complete the accepted interactive terminal release gate from ADR-0010, coordinating with feat(agent): introduce Ratatui-first TUI as a kernel-managed presentation plugin #306 and test(agent): establish Ratatui inline PTY and terminal compatibility gates #307; Ratatui is the normal interactive experience, headless JSON and explicit line fallback remain available.
4. Validate package-name ownership, publishing credentials/trusted publishing configuration and supported release targets before first publication.

The issue can be specified and reviewed now; implementation of the Huginn release configuration and public distribution is gated by the above.

Versioning and Release Please

• Configure manifest mode with one package per product, initially apps/rook and apps/huginn.
• Match the existing Profile Tailors conventions where appropriate: separate-pull-requests: true, always-update: true, include-component-in-tag: true, tag-separator: "@".
• Explicit, unambiguous future tags: rook@vX.Y.Z and huginn@vX.Y.Z. Preserve historical Rook tags; do not retag or rewrite old releases.
• Each package has its own manifest version, changelog and versioned package metadata. No global cortex@vX.Y.Z product release.
• Route GitHub Actions using path-scoped Release Please outputs (apps/rook--release_created, apps/huginn--release_created, corresponding --version, --tag_name, --sha), not the root outputs.
• A Rook-only commit opens/releases Rook only; a Huginn-only commit opens/releases Huginn only; simultaneous changes can release both with their respective versions.
• Define how shared Cargo crates map to affected consumers. The cargo-workspace plugin can propagate dependent bumps: update/release another product only when a real shared dependency change requires it, never merely because the products share a repository. Test the dependency graph and component-change detection.
• Make adding a future product a declarative manifest + distribution-job change, not a copy/paste of a monolithic release workflow.

Distribution contract — both products

On a successful product-specific GitHub Release, publish artifacts only for that product, built from its exact tag/SHA, never from mutable main:

The exact published name must be verified as available and owned before enabling writes. Docker tags must be product-local (X.Y.Z, controlled moving tags) and never collide across Rook/Huginn.

• Build platform/architecture-specific binaries only for targets actually validated by each product. Do not assume Huginn automatically supports every Rook target.
• Produce checksums, attach all archives to the correct GitHub Release, and enforce <binary> --version == release SemVer.
• npm: publish executable platform packages first, then the corresponding base wrapper with exact-version optionalDependencies; verify install/run on the supported systems. Use provenance/trusted publishing when available and appropriate.
• Docker: separately build/push product-specific multi-arch images to Docker Hub and GHCR; verify manifest platforms and run product-specific smoke tests. Huginn's container contract must be designed for a CLI/agent, not copied from Rook's long-running HTTP gateway/healthcheck.
• crates.io: cargo publish --dry-run --locked -p <product> must succeed before actual publication. Audit path-only/internal dependencies and publish = false declarations; publish necessary dependencies in dependency order or restructure packaging so the target binary crate is genuinely publishable. Never run unscoped cargo publish from the virtual workspace root.
• Use the repository's pinned rust-toolchain.toml, Cargo.lock where applicable, and explicit package selection in all build/publish jobs.
• Prefer idempotent/restartable distribution jobs that can safely retry a partially published release without rebuilding a different commit; verify registry versions rather than overwriting immutable publications.

Audit and repair the existing Rook pipeline before replicating it

The current .github/workflows/release.yml and release-please-config.json are not yet a safe template for a second component:

• Rook lives at apps/rook, but the workflow currently forwards root-only release_created/version/tag_name outputs; switch to the documented path-scoped outputs.
• Current Rook tags omit the component name; implement an explicit forward-only migration to rook@vX.Y.Z.
• Current cargo publish --locked lacks package selection in a virtual workspace and must be changed and validated against publishable crate dependencies.
• Audit npm package metadata and the build/publish workflow (including valid optionalDependencies package names, artifact paths and executable permissions).
• Make each registry and asset-publishing job depend exclusively on its own component's release and verified build artifacts.
• Preserve functional historical installations and releases; no gratuitous Rook behavior changes as part of adding Huginn.

Release verification

• Fixture/dry-run: feat(rook) changes only Rook's pending release and leaves Huginn's version unchanged.
• Fixture/dry-run: feat(huginn) changes only Huginn's pending release and leaves Rook's version unchanged.
• Fixture/dry-run: simultaneous product changes produce two independent release PRs, tags, changelogs and jobs.
• Shared-code fixture documents and tests the intended product impact, including cargo-workspace dependent bumps.
• No Huginn release configuration/publication runs while refactor(huginn): rename personal coding agent from agent to huginn #315 or the acceptance gates are incomplete.
• Product-specific job gating works when the other component is not released.
• Correct immutable tag SHA is used to build and publish every output; checksums match.
• Clean-machine installs from GitHub Releases, crates.io and npm run --version, doctor and one offline mock turn.
• Huginn released binary also passes interactive Ratatui startup under a PTY; no network provider is required for this smoke test.
• Docker Hub and GHCR images are distinct, multi-arch where validated, and pass appropriate per-product startup tests.
• Every published artifact reports a consistent product name and version; failures are actionable and partial releases can be retried.
• README and release documentation explain Cortex, Rook, Huginn, separate versions, install instructions and how to add future components.

Out of scope

• Publishing Muninn before that product exists (only design for future extensibility).
• Auto-update, extension marketplace or remote distribution of MCP servers.
• Mandating Rook as Huginn's runtime dependency; Rook is an optional protocol-compatible gateway.
• Shipping an unfinished interactive UX or inventing unvalidated platform support.

Related

• Rename gate: refactor(huginn): rename personal coding agent from agent to huginn #315
• Interactive terminal release gates: feat(agent): introduce Ratatui-first TUI as a kernel-managed presentation plugin #306, test(agent): establish Ratatui inline PTY and terminal compatibility gates #307; ADR-0010
• Distribution milestone: milestone(agent): distribution and Cortex integration #281
• Reference implementation: dallay/profiletailors.com/release-please-config.json and .github/workflows/release-please.yml.