# The Pack Ecosystem

Totem 1.25.0+ distributes ecosystem-specific baseline rules and structural constraints as installable NPM packages under the `@mmnto/pack-*` scope.

Packs replace the monolithic internal baseline system. You install a pack into your project using the standard Node.js ecosystem, and Totem dynamically incorporates its rules via the `loadInstalledPacks()` runtime invocation.

## Pack Categories

Packs are structurally divided into two distinct categories based on their role and scope:

### 1. Language & Architecture Packs

**(e.g., `@mmnto/pack-rust-architecture`, forthcoming: `@mmnto/pack-godot-architecture`)**
These packs encode structural, deterministic AST and regex rules specific to a language or framework. They are the core enforcement primitives that protect your architecture from common footguns (e.g., empty catch blocks in TypeScript, or incorrect macro usages in Rust).

### 2. Capability Packs

**(e.g., `@mmnto/pack-agent-security`)**
These packs provide cross-cutting rule families that aren't tied to a specific language. For instance, the `pack-agent-security` module (which is `private: true` and restricted to workspace-only use) provides immutable security constraints protecting against unauthorized code evaluation or network exfiltration.

> **Note on bot-interaction protocols.** A "Bot Interpretive Pack" archetype was previously proposed for distributing cohort bot-interaction protocols (CodeRabbit, Gemini Code Assist, etc.) as separate npm packages. That model was retired on 2026-05-12 per [ADR-105](https://github.com/mmnto-ai/totem-strategy/blob/main/adr/adr-105-bot-protocol-centralization.md). Bot-interaction protocols now live as canonical doctrine at `mmnto-ai/totem-strategy:doctrine/bot-protocols.md`, with mechanical enforcement deferred to runtime hooks ([`mmnto-ai/totem#1900`](https://github.com/mmnto-ai/totem/issues/1900)). The Pack channel remains valid for portable expertise (language packs, security packs); it was a channel mismatch for internal cohort protocols.

## Architecture and the Zero-Trust Default

Totem operates on a **zero-trust default** model for agent governance. The platform assumes that rules generated by AI (via the Pipeline Engine's 5-stage funnel in ADR-091: `Extract -> Classify -> Compile -> Verify-Against-Codebase -> Activate`) must be verified before enforcement.

When you install a pack, its rules enter a `pending-verification` state. Upon the first `totem lint` run, Totem locally validates these rules against your codebase. If they are safe and match the established patterns, they are promoted. This ensures that third-party or LLM-generated rules cannot arbitrarily break your build pipeline. Furthermore, security-critical packs like `@mmnto/pack-agent-security` provide **immutable** rules that cannot be downgraded or disabled by local developers or agents.

## Engine Configuration

To ensure compatibility, packs must declare their supported Totem version via the `engines` field in their `package.json`:

```json
{
  "engines": {
    "@mmnto/totem": ">=1.25.0"
  }
}
```

This acts as a strict structural contract (as amended by ADR-097 § Q6).

## Publishing & Trust

Canonical `@mmnto` packs are published to NPM via OIDC, include cryptographic attestations, and are Sigstore-signed. This provides supply-chain security for governance primitives, ensuring that the rules governing your codebase haven't been tampered with.

## Consumer Positioning: The Graduation Phase

The Pack ecosystem allows Totem to act as a focused governance engine while outsourcing ecosystem-specific domain knowledge. Instead of Totem needing to know the nuances of Rust macros, React hooks, or CodeRabbit's markdown quirks, you simply wire in the relevant Pack.

By publishing packs as versioned NPM artifacts, Totem enables a sustainable ecosystem where teams can share proven compliance constraints and bot guidelines as easily as they share standard libraries.

_(For details on how to wire these sensors into actuators across your organization, see the forthcoming context and hook orchestration guides.)_
