Pack author guide

A pack is a directory of Liquid templates that adds agents, skills, and instructions to vsuite or overrides built-in agents and skills by id. The built-in catalog stays available; packs are optional. A project selects pack agents and skills in vsuite.json, and vsuite generate renders them with the same engine and context as the catalog. See the example pack for a complete walkthrough, the boilerplate pack for a copyable starter pack, and the template context reference for every variable. Organisations packaging, distributing, and rolling out their own packs should read the enterprise pack guide.

Layout

my-pack/
├── vsuite-pack.yaml
├── agents/<id>.md.liquid
├── skills/<id>/SKILL.md.liquid
├── instructions/<id>.md.liquid
└── partials/<name>.md.liquid

vsuite-pack.yaml fields:

The config key a project gives the pack (acme in "packs": { "acme": … }, or --name on pack add) is its name in pack:<name> sources, pack:<name> partials, and error messages; it defaults to the manifest id.

Limits

• At most 500 files, each at most 256 KB.
• Agent, skill, and partial ids match [a-z0-9-]+.
• Symbolic links must resolve inside the pack directory.
• Every file must be a regular, valid UTF-8 text file without NUL bytes.

These limits are cooperative safeguards against mistakes, not a sandbox; see Trust model.

Front matter

Agent and skill templates start with YAML front matter:

---
description: Reviews diffs for security defects against the Acme standards and threat model.
tools: [read, search, execute, todo]
requiredSkills: [acme-threat-model]
---

Overrides inherit every field they omit from the built-in definition.

Templates

Templates use LiquidJS 10.x (exact version pinned in packages/templates/package.json) with a restricted configuration:

• strictVariables: an unknown variable is an error (TPL_UNKNOWN_VAR). Only paths in the context reference exist.
• lenientIf: {% if optional.field %} works for optional fields that may be absent.
• strictFilters: an unknown filter is an error (TPL_UNKNOWN_FILTER).
• ownPropertyOnly: templates see only the context’s own data.
• include, layout, and block are disabled (TPL_UNKNOWN_TAG). Use {% render %}.
• The date family of filters and sample are disabled so output is deterministic.
• Parse limit 1 Mi characters, render limit 2000 ms, memory limit 16 Mi units (TPL_LIMIT).

Filters

All Liquid built-in filters except those above, plus:

Partials

{% render %} accepts only two kinds of names:

• vsuite:<name>: a built-in partial (list below).
• pack:<name>: partials/<name>.md.liquid in the same pack.

Any other name, path, or .. fails with TPL_BAD_PARTIAL. Partials see the whole template context.

Built-in partials:

Required sections and auto-append

Agent templates must include five sections: telemetry, stack, skills, metrics, and memory. Place them with {% render "vsuite:<name>" %} where you want them. Any you do not place are appended to the end of the agent body in that order. Skill templates have no required sections.

• A partial placed inside an {% if %} branch that does not render does not count as placed, so it is appended.
• A required partial placed twice produces an MD_LINT warning.
• Required partials guard themselves: they render nothing when their condition is false, so you can place them unconditionally.

The UI preview marks which sections were auto-appended.

Instructions

An instructions/<id>.md.liquid file is a pack-only instruction template. It has no front matter and no selection: every loaded pack’s instructions are rendered for every configured target. Instructions see the standard template context but have no agent context (like skills).

Each rendered instruction is written to the target’s native location and auto-wired:

The <pack> part is the pack’s config name, so a pack renamed with pack add --name changes the file stem.

Errors

Every failure has a code, the pack name (catalog for built-in templates), and, where known, file, line, column, and a hint.

Using a pack in a project

vsuite.json:

"packs": {
  "acme":  { "source": "npm:@acme/vsuite-pack@^1.2.0" },
  "local": { "source": "path:./.vsuite/packs/team" },
  "infra": { "source": "git:https://git.example.com/infra/pack.git#v2.0.0" }
},
"agents": {
  "code-reviewer":   { "source": "pack:acme" },
  "secure-reviewer": { "source": "pack:acme" }
},
"skillSources": {
  "acme-threat-model": { "source": "pack:acme" }
}

Sources are path:<dir>, npm:<spec>, and git:<url>#<ref>. Entries default to source: "catalog"; set it back to catalog to revert an override. Use vsuite agent use and vsuite skill use rather than editing by hand (see the CLI README).

Lockfile

vsuite.lock.json (lockfileVersion: 2; version 1 files are read and rewritten) records per pack the source, the resolved version or commit, integrity (an SRI string, sha256- plus base64, over the sorted file list and contents), contextVersion, and generatedSkills / generatedAgents / generatedInstructions (ids last generated, so stale outputs are removed). pendingRemovalSkills / pendingRemovalAgents / pendingRemovalInstructions record outputs of removed packs that the next generate deletes. Commit the lockfile.

When pack content no longer matches the lock:

• path: packs: generate warns and relocks.
• npm: and git: packs: generate and the UI preview stop with PACK_INTEGRITY unless you pass --update-packs (or run vsuite pack update).

Validating

vsuite pack validate <dir> [--json] [--strict] needs no project. It checks the manifest, front matter, and layout, test-renders every template against built-in fixture contexts (empty and full stack, each target, metrics and memory on and off), and lints the Markdown. It exits non-zero on failure; --strict also fails on MD_LINT warnings.

Trust model

Packs are trusted code-adjacent content: install them only from sources you trust, pinned by version, commit, or path and verified by lockfile integrity. The size, count, and render limits are cooperative safeguards, not isolation. There is no signing or sandbox yet; the lockfile format leaves room for signature fields. The original security reviews are kept as historical records in docs/superpowers/reviews/ (dated 2026-10-02); this guide describes current behavior.

Versioning

• contextVersion versions the template context. This release supports 1 and 2 (current: 2); a breaking context change gets a new version and a new reference.
• vsuite in the manifest declares which vsuite releases the pack supports. Enforced: a vsuite release outside the range fails with PACK_MANIFEST.
• Bump the pack version on every release; consumers relock with vsuite pack update.