Imported from shrug-labs/packs (aipack-core/skills/aipack-system/SKILL.md). Install upstream with npx skills add shrug-labs/packs --skill aipack-system. Copyright stays with the author.

aipack System Reference

Operational knowledge for the aipack pack management system.

The SSOT Principle

Pack source (SSOT) → aipack sync → Harness locations (managed output)

NEVER manually create, edit, or delete files in harness locations. Harness locations (~/.claude/rules/, ~/.claude/skills/, ~/.claude/commands/, .mcp.json, etc.) are managed output. The SSOT is the pack source at ~/.config/aipack/packs/<pack>/.

This is a specific case of the generated-vs-authored principle: edit the input, not the output.

Sync Procedure

Every time you modify pack content:

1. Edit content in pack source (~/.config/aipack/packs/<pack>/)
2. Verify sync defaults: aipack config defaults get
   • Check defaults.profile — which profile will be used?
   • Check defaults.harnesses — which harnesses will be synced?
   • Check defaults.scope — global (default) or project?
   • Check defaults.auto_sync — will pack/profile mutations trigger a sync?
   • Check defaults.namespaced — will rendered content use natural IDs or <id>__aipack__<pack>?
3. Verify active profile: cat ~/.config/aipack/profiles/<profile>.yaml
   • Which packs are enabled? (enabled: true/false/null)
   • Which content is included/excluded per vector?
   • Are the changes you made in a pack that's actually enabled?
4. Dry-run: aipack sync --dry-run — preview what would change. Confirm new content appears in the plan.
5. Sync: aipack sync
   • MUTATION: a real sync writes managed harness files outside the conversation. Get explicit yes before the non-dry-run command.
6. Restart harness client if needed (see below)

Content vectors (rules, skills, workflows, agents, prompts, plugins, profiles, registries) are auto-discovered from their standard directories. You don't need to register new files in pack.json unless you want to filter which IDs are included. An explicit non-empty array in the manifest acts as a filter — only listed IDs sync.

Restart Requirements

After syncing, the harness client may need a restart for changes to take effect.

General principle:

• Always-on content (rules, settings, MCP config, permissions) is typically loaded at session/client start → restart needed
• On-demand content (skills, workflows/commands) may be picked up without restart → depends on harness

When in doubt: restart the harness client after syncing.

Profile Mechanics

Profiles are agent profiles — curated compositions of packs that define what the agent knows and can do. They control what content from which packs gets synced.

Enabling/disabling packs

packs:
  - name: pack-name
    enabled: true     # Force enabled
    enabled: false    # Force disabled
    enabled: null     # Pack default (usually enabled)

Filtering content per vector

packs:
  - name: pack-name
    rules:
      include: null          # null/omitted = include all (normal pack) or nothing (quiet pack)
      include: []            # empty array = include all (backward compat; same as null for normal packs)
      include: ["rule-name"] # specific rules only
      exclude: ["rule-name"] # all except these
    skills:
      include: null
      exclude: null
    workflows:
      include: null
      exclude: null
    agents:
      include: null
      exclude: null
    plugins:
      include: null
      exclude: null

Profile simplification

When a pack entry should include all content, omit the vector sections entirely:

- name: my-pack
  enabled: true
  mcp:
    some-server:
      enabled: true

• Omitting rules:, skills:, etc. means "include everything" for normal packs, "include nothing" for quiet packs.
• include: [] (empty list) is treated as "include all" for backward compatibility — it does NOT mean "include nothing." This is a common misunderstanding.
• Quiet packs (quiet: true on the pack entry) flip the default across every delivery mechanism — content vectors, plugin references, MCP servers, and harness settings. Omitted or empty selectors resolve to nothing; an explicit opt-in is required to activate anything (non-empty include list for content, an explicit mcp: entry per server, settings.enabled: true for configs). Before v0.24.0 quiet applied only to content vectors — quiet packs still contributed every manifest-declared MCP server and their configs/ settings.
• Only add include:/exclude: sections when you need to filter specific items.

Settings

A non-quiet pack with harness config files (configs/ in the manifest) contributes base settings automatically — no settings.enabled: true required. Quiet packs opt out by default and need explicit settings.enabled: true on the profile entry to contribute. Multiple packs' settings are deep-merged in profile order (first pack wins at leaf conflicts, warning emitted). Set settings.enabled: false on a pack entry to opt a non-quiet pack out.

Harness settings files are composed from three sources during sync:

