Loadout
Edit the declared source for each configured consumer. Generated harness files are outputs.
Instructions
- For setup or migration, read onboarding. Preview with
loadout init project --dry-run --jsonorloadout init global --dry-run --json, resolve harnesses and ownership, then apply the approved plan. Never execute discovered scripts or installers. - For ordinary changes, read configuration routing. Default to
personal configuration for the current project; explicit project/global scope takes precedence.
Locate the existing config and follow its declared producers: the manifest's harness blocks and
the source slices they name. Ask before widening scope or changing a source shared by other
consumers.
A repository that has not adopted loadout, where the user wants personal configuration, is
covered by a stealth source if one targets it: edit the stealth source's files and sync with
loadout sync --stealth <name>, neverinit projector a newloadout/there; see the stealth row of the scope table and “Stealth sources” in the same reference. - Apply a generic request to configured harnesses with a sound mapping. Report unsupported consumers. Keep MCP server definitions separate from MCP tool-approval policy. Preserve ordering, comments, private sources and unrelated fields; never create overlapping producers.
- Sync the edited source:
loadout sync --root <repo>for project/personal changes;loadout sync --globalfor the active global profile, orloadout sync --global --profile <name>when explicitly selected;loadout sync --stealth <name>for a stealth source. Rendered files are output: edit the source folder. Ask whether an unnamed change under a non-default profile belongs to that profile or its inherited default. - Report source files changed, harnesses reached, unsupported consumers and the sync result.
Examples
- “Set up Loadout here” previews discovery, resolves the scope and configured harnesses, and shows writes and removals before applying. Success leaves editable, uncommitted source.
- “Allow
just testfor me” edits the existing personal permissions producer and syncs. If the project has no personal producer, ask before changing committed ownership. - “Add my own MCP server for the work repositories” in a repository a stealth source targets edits the
stealth source's
mcp.tomland runsloadout sync --stealth <name>; it does not touch the repository's.mcp.jsonoropencode.json. - “Change the global Pi model” follows the settings fragment Pi's harness block names, edits its
defaultModelvalue and syncs the selected profile. Pi renders settings only when its block also declaresplugins.
Troubleshooting
- An unresolved preview needs an explicit scope, a harness choice, or a fix to the file it names;
--yesonly approves a resolved plan. Retain unsupported inputs and report their paths. - A missing personal producer requires a scope decision. Do not silently edit shared source or invent a second contributor claiming the same keys.
- A change made outside loadout belongs in the source, not beside it. When sync refuses an output,
or
checkreportshand-edited,owned-key,owned-key-removed,unknown,unmanaged,unmanaged-linkorunparsable, follow “Porting a change made outside loadout” in configuration routing. Runsync --forceonly after showing the diff and getting the user's approval; when sync cut a diff short, read the complete one in thesync-abort.difffile it names. A file holding a secret is never diffed: loadout names it and counts the lines that differ. Read the file on disk and the source directly to see the change, or move the secret to an environment variable. - A
project.instructionsor<harness>.instructionsnote that the document repeats a heading, or akit addline naming a project skill the kit already supplies, marks guidance held twice. Resolve it by “Guidance held twice” in configuration routing. - An init that lists
unadopteditems left copies that disagree across harnesses in place. Merge them by “Resolving conflicting copies at init” in onboarding. - An init that lists
secretsadopted them into the source as they were. Say the source's remote must stay private and offer to move each into an environment variable, by “Secrets in the adopted source” in onboarding. - A failed init has already put everything back. An init killed part way stops every later init until it is put back, which needs the user at a terminal, as the onboarding reference describes.
- In a linked git worktree of the registered global source, the checkout and merge hooks print that nothing was synced: a worktree is not the registered folder, so it never renders global scope. Edit and commit there as usual (its pre-commit check still runs), then sync from the registered source once the change reaches it.