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

[anandgupta42]

What does this PR do?

Introduces the Kit extension system — a way for anyone (vendors, solution architects, team leads, engineers) to create and distribute shareable development setups that bundle skills, MCP servers, and instructions into a single activatable unit.

The problem: Setting up Altimate Code for a specific data stack (dbt + Snowflake, Dagster + BigQuery, etc.) requires manually installing skills, configuring MCP servers, and writing instruction files. Each team member repeats this setup. There's no way to share a "complete setup" as a single artifact.

The solution: altimate-code kit activate dbt-snowflake — one command that installs 9 skills, configures the dbt MCP server, and adds best-practice instructions.

What's included

Core runtime (430 + 1,320 lines):

• Kit namespace with Zod schemas, state management, YAML loading
• Trust tiers: built-in, verified, community
• Skill packs with activation modes: always, detect, manual
• Full activate/deactivate lifecycle with MCP cleanup + instruction cleanup
• JSONC-preserving config writes via jsonc-parser (user comments preserved)

11 CLI commands:

Command	Description
kit list	List available kits with tier badges
kit create <name>	Scaffold a KIT.yaml
kit show <name>	Display full details
kit install <source>	Install from GitHub/URL/local
kit activate <name>	One command: install skills + configure MCP + add instructions + enable
kit deactivate <name>	Clean removal: instructions + MCP config + active-kits
kit remove <name>	Delete installed kit
kit detect	Auto-detect matching kits by project files
kit search [query]	Search remote registry (graceful when unavailable)
kit status	Show active kits
kit validate [name]	Validate kit format, MCP config, env vars

TUI startup nudge:

• Non-blocking kit detection when TUI starts
• One-line suggestion when matching kits found

Documentation (614 lines across 2 pages):

• User guide: docs/docs/configure/kits.md — Quick start, CLI reference, trust tiers, locations, roadmap
• Author guide: docs/docs/develop/kits.md — Full schema reference, step-by-step tutorial, 3 complete examples, publishing guide, troubleshooting

Strategy document:

• docs/PARTNER_ECOSYSTEM_PLAN.md — Competitive landscape analysis (Goose, Terraform, VS Code), three-layer model (Skills/MCP/Plugins), simulation results from 10 stakeholder scenarios

Architecture

altimate-code (this repo) = runtime
  packages/opencode/src/kit/     → schema, state, loading, activate/deactivate
  packages/opencode/src/cli/cmd/kit.ts → CLI commands

data-engineering-skills (separate repo) = content  
  kits/dbt-snowflake/KIT.yaml    → first built-in kit
  registry.json                  → machine-readable index

Zero vendor code in our repo. Kit content lives in external repos. We maintain the runtime + a pointer file.

KIT.yaml format

name: dbt-snowflake
description: Complete dbt + Snowflake development setup
version: 1.0.0

skills:
  - source: "AltimateAI/data-engineering-skills"
    select: [creating-dbt-models, testing-dbt-models, debugging-dbt-errors]

mcp:
  dbt:
    command: ["uvx", "dbt-mcp"]
    env_keys: ["DBT_PROJECT_DIR"]

detect:
  - files: ["dbt_project.yml"]
    message: "Detected dbt project — activate kit?"

instructions: |
  Use ref() for all model references.
  Follow staging → intermediate → marts layering.

Type of change

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

Issue for this PR

Closes #567

How did you verify your code works?

Automated testing:

• 60/60 E2E tests passing across 11 categories (name validation, activate/deactivate lifecycle, MCP merge/cleanup, JSONC comment preservation, detect, validate, install, TUI nudge code checks)

Stakeholder simulations (10 scenarios, 17+ personas):

Scenario	Score	Key Finding
Snowflake (Large Enterprise)	5/10	Demo-ready core, needs enforcement for enterprise
Dagster (Growth Startup)	6/10	Would partner conditionally
dbt Labs (Core Partnership)	6/10	MCP merge bug found + fixed
Airbyte (Mid-Market SaaS)	7/10	Stress test: 7 kits, 6 active, unicode, 1000-line instructions
Fortune 500 Bank (Enterprise)	4/10	Missing enforcement, use AGENTS.md today
Healthcare (HIPAA)	4/10	Instructions work, no enforcement mechanism
Solo Consultant (SA)	5/10	Best natural fit, needs kit switch
MSP Consulting (20 clients)	5/10	26/26 commands pass, switching friction measured
Series A Self-Serve	3→6/10	TUI nudge improved discovery
OSS Contributor	6/10	8 min to working kit

29 bugs found and fixed across 3 review rounds including:

• Security: git flag injection (-- added), path traversal validation, name validation on load
• Correctness: MCP config format translation, JSONC comment preservation, deactivate cleanup
• UX: merged 3 commands into 1 (activate), simplified template, graceful 404, partial failure messaging

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

🤖 Generated with Claude Code

[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]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: e9a22275-e95f-4257-befc-1ec448a5f19a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 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.}