Providers

Workloom's provider system solves a fundamental problem: every AI coding tool has different config formats, file locations, scoping rules, and trust behaviors. You shouldn't need to know these details — Workloom handles the translation.

How It Works

You write one canonical package. Workloom renders it correctly for each provider:

Canonical Package
  └── "Always write tests before implementation"
       │
       ├── Claude  → CLAUDE.md (instruction block)
       ├── Codex   → AGENTS.md (markdown section)
       ├── Copilot → .github/copilot-instructions.md
       └── Gemini  → Extension manifest (Phase 5)

Provider Capability Matrix

Each provider has different capabilities. Workloom models these explicitly:

Capability	Claude	Codex	Copilot	Gemini
Project instructions	CLAUDE.md	AGENTS.md	copilot-instructions.md	Extension
Nested targets	.claude/ per dir	Nested AGENTS.md	instructions/**	N/A
Skills/commands	.claude/skills/**	.codex/skills/**	N/A	N/A
Agent definitions	.claude/agents/**	.codex/agents/**	N/A	N/A
Settings	.claude/settings.json	.codex/config.toml	N/A	Extension config
Hooks	.claude/hooks/**	N/A	N/A	N/A
MCP servers	In settings.json	N/A	N/A	N/A
User-local config	settings.local.json	User config	N/A	User extensions

Supported Providers

Claude (Full Adapter)

Status: Production-ready

Renders to:

• CLAUDE.md — Project instructions
• .claude/settings.json — Project settings, MCP servers, tool permissions
• .claude/skills/**/*.md — Skill definitions
• .claude/agents/**/*.md — Agent definitions
• .claude/hooks/** — Lifecycle hooks (trust-gated)

Scoping: Project-level (.claude/) + nested CLAUDE.md per directory.

Codex (Full Adapter)

Status: Production-ready

Renders to:

• AGENTS.md — Root instructions (with multi-package merge support)
• .codex/config.toml — Project configuration
• .codex/skills/** — Skill definitions
• .codex/agents/** — Agent definitions
• Nested AGENTS.md files for monorepo targets

Scoping: Repo root + nested targets. Nested AGENTS.md refines parent by path.

Copilot (Full Adapter)

Status: Production-ready

Renders to:

• .github/copilot-instructions.md — Repository-level instructions
• .github/instructions/**/*.md — Scoped instruction files

Scoping: Committed projection model — files are expected to be in git.

Gemini (Fixtures Only)

Status: Schema modeled, renderer planned for Phase 5

The Gemini adapter models extension-based configuration. Since Gemini primarily uses user-local installation, Workloom will never auto-mutate user home directories — only generate install/link instructions.

Cursor (Planned)

Status: Phase 5

Will render to .cursor/rules/** and .cursorrules files.

Multi-Package Merge

When multiple packages render to the same file (e.g., two packages both contributing to AGENTS.md), Workloom merges deterministically:

1. Ordering: Alphabetical by package scope + name
2. Section separators: Clear headers marking which package contributed what
3. Ownership ranges: State tracks which lines belong to which package
4. Determinism: Same packages → same merged output, every time

<!-- AGENTS.md (merged by Workloom) -->

<!-- @acme/backend-baseline -->

# Backend Development Standards

Always validate input at API boundaries...

<!-- @acme/security-review -->

# Security Requirements

Never log sensitive data...

Provider Overrides

Packages can include provider-specific overrides for cases where the canonical format doesn't perfectly map:

{
  "assets": [
    {
      "path": "instructions/testing.md",
      "type": "instruction",
      "providers": ["claude", "codex"],
      "providerOverrides": {
        "claude": {
          "renderAs": "skill",
          "outputPath": ".claude/skills/testing/SKILL.md"
        }
      }
    }
  ]
}

Adding Provider Support

Workloom's adapter interface makes it straightforward to add new providers:

1. Declare capabilities (what file types, scoping rules, trust behaviors)
2. Implement the render function (canonical asset → provider-specific file)
3. Add test fixtures
4. Register in the render engine

The @workloom/renderer package handles orchestration — adapters only need to transform individual assets.