Docs / Concepts

One source, every assistant

You keep one source: .opencastle/ in the repository. sync compiles it, with OpenCastle's own content and any baseline the team extends, into each assistant's native files — CLAUDE.md and .claude/ for Claude Code, .cursor/rules/ for Cursor, .github/ for Copilot, and so on. sync --check compiles to a scratch directory and compares, so a hand edit or a forgotten recompile fails CI instead of drifting silently.

Three kinds of path, and who owns each:

• Yours: .opencastle/, and your own writing in a root file such as CLAUDE.md — above or below its managed block, the marked part every sync rewrites.
• Generated: the managed blocks, and whole directories such as .claude/agents/ or .cursor/rules/. A file you add to one is removed by the next sync, except a skill, which sync moves into .opencastle/skills/. Put anything else in .opencastle/ instead and it compiles for every assistant.
• Shared: MCP config files. OpenCastle updates its own servers and leaves yours.

Generated config is committed, like a lockfile: a teammate who clones the repository has working rules without running anything.

What an assistant is given, and when

Every token loaded before a task is paid for on every task, so OpenCastle keeps that part small and loads the rest when a task needs it.

• Always loaded — instructions. A short set of rules that hold in any project, the project's facts (.opencastle/project.instructions.md: stack and versions, commands, routes, environment variable names, read from the code by init), and the team's own instructions. npx opencastle explain shows what they cost; a team can set a budget.
• Skills load when a task matches their description: how to test, review, write an API, use this project's database or CMS. An assistant sees only their names and descriptions until then.
• Agents are specialists to delegate to. Prompts — /oc:implement-feature, /oc:bug-fix — start a piece of work. Workflow templates give recurring work its steps: a migration, a refactor, a security audit.

Agents and the Team Lead

Each agent has a scope, the files it may change, and what it reports when it finishes: the Developer, UI/UX Expert, Data Engineer, Security Expert, Testing Expert, Reviewer and others. A project gets the ones its stack needs.

The Team Lead coordinates work that spans several areas: it splits the work into tasks with one owner and their own files each, orders them by dependency, hands each to the specialist that fits, checks every result, has the combined change reviewed, and opens one pull request. A change in one area it makes itself. It all happens in your session.

Agents declare a tier — premium, standard or economy — instead of a model name. Your assistant picks the model for the tier: it knows which ones your account can use.

Integrations

An integration is a tool OpenCastle knows: Next.js, Supabase, Stripe, Playwright, Linear and others. init adds the ones your repository uses, and npx opencastle add <name> adds one later. Each brings a skill with that tool's version-specific details and, where the tool has one, an MCP server — the vendor's remote server, or a package pinned to an exact version — written in each assistant's own config format with its own spelling for environment variables. Every integration.

Layers and policy

What a repository compiles is three layers, each able to add to and override the one before:

1. OpenCastle's own content — the instructions, agents, skills, prompts and workflows it ships.
2. Baselines — npm packages, or paths, named in extends: the organisation's instructions, skills, MCP servers and policy, shared by every repository that extends them. A baseline is also an Agent Plugin.
3. The project — .opencastle/.

exclude leaves an item out — skills/seo-patterns, or skills/*. A baseline's policy says which MCP servers may run and reach which hosts, that every server is pinned, what no repository may drop, and how much may load before a task. A later layer can tighten a policy, never relax it.

The lock

sync records what every assistant is given in .opencastle/lock.json: each item, the layer it came from, and its digest; each MCP server and what it launches; the layers' versions; the always-loaded cost. A change to what the assistants are given moves the lock, so code review sees it. npx opencastle review turns the change into sentences on the pull request, marking with ⚠️ what deserves a careful look, and npx opencastle fleet reads the locks of many repositories at once.

Lessons

A lesson is something true for anyone working in the repository — a command that fails, a tool's quirk, a convention written down nowhere — in one file in .opencastle/lessons/, citing the code it is about. Agents save what they learn in their own memory, as they always do; in Claude Code and VS Code a hook copies what is about the project into lessons when the agent stops, and the lessons go into the pull request with the work. Claude Code, VS Code, Cursor and Windsurf load the lessons before every task by themselves; elsewhere agents read the index, .opencastle/LESSONS-LEARNED.md, by instruction. doctor names a lesson whose cited code has changed, and warns when the index grows past about 2,000 tokens; a lesson that has proven itself graduates into the skill it is about. Steps an agent had to work out — how to run the tests, how to release — go straight into a team skill in .opencastle/skills/, in the same change. Memory has three scopes, kept apart: personal (what your own assistant remembers about you, on your machine), team (lessons in the repository) and organisation (skills in the baseline). What the agent saves as about the user never becomes a lesson, so nobody sorts memories afterwards.

Convoy (experimental)

For work you would rather not sit and watch. npx opencastle convoy "<task>" — or /oc:convoy in your assistant — plans the work without changing anything and shows you the plan. The run starts each task in its own git worktree, several at a time, on the agent runtime init set up, reviews each, merges them onto a branch of its own, and runs your checks once at the end. Convoy runs log themselves; npx opencastle convoy dashboard shows them. Everything else on this page works without it. Worked runs.

Glossary