Quick Start

Let's run through the basics and see Workloom in action.

Validating a Workspace Manifest

A workspace manifest declares which AI packages apply to a repository. Let's validate a simple one:

pnpm wl validate fixtures/workspaces/simple-workspace.json

Expected output:

Valid workspace manifest: fixtures/workspaces/simple-workspace.json
  Workspace: Simple Workspace (wksp_simple_01)
  Targets: root
  Revision: 1

What this means:

• Workspace ID — wksp_simple_01 — The unique identifier for this workspace
• Org ID — org_acme — Which organization owns this workspace
• Targets — root — This workspace has one target (a single repo, in this case)
• Revision — 1 — Every change to the workspace increments the revision counter

The workspace is bound to a git repository and declares which packages (and versions) apply to that repo.

Validating a Package Manifest

Now let's validate a package:

pnpm wl validate fixtures/packages/workloom-baseline-v1.json

Expected output:

Valid package manifest: fixtures/packages/workloom-baseline-v1.json
  Package: @workloom/baseline@1.0.0
  Trust class: passive_text
  Assets: 5

What this means:

• Package ID — @workloom/baseline@1.0.0 — Scope, name, and semantic version (like npm)
• Trust class — passive_text — This package contains only instructions and prompts (safest trust level)
• Assets — 5 — This package defines 5 AI assets (skills, instructions, etc.)

What Are Assets?

Assets are the building blocks of packages — instructions, skills, hooks, MCP server configs, prompts, etc. Each asset has a trust class that determines what gates must pass before it can be rendered to disk.

Trust Gates in Action

Now let's see what happens when a workspace declares packages with trust requirements that violate org policies:

pnpm wl validate fixtures/workspaces/policy-denied-hooks.json

Expected output:

Trust gate violations in workspace manifest: fixtures/workspaces/policy-denied-hooks.json
  - Target "root" provider "claude" uses projection policy "generated_local"
    which is too permissive for trust-sensitive package "@workloom/secure-hooks@1.0.0"

Recommendation: Change projection policy to "approval_required" or "manual_review"
Exit code: 5 (policy violation)

What this means:

• This workspace references a package with executable hooks
• The workspace's projection policy for Claude is generated_local — which means files are rendered automatically without approval
• That's too permissive for hooks — they require explicit approval before they touch disk
• The validation fails with exit code 5

This is Workloom's trust model at work: no silent overwrites, no surprise shell commands. If you want hooks to run, you must explicitly approve them.

Understanding Policies

Workloom enforces trust policies per provider per workspace:

Policy	Behavior
forbidden	This asset type cannot be used with this provider
approval_required	File is rendered only after explicit approval
manual_review	Workloom renders with a "review me" flag; you approve in your editor
committed_projection	File is committed to git (org policy, not developer override)
generated_local	File is generated locally, auto-synced (safest for passive text)
user_local	File is local-only (never synced)

Hooks and MCP servers typically require approval_required or manual_review. Instructions and prompts can safely use generated_local.

What's Next

Now that you understand validation and trust gates, let's build your first workspace manifest from scratch. Head to Your First Workspace.

tip

Exit codes matter for CI integration. Exit code 0 = valid. Exit code 5 = policy violation. Exit code 2 = schema error. This makes Workloom easy to integrate into your build pipeline.