Packages

Packages are the fundamental unit of Workloom. A package is a versioned collection of AI workflow assets that can be published, shared, and rendered for multiple providers.

What's in a Package?

A package contains canonical assets — provider-agnostic definitions of AI workflow configurations:

Asset Type	Examples
instruction	System prompts, coding guidelines, team standards
skill	Reusable capabilities (review code, write tests, deploy)
agent	Agent definitions with goals, tools, and constraints
workflow	Multi-step automated processes
prompt	Templated prompts with variables
hook	Lifecycle hooks (pre-commit, post-deploy)
mcp_server	MCP server configurations
provider_config	Provider-specific settings
template	Scaffolding templates
policy	Organizational policy definitions

Package Identity

Every package has a scoped name following npm conventions:

@org/package-name

Examples:

• @acme/frontend-baseline — Standard config for frontend teams
• @acme/security-review — Security-focused skills and agents
• @acme/onboarding — New hire AI tool setup

Versioning

Packages use semantic versioning:

@acme/frontend-baseline@1.2.3
                         │ │ │
                         │ │ └── Patch: bug fixes, typo corrections
                         │ └──── Minor: new assets, non-breaking changes
                         └────── Major: breaking changes, removed assets

Immutability

Published versions are immutable. Once @acme/frontend-baseline@1.2.0 is published, its content can never change. This guarantees:

• Reproducible builds (same version = same rendered output)
• Safe rollbacks (previous versions are always available)
• Audit confidence (what was approved is what gets deployed)

Release Channels

Packages support release channels — moving pointers to specific versions:

Channel	Purpose
stable	Production-ready, fully reviewed
beta	Pre-release testing
canary	Bleeding edge, may break
security-required	Critical security update, should be applied immediately

A workspace can pin to a specific version or track a channel:

# Pin to exact version
[packages]
"@acme/frontend-baseline" = "1.2.0"

# Track stable channel
[packages]
"@acme/frontend-baseline" = { channel = "stable" }

Package Lifecycle

Draft → Pending Review → Approved → (Active | Deprecated | Yanked)

1. Draft: Created with wl push --draft. Only visible to the publisher.
2. Pending Review: Promoted with wl publish. Visible to reviewers.
3. Approved: Passed review. Available for workspace assignment.
4. Active: Assigned to one or more workspaces.
5. Deprecated: Superseded by a newer package. Still works, but flagged.
6. Yanked: Removed from resolution. Existing installs remain, but new pulls fail.

Trust Classification

Every asset in a package carries a trust class that determines how it's handled during sync:

Trust Class	Examples	Default Behavior
Passive text	Instructions, prompts	Auto-applied
Configuration	Provider settings	Manual review
Tool permission	Sandbox settings	Approval required
Executable hook	Shell commands	Approval required
Networked MCP	Server configs with URLs	Approval required

This ensures that a package can never silently escalate privileges or execute code without explicit consent.

Content Addressing

Every asset file is stored as a content-addressed object (SHA-256). This enables:

• Deduplication: Same content across packages/versions stored once
• Integrity verification: Content verified on every download
• Efficient sync: Only download objects you don't already have

Creating a Package

# Initialize a new package
mkdir my-package && cd my-package

# Create the package manifest
cat > package.workloom.json << 'EOF'
{
  "name": "@myorg/my-package",
  "version": "1.0.0",
  "assets": [
    {
      "path": "instructions/coding-standards.md",
      "type": "instruction",
      "trustClass": "passive_text",
      "providers": ["claude", "codex", "copilot"]
    }
  ]
}
EOF

# Write your canonical content
mkdir instructions
echo "# Coding Standards\n\nAlways write tests..." > instructions/coding-standards.md

# Publish as draft
wl push --draft