Workspaces

A workspace is an organizational unit that defines what packages should be installed where. Think of it as a deployment target — the bridge between published packages and your team's repositories.

What is a Workspace?

A workspace declares:

• Which packages your team uses (and at what versions)
• Which targets exist (root, apps/web, services/api)
• Which providers each target uses (Claude, Codex, Copilot)
• What projection policy governs file rendering
• What overrides apply for this specific workspace

Workspace Revisions

Every change to a workspace creates a new revision — an immutable snapshot of the workspace state at that point in time.

Revision 1: Initial setup (3 packages)
Revision 2: Added @acme/security-review@1.0.0
Revision 3: Updated @acme/frontend-baseline from 1.1.0 → 1.2.0
Revision 4: Added apps/mobile target
Revision 5: Rolled back to revision 3 (removed mobile target)

Revisions enable:

• Audit trails: Who changed what, and when
• Rollbacks: wl rollback --workspace-revision 3
• Reproducibility: Any revision can be re-rendered deterministically

Targets

A workspace can have multiple targets — different locations within a monorepo that get different configurations:

# .loom/binding.toml

[targets.root]
path = "."
providers = ["claude", "codex"]
packages = ["@acme/org-baseline"]

[targets.web]
path = "apps/web"
providers = ["claude"]
packages = ["@acme/frontend-baseline", "@acme/react-patterns"]

[targets.api]
path = "services/api"
providers = ["claude", "codex"]
packages = ["@acme/backend-baseline", "@acme/security-review"]

Each target gets its own rendered output. No cross-target overwrites — render plans are isolated by target ID and path.

Workspace Overrides

Sometimes a workspace needs to customize a package for its specific context. Overrides let you modify package behavior without forking:

{
  "overrides": {
    "@acme/frontend-baseline": {
      "variables": {
        "framework": "Next.js",
        "testRunner": "Vitest"
      },
      "excludeAssets": ["instructions/angular-patterns.md"]
    }
  }
}

Overrides are stored server-side as part of the workspace revision — they're versioned and auditable.

Projection Policy

The workspace's projection policy controls how rendered files land locally:

Scope	Behavior	Example
generated_local	Written locally, usually gitignored	.claude/skills/**
committed_projection	Generated, expected to be committed	.github/copilot-instructions.md
user_local	User config, never synced	.claude/settings.local.json
manual_review	Diff only, user applies manually	Trust-sensitive settings
approval_required	Blocked until approved	Hooks, MCP configs
forbidden	Cannot render for this target/provider	Unsupported asset types

Binding a Repository

To connect a repository to a workspace:

wl bind acme/frontend-team

This writes the binding to .loom/binding.toml:

[workspace]
org = "acme"
name = "frontend-team"
revision = 12

Multiple repositories can bind to the same workspace — they'll all receive the same desired state.

Workspace Administration

Workspaces are managed through:

1. Web UI: Visual management of packages, targets, and overrides
2. API: Programmatic workspace updates
3. CLI: wl push, wl publish, wl rollback for workflow-level operations

Roles

Role	Can Do
Org Admin	Create/delete workspaces, manage members, set policies
Workspace Admin	Add/remove packages, change targets, approve trust-sensitive
Developer	Pull, push drafts, view status
CI/Service Account	Read-only check operations