feat: Pack extension system — shareable bundles of skills, MCP servers, plugins, and instructions

[anandgupta42]

What does this PR do?

Introduces the Pack extension system — a shareable bundle format that packages skills, MCP servers, npm plugins, and instructions into one activatable unit. Vendors (dlt-hub, Airbyte, DuckDB lined up as first-wave partners) can ship a single repo with a PACK.yaml and users activate it in one command.

Why this, why now:

1. Every major data vendor shipped an MCP server in the last year. Snowflake, Databricks, BigQuery, MotherDuck, dbt, Atlan, Monte Carlo, Dagster, Airbyte — they all have one. But MCPs are raw surfaces: just tool lists. Nobody packages them into opinionated, dbt and lineage-aware workflows for coding agents. First-mover opportunity to become the bundler rather than another MCP consumer.

2. User pain is real and daily. Setting up altimate-code for a specific data stack today requires manually installing skills, configuring MCP servers, and writing instruction files. Every team member on the same project repeats this setup. Time-to-first-useful-agent is hours, not seconds.

3. Partner momentum. dlt-hub, Airbyte, and DuckDB partnerships are active and can ship the first vendor packs within weeks of this merging. Atlan, Monte Carlo, and Dagster are wave-2 targets. The go/no-go on the broader vendor program hinges on a clean extensibility primitive for partners to build against — this is it.

4. Defensible strategic position. Claude Code has plugins, Cursor has rules, Continue has blocks — but none are data-engineering-native. Packs give altimate-code a bundle format that ships opinionated dbt, lineage, and cost-aware experiences on top of raw MCPs. Vendors gain distribution; altimate-code gains the integration moat.

Usage: altimate-code pack install AltimateAI/data-engineering-skills, then altimate-code pack activate dbt-snowflake. That installs skills into the project skills directory, configures the MCP server in the project config (preserving JSONC comments), appends declared npm plugins to the plugin list, writes pack-scoped instructions, and prompts a restart so the plugin loader picks up the new specs.

Runtime additions under packages/opencode/src/pack/: Pack.Info Zod schema (skills, skill_groups, mcp, plugins, instructions, detect, trust metadata), Pack.Manifest schema plus SHA256 computeContentHash (CRLF/LF normalized), Pack.ActivationSidecar recording exactly what each pack wrote so deactivate cleans up ownership-aware, hardcoded VERIFIED and BUILTIN allowlists with env-var overrides (ALTIMATE_CODE_VERIFIED_PACKS and ALTIMATE_CODE_BUILTIN_PACKS), and integrity check comparing content hash plus name, version, and tier against the manifest.

CLI subcommands (11 total): list, create, show, install, activate, deactivate, remove, detect, search, status, validate. Ownership-aware cleanup via the sidecar means deactivate and remove leave user-modified MCP entries in place and report which were preserved.

Remote registry: pack search hits a configurable URL (packs.registry config field or ALTIMATE_CODE_PACK_REGISTRY env var), caches for 24 hours, supports --refresh to bypass cache, and falls back to stale cache when the registry is unreachable.

Telemetry: new event types pack_created, pack_installed, pack_applied (with tier, tamper_detected, tier_downgraded), pack_deactivated, pack_removed, pack_integrity_warning.

Docs: docs/docs/configure/packs.md (user), docs/docs/develop/packs.md (author), docs/PARTNER_ECOSYSTEM_PLAN.md (strategy).

Type of change

• New feature (non-breaking change which adds functionality)

Issue for this PR

Closes #567

How did you verify your code works?

• 31 of 31 pack tests pass — 20 runtime tests plus 11 CLI integration tests covering MCP ownership via sidecar, plugin refcount by canonical name, legacy fallback when the sidecar is missing, instructions cleanup, sidecar roundtrip, and legacy active-packs file support in the alternate directory layout
• 235 of 236 tests pass across pack, config, and plugin suites (1 pre-existing config timeout unrelated to this change)
• TypeScript clean across all workspace packages via bun typecheck
• Marker Guard clean via bun run script/upstream/analyze.ts --markers --base main --strict
• Multi-model consensus code review (3 external models plus local review) ran before marking ready. All CRITICAL and MAJOR findings were addressed in the final commit including ownership-aware MCP cleanup, canonical-name plugin refcounting, PackRemoveCommand invoking the cleanup helper, TOCTOU-hardened plugin writes in activate, manifest metadata comparison, Zod-validated registry cache, and remote-install rollback on manifest-write failure

