Core concepts
Organizations, origins, assets, selections, and the states a change moves through.
Organization
The organization is the root of everything in BarnDog. You connect to it once, when you sign in, and you never have to type it in a command again.
Inside the organization there are teams, repositories (each owned by one team), and developers.
Origins
Every asset has an origin, which is the scope that owns it. Commands take the origin with --origin:
| Origin | Owner |
|---|---|
org | The whole organization |
team/<team-slug> | A team, such as team/frontend |
repo/<repo-slug> | A repository, such as repo/dashboard |
dev/<handle> | A developer's personal assets |
me | Shorthand for your own dev/<your-handle> |
Names are unique per asset kind within one origin. The same name can exist in different origins: team/frontend and team/mobile can each have their own react-guidelines Skill.
Behind the scenes, every asset has a permanent ID. Renaming an asset or moving it to another origin never breaks your selections or its history.
Assets
Skills, MCP configurations, and Hooks are the three kinds of asset.
- Skills are packages of files with a required
SKILL.md. Each Skill has its own Git-backed history. - MCP configurations describe how to connect to an MCP server. They list the secret variables a server needs, but credentials stay on your machine.
- Hooks run a command when a lifecycle event happens. Each Hook states which harnesses it supports, and BarnDog never claims it works where it doesn't.
Recommended and optional
Each scope marks its shared assets as recommended or optional. Recommended assets are the suggested setup. Optional assets are there for anyone who wants them. Neither kind is installed automatically: you always choose what to install.
Your selections
Your choices live in one file per machine, ~/.barndog/config.yaml. They include:
- the harnesses BarnDog manages,
- the assets you installed, and whether each one is enabled or disabled.
Disabling an asset keeps it selected but removes it from your harnesses on the next sync. Enabling it again brings it back. Nothing you do locally changes the shared asset.
If two selections supply the same asset, it is installed once. If two different assets would end up with the same name in one harness, BarnDog stops and asks you to resolve it instead of picking one silently.
Published, Draft, and Suggested Change
Shared Skills and Hooks move through three states:
- Published: the current version everyone receives through
barndog sync. Published versions are numberedv1,v2, and so on, and never change once published. - Draft: private, unfinished edits in the web workspace.
- Suggested Change: a proposed edit waiting for review, like a pull request. When it is merged, it becomes the next published version.
Members merge Suggested Changes under their team's or repository's merge rules. Admins can publish directly. See Review and merge Suggested Changes.