Boilerplate starter pack

A copyable vsuite pack that exercises every pack feature: two new agents, two skills, a shared pack:* partial, and an instructions/*.md.liquid file that is auto-wired per target. It is the worked example for the pack author guide and the docs page Boilerplate pack.

The pack is loaded by packages/packs/tests/boilerplate.test.ts, so it cannot silently rot.

What’s in the pack

boilerplate-pack/
├── vsuite-pack.yaml                          # manifest (id: boilerplate, contextVersion: 2)
├── agents/
│   ├── api-designer.md.liquid                # new agent, places vsuite:evidence + pack:boilerplate-standards
│   └── release-manager.md.liquid             # new agent, places vsuite:efficiency + vsuite:skills + pack partial
├── skills/
│   ├── api-contract-review/SKILL.md.liquid   # uses {{ pack.id }} and {{ target.id }}
│   └── release-readiness/SKILL.md.liquid     # uses {{ pack.id }}, {{ pack.version }}, {{ project.stack }}
├── partials/
│   └── boilerplate-standards.md.liquid       # rendered with {% render "pack:boilerplate-standards" %}
├── instructions/
│   └── development-standards.md.liquid       # pack-only, auto-wired for every target
├── .vscode/
│   └── settings.json                         # preconfigured Liquid authoring
└── README.md

Files vsuite does not read (README.md, .vscode/, package.json, CI config) are ignored and are not part of the pack integrity hash.

Prerequisites

• Node.js 24 or later.
• vsuite 0.4.0 or later, which is the release that added packs. From this monorepo run pnpm install once, then use pnpm vsuite <args> to run the CLI from source.

1. Validate the pack locally

pack validate needs no project. It checks the manifest, the layout, and the front matter, then test-renders every template against built-in fixture contexts (empty and full stack, every target, metrics and memory on and off) and lints the generated Markdown.

pnpm vsuite pack validate examples/boilerplate-pack --strict

Expected output:

Pack examples/boilerplate-pack is valid

The pnpm vitest run --project @vsuite/packs suite covers the same pack through the loader.

2. Use it in a project

Copy the folder into the project you are testing, for example .vsuite/packs/boilerplate, then point the project at it. You can edit vsuite.json by hand or use the CLI.

Option A: edit vsuite.json

{
  "packs": {
    "boilerplate": { "source": "path:./.vsuite/packs/boilerplate" }
  },
  "agents": {
    "api-designer": { "source": "pack:boilerplate" },
    "release-manager": { "source": "pack:boilerplate" }
  },
  "skillSources": {
    "api-contract-review": { "source": "pack:boilerplate" },
    "release-readiness": { "source": "pack:boilerplate" }
  }
}

path: resolves relative to the project root, so a project next to this monorepo can also point at path:../vsuite/examples/boilerplate-pack without copying anything.

Option B: the CLI flow

vsuite pack add path:./.vsuite/packs/boilerplate --name boilerplate
vsuite agent use api-designer --from boilerplate
vsuite agent use release-manager --from boilerplate
vsuite generate

agent use adds each new pack agent as a specialist. Both skills are required by those agents, so they are generated automatically; add vsuite skill use <id> --from boilerplate only when a pack overrides a catalog skill or a project selects one explicitly.

Generate

vsuite generate

A changed path: pack relocks with a warning. Commit vsuite.json, vsuite.lock.json, and the generated target folders together.

Expected output per target

With both agents selected, both skills required, and a target listed in targets, vsuite generate writes:

The instruction is wired natively as well:

• OpenCode: the path is appended to the instructions array in .opencode/opencode.json.
• Claude Code: everything under .claude/rules/ is auto-loaded.
• GitHub Copilot: the file starts with applyTo: "**" so it applies to the whole repository.

The instruction file name is <pack>-<id>, so a pack renamed with pack add --name changes the stem.

Authoring with Liquid

.vscode/settings.json associates *.md.liquid with the Liquid language and sets two-space tabs and word wrap. The vsuite:* and pack:* delimiters ({{ ... }} and {% ... %}) are provided by the Liquid language support installed in the editor; the association is what makes highlighting, comment toggling, and formatting pleasant.

When you edit a template:

1. Run vsuite pack validate examples/boilerplate-pack --strict to catch unknown variables (TPL_UNKNOWN_VAR), bad partial names (TPL_BAD_PARTIAL), and Markdown lint.
2. vsuite pack update boilerplate (if the pack is installed) then vsuite generate to relock a path: pack.
3. Review the generated Markdown diff, not just the template diff.