Checklist

• My code follows the guidelines of this project
• I have performed a self-review of my own code
• New and existing tests pass locally with my changes
• I have added adequate documentation for this feature
• All altimate_change markers are in place for upstream-shared files

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 5416d0ca-5bf0-4990-ade3-e1dcbc56b0f6

📥 Commits

Reviewing files that changed from the base of the PR and between c438bb0 and 09fe431.

📒 Files selected for processing (16)

• .github/meta/commit.txt
• docs/PARTNER_ECOSYSTEM_PLAN.md
• docs/docs/configure/index.md
• docs/docs/configure/packs.md
• docs/docs/develop/ecosystem.md
• docs/docs/develop/packs.md
• docs/mkdocs.yml
• packages/opencode/src/altimate/telemetry/index.ts
• packages/opencode/src/cli/cmd/pack.ts
• packages/opencode/src/cli/cmd/tui/thread.ts
• packages/opencode/src/config/config.ts
• packages/opencode/src/index.ts
• packages/opencode/src/pack/index.ts
• packages/opencode/src/pack/pack.ts
• packages/opencode/test/pack/pack-cli.test.ts
• packages/opencode/test/pack/pack.test.ts

Disabled knowledge base sources:

• Jira integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

📝 Walkthrough

Walkthrough

This PR introduces a comprehensive "Pack" system for bundling and distributing skills, MCP servers, and instructions as reusable units. It adds CLI commands for pack lifecycle management (create, install, activate, deactivate, detect), implements integrity verification with tier-based trust levels and content hashing, tracks activation state via sidecars, and provides extensive documentation and tests.

Changes

Cohort / File(s)	Summary
Documentation - Pack System Guides docs/PARTNER_ECOSYSTEM_PLAN.md, docs/docs/configure/packs.md, docs/docs/develop/packs.md, docs/docs/develop/ecosystem.md	New comprehensive pack documentation covering end-to-end ecosystem strategy, configuration guide with CLI commands and schema reference, development tutorial with PACK.yaml examples, and trust/integrity mechanisms.
Documentation - Navigation docs/docs/configure/index.md, docs/mkdocs.yml	Added pack configuration guide card and MkDocs navigation entries for Configure and Reference sections.
Metadata .github/meta/commit.txt	Updated commit note documenting Kit→Pack rename across conventions, schemas, telemetry prefixes, and file structure.
Telemetry packages/opencode/src/altimate/telemetry/index.ts	Extended Telemetry.Event union with six new pack lifecycle events: pack_created, pack_installed, pack_applied, pack_removed, pack_deactivated, pack_integrity_warning; captures impacts and trust/integrity signals.
Core Pack Module packages/opencode/src/pack/pack.ts, packages/opencode/src/pack/index.ts	New Pack namespace with Zod schemas for pack metadata, MCP configuration, skill groups, trust tiers, and activation sidecars; implements filesystem-backed state discovery, content hashing, manifest integrity verification, tier allowlist enforcement, and lifecycle APIs.
CLI Pack Command packages/opencode/src/cli/cmd/pack.ts	New top-level pack command with subcommands: list, create, show, install, remove, detect, activate, deactivate, status, validate, search; includes ownership-aware cleanup, JSONC-preserving config edits, sidecar-based activation tracking, and registry search with caching.
Configuration packages/opencode/src/config/config.ts	Added optional packs config schema with paths, urls, and registry fields; extended Config.Info to include new packs section.
CLI Integration packages/opencode/src/index.ts	Registered new PackCommand with yargs CLI command chain.
TUI Enhancement packages/opencode/src/cli/cmd/tui/thread.ts	Added deferred startup routine to detect available packs on TUI initialization and suggest activation if none are active.
Tests - Unit packages/opencode/test/pack/pack.test.ts	Comprehensive test suite for pack discovery, parsing, lifecycle (activate/deactivate), integrity verification, manifest round-tripping, tier downgrades, and skill extraction.
Tests - Integration packages/opencode/test/pack/pack-cli.test.ts	Integration tests for cleanup behavior with sidecars, MCP/plugin/instruction removal, ownership-aware preservation, legacy fallback paths, and sidecar persistence.