1. Base templates (from contributing packs) — the user's non-managed harness preferences. Templates must never redeclare managed keys.
2. Computed managed keys — MCP server configs, permissions, content paths, agent definitions. Entirely determined by aipack processing pack content and profile resolution. These overwrite any matching keys from templates.
3. Harness/user edits on disk — preserved between syncs for keys not managed by aipack.

If a template redeclares a managed key, the managed value silently overwrites it during sync — the user's preference is dropped with no warning.

Drop-in plugin files (configs.harness_plugins) are pure copies. Same-filename drop-ins from different packs produce an error. First-class plugin references live under plugins/<id>.json, are selectable through profile plugins: include/exclude, and sync additively to harness plugin enablement files. Removing a plugin reference from a profile stops aipack from re-asserting it but does not uninstall or disable it in the harness.

Toggling after sync

To change what's active without editing pack source:

1. Edit the profile YAML at ~/.config/aipack/profiles/<name>.yaml
2. Adjust enabled, include, or exclude as needed. Use aipack profile refs first when changing params or env-backed MCP/settings templates.
3. Re-sync: aipack sync
4. Restart harness client if needed

MCP per-server config

packs:
  - name: pack-name
    mcp:
      server-name:
        enabled: true                   # Enable/disable this MCP server
        allowed_tools: []               # Tools visible to the harness (ask per call where prompted)
        always_allowed_tools: []        # Subset auto-approved without per-call prompt
        disabled_tools: []              # Explicit block; takes precedence over allow lists

A silent profile (all three lists omitted or empty) emits no allow list to the harness, so the harness's native default applies. Use the TUI tri-state tool picker (t on an MCP entry in the profiles tab) to edit these lists interactively; the picker probes the server live and persists the selection back to the profile.

Params and env refs

• Use {params.KEY} for required profile params and {params.KEY:-default} for literal defaults.
• Use {env:KEY} for machine-local or secret values. aipack reads ~/.config/aipack/.env first, then the process environment.
• Check required values with aipack profile refs or the shorter aipack setup.
• Set stable params with aipack config params set <key> <value> --profile <profile>.
• Set local env values with aipack config env set KEY VALUE; inspect the file path with aipack config env path.

Common Commands

Scope and targeting

• --scope global (default) — writes to ~/ prefixed locations (user-level config)
• --scope project — writes to current project directory
• --harness <name> — target specific harness (claudecode, opencode, codex, cline)
• --profile <name> — use specific profile (overrides sync-config default)
• --profile-path <path> — use a profile file outside config directory

Scope duplication hazard

Do NOT sync both --scope global and --scope project for the same project. Claude Code loads rules from both ~/.claude/rules/ (global) and <project>/.claude/rules/ (project) — identical content in both means double token cost and duplicate system prompt entries.

Pick one scope per project. For workspace-meta repos, use global only.

Bundled content (--with / -w)

Core content (rules, skills, workflows, agents, prompts, MCP, configs) is always installed. Packs can also bundle profiles, registries, and extras — these are gated by --with:

• -w all — accept all bundled content
• -w profiles / -w p — apply bundled profiles
• -w registries / -w r — merge bundled registry entries
• -w extras / -w e — keep bundled extras (scripts, data files)

Remote installs without --with preview bundled content then strip it. Local installs accept everything by default.

OpenCode settings vs plugin files

• In pack manifests, configs.harness_settings.opencode maps to opencode.json.
• configs.harness_plugins.opencode maps to oh-my-opencode.json.
• For OpenCode, --skip-settings skips opencode.json but does not skip oh-my-opencode.json.

Harness Write Targets

Each harness writes content to different locations:

Global scope prefixes with ~/ (e.g., ~/.claude/rules/). Project scope writes to the project directory.

Pack Manifest (pack.json)

{
  "schema_version": 1,
  "name": "pack-name",
  "version": "YYYY.MM.DD",
  "root": "."
}

Content vectors are auto-discovered from standard directories. Explicit arrays act as filters:

{
  "rules": ["rule-one", "rule-two"],
  "skills": ["deploy"],
  "plugins": ["linear"],
  "profiles": ["dev", "lean"],
  "registries": ["team-tools"],
  "extras": ["scripts/run-server.sh", "data"],
  "mcp": ["server-one", "server-two"],
  "configs": { "harness_settings": { ... } }
}

