How It Works

Workloom is not rsync, Dropbox, or a generic bidirectional sync tool. It is a desired-state workflow:

canonical package assets
  -> workspace revision
  -> deterministic render plan
  -> provider-specific projected files
  -> local ownership, approval, and drift state

Core Concepts

Concept	Purpose
Package	Versioned bundle of AI workflow assets.
Workspace	Repo, folder, monorepo target, or unique key that receives package assignments.
Asset	Atomic package item such as an instruction, skill, agent, workflow, prompt, MCP server, hook, policy, template, telemetry schema, or provider config.
Renderer	Converts canonical assets into provider-specific files.
Sync planner	Decides whether planned files are safe to write.
Drift checker	Reports whether local state still matches desired state.

Local File Model

Workloom keeps canonical AI workflow content in the registry. Local files fall into three categories:

Category	Current path	Commit policy
Team binding	workloom.workspace.json	Commit when the repo or folder should advertise its Workloom workspace.
Optional lock	workloom.lock.json	Commit when the organization wants deterministic CI installs.
Runtime state	.workloom/state/	Ignore; contains auth cache, render ownership, drift baseline, and local approval state.

For private folders or ad hoc systems, the planned local-only binding map is ~/.config/workloom/bindings.json. A future workloom.binding.json alias can be introduced if the committed pointer needs to split from full workspace manifests, but .loom/binding.json is not the current product namespace.

Provider Model

The current prototype renders fixture-backed projections for:

• Claude project settings.
• Codex AGENTS.md.
• GitHub Copilot committed instructions.
• Gemini install/link previews.

Provider-specific renderers live in provider adapter packages. User-home config mutation is intentionally out of scope for the current implementation; Gemini surfaces produce previews without writing user-home configuration.

Safety Model

Before writing, Workloom checks:

• workspace-relative paths;
• case-colliding output paths;
• committed projection approval requirements;
• trust-sensitive package approvals;
• MCP servers, permission wildcards, sandbox weakening, inline secrets, and unknown high-risk provider settings.

Restore uses the .workloom/state/render-plan.json ownership baseline before rewriting files. Files that look like Workloom output but are not in the ownership baseline are reported as drift and left untouched.