Sequence Diagrams

sequenceDiagram
    actor User
    participant CLI as pack activate
    participant Pack as Pack Module
    participant Manifest as Manifest/Hash
    participant Config as Project Config
    participant Skills as Skill System
    participant MCP as MCP Config

    User->>CLI: activate <pack-name>
    CLI->>Pack: get(pack-name)
    Pack->>Manifest: readManifest()
    Pack-->>Pack: verify content hash
    Pack-->>Pack: check tier allowlist
    CLI-->>User: show integrity warnings
    User-->>CLI: confirm activation
    
    CLI->>Skills: install referenced skills
    Skills-->>Skills: fetch & validate SKILL.md
    
    CLI->>Config: write MCP entries
    Config-->>Config: preserve JSONC comments
    
    CLI->>Config: create instruction files
    
    CLI->>Pack: writeActivationSidecar()
    Pack-->>Pack: record applied changes
    
    CLI-->>User: activation complete

Loading

sequenceDiagram
    actor User
    participant CLI as pack deactivate
    participant Pack as Pack Module
    participant Sidecar as Sidecar Record
    participant Config as Project Config
    participant MCP as MCP Cleanup
    participant Plugins as Plugin Cleanup

    User->>CLI: deactivate <pack-name>
    CLI->>Sidecar: readActivationSidecar()
    
    alt Sidecar found
        Sidecar-->>CLI: activation metadata
        CLI->>Config: read current config
        CLI->>MCP: match & remove owned entries
        MCP-->>MCP: preserve user modifications
        CLI->>Plugins: refcount canonical names
        Plugins-->>Plugins: keep if other packs use
        CLI->>Config: delete pack instruction files
    else Sidecar missing (legacy)
        CLI->>Config: name-based cleanup attempt
        Config-->>Config: best-effort removal
    end
    
    CLI->>Pack: deleteActivationSidecar()
    CLI-->>User: deactivation complete

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~65 minutes

Possibly related PRs

• PR #556: Modifies packages/opencode/src/altimate/telemetry/index.ts to add new event types; both PRs extend the telemetry union with event schema changes, creating a potential merge conflict or coordination need.

Suggested reviewers

• kulvirgit
• suryaiyer95
• mdesmet

Poem

🐰 Hops of joy for Packs so neat,
Bundling skills in bundles sweet,
From Kit to Pack, the system's grown,
Trust and tiers in sidecars shown—
Activate, deactivate with care,
Integrity checks everywhere! 🎉

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/kit-extension-ecosystem

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[gitguardian]

⚠️ GitGuardian has uncovered 3 secrets following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

🔎 Detected hardcoded secrets in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
29326785	Triggered	Generic Password	abc632b	packages/opencode/test/altimate/connections.test.ts	View secret
29327588	Triggered	Generic Password	abc632b	packages/opencode/test/altimate/connections.test.ts	View secret
30431051	Triggered	Generic Database Assignment	abc632b	packages/opencode/test/altimate/connections.test.ts	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secrets safely. Learn here the best practices.
3. Revoke and rotate these secrets.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}

[gitguardian]

⚠️ GitGuardian has uncovered 3 secrets following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

🔎 Detected hardcoded secrets in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
29326785	Triggered	Generic Password	abc632b	packages/opencode/test/altimate/connections.test.ts	View secret
29327588	Triggered	Generic Password	abc632b	packages/opencode/test/altimate/connections.test.ts	View secret
30431051	Triggered	Generic Database Assignment	abc632b	packages/opencode/test/altimate/connections.test.ts	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secrets safely. Learn here the best practices.
3. Revoke and rotate these secrets.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}

[github-actions]

👋 This PR was automatically closed by our quality checks.

Common reasons:

• New GitHub account with limited contribution history
• PR description doesn't meet our guidelines
• Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

[github-actions]

👋 This PR was automatically closed by our quality checks.

Common reasons:

• New GitHub account with limited contribution history
• PR description doesn't meet our guidelines
• Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

[github-actions]

👋 This PR was automatically closed by our quality checks.

Common reasons:

• New GitHub account with limited contribution history
• PR description doesn't meet our guidelines
• Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.