Repository navigation
Description
Summary
multi-agent still reads its user-global and personal config layers from ~/.claude and .claude/. Move both to the config-cascade layers.
Current behavior
plugins/multi-agent/scripts/resolve-roles.sh reads two old paths as layers:
:288USER_LAYER="$USER_HOME_DIR/.claude/multi-agent.yaml"(user-global file):302PERSONAL_OVERRIDE="$ROOT/.claude/multi-agent.local.yaml"(personal override)
plugins/multi-agent/skills/setup/scripts/setup.sh checks and writes the same paths (header comment :16 user <home>/.claude/multi-agent.yaml, :23 local <root>/.claude/multi-agent.local.yaml, :77 gitignore probe for .claude/multi-agent.local.yaml) and reads a legacy team file at :87 and :172 (yaml="$ROOT/.claude/multi-agent.yaml").
The team layer already reads <home>/multi-agent.yaml (resolve-roles.sh:301).
Desired behavior
Per the config-cascade layers:
| Old path | Layer |
|---|---|
~/.claude/multi-agent.yaml |
userConfig (no user-global file layer) |
<root>/.claude/multi-agent.yaml |
team: <home>/multi-agent.yaml |
<root>/.claude/multi-agent.local.yaml |
personal: <home>/multi-agent.local.yaml |
The resolver and setup read and write the contract layers; a file at an old path keeps being read during a dual-read window (see the acceptance criteria) and is reported with a warning. The canonical location list (docs/contracts/config-cascade/locations.md) lands in the docs/config-locations pull request.
Key interfaces
resolve-roles.shlayer list and the provenance it prints per valuesetup.shcheckandapplypaths
Acceptance criteria
- The resolver reads the config-cascade layers (the layers).
- Dual-read window: while an old-path file exists, it is still read and its values still apply where no new-layer file supplies that layer; each run prints one warning naming the old file and the new location to move it to. No setting in an old file is silently dropped.
-
setup.sh(checkandapply) names each old file it finds and after a preview and a yes, moves its settings to the new location, checks the new location resolves the same values, then deletes the old file, so migration ends in one home, never two (owner 2026-11-21: "we don't have dual approaches, and that stuff gets cleaned up"); the dual-read warning names that setup command, so normal skill use leads to the migration. - Removing the old-path read is a separate later change, made only once no old file is reported.
- The plugin's tests cover: new layer only; old file only (values apply, warning printed); both present (new wins, warning names both).
Placement rule (owner decisions 2026-11-21, #18000 Q1 and #18009 Q2)
For each key in the old user-global file, choose the new home by what the key is:
- a per-repo convention (what a repository's commits, PRs or files must look like): the team file
<home>/<concern>.yaml, with the personal override for one person in one repo; no newuserConfigoption; - a per-user value
userConfigcan hold (string, number, boolean, directory, file, list of strings): auserConfigoption; - a per-user structure
userConfigcannot hold (a list of objects, a nested map): onefile-typeduserConfigoption naming the user's file, which keeps the structure as it is.
If a key fits none of these, stop as design-change and name the key.
Out of scope
Other plugins' resolvers (one issue each), and userConfig option names beyond what this plugin needs.
Metadata
Metadata
Assignees
Labels
Type
Fields
Work status
Priority
Activity
github-actions commentedon Nov 21, 2026
Size: Medium
Complexity: Medium
Uncertainty: Known
Flags: none
Blocked by: none
Blast radius: multi-agent's resolve-roles.sh, setup.sh and their tests; anyone running the multi-agent resolver or setup skill, plus users with old-path config files.
Reversible: yes; revert the change, though a file migrated by setup is moved and the old file deleted, so the user would move it back.
Open questions: none
I read this as moving the multi-agent resolver and setup from the old
~/.claudeand.claude/config paths to the config-cascade layers. Old files stay readable with a warning during a dual-read window, and setup migrates them. The issue gives the layer mapping, a placement rule and exact acceptance criteria, so I see no open design question. I found no open duplicate and no merged pull request that already does this. The sibling per-plugin issues (e.g. #17999, #18000) cover other plugins' resolvers.Automated triage. A maintainer reviews it.
melodic-automation-lanes commentedon Nov 21, 2026
{"v":1,"actor_id":337595936,"title_sha256":"9386da9ce2068014ecfae6ef17c3f1d88fc0ba1ea37b62ced70c663d2547803a","body_sha256":"789384d62757432be77ee90d23aabc3bab9ea1e0217d75c1c3a1098dfde2b14e"}
docs(config-cascade): match locations.md to the contract and scope ea…
docs(config-cascade): point multi-agent and ai-slop old-path docs at …
melodic-automation-lanes commentedon Nov 21, 2026
This records a re-fire of an earlier stop, not a new one. The start gate stopped run 44949339952, the work-resolve-issue run that
agent-readystarted, before any model turn, because the GITHUB_TOKEN budget was under its start-gate share, or the window was projected to have under its start-project share of the header's limit left by the run's expected end (github-token start-gate, start-project and start-run-minutes in rate-limits.json; the run's start-gate notice names which); that run ended at 2026-11-21T21:19:19Z. work-unblock has now removed and addedagent-readyback to start a fresh run. A budget stop is the lanes' load, not a fault in this issue: it never counts toward limits.limit-stops-per-issue or thekill-switchwait.github-actions commentedon Nov 21, 2026
melodic-automation-lanes commentedon Nov 21, 2026
The work-resolve-issue lane stopped on this issue (
issue-edited-trusted): the issue's title or body changed after agent-ready was added, and every change came from a listed human or one of our listed Apps, so intake triage refines and admits the edited text again.It set Work status to needs-triage, so the hourly triage sweep sends it back through intake triage, and it waits on no decision from a person.
In the run's words:
Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/44954432186
github-actions commentedon Nov 21, 2026
The triage sweep dispatched intake triage for this issue (dispatch 1; 2 runs that reach intake, or 6 dispatches, hand it to a maintainer).
melodic-automation-lanes commentedon Nov 21, 2026
{"v":1,"actor_id":337595936,"title_sha256":"9386da9ce2068014ecfae6ef17c3f1d88fc0ba1ea37b62ced70c663d2547803a","body_sha256":"623ee2e5a932e51fec0a2179eeab04eb85d557dff0572e1da25cf8434590471f"}