Skip to main content

Key Decisions

Architectural decisions made during Workloom's design.

Registry as source of truth, not local files​

Decision: The Workloom registry owns canonical package definitions. Local files are generated projections.

Rationale: If local files are the source of truth, there is no mechanism for organization-wide distribution, versioning, or drift detection. The registry model follows the same pattern as npm, RubyGems, and Docker registries.

Implication: Generated provider files should be treated like node_modules — important but not canonical.

Provider-aware rendering, not generic file copy​

Decision: Each provider has a dedicated renderer that produces the correct file format and location. There is no generic "copy files to destination" path.

Rationale: Claude, Codex, Copilot, and Gemini all consume different files in different formats. A generic copier would require every package author to maintain provider-specific variants. Renderers encode provider knowledge once.

Implication: Adding a new provider requires writing a new renderer package, not just configuration.

HTTPS transport, not rsync/SSH​

Decision: Workloom uses HTTPS for all registry communication. rsync and SSH are never required.

Rationale: rsync has poor Windows support, requires SSH setup, doesn't integrate with SSO/device login, doesn't work well with corporate proxies, and adds installation burden. HTTPS with content-addressed objects is simpler and more reliable for .md and .json assets.

Implication: No single-binary distribution that shells out to rsync. The CLI is a pure Node.js/TypeScript tool.

Immutable package versions​

Decision: Once a package version is published, it cannot be changed.

Rationale: Mutability in package registries leads to supply chain attacks, non-reproducible builds, and broken downstream dependencies. Immutability is a resolved problem in npm, Docker, and other registries.

Implication: Fixing a published package requires publishing a new version.

Workspace revisions, not workspace mutations​

Decision: Every workspace configuration change creates a new revision. Revisions are monotonically increasing integers.

Rationale: This enables rollback, audit trails, and deterministic resolution. If two developers are on different revisions, wl status can tell them exactly how far apart they are.

Phase 0/1 dependency gate​

Decision: Phase 0/1 forbids databases, ORMs, cloud SDKs, web frameworks (for the API), queues, auth provider SDKs, and desktop frameworks without an explicit plan update.

Rationale: Proving the local wl workflow with fixture registries and in-memory stores is more valuable than prematurely building infrastructure. Dependencies can be added when needed, but removing them is painful.

Implication: The API currently uses in-memory stores. The CLI works with a local dev server. This is intentional and will be replaced with persistent backends in Phase 2.

Committed binding, generated provider files​

Decision: .loom/binding.toml is committed. Generated provider files follow a per-provider policy (usually gitignored for Claude/Codex, committed for Copilot).

Rationale: The binding file is tiny and tells cloners which workspace this repo belongs to. Generated files are large and regenerable. Copilot is the exception because GitHub's cloud features read committed instruction files.

Monorepo-native target model​

Decision: Workspaces support multiple targets at different sub-paths, each with independent package selections and provider configurations.

Rationale: Monorepos are the dominant architecture in organizations that would use Workloom. Codex's layered AGENTS.md discovery and Copilot's path-specific instruction files both support path-aware rendering.