All content fields use bare IDs (e.g., "profiles": ["dev"] corresponds to profiles/dev.yaml; "plugins": ["linear"] corresponds to plugins/linear.json). Extras are the exception — they use relative paths because they can reference files outside standard directories.

Tool permissions are entirely a profile concern — pack.json lists server IDs only. Profiles own allowed_tools / always_allowed_tools / disabled_tools per server. A silent profile (no allow-list entries) emits no allow list, so the harness's native default applies. Packs that want opinionated defaults ship them through a named bundled profile such as profiles/team.yaml, not the manifest. Do not use profiles/default.yaml; default is reserved for the user's local default profile and is rejected by pack validate. Pre-v0.23 packs use schema_version: 1 with a nested mcp: { servers: { ... }, default_allowed_tools: [...] } object; they still load in v0.23+ under the dedicated v1 parser, but v1's pack-level tool policy is read and discarded — use schema_version: 2 with a bundled profile to express tool policy.

Configuration Locations

Pack state lives in aipack.lock, not sync-config.yaml. To answer which packs are installed and at what version, read the lockfile. To answer which profile/harnesses/scope sync uses by default, read sync-config.yaml. The lockfile is rewritten on every install/update — do not hand-edit. Older configs that still carry installed_packs: in sync-config.yaml auto-migrate to the lockfile on the first v0.21+ command.

Pack Installation

Version pinning

Packs can be pinned to an exact semver tag, a partial semver, a namespaced tag (multi-pack monorepos), or a commit hash. Pins are stored in aipack.lock and respected by pack update.

--ref is the primary flag since v0.22. --version stays as a Kong alias for historical scripts — --version X is equivalent to --ref X on both pack install and pack update. Any git ref shape is accepted: exact semver, partial semver, namespaced semver, commit hash, latest, branch name, or non-semver tag. The @<spec> positional shorthand follows the same rules.

For multi-pack monorepos: once a pack is installed at a namespaced tag (my-pack/v0.3.0), subsequent pack update my-pack --ref 0.3.1 auto-inherits the my-pack/ prefix from the lockfile — users can pass bare semver on updates without retyping the prefix. pack versions my-pack similarly scopes its tag listing to the installed prefix.

pack update <name> against a pinned pack re-resolves the pin's matcher (e.g. v1 finds the new highest matching tag) but preserves the pin shape. pack update against an unpinned pack always moves to the latest default-branch commit. aipack doctor reports drift between an installed pack's recorded ref and its remote head.

Profile params after install

When switching to a new profile, run aipack setup <profile> or aipack profile refs <profile> before sync. Carry over stable params from previous profiles with aipack config params set <key> <value> --profile <profile>; put machine-local values in .env with aipack config env set. Bare {params.*} refs and missing {env:*} refs skip MCP servers or fail settings expansion.

Content collisions

When two packs ship content with the same ID (e.g., both have rules/anti-slop.md), the defaults.collision_strategy in sync-config.yaml determines what happens: last-wins (default — later pack in profile order wins), first-wins (earlier pack wins), or error (fail with remediation YAML). Explicit overrides in the profile always take precedence over the strategy: overrides.rules: ["anti-slop"]. When rule, agent, workflow, or skill collisions should coexist, set defaults.namespaced: true so harness-visible names render as <id>__aipack__<pack>; MCP servers, plugins, and settings keys still need one winner.

Personal Pack MCP Override

When a team pack's MCP server is broken (e.g., uvx-based server failing due to registry timeouts), override it from a personal pack without modifying the team pack:

1. Install the MCP server locally (e.g., venv at ~/.local/share/mcp-servers/<name>/)
2. Create ~/.config/aipack/packs/<personal>/mcp/<server>.json pointing to the local binary
3. In the active profile, disable the team pack's server: packs[<team-pack>].mcp.<server>.enabled: false
4. The personal pack provides the server instead — no collision, no override key needed

This works because profiles control which pack provides each MCP server. Disabling in one pack and enabling in another is clean composition, not a hack.

Discipline (Observed Anti-Patterns)

These are behavioral failures observed in real sessions. Each one wasted significant time.

Content Lifecycle

Observed failure → Draft in personal pack → Battle-test → Promote to team pack

1. Notice agent misbehavior or knowledge gap
2. Draft content in personal pack (using pack-content-craft methodology)
3. Sync and test — does it change behavior? (TDD loop)
4. After proving value, promote to team pack via PR
5. Team pack content flows to all team members via their profiles and sync