@vsuite/templates

Liquid templates for catalog agents and skills, the shared vsuite: partials they render, the restricted Liquid renderer, the template context builder, and the generated agent-metrics scripts. Non-goals: target frontmatter and file paths (@vsuite/targets), deciding what is selected (@vsuite/catalog), and writing files (@vsuite/core).

This is a private, source-only workspace package (exports → ./src/index.ts). It is bundled into the @krizic/vsuite CLI and the desktop UI and is not published to npm. Workspace consumers depend on it with "@vsuite/templates": "workspace:*".

Layout

Path	Contents
`templates/agents/<id>.md.liquid`	One body template per catalog agent.
`templates/skills/<id>.md.liquid`	Built-in skill templates.
`templates/skills/conventions/<id>.md.liquid`	Convention skill templates (loaded into the same skill map; ids must be unique).
`templates/partials/vsuite/<name>.md.liquid`	Shared sections rendered as `{% render "vsuite:<name>" %}` (for example `stack`, `skills`, `metrics`, `memory`, `telemetry`, `roster`, `collaboration`).
`src/load-templates.ts`	Reads the template directory into `templates`.
`src/context.ts`	`buildTemplateContext`: the only object templates see (contract in context reference).
`src/render-liquid.ts`	`renderAgent` / `renderSkill`: render a template and append missing required sections.
`src/render.ts`	`renderAgentBody` / `renderSkillBody`: render a built-in agent or skill by id.
`src/renderer/`	Restricted `liquidjs` engine: partial resolution (`vsuite:` and `pack:` only), custom filters, parse/render/memory limits, `TemplateError`.
`src/markdown-lint.ts`	Lint of rendered Markdown, reported as render diagnostics.
`src/scripts.ts`	Job-metrics schema, validator, telemetry merge script, and metrics script.
`scripts/capture-goldens.ts`	Rewrites the golden outputs in `tests/golden/`.

Public API

Export	Kind	Description
`templates`	const `TemplateSources`	Agent, skill, and partial sources keyed by id, loaded once from the template directory.
`TemplateSources`	type	`{ agents; skills; partials }`, each a `ReadonlyMap<string, string>`.
`buildTemplateContext`	function `(input: BuildTemplateContextInput) => TemplateContext`	Builds the pure template context (target, agent, project stack and preferences, capabilities, skills, roster, MCPs, pack). Throws if a preference the agent declares is missing.
`BuildTemplateContextInput`, `RosterAgent`	types	Input to `buildTemplateContext`; roster metadata for non-catalog or overridden agents.
`renderAgent`	function `(source, context, file, sources?) => AgentRenderResult`	Renders an agent template, then appends each `REQUIRED_SECTIONS` partial the template did not place and whose condition holds. Returns `{ output, appended, diagnostics }`.
`renderSkill`	function `(source, context, file, sources?) => { output; diagnostics }`	Renders a skill template; no sections are appended.
`REQUIRED_SECTIONS`, `RequiredSection`	const, type	`telemetry`, `stack`, `skills`, `metrics`, `memory`, in append order.
`RenderSources`	type	Partials for one render: built-ins plus optional `packPartials` (`pack:` names).
`RenderDiagnostic`	type	Warning or error from rendering or Markdown lint.
`renderAgentBody`	function `(id, preferences, capabilities?, selectedAgents?, target, requiredSkills?, stack?) => string`	Builds the context and renders a built-in agent.
`renderSkillBody`	function `(id, preferences?, capabilities?) => string`	Builds the context and renders a built-in skill.
`TemplateError`, `TemplateErrorCode`	class, type	Typed render failure (for example `TPL_UNKNOWN_VAR`).
`lintMarkdown`, `MarkdownLintDiagnostic`, `MarkdownLintRule`	function, types	Markdown lint used by the renderer.
`Preferences`, `StackEntry`, `preferenceValue`	types, function	Preferences and stack from `vsuite.json`; dotted preference lookup.
`renderMetricsSchema`, `renderMetricsValidator`, `renderMergeTelemetryScript`, `renderMetricsScript`	functions	`.vsuite/agent-metrics/` files and `<targetDir>/scripts/agent-metrics.mjs`.
`renderVsuiteMcpServer`	function	`.vsuite/vsuite-mcp.mjs`: dependency-free stdio MCP server with `current_time` and `log_job`.
`renderMcpEnvWrapper`, `quoteWindowsArgSource`	functions	`.vsuite/mcp-env.mjs`: loads `.vsuite/.env` before starting a stdio MCP server.
`renderAgentmemoryTosGuard`, `renderAgentmemoryGitignore`	functions	Files under `.vsuite/agentmemory/` written when agent memory is enabled.

Dependencies

Workspace: @vsuite/catalog.
Third-party: liquidjs 10.30.0 (pinned exact; restricted engine in src/renderer/). Dev: @vsuite/test-utils.
Used by: @vsuite/core, @vsuite/packs, @vsuite/workflows.

Diagrams

flowchart LR
  TPL["templates/agents, skills (.md.liquid)"] --> LOAD["templates (load-templates)"]
  PART["templates/partials/vsuite"] --> LOAD
  IN["target, preferences, stack, capabilities, roster, skills, MCPs"] --> CTX["buildTemplateContext"]
  LOAD --> R["renderAgent / renderSkill (restricted liquidjs)"]
  CTX --> R
  PACK["pack templates + pack: partials"] --> R
  R --> APP["append missing REQUIRED_SECTIONS (agents only)"]
  APP --> LINT["lintMarkdown → diagnostics"]
  LINT --> OUT["agent or skill markdown body"]
  SEL["selected agents, target"] --> SCR["renderMetricsSchema / renderMetricsValidator / renderMergeTelemetryScript / renderMetricsScript"]
  SCR --> MOUT["job-metrics files"]

Packaging

defaultTemplateRoot() looks for ./templates/ next to the running module, then ../templates/ (source and tests). Bundles copy packages/templates/templates next to their output: the CLI in packages/cli/tsup.config.ts (onSuccess), the UI in packages/ui/electron.vite.config.ts (vsuite-copy-templates plugin). The package files list includes templates.

Usage

import { renderAgentBody, renderSkillBody } from "@vsuite/templates";
 
const agent = renderAgentBody("docs-steward", { documentation: { location: "docs" } }, [], [], "opencode");
const skill = renderSkillBody("evidence-based-qa");

Testing

pnpm vitest run --project @vsuite/templates

Golden tests in tests/golden/ render every entry of the golden matrix (matrix.ts) and compare with the committed outputs under agent/, skill/, and convention/; parity.test.ts and matrix.test.ts guard parity and coverage. After an intended output change, recapture and review the diff:

pnpm --filter @vsuite/templates golden:capture

Attribution

templates/skills/brainstorming.md.liquid and templates/skills/writing-plans.md.liquid vendor the corresponding skill text from superpowers v5.1.0 (MIT, © 2025 Jesse Vincent). They carry only the necessary adaptations — rewritten cross-references, an optional visual companion, and a self-contained execution handoff — so no superpowers: ids or external companion files remain.