From 3d0e808429003e083b6f169f6ada6b6765119e48 Mon Sep 17 00:00:00 2001 From: "melodic-automation-lanes[bot]" <337595936+melodic-automation-lanes[bot]@users.noreply.github.com> Date: Sat, 21 Nov 2026 23:27:37 +0000 Subject: [PATCH 1/3] Resolve issue #17998 Lane-Activity: work-resolve-issue/resolve-issue --- ...ssue-issue-17998-44959703861-1-92403b68.md | 7 + ...ssue-issue-17998-44959703861-1-e92d82f0.md | 12 + docs/contracts/config-cascade/README.md | 4 +- plugins/discovery/README.md | 6 +- .../multi-agent/.claude-plugin/plugin.json | 7 + plugins/multi-agent/README.md | 55 +++- .../case.yaml | 2 +- .../prompt.md | 4 +- .../samples/recommends-local-ignore-line.json | 8 +- plugins/multi-agent/reference/config.md | 25 +- .../schemas/multi-agent.schema.json | 4 +- plugins/multi-agent/scripts/resolve-roles.sh | 73 ++++-- .../multi-agent/scripts/resolve-roles.test.sh | 29 +++ plugins/multi-agent/skills/route/SKILL.md | 5 +- .../multi-agent/skills/route/scripts/route.sh | 4 +- plugins/multi-agent/skills/setup/SKILL.md | 79 ++++-- .../multi-agent/skills/setup/scripts/setup.sh | 237 +++++++++++++++--- .../skills/setup/scripts/setup.test.sh | 90 ++++++- 18 files changed, 532 insertions(+), 119 deletions(-) create mode 100644 .changes/discovery/work-resolve-issue-issue-17998-44959703861-1-92403b68.md create mode 100644 .changes/multi-agent/work-resolve-issue-issue-17998-44959703861-1-e92d82f0.md diff --git a/.changes/discovery/work-resolve-issue-issue-17998-44959703861-1-92403b68.md b/.changes/discovery/work-resolve-issue-issue-17998-44959703861-1-92403b68.md new file mode 100644 index 00000000000..a5fc6c75ccd --- /dev/null +++ b/.changes/discovery/work-resolve-issue-issue-17998-44959703861-1-92403b68.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- The README's multi-agent example names the role map's new personal override, `docs/conventions/multi-agent.local.yaml` ([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)). diff --git a/.changes/multi-agent/work-resolve-issue-issue-17998-44959703861-1-e92d82f0.md b/.changes/multi-agent/work-resolve-issue-issue-17998-44959703861-1-e92d82f0.md new file mode 100644 index 00000000000..56a3527f9ff --- /dev/null +++ b/.changes/multi-agent/work-resolve-issue-issue-17998-44959703861-1-e92d82f0.md @@ -0,0 +1,12 @@ +--- +bump: minor +--- + +### Added + +- A `role_map_file` option (type `file`) names your own role map file, the user layer of the config cascade. `/multi-agent:route` and `/multi-agent:setup` pass it to the resolver, and `/multi-agent:setup apply --layer user` writes to it ([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)). +- `/multi-agent:setup apply --migrate` moves each old file into its new location after a preview and a yes: `~/.claude/multi-agent.yaml` into the `role_map_file` file, `.claude/multi-agent.local.yaml` into `/multi-agent.local.yaml`, and a retired `.claude/multi-agent.yaml` into the team YAML. A key the new file already sets keeps its value and is named. The command reads the new file back and checks the layers still resolve the same values before it deletes the old file ([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)). + +### Changed + +- The personal override is now `/multi-agent.local.yaml`, and `setup check` recommends the `/**/*.local.*` ignore line. An old `~/.claude/multi-agent.yaml` or `.claude/multi-agent.local.yaml` is still read while its new file is absent. Each run names each old file in `notes`, with its new location and the migrate command. `setup apply --layer user` and `--layer local` refuse while that layer's old file exists ([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)). diff --git a/docs/contracts/config-cascade/README.md b/docs/contracts/config-cascade/README.md index 85e2efd3e8d..3ea0233f3dd 100644 --- a/docs/contracts/config-cascade/README.md +++ b/docs/contracts/config-cascade/README.md @@ -719,7 +719,7 @@ its conformance cell. | `authoring-formats` | no-floor | convention doc at the consumer's convention home, `/authoring-formats/README.md` (the pointer line binds ``) | team, via pointer line | team via pointer line | convention doc | declared under the expression doctrine as a new surface, not a migration: no retired dedicated file, no retirement record, no dual-read window. One layer, no personal override channel, unknown keys inert. Keys (`acceptance_criteria_format`, `diagram_dialect.data`, `diagram_dialect.system`) owned by [`authoring-formats`](../authoring-formats/README.md#c4-dialect-surfaces), which also states the ladder each consuming plugin restates in one bundled file and maps the system key against architecture's `landscape_dialect` rather than restating mermaid fitness here. `diagram_dialect.system` deliberately has no default, so an absent surface emits no C4 container view. No policy-floor class: both keys are team format choices, and the doctrine gives this class no personal layer to weaken them from. **Read on `main` by `/planning:interview` and `/planning:prd` (`acceptance_criteria_format`), by `/planning:design` (`diagram_dialect.data`, `diagram_dialect.system`), by `/architecture:map-data` (`diagram_dialect.data`), and by `/architecture:map-components`, `/architecture:map-context`, `/architecture:map-containers`, and `/architecture:map-deployment` (`diagram_dialect.system`)**, each resolving `` through its plugin's bundled `lib/resolve-convention-home.sh`. Any further consuming slice lands per skill and updates that doc's Consumers table in the same change | | `instruction-placement` | team-only | `.claude/instruction-placement.md` | all three | team on conflict (policy-floor) | per-key | conforms; per-key override (suppression entries merge per `finding_id`), plus policy-floor inversion: the team layer wins a direct conflict and a personal-only entry is reported `personal-only, not applied`, since a decline removes a placement proposal from every future report and a personal layer hiding one the team never accepted is the weakening this class prevents. `suppressions` is the surface's only key today; the plugin's `userConfig` dials stay personal and are never keys here. Written (team layer only) by `/instruction-placement:realign` behind its per-item gate, read by `/instruction-placement:audit` and `/instruction-placement:delta`. Keys owned by the plugin's `reference/consumer-config.md`; suppression-entry keys by [`finding-suppression`](../finding-suppression/README.md) | | `overengineering` | team-only | `.claude/overengineering.md` | all three | team on conflict for protected keys | per-key | conforms; per-key override, plus policy-floor inversion on two key groups: the protected-categories set and the suppression entries (which merge per `finding_id`). On both, the team layer wins a direct conflict, personal layers may extend or tighten only, and a personal contribution is named in the report: a gitignored personal override emptying the protected set would defeat the plugin's FLAG-FOR-HUMAN cap on security-class artifacts, and a personal-only suppression is the same weakening `audit-pass` prevents above. Narrowing or emptying the protected set stays available on the tracked layer, spelled one category at a time so the diff names each protection dropped. The threshold and observation-window keys take ordinary refinement. Keys owned by the plugin's `reference/consumer-config.md`; suppression-entry keys by [`finding-suppression`](../finding-suppression/README.md) | -| `multi-agent` | no-floor | team: `/multi-agent.yaml`, `` being the bound convention home, else `docs/conventions`; user-global `~/.claude/multi-agent.yaml`; personal override `.claude/multi-agent.local.yaml` | all three | later layer | per-key | the team file is validated by `plugins/multi-agent/schemas/multi-agent.schema.json`. The old team locations, the config block in `docs/conventions/multi-agent.md` and `.claude/multi-agent.yaml`, are not read; `/multi-agent:setup check` names each one it finds, and while the YAML is absent the first `/multi-agent:setup apply --layer team` write copies one old file's keys into it, leaving that file in place. Rule 5 holds: a layer that does not parse or names another schema is skipped and named, and an unknown key or a value outside its allowed set is reported and inert. No policy-floor class: every key is a routing dial, and turning the fan-out guard off is a documented opt-in on whichever layer sets it. Keys owned by [`plugins/multi-agent/reference/config.md`](../../../plugins/multi-agent/reference/config.md); resolved by `plugins/multi-agent/scripts/resolve-roles.sh`, read by `/multi-agent:route`, `/multi-agent:audit-defaults` and `/multi-agent:setup check`; written by `/multi-agent:setup apply` (any of the three layers, after a preview and an explicit yes) | +| `multi-agent` | no-floor | team: `/multi-agent.yaml`, `` being the bound convention home, else `docs/conventions`; `userConfig`: the file the `role_map_file` option names; personal override `/multi-agent.local.yaml`. Until `/multi-agent:setup apply --migrate` moves them, the old `~/.claude/multi-agent.yaml` and `.claude/multi-agent.local.yaml` still supply their layer while its new file is absent, and each run names each old file in `notes` | all three | later layer | per-key | the team file is validated by `plugins/multi-agent/schemas/multi-agent.schema.json`. The old team locations, the config block in `docs/conventions/multi-agent.md` and `.claude/multi-agent.yaml`, are not read; `/multi-agent:setup check` names each one it finds, and while the YAML is absent the first `/multi-agent:setup apply --layer team` write copies one old file's keys into it, leaving that file in place. Rule 5 holds: a layer that does not parse or names another schema is skipped and named, and an unknown key or a value outside its allowed set is reported and inert. No policy-floor class: every key is a routing dial, and turning the fan-out guard off is a documented opt-in on whichever layer sets it. Keys owned by [`plugins/multi-agent/reference/config.md`](../../../plugins/multi-agent/reference/config.md); resolved by `plugins/multi-agent/scripts/resolve-roles.sh`, read by `/multi-agent:route`, `/multi-agent:audit-defaults` and `/multi-agent:setup check`; written by `/multi-agent:setup apply` (any of the three layers, after a preview and an explicit yes) | | `multi-agent` (`verification`) | team-only | team: `/multi-agent.yaml`, the role map's team file (`` from the convention-home pointer line at the default branch, default `docs/conventions`; schema `plugins/multi-agent/schemas/multi-agent.schema.json`) | team only | the team file at the default branch; a skill entry over the plugin value; an invalid value resolves `standard`, no value `light` | per-key | conforms to the [location axis](#location-of-the-team-layer-a-docs-convention-file-or-claudename) ([ADR 0064](../../adr/0064-home-plugin-customization-in-docs-conventions-yaml.md)); no `userConfig` option, and the user-global and personal files do not set it: `scripts/resolve-roles.sh` passes over the keys in every layer, and `/multi-agent:setup apply` writes them to the team layer only. `verification_skills.` beats `verification`. `lib/read-verification.sh` (the plugin's copy) reads the file at `origin/` after a fetch, never the working tree, so a branch cannot lower its own level, and names a working-tree copy that gives another level. An invalid value or a file that does not parse is named and resolves `standard`; no value resolves `light`. Levels owned by [`docs/contracts/verification-level/README.md`](../verification-level/README.md); read by `/multi-agent:audit-defaults`. This row covers `verification` and `verification_skills` | | `review-digest` | no-floor | team: `docs/conventions/review-digest.yaml`; user-global `~/.claude/review-digest.json`; personal override `.claude/review-digest.local.json` | all three | later layer; `--policy` over every layer | per-key (lists replace) | conforms to the [location axis](#location-of-the-team-layer-a-docs-convention-file-or-claudename): the team layer is the YAML file alone, the [ADR 0064](../../adr/0064-home-plugin-customization-in-docs-conventions-yaml.md) team file. Rule 5 holds: a layer that does not parse is named and skipped, an invalid value is reported and ignored, and an unknown key is inert. Declared deviation from the per-layer verdicts: an untracked team layer is reported and resolved as absent rather than stopping, and a personal override that is not gitignored is reported and still applied, since every key only decides when a reader is offered a view. No policy-floor class. Keys owned by [`review-digest`](../../conventions/review-digest.md); resolved by `plugins/review/lib/review-digest.mjs` for `/review:explain-change` (whose `digest-policy.mjs` also reads the `rendered-views` `medium` key) and `/review:reviewer-media` | | `reviewer-media` | team-only for `voice_command` and `allow_unattended_paid_voice`, no-floor otherwise | team: `docs/conventions/reviewer-media.yaml` read at the pull request's `baseRefOid`; personal override `docs/conventions/reviewer-media.local.yaml`, applied only when untracked | team and personal override; no user-global file | later layer; `--policy` over every layer | per-key (lists replace) | conforms: read through `readLayers` with the base-commit team text; an invalid team value falls to the default, an invalid personal value leaves the team value, and a team-only key in the personal override is refused. Keys owned by [`reviewer-media`](../../conventions/reviewer-media.md); resolved by `plugins/review/skills/reviewer-media/scripts/decide.mjs` | @@ -788,7 +788,7 @@ model-run skill with no reader script, so the rule lives in the skill text. | `bugs` | implements | `scripts/concat-gotchas.sh` classifies its root inline (`CLAUDE_PROJECT_DIR`, else `git rev-parse --show-toplevel`) with the same rule and skips a team or personal override path that is the user-global file; it does not source the resolver. `/bugs:scan` reads `docs/conventions/bugs.yaml` in its skill text, with no reader script; the `verification` key is read by `lib/read-verification.sh`, which sources the plugin's `lib/config-root.sh` | | `docs-naming` | implements | `scripts/resolve-config.sh` sources its `lib/config-root.sh` copy and classifies `--root` (else the git toplevel of the current directory) against `--home`; `paths` reports team and personal override as not-applicable at a `home` or `non-repo` root | | `ai-slop` | implements | `skills/audit/scripts/detect.sh` sources its `lib/config-root.sh` copy and classifies its root (`CLAUDE_PROJECT_DIR`, else `git rev-parse --show-toplevel`, else `pwd`) before the team and personal override reads; a team or personal override file that is the user-global file is read once; the `verification` key is read by `lib/read-verification.sh`, which sources the plugin's `lib/config-root.sh` | -| `multi-agent` | implements | `scripts/resolve-roles.sh` sources its `lib/config-root.sh` copy and classifies `--root` (else `CLAUDE_PROJECT_DIR`, else the git toplevel) against `--home`; team and personal override are reported not-applicable at a `home` or `non-repo` root, and a team or personal override path that is the user-global file is read once; `/multi-agent:setup apply --layer team` and `--layer local` refuse at a `home` or `non-repo` root; the `verification` key is read by `lib/read-verification.sh`, which sources the plugin's `lib/config-root.sh` | +| `multi-agent` | implements | `scripts/resolve-roles.sh` sources its `lib/config-root.sh` copy and classifies `--root` (else `CLAUDE_PROJECT_DIR`, else the git toplevel) against `--home`; team and personal override are reported not-applicable at a `home` or `non-repo` root, and a team or personal override path that is the user layer's file is read once; `/multi-agent:setup apply --layer team` and `--layer local` refuse at a `home` or `non-repo` root; the `verification` key is read by `lib/read-verification.sh`, which sources the plugin's `lib/config-root.sh` | | `review-digest` | implements | `lib/review-digest.mjs` classifies its root inline (`CLAUDE_PROJECT_DIR`, else the nearest directory holding `.git`) and skips team and personal override when the root is the home directory, above it, or not a working tree, and any team or personal override path that is the user-global file; it does not source the resolver | | `reviewer-media` | implements | `skills/reviewer-media/scripts/decide.mjs` classifies its root with `lib/review-digest.mjs` `projectRootOf` (`CLAUDE_PROJECT_DIR`, else the nearest directory holding `.git`) and skips team and personal override when the root is the home directory, above it, or not a working tree | | `attribution` | implements | `skills/audit/scripts/lib.sh` sources its `lib/config-root.sh` copy; `cfg_layers_init` skips team and personal override unless `config_root_classify` returns `repo`, and skips a layer that `config_root_paths_same` matches to the user-global file; the `verification` key is read by `lib/read-verification.sh`, which sources the plugin's `lib/config-root.sh` | diff --git a/plugins/discovery/README.md b/plugins/discovery/README.md index 8afccac4960..0c090fc7860 100644 --- a/plugins/discovery/README.md +++ b/plugins/discovery/README.md @@ -154,16 +154,12 @@ config layers for the agent's role replaces that pin on the spawn: `retrieval` f `worker` for `researcher` and `intent-tracer`, `verifier` for `research-verifier`. Set it on the `research` workload to move these agents and the `research-sweep` stages without moving other plugins' agents in that role, for example -`roles.worker.workloads.research.model: sonnet` in `.claude/multi-agent.local.yaml`. Layers and +`roles.worker.workloads.research.model: sonnet` in `docs/conventions/multi-agent.local.yaml`. Layers and keys: the multi-agent plugin's `reference/config.md`. A layer value of `inherit` keeps the pin, because a spawn's `model` takes an alias only ([sub-agents: choose a model](https://code.claude.com/docs/en/sub-agents#choose-a-model)). With no such layer, or without `multi-agent`, the pins apply. The rule: `reference/parent-contract.md`, "The worker's model is the parent's call". -The multi-agent plugin still reads `.claude/multi-agent.local.yaml` until it migrates -([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)); then the file -moves where [config locations](reference/config-locations.md) says. - ### Options reference diff --git a/plugins/multi-agent/.claude-plugin/plugin.json b/plugins/multi-agent/.claude-plugin/plugin.json index 1ff9bac199a..2ee22dd866f 100644 --- a/plugins/multi-agent/.claude-plugin/plugin.json +++ b/plugins/multi-agent/.claude-plugin/plugin.json @@ -18,5 +18,12 @@ ], "metadata": { "category": "workflow" + }, + "userConfig": { + "role_map_file": { + "type": "file", + "title": "Role map file", + "description": "Path to your own role map file, the layer that applies in every repository, under the team file and your personal override. Same keys as the team file. Unset: no user layer. /multi-agent:setup apply --layer user writes it; apply --migrate moves an old ~/.claude/multi-agent.yaml into it." + } } } diff --git a/plugins/multi-agent/README.md b/plugins/multi-agent/README.md index 9b527f5792c..9a60e7d28e0 100644 --- a/plugins/multi-agent/README.md +++ b/plugins/multi-agent/README.md @@ -124,15 +124,52 @@ and its evidence: [`reference/routing-rubric.md`](reference/routing-rubric.md). ## Configuration -One configuration, layered user-global (`~/.claude/multi-agent.yaml`), team -(`docs/conventions/multi-agent.yaml`) and a gitignored personal override -(`.claude/multi-agent.local.yaml`), each overriding the bundled defaults per -key. `/multi-agent:setup` writes any of the three. Keys, values and layering: -[`reference/config.md`](reference/config.md). - -This plugin still reads `~/.claude/multi-agent.yaml` and `.claude/multi-agent.local.yaml` until it -migrates ([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)); then the -files move where [config locations](reference/config-locations.md) says. +One configuration, layered: your own file, named by the `role_map_file` +option (set it in `/config`), then the team file +(`docs/conventions/multi-agent.yaml`), then a gitignored personal override +(`docs/conventions/multi-agent.local.yaml`). Each overrides the bundled defaults +per key, and `/multi-agent:setup` writes any of the three. Keys, values and +layering: [`reference/config.md`](reference/config.md); where each file lives: +[config locations](reference/config-locations.md). + +An old `~/.claude/multi-agent.yaml` or `.claude/multi-agent.local.yaml` is still read while its new +file is absent, and each run warns about it; `/multi-agent:setup apply --migrate` moves it and +deletes the old file. + + + +### Options reference + +Generated from this plugin's `.claude-plugin/plugin.json`. For how Claude Code asks for +these and hands them to the plugin, see [User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration). + +| Option | Type | Default | Description | +| --- | --- | --- | --- | +| `role_map_file` | file | *(none)* | Path to your own role map file, the layer that applies in every repository, under the team file and your personal override. Same keys as the team file. Unset: no user layer. /multi-agent:setup apply --layer user writes it; apply --migrate moves an old ~/.claude/multi-agent.yaml into it. | + +### How to set these + +Set the options above for `multi-agent@`, replacing `` with the +marketplace you installed this plugin from: + +- **In a session or headless:** [`/plugin` in a session](https://code.claude.com/docs/en/plugins/cli-reference#plugin-in-a-session) or + [`claude plugin configure`](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure). The configure command is the preferred + headless route in the [plugin-reconfiguration convention](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/plugin-reconfiguration/README.md), which records its limits. +- **By hand:** under [`pluginConfigs`](https://code.claude.com/docs/en/settings-reference#pluginconfigs) in your **user** settings. + +Do **not** uninstall the plugin to reconfigure it: see [What an uninstall deletes and keeps](https://code.claude.com/docs/en/plugins/cli-reference#what-an-uninstall-deletes-and-keeps). +For a Claude Code release without `plugin configure`, see [Plugin install](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install). + +### Upstream documentation + +- [User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration) +- [Plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure) +- [Plugin install options](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install) +- [Plugins and skills settings](https://code.claude.com/docs/en/settings-reference#plugins-and-skills) +- [Settings files and who they affect](https://code.claude.com/docs/en/settings#settings-files-and-who-they-affect) +- [Manage installed plugins](https://code.claude.com/docs/en/plugins/install#manage-installed-plugins) + + ## Requirements diff --git a/plugins/multi-agent/evals/setup-check-shows-role-map-and-ignore-gap/case.yaml b/plugins/multi-agent/evals/setup-check-shows-role-map-and-ignore-gap/case.yaml index 008ef11e687..5bfb295a24b 100644 --- a/plugins/multi-agent/evals/setup-check-shows-role-map-and-ignore-gap/case.yaml +++ b/plugins/multi-agent/evals/setup-check-shows-role-map-and-ignore-gap/case.yaml @@ -29,7 +29,7 @@ graders: target: 'last_message' - name: 'recommends-local-ignore-line' type: 'regex' - pattern: '\.claude/\*\*/\*\.local\.\*' + pattern: 'docs/conventions/\*\*/\*\.local\.\*' target: 'last_message' - name: 'no-write' type: 'tool_used' diff --git a/plugins/multi-agent/evals/setup-check-shows-role-map-and-ignore-gap/prompt.md b/plugins/multi-agent/evals/setup-check-shows-role-map-and-ignore-gap/prompt.md index 6ad12a8f514..0b62ccc4d22 100644 --- a/plugins/multi-agent/evals/setup-check-shows-role-map-and-ignore-gap/prompt.md +++ b/plugins/multi-agent/evals/setup-check-shows-role-map-and-ignore-gap/prompt.md @@ -1,10 +1,10 @@ --- -description: "Explicit check in a git repository with no multi-agent layer and no .gitignore. setup SKILL.md check: run the bundled scripts/setup.sh check, show one single/fanout line per role with the layer behind each value, the layers rows and notes, and the personal-override row, which is WARN here with the recommended .claude/**/*.local.* line; recommend the line, never edit .gitignore, modify nothing. ran-setup-check is a with-only indicator: the script ships only with the plugin. role-lines checks the line shape, not a value, so a host user layer cannot flip it. The setup skill is disable-model-invocation and the prompt invokes it by slash command, so no Skill tool call is graded. Legacy setup 1 adds the session alias to the prompt (session=opus, stated literally since the eval model is not Opus): ran-check-session-opus (with-only) checks the call carries it, inherit-wording that an orchestrator, worker or verifier line writes inherit as inherit: omit the model option (SKILL.md check step 1), and no-bare-inherit that no role line writes a bare inherit. Needs --scaffold --allow-tools Bash Write Edit (Write and Edit are granted so the must-not graders can fail)." +description: "Explicit check in a git repository with no multi-agent layer and no .gitignore. setup SKILL.md check: run the bundled scripts/setup.sh check, show one single/fanout line per role with the layer behind each value, the layers rows and notes, and the personal-override row, which is WARN here with the recommended docs/conventions/**/*.local.* line; recommend the line, never edit .gitignore, modify nothing. ran-setup-check is a with-only indicator: the script ships only with the plugin. role-lines checks the line shape, not a value, so a host user layer cannot flip it. The setup skill is disable-model-invocation and the prompt invokes it by slash command, so no Skill tool call is graded. Legacy setup 1 adds the session alias to the prompt (session=opus, stated literally since the eval model is not Opus): ran-check-session-opus (with-only) checks the call carries it, inherit-wording that an orchestrator, worker or verifier line writes inherit as inherit: omit the model option (SKILL.md check step 1), and no-bare-inherit that no role line writes a bare inherit. Needs --scaffold --allow-tools Bash Write Edit (Write and Edit are granted so the must-not graders can fail)." tags: ['multi-agent', 'setup', 'check', 'read-only'] max_turns: 10 timeout_seconds: 300 allowed_tools: [Read, Glob, Grep, Skill, Bash, Write, Edit] -expected_outcome: 'Runs setup.sh check session=opus (never apply or --write), writes inherit as inherit: omit the model option, shows a single/fanout line for each of orchestrator, worker, verifier and retrieval, reports the personal-override WARN and recommends the .claude/**/*.local.* line without editing .gitignore; writes and edits nothing.' +expected_outcome: 'Runs setup.sh check session=opus (never apply or --write), writes inherit as inherit: omit the model option, shows a single/fanout line for each of orchestrator, worker, verifier and retrieval, reports the personal-override WARN and recommends the docs/conventions/**/*.local.* line without editing .gitignore; writes and edits nothing.' --- /multi-agent:setup check. This session runs on Opus (session=opus). diff --git a/plugins/multi-agent/evals/setup-check-shows-role-map-and-ignore-gap/samples/recommends-local-ignore-line.json b/plugins/multi-agent/evals/setup-check-shows-role-map-and-ignore-gap/samples/recommends-local-ignore-line.json index e01e9203fcd..f32f1e9fd05 100644 --- a/plugins/multi-agent/evals/setup-check-shows-role-map-and-ignore-gap/samples/recommends-local-ignore-line.json +++ b/plugins/multi-agent/evals/setup-check-shows-role-map-and-ignore-gap/samples/recommends-local-ignore-line.json @@ -1,14 +1,18 @@ { "pass": [ { - "answer": "WARN personal-override: `.claude/multi-agent.local.yaml` is not gitignored. Add `.claude/**/*.local.*` to `.gitignore`." + "answer": "WARN personal-override: `docs/conventions/multi-agent.local.yaml` is not gitignored. Add `docs/conventions/**/*.local.*` to `.gitignore`." } ], "fail": [ { - "answer": "WARN personal-override: `.claude/multi-agent.local.yaml` is not gitignored. Add `.claude/*.local.*` to `.gitignore`.", + "answer": "WARN personal-override: `docs/conventions/multi-agent.local.yaml` is not gitignored. Add `docs/conventions/*.local.*` to `.gitignore`.", "why": "flat rule, not the recursive one" }, + { + "answer": "WARN personal-override: `.claude/multi-agent.local.yaml` is not gitignored. Add `.claude/**/*.local.*` to `.gitignore`.", + "why": "the old personal override path's line" + }, { "answer": "WARN personal-override: not gitignored.", "why": "no recommended line" diff --git a/plugins/multi-agent/reference/config.md b/plugins/multi-agent/reference/config.md index e684b0bb58d..f70a6e5c0f3 100644 --- a/plugins/multi-agent/reference/config.md +++ b/plugins/multi-agent/reference/config.md @@ -11,13 +11,21 @@ this page owns the keys. | Layer | Path | |---|---| | Bundled | `${CLAUDE_PLUGIN_ROOT}/reference/defaults.yaml` | -| User-global | `~/.claude/multi-agent.yaml` | +| `userConfig` (`user-config`) | the file the `role_map_file` option names; unset means no user layer | | Team | `/multi-agent.yaml`, `` being the convention home the repository binds, else `docs/conventions` | -| Personal override | `.claude/multi-agent.local.yaml` (gitignored) | +| Personal override | `/multi-agent.local.yaml` (gitignored by `/**/*.local.*`) | -The resolver still reads the user-global and personal override paths above until it migrates -([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)); then the files -move where [config locations](config-locations.md) says. +The user layer is a nested map of the same keys as the team file, which no +scalar `userConfig` option can hold, so the plugin's one `role_map_file` +option (type `file`) names a file that keeps it, and `/config` sets it. + +**Old paths, read during the migration window.** While no new file supplies +the user layer, `~/.claude/multi-agent.yaml` still does, named `user-global` +in `source`; while `/multi-agent.local.yaml` is absent, +`.claude/multi-agent.local.yaml` still supplies the personal override. Every +run names each old file it finds, read or not, in `notes`, with its new +location and `/multi-agent:setup apply --migrate`, which moves the file after a +preview and a yes and then deletes it. A later change removes these reads. Later layers win per key. Team and personal override are read only when the root is a repository that is neither `$HOME` nor an ancestor of it @@ -28,7 +36,8 @@ resolver no longer reads the old team locations, the config block in `/multi-agent:setup check` names each one it finds. While the team YAML is absent, the first `/multi-agent:setup apply --layer team` write copies the keys of one of them, the block when there is one, into the new YAML and leaves the -old file in place. Every layer declares `schema: 1`; a layer that does not +old file in place; `/multi-agent:setup apply --migrate` moves +`.claude/multi-agent.yaml` into the YAML and deletes it. Every layer declares `schema: 1`; a layer that does not parse or names another schema is skipped and named in `notes`, and the layers around it still apply. The format is a YAML subset: nested mappings, scalars, comments. No lists. `/multi-agent:setup apply` writes a layer after a preview @@ -50,7 +59,7 @@ and an explicit yes. `verification` is not part of the role map. It sets whether `/multi-agent:audit-defaults` runs its skeptic panel: `light` and `off` skip it and report every finding `unverified`, so no diff is proposed. It is read from the team file at the default branch only, through -`lib/read-verification.sh`; the resolver ignores it in every layer, and the user-global and +`lib/read-verification.sh`; the resolver ignores it in every layer, and the user and personal files cannot set it. A skill entry beats the plugin value ([verification level](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/verification-level/README.md)). @@ -141,7 +150,7 @@ changes nothing. Setting `fanout.frontier_guard: false` is an explicit opt-in to frontier fan-outs. Set it on the layer whose scope you mean: the personal override for one -checkout, the user-global file for every repository on one machine. +checkout, the user file for every repository you work in. Before a fan-out wider than about four workers, run one worker as a pilot and confirm plan usage remains for the rest: a usage limit reached mid-fan-out diff --git a/plugins/multi-agent/schemas/multi-agent.schema.json b/plugins/multi-agent/schemas/multi-agent.schema.json index dae18a0ea5a..311e784d53f 100644 --- a/plugins/multi-agent/schemas/multi-agent.schema.json +++ b/plugins/multi-agent/schemas/multi-agent.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/plugins/multi-agent/schemas/multi-agent.schema.json", "title": "Multi-agent team config", - "description": "Schema for a repository's docs/conventions/multi-agent.yaml: the team layer of the multi-agent plugin's role map. A value here overrides the bundled default and the user-global file, and a personal .claude/multi-agent.local.yaml overrides it. Keys and resolution: plugins/multi-agent/reference/config.md. Contract: docs/adr/0064-home-plugin-customization-in-docs-conventions-yaml.md.", + "description": "Schema for a repository's docs/conventions/multi-agent.yaml: the team layer of the multi-agent plugin's role map. A value here overrides the bundled default and the user file the role_map_file option names, and a personal docs/conventions/multi-agent.local.yaml overrides it. Keys and resolution: plugins/multi-agent/reference/config.md. Contract: docs/adr/0064-home-plugin-customization-in-docs-conventions-yaml.md.", "type": "object", "additionalProperties": false, "required": ["schema"], @@ -48,7 +48,7 @@ "verification": { "enum": ["off", "light", "standard", "strict"], "default": "light", - "description": "How much independent checking this plugin's skills run: off, light (the default: skip the verifier dispatch), standard (run it) or strict (also run the optional passes). Read from this team file's committed copy on the default branch only, so a branch cannot lower it and the user-global and personal files cannot set it. Levels: docs/contracts/verification-level/README.md." + "description": "How much independent checking this plugin's skills run: off, light (the default: skip the verifier dispatch), standard (run it) or strict (also run the optional passes). Read from this team file's committed copy on the default branch only, so a branch cannot lower it and the user and personal files cannot set it. Levels: docs/contracts/verification-level/README.md." }, "verification_skills": { "type": "object", diff --git a/plugins/multi-agent/scripts/resolve-roles.sh b/plugins/multi-agent/scripts/resolve-roles.sh index ec7a7d3df5b..a4a7c098c6f 100755 --- a/plugins/multi-agent/scripts/resolve-roles.sh +++ b/plugins/multi-agent/scripts/resolve-roles.sh @@ -3,12 +3,17 @@ # # LAYERS, bottom to top, each overriding per key: # bundled reference/defaults.yaml -# user-global /.claude/multi-agent.yaml -# team /multi-agent.yaml ( is the convention home the -# repository binds, else docs/conventions) -# personal-override /.claude/multi-agent.local.yaml +# user-config the file the role_map_file userConfig option names (--user-file) +# team //multi-agent.yaml ( is the convention home +# the repository binds, else docs/conventions) +# personal-override //multi-agent.local.yaml +# Dual-read window: while no file above supplies the user-config or the +# personal-override layer, its old file still does: ~/.claude/multi-agent.yaml +# (the layer is then named user-global) or /.claude/multi-agent.local.yaml. +# Each old file found adds one note naming it, its new location and +# /multi-agent:setup apply --migrate, whether it was read or not. # Team and personal-override apply only when lib/config-root.sh classifies as -# `repo`; a team or personal-override path that is the user-global file is read once. +# `repo`; a team or personal-override path that is the user layer's file is read once. # A layer that does not parse, or declares a schema other than 1, is skipped # and named in `notes`. A key with a value outside its allowed set is rejected # and named; the layer below keeps the key. Keys and values: reference/config.md. @@ -35,7 +40,10 @@ # as frontier # --root repository root (default: CLAUDE_PROJECT_DIR, else the # git toplevel) -# --home directory holding .claude/multi-agent.yaml (default $HOME) +# --home the user's home, holding the old .claude/multi-agent.yaml +# (default $HOME) +# --user-file the file the role_map_file option names; empty or an +# unsubstituted ${user_config.role_map_file} means unset # --defaults bundled layer (tests) # # JSON shape: {"session_model", "session_frontier", "workload", "roles": {: @@ -95,16 +103,18 @@ WORKLOAD="" SESSION_MODEL="" ROOT="" USER_HOME_DIR="${HOME:-}" +USER_FILE="" while [[ $# -gt 0 ]]; do case "$1" in pointers) MODE=pointers ;; - --workload | --session-model | --root | --home | --defaults) + --workload | --session-model | --root | --home | --user-file | --defaults) [[ $# -gt 1 ]] || die "$1 needs a value" case "$1" in --workload) WORKLOAD="$2" ;; --session-model) SESSION_MODEL="$2" ;; --root) ROOT="$2" ;; --home) USER_HOME_DIR="$2" ;; + --user-file) USER_FILE="$2" ;; *) DEFAULTS="$2" ;; esac shift @@ -284,13 +294,39 @@ read_layer() { [[ -n "$ROOT" ]] || ROOT="$(config_root_resolve)" ROOT_CLASS="$(HOME="$USER_HOME_DIR" config_root_classify "$ROOT")" +MIGRATE="/multi-agent:setup apply --migrate" USER_LAYER="" -[[ -n "$USER_HOME_DIR" ]] && USER_LAYER="$USER_HOME_DIR/.claude/multi-agent.yaml" -if [[ -n "$USER_LAYER" && -f "$USER_LAYER" ]]; then - read_layer user-global "$USER_LAYER" -else - layer_state user-global "$USER_LAYER" absent -fi + +dual_read() { + local label="$1" old_label="$2" new="$3" old="$4" where="$5" has_old=0 + READ_FILE="" + [[ -n "$old" && -f "$old" ]] && ! config_root_paths_same "$old" "$USER_LAYER" && has_old=1 + if [[ -n "$new" && -f "$new" ]]; then + if config_root_paths_same "$new" "$USER_LAYER"; then + layer_state "$label" "$new" absent + else + read_layer "$label" "$new" + READ_FILE="$new" + fi + if ((has_old)) && ! config_root_paths_same "$old" "$new"; then + NOTES+=("$old_label: $old is an old path and not read, since $new supplies the layer; $MIGRATE merges its keys into $new and deletes it") + fi + elif ((has_old)); then + read_layer "$old_label" "$old" + READ_FILE="$old" + NOTES+=("$old_label: $old is an old path, still read until it moves; $MIGRATE moves it to $where and deletes it") + else + layer_state "$label" "$new" absent + fi +} + +[[ "$USER_FILE" == "\${user_config."* ]] && USER_FILE="" +OLD_USER="" +[[ -n "$USER_HOME_DIR" ]] && OLD_USER="$USER_HOME_DIR/.claude/multi-agent.yaml" +user_where="the file the role_map_file option names (set it in /config)" +[[ -n "$USER_FILE" ]] && user_where="$USER_FILE" +dual_read user-config user-global "$USER_FILE" "$OLD_USER" "$user_where" +USER_LAYER="$READ_FILE" # The convention home is the one the repository binds in AGENTS.md or CLAUDE.md # (lib/resolve-convention-home.sh); docs/conventions when it binds none. @@ -299,21 +335,18 @@ if [[ -f "$SCRIPT_DIR/../lib/resolve-convention-home.sh" ]]; then home_out="$(bash "$SCRIPT_DIR/../lib/resolve-convention-home.sh" --root "$ROOT" 2>/dev/null)" && CONVENTION_HOME="$home_out" fi TEAM_CONCERN="$ROOT/$CONVENTION_HOME/multi-agent.yaml" -PERSONAL_OVERRIDE="$ROOT/.claude/multi-agent.local.yaml" +PERSONAL_OVERRIDE="$ROOT/$CONVENTION_HOME/multi-agent.local.yaml" if [[ "$ROOT_CLASS" != repo ]]; then layer_state team "$TEAM_CONCERN" "not-applicable ($ROOT_CLASS root)" layer_state personal-override "$PERSONAL_OVERRIDE" "not-applicable ($ROOT_CLASS root)" else - if [[ -f "$TEAM_CONCERN" ]]; then + if [[ -f "$TEAM_CONCERN" ]] && ! config_root_paths_same "$TEAM_CONCERN" "$USER_LAYER"; then read_layer team "$TEAM_CONCERN" else layer_state team "$TEAM_CONCERN" absent fi - if [[ -f "$PERSONAL_OVERRIDE" ]] && ! config_root_paths_same "$PERSONAL_OVERRIDE" "$USER_LAYER"; then - read_layer personal-override "$PERSONAL_OVERRIDE" - else - layer_state personal-override "$PERSONAL_OVERRIDE" absent - fi + dual_read personal-override personal-override "$PERSONAL_OVERRIDE" \ + "$ROOT/.claude/multi-agent.local.yaml" "$PERSONAL_OVERRIDE" fi # A workload is declared when its last workloads. value is true. diff --git a/plugins/multi-agent/scripts/resolve-roles.test.sh b/plugins/multi-agent/scripts/resolve-roles.test.sh index a0855a38b8b..367165096a2 100755 --- a/plugins/multi-agent/scripts/resolve-roles.test.sh +++ b/plugins/multi-agent/scripts/resolve-roles.test.sh @@ -174,6 +174,35 @@ out="$(run layered worker --session-model opus)" assert_contains "user-global effort and personal override model merge per key" "$out" '"single":{"model":"sonnet","omit_model":false,"effort":"high"' assert_contains "source names the layer per value" "$out" '"source":{"model":"personal-override","effort":"user-global"}' +fixture newlayers +printf 'schema: 1\nroles:\n worker:\n effort: high\n' >"$T/newlayers/user.yaml" +printf 'schema: 1\nroles:\n worker:\n model: sonnet\n' >"$T/newlayers/repo/docs/conventions/multi-agent.local.yaml" +out="$(run newlayers worker --session-model opus --user-file "$T/newlayers/user.yaml")" +assert_contains "new layers: user file effort and personal override model merge per key" "$out" '"single":{"model":"sonnet","omit_model":false,"effort":"high"' +assert_contains "new layers: source names user-config and personal-override" "$out" '"source":{"model":"personal-override","effort":"user-config"}' +assert_contains "new layers: the personal row names the home path" "$out" '"layer":"personal-override","path":"'"$T/newlayers/repo/docs/conventions/multi-agent.local.yaml"'","state":"read"' +assert_lacks "new layers: no old-path warning" "$out" 'old path' + +fixture oldonly +printf 'schema: 1\nroles:\n worker:\n effort: high\n' >"$T/oldonly/home/.claude/multi-agent.yaml" +printf 'schema: 1\nroles:\n worker:\n model: sonnet\n' >"$T/oldonly/repo/.claude/multi-agent.local.yaml" +out="$(run oldonly worker --session-model opus --user-file '${user_config.role_map_file}')" +assert_contains "old only: values apply" "$out" '"single":{"model":"sonnet","omit_model":false,"effort":"high"' +assert_contains "old only: an unsubstituted option reads as unset" "$out" '"source":{"model":"personal-override","effort":"user-global"}' +assert_contains "old only: the user file warning names the option and setup" "$out" "user-global: $T/oldonly/home/.claude/multi-agent.yaml is an old path, still read until it moves; /multi-agent:setup apply --migrate moves it to the file the role_map_file option names" +assert_contains "old only: the personal warning names the new location" "$out" "personal-override: $T/oldonly/repo/.claude/multi-agent.local.yaml is an old path, still read until it moves; /multi-agent:setup apply --migrate moves it to $T/oldonly/repo/docs/conventions/multi-agent.local.yaml" +assert_eq "old only: one warning per old file on stderr" 2 "$(grep -c 'is an old path' "$T/oldonly.err")" + +fixture both +printf 'schema: 1\nroles:\n worker:\n effort: low\n' >"$T/both/home/.claude/multi-agent.yaml" +printf 'schema: 1\nroles:\n worker:\n effort: high\n' >"$T/both/user.yaml" +printf 'schema: 1\nroles:\n worker:\n model: opus\n' >"$T/both/repo/.claude/multi-agent.local.yaml" +printf 'schema: 1\nroles:\n worker:\n model: sonnet\n' >"$T/both/repo/docs/conventions/multi-agent.local.yaml" +out="$(run both worker --session-model opus --user-file "$T/both/user.yaml")" +assert_contains "both: the new files win" "$out" '"single":{"model":"sonnet","omit_model":false,"effort":"high"' +assert_contains "both: the user warning names both files" "$out" "user-global: $T/both/home/.claude/multi-agent.yaml is an old path and not read, since $T/both/user.yaml supplies the layer" +assert_contains "both: the personal warning names both files" "$out" "personal-override: $T/both/repo/.claude/multi-agent.local.yaml is an old path and not read, since $T/both/repo/docs/conventions/multi-agent.local.yaml supplies the layer" + # Turning the guard off is the explicit opt-in to frontier fan-outs. fixture optout printf 'schema: 1\nfanout:\n frontier_guard: false\n' >"$T/optout/repo/docs/conventions/multi-agent.yaml" diff --git a/plugins/multi-agent/skills/route/SKILL.md b/plugins/multi-agent/skills/route/SKILL.md index 0332c72ebdd..18051616b18 100644 --- a/plugins/multi-agent/skills/route/SKILL.md +++ b/plugins/multi-agent/skills/route/SKILL.md @@ -30,11 +30,12 @@ read it when a note or a user question concerns a key, a layer or the guard. ## Run ```bash -${CLAUDE_SKILL_DIR}/scripts/route.sh $ARGUMENTS +${CLAUDE_SKILL_DIR}/scripts/route.sh $ARGUMENTS --user-file '${user_config.role_map_file}' ``` Append `session=` when `$ARGUMENTS` carries none and you know your model -family. +family. Keep `--user-file` exactly as written: it names the user layer's file, +and the resolver reads an empty or unsubstituted value as no user layer. ## Output diff --git a/plugins/multi-agent/skills/route/scripts/route.sh b/plugins/multi-agent/skills/route/scripts/route.sh index 7db485930a9..3175beeeabd 100755 --- a/plugins/multi-agent/skills/route/scripts/route.sh +++ b/plugins/multi-agent/skills/route/scripts/route.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# route.sh [workload] [session=] +# route.sh [workload] [session=] [--user-file ] # Translates the skill's arguments for scripts/resolve-roles.sh and runs it: # the first bare argument is the role, the second the workload. set -uo pipefail @@ -17,7 +17,7 @@ for a in "$@"; do fi case "$a" in session=*) [[ -n "${a#session=}" ]] && pass+=(--session-model "${a#session=}") ;; - --workload | --session-model | --root | --home | --defaults) pass+=("$a") value=1 ;; + --workload | --session-model | --root | --home | --user-file | --defaults) pass+=("$a") value=1 ;; -*) pass+=("$a") ;; *) if ((++bare == 2)); then pass+=(--workload "$a"); else pass+=("$a"); fi ;; esac diff --git a/plugins/multi-agent/skills/setup/SKILL.md b/plugins/multi-agent/skills/setup/SKILL.md index 2c32cde9004..09d32f5b86d 100644 --- a/plugins/multi-agent/skills/setup/SKILL.md +++ b/plugins/multi-agent/skills/setup/SKILL.md @@ -1,6 +1,6 @@ --- description: "Check the multi-agent role map (model and effort per role and the layer behind each value) or write confirmed keys into the user, team or local multi-agent.yaml layer." -argument-hint: "[check|apply] [--layer user|team|local] [= ...] [session=]" +argument-hint: "[check|apply] [--layer user|team|local|--migrate] [= ...] [session=]" user-invocable: true disable-model-invocation: true allowed-tools: ["Bash(${CLAUDE_SKILL_DIR}/scripts/setup.sh:*)"] @@ -10,24 +10,24 @@ shell: bash ## Purpose `/multi-agent:route` resolves the role map through four layers: the bundled -defaults, `~/.claude/multi-agent.yaml`, the team layer and -`.claude/multi-agent.local.yaml`. This skill shows what those layers resolve to +defaults, the user file the `role_map_file` option names, the team layer and +`/multi-agent.local.yaml`. This skill shows what those layers resolve to and writes one of them. All three consumer layers absent is a valid state: the bundled defaults apply. Keys, values, layer paths and the fan-out guard are defined in [`${CLAUDE_PLUGIN_ROOT}/reference/config.md`](${CLAUDE_PLUGIN_ROOT}/reference/config.md). -This plugin still reads `~/.claude/multi-agent.yaml` and `.claude/multi-agent.local.yaml` until it -migrates ([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)); then the -files move where [config locations](../../reference/config-locations.md) says. +An old `~/.claude/multi-agent.yaml` or `.claude/multi-agent.local.yaml` is still read while its new +file is absent, with a warning; `apply --migrate` moves it. No argument means `check`. It installs nothing; the resolver needs only Bash, -awk and git. +awk and git. Pass `--user-file '${user_config.role_map_file}'` on every +`setup.sh` call, exactly as written below. ## `check` (read-only) ```bash -${CLAUDE_SKILL_DIR}/scripts/setup.sh check session= +${CLAUDE_SKILL_DIR}/scripts/setup.sh check session= --user-file '${user_config.role_map_file}' ``` Pass `session=` with the family in your own model ID (`opus`, `sonnet`, @@ -41,12 +41,14 @@ Show: 2. the `layers` rows (read, absent, skipped, or not applicable at a home or non-repository root) and every entry of `notes` as written; each note (a skipped layer, a rejected value, an ignored key) is a finding to report; -3. the personal-override row: PASS when `.claude/multi-agent.local.yaml` is gitignored, - else WARN with the recommended line `.claude/**/*.local.*`. Recommend the - line; do not edit `.gitignore`; -4. each `WARN team:` row: a retired team file (the config block in +3. the personal-override row: PASS when `/multi-agent.local.yaml` is + gitignored, else WARN with the recommended line `/**/*.local.*`. + Recommend the line; do not edit `.gitignore`; +4. each `WARN user-config:` or `WARN personal-override:` row naming an old + path, and each `WARN team:` row: a retired team file (the config block in `docs/conventions/multi-agent.md`, or `.claude/multi-agent.yaml`) that the - resolver no longer reads. Relay the row's next step as written. + resolver no longer reads. Relay the row's next step as written, and offer + `apply --migrate` for each old file. It modifies nothing. @@ -54,20 +56,23 @@ It modifies nothing. 1. Run `check` and show the map. This is the before state. 2. Settle the layer with the user, recommendation first: - - `local` (`.claude/multi-agent.local.yaml`): this checkout only, for this + - `local` (`/multi-agent.local.yaml`): this checkout only, for this person. The default for a personal preference. - `team`: `docs/conventions/multi-agent.yaml` (under the convention home the repository binds). Shared with everyone who clones the repository. - - `user` (`~/.claude/multi-agent.yaml`): every repository on this machine. + - `user`: the file the `role_map_file` option names, for every repository + you work in. While the option is unset, `apply --layer user` stops: ask + the user to set it in `/config` to a file of their choosing, then rerun. - `team` and `local` are refused at a home or non-repository root. + `team` and `local` are refused at a home or non-repository root. `user` and + `local` are refused while that layer's old file exists: migrate first. 3. Settle the keys. Ask only for what the user wants changed; each value comes from the table in `config.md`. Pass every key to set as `=`, and `=` to remove one from that layer. Existing keys in the layer are kept. 4. Preview, writing nothing: ```bash - ${CLAUDE_SKILL_DIR}/scripts/setup.sh apply --layer = ... + ${CLAUDE_SKILL_DIR}/scripts/setup.sh apply --layer --user-file '${user_config.role_map_file}' = ... ``` It prints the target path and a diff. It exits 1 without writing when the @@ -76,7 +81,7 @@ It modifies nothing. 5. Show the diff and ask for an explicit yes. Write only on that yes: ```bash - ${CLAUDE_SKILL_DIR}/scripts/setup.sh apply --layer --write = ... + ${CLAUDE_SKILL_DIR}/scripts/setup.sh apply --layer --write --user-file '${user_config.role_map_file}' = ... ``` It prints the path written and the keys it read back from the file. @@ -86,6 +91,36 @@ It modifies nothing. changes. For `team`, offer `git add` and a commit and run each only when the user accepts. +### `apply --migrate` + +Moves each old file into its new location, so each layer ends with one file: +`~/.claude/multi-agent.yaml` into the `role_map_file` option's file, +`.claude/multi-agent.local.yaml` into `/multi-agent.local.yaml`, and the +retired `.claude/multi-agent.yaml` into the team YAML. + +1. Run `check` and show the map and the old-path rows. +2. Preview, writing nothing: + + ```bash + ${CLAUDE_SKILL_DIR}/scripts/setup.sh apply --migrate --user-file '${user_config.role_map_file}' + ``` + + It prints one `would move:` line and a diff per old file. A key the new + file already sets keeps its value, and a `kept:` line names it with the old + value. A `skip:` line means the old user file has no new home yet: relay + its step (set the option in `/config`). +3. Show the preview and ask for an explicit yes. Move only on that yes: + + ```bash + ${CLAUDE_SKILL_DIR}/scripts/setup.sh apply --migrate --write --user-file '${user_config.role_map_file}' + ``` + + For each file it writes the new file, reads it back, checks that the + layers resolve the values the old file gave (when the old file was the one + read), and only then deletes the old file. On a failed check it exits 1 + and keeps the old file; relay the message. +4. Run `check` again and show the after map beside the before one. + ### The fan-out guard With `fanout.frontier_guard: true`, the bundled value, a stage that runs more @@ -103,8 +138,8 @@ every agent of the stage on the frontier model (rates: [Manage costs: Track your costs](https://code.claude.com/docs/en/costs#track-your-costs)). Before writing it, say this and ask the user to confirm that specific key, separately from the rest of the change. Recommend the narrowest layer that -covers what they mean: `local` for one checkout, `user` for one machine, `team` -only when the whole team has agreed. +covers what they mean: `local` for one checkout, `user` for every repository +you work in, `team` only when the whole team has agreed. ## What this skill does not do @@ -131,6 +166,8 @@ Prints the map the next workflow reads from `args.roles`. not read. - The first `team` write creates the YAML. A retired team file, which the resolver no longer reads, seeds its keys and stays as it was; `check` names - it until it is deleted. + it until it is deleted. `apply --migrate` moves a retired + `.claude/multi-agent.yaml` and deletes it; the config block in + `docs/conventions/multi-agent.md` is left to delete by hand. - Team and local layers resolve against the repository root of the working directory. Inside a second worktree, run from that worktree. diff --git a/plugins/multi-agent/skills/setup/scripts/setup.sh b/plugins/multi-agent/skills/setup/scripts/setup.sh index 36ec37bd5d9..82d16123aed 100755 --- a/plugins/multi-agent/skills/setup/scripts/setup.sh +++ b/plugins/multi-agent/skills/setup/scripts/setup.sh @@ -3,29 +3,42 @@ # # setup.sh check [session=] # The resolved map through the route wrapper (JSON on stdout, notes on -# stderr), then one row on the personal override's gitignore state and a -# WARN row for each retired team file still present. +# stderr), then one row on the personal override's gitignore state, a +# WARN row for each retired team file still present and one for each +# old user or personal file. # setup.sh apply --layer user|team|local [--write] = ... # Merges the pairs into that layer's existing keys. `=` with no # value removes the key. Without --write it prints the target path and a # diff and writes nothing; with --write it writes, then reads the file # back. The candidate is resolved before anything is written: a key the -# resolver would reject or ignore stops the run with exit 1. +# resolver would reject or ignore stops the run with exit 1. user and +# local are refused while that layer's old file exists. +# setup.sh apply --migrate [--write] +# Moves each old file into its new location: ~/.claude/multi-agent.yaml +# to the user file, /.claude/multi-agent.local.yaml to local and +# /.claude/multi-agent.yaml to team. A key the new file already +# sets keeps its value; every other key of the old file is added. +# Without --write it prints each move and a diff; with --write it +# writes the new file, reads it back, resolves the layers, and only +# then deletes the old file. # # Layers (reference/config.md): -# user /.claude/multi-agent.yaml +# user the file the role_map_file userConfig option names (--user-file); +# refused while the option is unset # team //multi-agent.yaml, being the convention home the # repository binds, else docs/conventions. While that file is absent, # the keys of a retired team file (the config block in # docs/conventions/multi-agent.md, else .claude/multi-agent.yaml), # which the resolver no longer reads, seed it; that file is left as # it is, and check names it. -# local /.claude/multi-agent.local.yaml +# local //multi-agent.local.yaml # team and local are refused unless lib/config-root.sh classifies as repo. # A layer file is rewritten whole, so comments in it are not kept. # -# Options for tests: --root (default CLAUDE_PROJECT_DIR, else the git -# toplevel), --home (default $HOME). +# --user-file takes the role_map_file option's value; empty or an +# unsubstituted ${user_config.role_map_file} means unset. Options for tests: +# --root (default CLAUDE_PROJECT_DIR, else the git toplevel), --home +# (default $HOME). # # Exit: 0 done (or nothing to change); 1 the candidate does not resolve # cleanly, or the existing layer does not parse; 2 usage error or a refused layer. @@ -46,20 +59,22 @@ die() { ACTION="${1:-check}" [[ $# -gt 0 ]] && shift -LAYER="" WRITE=0 ROOT="" HOME_DIR="${HOME:-}" +LAYER="" WRITE=0 MIGRATE=0 ROOT="" HOME_DIR="${HOME:-}" USER_FILE="" SESSION=() PAIRS=() while [[ $# -gt 0 ]]; do case "$1" in - --layer | --root | --home) + --layer | --root | --home | --user-file) [[ $# -gt 1 ]] || die "$1 needs a value" case "$1" in --layer) LAYER="$2" ;; --root) ROOT="$2" ;; + --user-file) USER_FILE="$2" ;; *) HOME_DIR="$2" ;; esac shift ;; --write) WRITE=1 ;; + --migrate) MIGRATE=1 ;; session=*) SESSION=("$1") ;; *=*) PAIRS+=("$1") ;; *) die "unknown argument '$1'" ;; @@ -68,20 +83,57 @@ while [[ $# -gt 0 ]]; do done [[ -n "$ROOT" ]] || ROOT="$(config_root_resolve)" CLASS="$(HOME="$HOME_DIR" config_root_classify "$ROOT")" +[[ "$USER_FILE" == "\${user_config."* ]] && USER_FILE="" LOCATE=(--root "$ROOT" --home "$HOME_DIR") +[[ -n "$USER_FILE" ]] && LOCATE+=(--user-file "$USER_FILE") +OLD_USER="" +[[ -n "$HOME_DIR" ]] && OLD_USER="$HOME_DIR/.claude/multi-agent.yaml" +OLD_LOCAL="$ROOT/.claude/multi-agent.local.yaml" +SET_OPTION="set the role_map_file option in /config to the file that should hold it" +OLD_USER_SAME=0 +[[ -n "$USER_FILE" ]] && config_root_paths_same "$OLD_USER" "$USER_FILE" && OLD_USER_SAME=1 +NAME_OUTSIDE="the role_map_file option names the old file $OLD_USER; name a file outside ~/.claude" + +old_beside() { + [[ -e "$1" || -L "$1" ]] && ! config_root_paths_same "$1" "$2" +} check() { + local home "$ROUTE" all "${SESSION[@]+"${SESSION[@]}"}" "${LOCATE[@]}" || return if [[ "$CLASS" != repo ]]; then printf 'INFO personal-override: not applicable at a %s root\n' "$CLASS" - elif git -C "$ROOT" check-ignore -q .claude/multi-agent.local.yaml; then - printf 'PASS personal-override: .claude/multi-agent.local.yaml is gitignored\n' else - printf 'WARN personal-override: .claude/multi-agent.local.yaml is not gitignored; the recommended line is .claude/**/*.local.*\n' + home="$(convention_home)" + if git -C "$ROOT" check-ignore -q "$home/multi-agent.local.yaml"; then + printf 'PASS personal-override: %s/multi-agent.local.yaml is gitignored\n' "$home" + else + printf 'WARN personal-override: %s/multi-agent.local.yaml is not gitignored; the recommended line is %s/**/*.local.*\n' "$home" "$home" + fi fi + old_rows if [[ "$CLASS" == repo ]]; then retired_rows; fi } +old_rows() { + local new_local + if [[ -n "$OLD_USER" && -f "$OLD_USER" ]]; then + if ((OLD_USER_SAME)); then + printf 'WARN user-config: %s, then run apply --migrate\n' "$NAME_OUTSIDE" + elif [[ -n "$USER_FILE" ]]; then + printf 'WARN user-config: %s is an old path; apply --migrate moves its keys into %s and deletes it\n' "$OLD_USER" "$USER_FILE" + else + printf 'WARN user-config: %s is an old path; %s, then run apply --migrate\n' "$OLD_USER" "$SET_OPTION" + fi + fi + [[ "$CLASS" == repo ]] || return 0 + new_local="$ROOT/$(convention_home)/multi-agent.local.yaml" + if old_beside "$OLD_LOCAL" "$new_local"; then + printf 'WARN personal-override: %s is an old path; apply --migrate moves its keys into %s and deletes it\n' \ + "$OLD_LOCAL" "$new_local" + fi +} + # One WARN row per retired team file the resolver no longer reads. retired_rows() { local md="$ROOT/docs/conventions/multi-agent.md" yaml="$ROOT/.claude/multi-agent.yaml" @@ -110,13 +162,13 @@ retired_rows() { fi if [[ -L "$yaml" ]]; then printf 'WARN team: %s is a symlink and no longer read; delete it\n' "$yaml" - elif [[ -e "$yaml" ]]; then + elif [[ -e "$yaml" ]] && ! config_root_paths_same "$yaml" "$target"; then if ((seeds)) && link="$(symlink_in "$yaml")"; then printf 'WARN team: %s is no longer read, and apply --layer team refuses it while %s is absent, since %s is a symlink; %s\n' "$yaml" "$target" "$link" "$manual" - elif ((seeds)); then - printf 'WARN team: %s is no longer read; the first apply --layer team copies its keys into %s, then delete it\n' "$yaml" "$target" + elif link="$(symlink_in "$yaml")"; then + printf 'WARN team: %s is no longer read, and apply --migrate refuses it, since %s is a symlink; %s\n' "$yaml" "$link" "$manual" else - printf 'WARN team: %s is no longer read; %s\n' "$yaml" "$manual" + printf 'WARN team: %s is no longer read; apply --migrate moves its keys into %s and deletes it\n' "$yaml" "$target" fi fi } @@ -167,19 +219,46 @@ symlink_in() { return 1 } +make_tmp() { + tmp="$(mktemp -d)" + trap 'rm -rf "$tmp"' EXIT +} + +check_candidate() { + rm -rf "${tmp:?}/repo" "${tmp:?}/home" + mkdir -p "$tmp/repo/docs/conventions" "$tmp/home" + git -C "$tmp/repo" init -q + printf '%s\n' "$1" >"$tmp/repo/docs/conventions/multi-agent.local.yaml" + if ! "$RESOLVER" --root "$tmp/repo" --home "$tmp/home" all >/dev/null 2>"$tmp/notes" || + [[ -s "$tmp/notes" ]]; then + printf 'setup: the layer would not resolve cleanly; nothing written:\n' >&2 + sed 's/^resolve-roles: personal-override/ candidate/; s/^resolve-roles: / /' "$tmp/notes" >&2 + exit 1 + fi +} + apply() { + ((MIGRATE)) && { + migrate + return + } local target existing="" records body old_label seed="" seed_block=0 local legacy_md="$ROOT/docs/conventions/multi-agent.md" legacy_yaml="$ROOT/.claude/multi-agent.yaml" case "$LAYER" in user) - [[ -n "$HOME_DIR" ]] || die "no home directory to hold the user layer" - target="$HOME_DIR/.claude/multi-agent.yaml" + [[ -n "$USER_FILE" ]] || die "the user layer is the file the role_map_file option names; $SET_OPTION" + ((!OLD_USER_SAME)) || die "$NAME_OUTSIDE, then run apply --migrate" + [[ -z "$OLD_USER" || ! -f "$OLD_USER" ]] || + die "$OLD_USER is the old user file; run apply --migrate first, so the user layer has one home" + target="$USER_FILE" ;; team | local) [[ "$CLASS" == repo ]] || die "the $LAYER layer is not applicable at a $CLASS root; run from the repository, or use --layer user" if [[ "$LAYER" == local ]]; then - target="$ROOT/.claude/multi-agent.local.yaml" + target="$ROOT/$(convention_home)/multi-agent.local.yaml" + ! old_beside "$OLD_LOCAL" "$target" || + die "$OLD_LOCAL is the old personal file; run apply --migrate first, so the local layer has one home" else target="$ROOT/$(convention_home)/multi-agent.yaml" # Until the YAML exists, the retired team file seeds it, so the first @@ -234,17 +313,8 @@ apply() { done body="$(grep -v '^$' <<<"$existing" | render)" - tmp="$(mktemp -d)" - trap 'rm -rf "$tmp"' EXIT - mkdir -p "$tmp/repo/.claude" "$tmp/home" - git -C "$tmp/repo" init -q - printf '%s\n' "$body" >"$tmp/repo/.claude/multi-agent.local.yaml" - if ! "$RESOLVER" --root "$tmp/repo" --home "$tmp/home" all >/dev/null 2>"$tmp/notes" || - [[ -s "$tmp/notes" ]]; then - printf 'setup: the layer would not resolve cleanly; nothing written:\n' >&2 - sed 's/^resolve-roles: personal-override/ candidate/; s/^resolve-roles: / /' "$tmp/notes" >&2 - exit 1 - fi + make_tmp + check_candidate "$body" printf '%s\n' "$body" >"$tmp/new" : >"$tmp/old" @@ -275,6 +345,113 @@ apply() { awk -F '\t' '$1!="block" { print " " $1 ": " $2 }' } +records_of() { + local r + if ! r="$(awk -f "$PARSER" "$1")"; then + printf 'setup: %s does not parse (%s); fix or remove it before apply\n' \ + "$1" "$(awk -F '\t' '$1=="error"{print "line " $2 ": " $3}' <<<"$r")" >&2 + return 1 + fi + awk -F '\t' '$1!="schema" && $1!="block"' <<<"$r" +} + +sorted_records() { grep -v '^$' <<<"$1" | LC_ALL=C sort; } + +resolved_roles() { + local json cut=',"layers":' + json="$("$RESOLVER" "${LOCATE[@]}" all 2>/dev/null)" || return 1 + json="${json%%"$cut"*}" + printf '%s' "${json//user-global/user-config}" +} + +migrate() { + local found=0 old_team="$ROOT/.claude/multi-agent.yaml" home + ((${#PAIRS[@]} == 0)) || die "apply --migrate takes no =" + make_tmp + if [[ -n "$OLD_USER" && -f "$OLD_USER" ]]; then + found=1 + if [[ -z "$USER_FILE" ]]; then + printf 'skip: %s stays until the user layer has a new home; %s, then rerun apply --migrate\n' "$OLD_USER" "$SET_OPTION" + elif ((OLD_USER_SAME)); then + printf 'skip: %s, then rerun apply --migrate\n' "$NAME_OUTSIDE" + else + move_file user "$OLD_USER" "$USER_FILE" + fi + fi + if [[ "$CLASS" == repo ]]; then + home="$(convention_home)" + if old_beside "$OLD_LOCAL" "$ROOT/$home/multi-agent.local.yaml"; then + found=1 + move_file local "$OLD_LOCAL" "$ROOT/$home/multi-agent.local.yaml" + fi + if old_beside "$old_team" "$ROOT/$home/multi-agent.yaml"; then + found=1 + move_file team "$old_team" "$ROOT/$home/multi-agent.yaml" + fi + fi + ((found)) || printf 'nothing to migrate: no old file found\n' +} + +move_file() { + local layer="$1" old="$2" new="$3" old_recs new_recs="" merged key value kept body + local label=/dev/null live=0 before="" back + if [[ "$layer" != user ]]; then + refuse_symlink "$old" + refuse_symlink "$new" + fi + old_recs="$(records_of "$old")" || exit 1 + if [[ -f "$new" ]]; then + new_recs="$(records_of "$new")" || exit 1 + elif [[ "$layer" != team ]]; then + live=1 + fi + merged="$new_recs" + while IFS=$'\t' read -r key value; do + [[ -n "$key" ]] || continue + if [[ "$layer" != team && "$key" == verification* ]]; then + printf 'note: %s in %s is read from the team layer only, so it is not carried; set it with apply --layer team\n' "$key" "$old" + continue + fi + if kept="$(awk -F '\t' -v k="$key" '$1==k { print $2; found=1 } END { exit !found }' <<<"$new_recs")"; then + [[ "$kept" == "$value" ]] || + printf 'kept: %s: %s from %s (the old file says %s)\n' "$key" "$kept" "$new" "$value" + continue + fi + merged+=$'\n'"$key"$'\t'"$value" + done <<<"$old_recs" + body="$(grep -v '^$' <<<"$merged" | render)" + ((live)) || check_candidate "$body" + + printf '%s\n' "$body" >"$tmp/new" + : >"$tmp/old" + [[ -f "$new" ]] && cp "$new" "$tmp/old" && label="$new" + if ((!WRITE)); then + printf 'would move: %s into %s (%s layer), then delete %s\n' "$old" "$new" "$layer" "$old" + grep -q '#' "$old" "$tmp/old" && + printf 'note: the new file is written whole; comments in either file are not kept\n' + diff -u --label "$label" --label "$new" "$tmp/old" "$tmp/new" + return 0 + fi + + ((live)) && before="$(resolved_roles)" + mkdir -p "$(dirname "$new")" || die "cannot create $(dirname "$new")" + if ! { cp "$tmp/new" "$new.tmp.$$" && mv -f "$new.tmp.$$" "$new"; }; then + rm -f "$new.tmp.$$" + die "cannot write $new" + fi + back="$(records_of "$new")" || exit 1 + if [[ "$(sorted_records "$back")" != "$(sorted_records "$merged")" ]]; then + printf 'setup: %s does not read back the keys written; %s is kept\n' "$new" "$old" >&2 + exit 1 + fi + if ((live)) && [[ "$(resolved_roles)" != "$before" ]]; then + printf 'setup: %s does not resolve the values %s did; both are kept\n' "$new" "$old" >&2 + exit 1 + fi + rm -f -- "$old" || die "wrote $new, but cannot delete $old" + printf 'moved: %s into %s (%s layer); deleted %s\n' "$old" "$new" "$layer" "$old" +} + case "$ACTION" in check) check ;; apply) apply ;; diff --git a/plugins/multi-agent/skills/setup/scripts/setup.test.sh b/plugins/multi-agent/skills/setup/scripts/setup.test.sh index ea0c2dc3f52..a442b76828b 100755 --- a/plugins/multi-agent/skills/setup/scripts/setup.test.sh +++ b/plugins/multi-agent/skills/setup/scripts/setup.test.sh @@ -29,33 +29,33 @@ run() { # run fixture dry out="$(run dry apply --layer local roles.worker.effort=high)" -assert_contains "dry run names the personal override path" "$out" "would write: $T/dry/repo/.claude/multi-agent.local.yaml" +assert_contains "dry run names the personal override path" "$out" "would write: $T/dry/repo/docs/conventions/multi-agent.local.yaml" assert_contains "dry run shows the new key in a diff" "$out" '+ effort: high' state=absent -[[ -e "$T/dry/repo/.claude/multi-agent.local.yaml" ]] && state=present +[[ -e "$T/dry/repo/docs/conventions/multi-agent.local.yaml" ]] && state=present assert_eq "dry run writes nothing" absent "$state" fixture local out="$(run local apply --layer local --write roles.worker.effort=high fanout.frontier_guard=false)" -assert_contains "write reports the path" "$out" "wrote: $T/local/repo/.claude/multi-agent.local.yaml (local layer)" +assert_contains "write reports the path" "$out" "wrote: $T/local/repo/docs/conventions/multi-agent.local.yaml (local layer)" assert_contains "write reads the stored value back" "$out" ' fanout.frontier_guard: false' -assert_eq "written file is the rendered subset" "$(cat "$T/local/repo/.claude/multi-agent.local.yaml")" \ +assert_eq "written file is the rendered subset" "$(cat "$T/local/repo/docs/conventions/multi-agent.local.yaml")" \ $'schema: 1\nfanout:\n frontier_guard: false\nroles:\n worker:\n effort: high' out="$(run local check session=fable)" assert_contains "check shows the personal override as the source" "$out" '"source":{"model":"bundled","effort":"personal-override"}' assert_contains "check shows the guard off: fan-out inherits under fable" "$out" '"fanout":{"model":"inherit","omit_model":true,"effort":"high","guarded":false}' assert_contains "check warns when the personal override is not ignored" "$out" 'WARN personal-override' out="$(run local apply --layer local --write roles.worker.effort=high)" -assert_eq "rerun with the same value is unchanged" "unchanged: $T/local/repo/.claude/multi-agent.local.yaml" "$out" +assert_eq "rerun with the same value is unchanged" "unchanged: $T/local/repo/docs/conventions/multi-agent.local.yaml" "$out" run local apply --layer local --write fanout.frontier_guard= >/dev/null -assert_lacks "an empty value removes the key" "$(cat "$T/local/repo/.claude/multi-agent.local.yaml")" 'frontier_guard' +assert_lacks "an empty value removes the key" "$(cat "$T/local/repo/docs/conventions/multi-agent.local.yaml")" 'frontier_guard' fixture reject run reject apply --layer local --write roles.worker.model=claude-opus-5-5 >/dev/null assert_eq "a value the resolver rejects exits 1" 1 "$?" assert_contains "the rejection is relayed" "$(cat "$T/reject.err")" "roles.worker.model rejected" state=absent -[[ -e "$T/reject/repo/.claude/multi-agent.local.yaml" ]] && state=present +[[ -e "$T/reject/repo/docs/conventions/multi-agent.local.yaml" ]] && state=present assert_eq "a rejected candidate writes nothing" absent "$state" run reject apply --layer local --write roles.judge.model=opus >/dev/null assert_eq "an unknown role exits 1" 1 "$?" @@ -111,7 +111,7 @@ out="$(run claudefile apply --layer team roles.verifier.effort=high)" assert_contains "team targets the concern YAML, not the .claude file" "$out" "would write: $T/claudefile/repo/docs/conventions/multi-agent.yaml" assert_contains "the .claude file seeds the preview" "$out" '+ effort: low' out="$(run claudefile check session=opus)" -assert_contains "check names the retired .claude file and the seed" "$out" "WARN team: $T/claudefile/repo/.claude/multi-agent.yaml is no longer read; the first apply --layer team copies its keys into $T/claudefile/repo/docs/conventions/multi-agent.yaml, then delete it" +assert_contains "check names the retired .claude file and the migration" "$out" "WARN team: $T/claudefile/repo/.claude/multi-agent.yaml is no longer read; apply --migrate moves its keys into $T/claudefile/repo/docs/conventions/multi-agent.yaml and deletes it" assert_contains "the resolver does not read the retired .claude file" "$out" '"layer":"team","path":"'"$T/claudefile/repo/docs/conventions/multi-agent.yaml"'","state":"absent"' fixture existing @@ -128,8 +128,8 @@ out="$(run team check session=opus)" assert_lacks "no retired file: no team WARN row" "$out" 'WARN team' fixture broken -mkdir -p "$T/broken/repo/.claude" -printf 'schema: 1\nroles:\n\tworker:\n' >"$T/broken/repo/.claude/multi-agent.local.yaml" +mkdir -p "$T/broken/repo/docs/conventions" +printf 'schema: 1\nroles:\n\tworker:\n' >"$T/broken/repo/docs/conventions/multi-agent.local.yaml" run broken apply --layer local --write roles.worker.effort=low >/dev/null assert_eq "an unparsable layer is not overwritten" 1 "$?" assert_contains "the parse error names the line" "$(cat "$T/broken.err")" 'line 3: tab indentation' @@ -175,7 +175,7 @@ assert_eq "a symlinked docs file beside a .claude file is refused" 2 "$?" out="$(run mdbeside check session=opus)" assert_contains "check names the symlinked docs file beside a .claude file" "$out" "WARN team: apply --layer team refuses $T/mdbeside/repo/docs/conventions/multi-agent.md while" assert_lacks "check promises no seed apply would refuse" "$out" 'the first apply --layer team copies' -assert_contains "the .claude file gets the copy-by-hand row" "$out" "WARN team: $T/mdbeside/repo/.claude/multi-agent.yaml is no longer read; copy any key still wanted into $T/mdbeside/repo/docs/conventions/multi-agent.yaml, then delete it" +assert_contains "the .claude file gets the migration row" "$out" "WARN team: $T/mdbeside/repo/.claude/multi-agent.yaml is no longer read; apply --migrate moves its keys into $T/mdbeside/repo/docs/conventions/multi-agent.yaml and deletes it" # A regular .claude file in a symlinked .claude directory: apply refuses it. fixture claudedir @@ -189,8 +189,72 @@ assert_contains "check names the symlinked .claude directory" "$out" "WARN team: assert_lacks "check promises no seed from a symlinked directory" "$out" 'the first apply --layer team copies' fixture user -out="$(run user apply --layer user --write fanout.model=sonnet)" -assert_contains "user layer goes under the home" "$out" "wrote: $T/user/home/.claude/multi-agent.yaml" +run user apply --layer user --write fanout.model=sonnet >/dev/null +assert_eq "user layer with the option unset is refused" 2 "$?" +assert_contains "the refusal names the option" "$(cat "$T/user.err")" 'role_map_file option' +run user apply --layer user --write --user-file '${user_config.role_map_file}' fanout.model=sonnet >/dev/null +assert_eq "an unsubstituted option is unset" 2 "$?" +out="$(run user apply --layer user --write --user-file "$T/user/role-map.yaml" fanout.model=sonnet)" +assert_contains "user layer goes to the option's file" "$out" "wrote: $T/user/role-map.yaml (user layer)" +state=absent +[[ -e "$T/user/home/.claude/multi-agent.yaml" ]] && state=present +assert_eq "nothing is written under ~/.claude" absent "$state" + +fixture mig +mkdir -p "$T/mig/home/.claude" "$T/mig/repo/.claude" +printf 'schema: 1\nroles:\n worker:\n effort: high\n' >"$T/mig/home/.claude/multi-agent.yaml" +printf 'schema: 1\nroles:\n worker:\n model: sonnet\n' >"$T/mig/repo/.claude/multi-agent.local.yaml" +out="$(run mig check session=opus)" +assert_contains "check: the old user file row names the option" "$out" "WARN user-config: $T/mig/home/.claude/multi-agent.yaml is an old path; set the role_map_file option in /config" +assert_contains "check: the old personal file row names the new path" "$out" "WARN personal-override: $T/mig/repo/.claude/multi-agent.local.yaml is an old path; apply --migrate moves its keys into $T/mig/repo/docs/conventions/multi-agent.local.yaml and deletes it" +assert_contains "check: the dual-read warning names the setup command" "$(cat "$T/mig.err")" '/multi-agent:setup apply --migrate' +run mig apply --layer local --write roles.worker.effort=low >/dev/null +assert_eq "local apply beside the old personal file is refused" 2 "$?" +assert_contains "the refusal names the migration" "$(cat "$T/mig.err")" 'run apply --migrate first' +run mig apply --layer user --write --user-file "$T/mig/role-map.yaml" roles.worker.effort=low >/dev/null +assert_eq "user apply beside the old user file is refused" 2 "$?" +out="$(run mig apply --migrate)" +assert_contains "migrate without the option skips the user file" "$out" "skip: $T/mig/home/.claude/multi-agent.yaml stays until the user layer has a new home" +assert_contains "migrate previews the personal move" "$out" "would move: $T/mig/repo/.claude/multi-agent.local.yaml into $T/mig/repo/docs/conventions/multi-agent.local.yaml (local layer)" +assert_contains "migrate preview shows the keys" "$out" '+ model: sonnet' +state=absent +[[ -e "$T/mig/repo/docs/conventions/multi-agent.local.yaml" ]] && state=present +assert_eq "migrate preview writes nothing" absent "$state" +out="$(run mig apply --migrate --write --user-file "$T/mig/role-map.yaml")" +assert_eq "migrate write exits 0" 0 "$?" +assert_contains "migrate moves the user file" "$out" "moved: $T/mig/home/.claude/multi-agent.yaml into $T/mig/role-map.yaml (user layer)" +assert_contains "migrate moves the personal file" "$out" "moved: $T/mig/repo/.claude/multi-agent.local.yaml into $T/mig/repo/docs/conventions/multi-agent.local.yaml (local layer)" +assert_eq "the user file holds the old keys" $'schema: 1\nroles:\n worker:\n effort: high' "$(cat "$T/mig/role-map.yaml")" +state=absent +[[ -e "$T/mig/home/.claude/multi-agent.yaml" || -e "$T/mig/repo/.claude/multi-agent.local.yaml" ]] && state=present +assert_eq "migrate deletes the old files" absent "$state" +out="$(run mig check session=opus --user-file "$T/mig/role-map.yaml")" +assert_contains "after migrate: the same values from the new layers" "$out" '"single":{"model":"sonnet","omit_model":false,"effort":"high","guarded":false},"fanout":{"model":"sonnet","omit_model":false,"effort":"high","guarded":false},"source":{"model":"personal-override","effort":"user-config"}' +assert_lacks "after migrate: no old-path row" "$out" 'old path' +out="$(run mig apply --migrate --user-file "$T/mig/role-map.yaml")" +assert_eq "migrate with no old file says so" "nothing to migrate: no old file found" "$out" + +fixture migboth +mkdir -p "$T/migboth/repo/.claude" "$T/migboth/repo/docs/conventions" +printf 'schema: 1\nroles:\n worker:\n effort: low\n model: sonnet\n' >"$T/migboth/repo/.claude/multi-agent.local.yaml" +printf 'schema: 1\nroles:\n worker:\n effort: high\n' >"$T/migboth/repo/docs/conventions/multi-agent.local.yaml" +out="$(run migboth apply --migrate --write)" +assert_contains "both: the kept key is named" "$out" "kept: roles.worker.effort: high from $T/migboth/repo/docs/conventions/multi-agent.local.yaml (the old file says low)" +assert_eq "both: the old key the new file lacks is added" $'schema: 1\nroles:\n worker:\n effort: high\n model: sonnet' \ + "$(cat "$T/migboth/repo/docs/conventions/multi-agent.local.yaml")" +state=absent +[[ -e "$T/migboth/repo/.claude/multi-agent.local.yaml" ]] && state=present +assert_eq "both: the old file is deleted" absent "$state" + +fixture migteam +mkdir -p "$T/migteam/repo/.claude" +printf 'schema: 1\nroles:\n worker:\n effort: low\n' >"$T/migteam/repo/.claude/multi-agent.yaml" +out="$(run migteam apply --migrate --write)" +assert_contains "team: the retired file moves into the YAML" "$out" "moved: $T/migteam/repo/.claude/multi-agent.yaml into $T/migteam/repo/docs/conventions/multi-agent.yaml (team layer)" +assert_eq "team: the YAML holds its keys" $'schema: 1\nroles:\n worker:\n effort: low' "$(cat "$T/migteam/repo/docs/conventions/multi-agent.yaml")" +state=absent +[[ -e "$T/migteam/repo/.claude/multi-agent.yaml" ]] && state=present +assert_eq "team: the retired file is deleted" absent "$state" mkdir -p "$T/homeroot" git -C "$T/homeroot" init -q From b93ec3c04757c184ce9c2795bb1feecc217488ca Mon Sep 17 00:00:00 2001 From: "melodic-automation-lanes[bot]" <337595936+melodic-automation-lanes[bot]@users.noreply.github.com> Date: Sat, 21 Nov 2026 23:50:29 +0000 Subject: [PATCH 2/3] Fix failing CI checks on work-resolve-issue/issue-17998-44959703861-1 Lane-Activity: pr-unblock/fix-ci --- plugins/multi-agent/scripts/resolve-roles.sh | 135 +++++++++--------- .../multi-agent/skills/route/scripts/route.sh | 1 - .../multi-agent/skills/setup/scripts/setup.sh | 95 ++++++------ 3 files changed, 122 insertions(+), 109 deletions(-) diff --git a/plugins/multi-agent/scripts/resolve-roles.sh b/plugins/multi-agent/scripts/resolve-roles.sh index a4a7c098c6f..a93151d568d 100755 --- a/plugins/multi-agent/scripts/resolve-roles.sh +++ b/plugins/multi-agent/scripts/resolve-roles.sh @@ -1,74 +1,79 @@ #!/usr/bin/env bash -# resolve-roles.sh: resolve the multi-agent role map through the config cascade. -# -# LAYERS, bottom to top, each overriding per key: -# bundled reference/defaults.yaml -# user-config the file the role_map_file userConfig option names (--user-file) -# team //multi-agent.yaml ( is the convention home -# the repository binds, else docs/conventions) -# personal-override //multi-agent.local.yaml -# Dual-read window: while no file above supplies the user-config or the -# personal-override layer, its old file still does: ~/.claude/multi-agent.yaml -# (the layer is then named user-global) or /.claude/multi-agent.local.yaml. -# Each old file found adds one note naming it, its new location and -# /multi-agent:setup apply --migrate, whether it was read or not. -# Team and personal-override apply only when lib/config-root.sh classifies as -# `repo`; a team or personal-override path that is the user layer's file is read once. -# A layer that does not parse, or declares a schema other than 1, is skipped -# and named in `notes`. A key with a value outside its allowed set is rejected -# and named; the layer below keeps the key. Keys and values: reference/config.md. -# -# Every role resolves to two variants: -# single a stage that runs one agent: the role's own model and effort. -# fanout a stage that runs more than one agent. With fanout.frontier_guard -# on, a model that is `inherit` under a frontier or unknown session, -# or a frontier alias, becomes fanout.model. -# -# Usage: -# resolve-roles.sh [options] JSON on stdout -# resolve-roles.sh pointers [--defaults F] TSV owner, key, value of every -# pointer*, as_of and recheck default -# Options: -# --workload apply roles..workloads. keys; -# is a workload some layer declares -# (workloads.: true); the bundled -# layer declares code, research and -# mechanical -# --session-model the session model's alias (opus, -# sonnet, haiku, fable); omitted -# means unknown, which the guard treats -# as frontier -# --root repository root (default: CLAUDE_PROJECT_DIR, else the -# git toplevel) -# --home the user's home, holding the old .claude/multi-agent.yaml -# (default $HOME) -# --user-file the file the role_map_file option names; empty or an -# unsubstituted ${user_config.role_map_file} means unset -# --defaults bundled layer (tests) -# -# JSON shape: {"session_model", "session_frontier", "workload", "roles": {: -# {"role", "single": V, "fanout": V, "source": {"model", "effort"}, "basis": -# {"model", "fanout_model", "effort"}}}, "layers": [{"layer", "path", "state"}], -# "notes": [...]}, where V is {"model", "omit_model", "effort", "guarded"}. A -# basis is `upstream` or `judgment` as the bundled layer records it -# (basis_ in reference/defaults.yaml), `config` when a consumer layer -# supplied the value, or `unrecorded` when the bundled entry names none. -# `fanout_model` is the fanout variant's model basis: the role's own unless the -# guard replaced it, then fanout.model's. `omit_model` is true when model is -# `inherit`: the caller passes no model option and the agent runs on the -# session model. `guarded` is true when the fan-out guard replaced the model. -# A role whose single or fanout model is haiku, named or inherited from a haiku -# session, gains one `notes` entry pointing at reference/routing-rubric.md; the -# role still resolves. -# -# Exit: 0 resolved; 2 usage error, unknown role (valid roles on stderr), -# undeclared workload (declared ones on stderr), or an unreadable bundled layer. set -uo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" PARSER="$SCRIPT_DIR/yaml-subset.awk" DEFAULTS="$SCRIPT_DIR/../reference/defaults.yaml" +usage() { + cat <<'EOF' +resolve-roles.sh: resolve the multi-agent role map through the config cascade. + +LAYERS, bottom to top, each overriding per key: + bundled reference/defaults.yaml + user-config the file the role_map_file userConfig option names (--user-file) + team //multi-agent.yaml ( is the convention home + the repository binds, else docs/conventions) + personal-override //multi-agent.local.yaml +Dual-read window: while no file above supplies the user-config or the +personal-override layer, its old file still does: ~/.claude/multi-agent.yaml +(the layer is then named user-global) or /.claude/multi-agent.local.yaml. +Each old file found adds one note naming it, its new location and +/multi-agent:setup apply --migrate, whether it was read or not. +Team and personal-override apply only when lib/config-root.sh classifies as +`repo`; a team or personal-override path that is the user layer's file is read once. +A layer that does not parse, or declares a schema other than 1, is skipped +and named in `notes`. A key with a value outside its allowed set is rejected +and named; the layer below keeps the key. Keys and values: reference/config.md. + +Every role resolves to two variants: + single a stage that runs one agent: the role's own model and effort. + fanout a stage that runs more than one agent. With fanout.frontier_guard + on, a model that is `inherit` under a frontier or unknown session, + or a frontier alias, becomes fanout.model. + +Usage: + resolve-roles.sh [options] JSON on stdout + resolve-roles.sh pointers [--defaults F] TSV owner, key, value of every + pointer*, as_of and recheck default +Options: + --workload apply roles..workloads. keys; + is a workload some layer declares + (workloads.: true); the bundled + layer declares code, research and + mechanical + --session-model the session model's alias (opus, + sonnet, haiku, fable); omitted + means unknown, which the guard treats + as frontier + --root repository root (default: CLAUDE_PROJECT_DIR, else the + git toplevel) + --home the user's home, holding the old .claude/multi-agent.yaml + (default $HOME) + --user-file the file the role_map_file option names; empty or an + unsubstituted ${user_config.role_map_file} means unset + --defaults bundled layer (tests) + +JSON shape: {"session_model", "session_frontier", "workload", "roles": {: +{"role", "single": V, "fanout": V, "source": {"model", "effort"}, "basis": +{"model", "fanout_model", "effort"}}}, "layers": [{"layer", "path", "state"}], +"notes": [...]}, where V is {"model", "omit_model", "effort", "guarded"}. A +basis is `upstream` or `judgment` as the bundled layer records it +(basis_ in reference/defaults.yaml), `config` when a consumer layer +supplied the value, or `unrecorded` when the bundled entry names none. +`fanout_model` is the fanout variant's model basis: the role's own unless the +guard replaced it, then fanout.model's. `omit_model` is true when model is +`inherit`: the caller passes no model option and the agent runs on the +session model. `guarded` is true when the fan-out guard replaced the model. +A role whose single or fanout model is haiku, named or inherited from a haiku +session, gains one `notes` entry pointing at reference/routing-rubric.md; the +role still resolves. + +Exit: 0 resolved; 2 usage error, unknown role (valid roles on stderr), +undeclared workload (declared ones on stderr), or an unreadable bundled layer. +EOF +} + # Validation constants: a chosen subset of the aliases at # https://code.claude.com/docs/en/model-config#model-aliases and the levels at # https://code.claude.com/docs/en/model-config#choose-an-effort-level (as of @@ -120,7 +125,7 @@ while [[ $# -gt 0 ]]; do shift ;; -h | --help) - sed -n '2,/^# Exit:/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//' + usage exit 0 ;; -*) die "unknown option '$1'" ;; diff --git a/plugins/multi-agent/skills/route/scripts/route.sh b/plugins/multi-agent/skills/route/scripts/route.sh index 3175beeeabd..8fe3a541641 100755 --- a/plugins/multi-agent/skills/route/scripts/route.sh +++ b/plugins/multi-agent/skills/route/scripts/route.sh @@ -1,5 +1,4 @@ #!/usr/bin/env bash -# route.sh [workload] [session=] [--user-file ] # Translates the skill's arguments for scripts/resolve-roles.sh and runs it: # the first bare argument is the role, the second the workload. set -uo pipefail diff --git a/plugins/multi-agent/skills/setup/scripts/setup.sh b/plugins/multi-agent/skills/setup/scripts/setup.sh index 82d16123aed..42643a4fde6 100755 --- a/plugins/multi-agent/skills/setup/scripts/setup.sh +++ b/plugins/multi-agent/skills/setup/scripts/setup.sh @@ -1,47 +1,4 @@ #!/usr/bin/env bash -# setup.sh: inspect or write one layer of the multi-agent role map. -# -# setup.sh check [session=] -# The resolved map through the route wrapper (JSON on stdout, notes on -# stderr), then one row on the personal override's gitignore state, a -# WARN row for each retired team file still present and one for each -# old user or personal file. -# setup.sh apply --layer user|team|local [--write] = ... -# Merges the pairs into that layer's existing keys. `=` with no -# value removes the key. Without --write it prints the target path and a -# diff and writes nothing; with --write it writes, then reads the file -# back. The candidate is resolved before anything is written: a key the -# resolver would reject or ignore stops the run with exit 1. user and -# local are refused while that layer's old file exists. -# setup.sh apply --migrate [--write] -# Moves each old file into its new location: ~/.claude/multi-agent.yaml -# to the user file, /.claude/multi-agent.local.yaml to local and -# /.claude/multi-agent.yaml to team. A key the new file already -# sets keeps its value; every other key of the old file is added. -# Without --write it prints each move and a diff; with --write it -# writes the new file, reads it back, resolves the layers, and only -# then deletes the old file. -# -# Layers (reference/config.md): -# user the file the role_map_file userConfig option names (--user-file); -# refused while the option is unset -# team //multi-agent.yaml, being the convention home the -# repository binds, else docs/conventions. While that file is absent, -# the keys of a retired team file (the config block in -# docs/conventions/multi-agent.md, else .claude/multi-agent.yaml), -# which the resolver no longer reads, seed it; that file is left as -# it is, and check names it. -# local //multi-agent.local.yaml -# team and local are refused unless lib/config-root.sh classifies as repo. -# A layer file is rewritten whole, so comments in it are not kept. -# -# --user-file takes the role_map_file option's value; empty or an -# unsubstituted ${user_config.role_map_file} means unset. Options for tests: -# --root (default CLAUDE_PROJECT_DIR, else the git toplevel), --home -# (default $HOME). -# -# Exit: 0 done (or nothing to change); 1 the candidate does not resolve -# cleanly, or the existing layer does not parse; 2 usage error or a refused layer. set -uo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -52,6 +9,54 @@ PARSER="$PLUGIN_DIR/scripts/yaml-subset.awk" # shellcheck source=../../../lib/config-root.sh . "$PLUGIN_DIR/lib/config-root.sh" +usage() { + cat <<'EOF' +setup.sh: inspect or write one layer of the multi-agent role map. + + setup.sh check [session=] + The resolved map through the route wrapper (JSON on stdout, notes on + stderr), then one row on the personal override's gitignore state, a + WARN row for each retired team file still present and one for each + old user or personal file. + setup.sh apply --layer user|team|local [--write] = ... + Merges the pairs into that layer's existing keys. `=` with no + value removes the key. Without --write it prints the target path and a + diff and writes nothing; with --write it writes, then reads the file + back. The candidate is resolved before anything is written: a key the + resolver would reject or ignore stops the run with exit 1. user and + local are refused while that layer's old file exists. + setup.sh apply --migrate [--write] + Moves each old file into its new location: ~/.claude/multi-agent.yaml + to the user file, /.claude/multi-agent.local.yaml to local and + /.claude/multi-agent.yaml to team. A key the new file already + sets keeps its value; every other key of the old file is added. + Without --write it prints each move and a diff; with --write it + writes the new file, reads it back, resolves the layers, and only + then deletes the old file. + +Layers (reference/config.md): + user the file the role_map_file userConfig option names (--user-file); + refused while the option is unset + team //multi-agent.yaml, being the convention home the + repository binds, else docs/conventions. While that file is absent, + the keys of a retired team file (the config block in + docs/conventions/multi-agent.md, else .claude/multi-agent.yaml), + which the resolver no longer reads, seed it; that file is left as + it is, and check names it. + local //multi-agent.local.yaml +team and local are refused unless lib/config-root.sh classifies as repo. +A layer file is rewritten whole, so comments in it are not kept. + +--user-file takes the role_map_file option's value; empty or an +unsubstituted ${user_config.role_map_file} means unset. Options for tests: +--root (default CLAUDE_PROJECT_DIR, else the git toplevel), --home + (default $HOME). + +Exit: 0 done (or nothing to change); 1 the candidate does not resolve +cleanly, or the existing layer does not parse; 2 usage error or a refused layer. +EOF +} + die() { printf 'setup: %s\n' "$1" >&2 exit 2 @@ -59,6 +64,10 @@ die() { ACTION="${1:-check}" [[ $# -gt 0 ]] && shift +if [[ "$ACTION" == -h || "$ACTION" == --help ]]; then + usage + exit 0 +fi LAYER="" WRITE=0 MIGRATE=0 ROOT="" HOME_DIR="${HOME:-}" USER_FILE="" SESSION=() PAIRS=() while [[ $# -gt 0 ]]; do From a39b5569726f9a912f20da60f3018eff1f9199d9 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 20:31:40 -0500 Subject: [PATCH 3/3] fix(multi-agent): expand ~/ in role_map_file and refuse a relative path The role_map_file option reached setup.sh and resolve-roles.sh verbatim, and both skills pass it single-quoted, so a value of ~/role-map.yaml made apply --layer user --write create /~/role-map.yaml, apply --migrate move the old user file there, and the resolver read the user layer only from that cwd. Claude Code's plugins reference does not say it expands ~ or makes a file-type value absolute, and both scripts also take the value from --user-file. Both scripts now expand a leading ~/ against their home variable after the unsubstituted-value check. setup.sh refuses any other non-absolute value with exit 2 before computing LOCATE and the old-file comparison. The resolver skips the user-config layer with a note instead of exiting, matching how it skips a malformed layer, so one bad option does not break routing for every skill. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01RAoAtUnz4WHB5auUnwQYq7 --- ...k-resolve-issue-issue-17998-44959703861-1-e92d82f0.md | 2 +- plugins/multi-agent/scripts/resolve-roles.sh | 5 +++++ plugins/multi-agent/scripts/resolve-roles.test.sh | 9 +++++++++ plugins/multi-agent/skills/setup/scripts/setup.sh | 3 +++ plugins/multi-agent/skills/setup/scripts/setup.test.sh | 5 +++++ 5 files changed, 23 insertions(+), 1 deletion(-) diff --git a/.changes/multi-agent/work-resolve-issue-issue-17998-44959703861-1-e92d82f0.md b/.changes/multi-agent/work-resolve-issue-issue-17998-44959703861-1-e92d82f0.md index 56a3527f9ff..a770cfd896b 100644 --- a/.changes/multi-agent/work-resolve-issue-issue-17998-44959703861-1-e92d82f0.md +++ b/.changes/multi-agent/work-resolve-issue-issue-17998-44959703861-1-e92d82f0.md @@ -4,7 +4,7 @@ bump: minor ### Added -- A `role_map_file` option (type `file`) names your own role map file, the user layer of the config cascade. `/multi-agent:route` and `/multi-agent:setup` pass it to the resolver, and `/multi-agent:setup apply --layer user` writes to it ([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)). +- A `role_map_file` option (type `file`) names your own role map file, the user layer of the config cascade. `/multi-agent:route` and `/multi-agent:setup` pass it to the resolver, and `/multi-agent:setup apply --layer user` writes to it. A leading `~/` expands against your home; any other path that is not absolute is refused by `setup` and skipped with a note by the resolver ([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)). - `/multi-agent:setup apply --migrate` moves each old file into its new location after a preview and a yes: `~/.claude/multi-agent.yaml` into the `role_map_file` file, `.claude/multi-agent.local.yaml` into `/multi-agent.local.yaml`, and a retired `.claude/multi-agent.yaml` into the team YAML. A key the new file already sets keeps its value and is named. The command reads the new file back and checks the layers still resolve the same values before it deletes the old file ([#17998](https://github.com/melodic-software/claude-code-plugins/issues/17998)). ### Changed diff --git a/plugins/multi-agent/scripts/resolve-roles.sh b/plugins/multi-agent/scripts/resolve-roles.sh index a93151d568d..557a235010f 100755 --- a/plugins/multi-agent/scripts/resolve-roles.sh +++ b/plugins/multi-agent/scripts/resolve-roles.sh @@ -326,6 +326,11 @@ dual_read() { } [[ "$USER_FILE" == "\${user_config."* ]] && USER_FILE="" +[[ -n "$USER_HOME_DIR" && "$USER_FILE" == \~/* ]] && USER_FILE="$USER_HOME_DIR/${USER_FILE#\~/}" +if [[ -n "$USER_FILE" && "$USER_FILE" != /* ]]; then + NOTES+=("user-config layer skipped: the role_map_file option '${USER_FILE//[^[:print:]]/?}' is not an absolute path; set an absolute path in /config") + USER_FILE="" +fi OLD_USER="" [[ -n "$USER_HOME_DIR" ]] && OLD_USER="$USER_HOME_DIR/.claude/multi-agent.yaml" user_where="the file the role_map_file option names (set it in /config)" diff --git a/plugins/multi-agent/scripts/resolve-roles.test.sh b/plugins/multi-agent/scripts/resolve-roles.test.sh index 367165096a2..2b7db41d00a 100755 --- a/plugins/multi-agent/scripts/resolve-roles.test.sh +++ b/plugins/multi-agent/scripts/resolve-roles.test.sh @@ -183,6 +183,15 @@ assert_contains "new layers: source names user-config and personal-override" "$o assert_contains "new layers: the personal row names the home path" "$out" '"layer":"personal-override","path":"'"$T/newlayers/repo/docs/conventions/multi-agent.local.yaml"'","state":"read"' assert_lacks "new layers: no old-path warning" "$out" 'old path' +fixture tilde +printf 'schema: 1\nroles:\n worker:\n effort: high\n' >"$T/tilde/home/user.yaml" +out="$(run tilde worker --session-model opus --user-file \~/user.yaml)" +assert_contains "tilde: a leading ~/ reads the file under the home" "$out" '"layer":"user-config","path":"'"$T/tilde/home/user.yaml"'","state":"read"' +out="$(run tilde worker --session-model opus --user-file user.yaml)" +assert_eq "relative: the resolver still exits 0" 0 "$?" +assert_contains "relative: the note asks for an absolute path" "$out" "user-config layer skipped: the role_map_file option 'user.yaml' is not an absolute path; set an absolute path in /config" +assert_contains "relative: the user layer is absent" "$out" '"layer":"user-config","path":"","state":"absent"' + fixture oldonly printf 'schema: 1\nroles:\n worker:\n effort: high\n' >"$T/oldonly/home/.claude/multi-agent.yaml" printf 'schema: 1\nroles:\n worker:\n model: sonnet\n' >"$T/oldonly/repo/.claude/multi-agent.local.yaml" diff --git a/plugins/multi-agent/skills/setup/scripts/setup.sh b/plugins/multi-agent/skills/setup/scripts/setup.sh index 42643a4fde6..9b86f81f1da 100755 --- a/plugins/multi-agent/skills/setup/scripts/setup.sh +++ b/plugins/multi-agent/skills/setup/scripts/setup.sh @@ -93,6 +93,9 @@ done [[ -n "$ROOT" ]] || ROOT="$(config_root_resolve)" CLASS="$(HOME="$HOME_DIR" config_root_classify "$ROOT")" [[ "$USER_FILE" == "\${user_config."* ]] && USER_FILE="" +[[ -n "$HOME_DIR" && "$USER_FILE" == \~/* ]] && USER_FILE="$HOME_DIR/${USER_FILE#\~/}" +[[ -z "$USER_FILE" || "$USER_FILE" == /* ]] || + die "the role_map_file option '$USER_FILE' is not an absolute path; set an absolute path in /config" LOCATE=(--root "$ROOT" --home "$HOME_DIR") [[ -n "$USER_FILE" ]] && LOCATE+=(--user-file "$USER_FILE") OLD_USER="" diff --git a/plugins/multi-agent/skills/setup/scripts/setup.test.sh b/plugins/multi-agent/skills/setup/scripts/setup.test.sh index a442b76828b..aa5c88d42e4 100755 --- a/plugins/multi-agent/skills/setup/scripts/setup.test.sh +++ b/plugins/multi-agent/skills/setup/scripts/setup.test.sh @@ -199,6 +199,11 @@ assert_contains "user layer goes to the option's file" "$out" "wrote: $T/user/ro state=absent [[ -e "$T/user/home/.claude/multi-agent.yaml" ]] && state=present assert_eq "nothing is written under ~/.claude" absent "$state" +out="$(run user apply --layer user --write --user-file \~/role-map.yaml fanout.model=sonnet)" +assert_contains "a leading ~/ expands against the home" "$out" "wrote: $T/user/home/role-map.yaml (user layer)" +run user apply --layer user --write --user-file role-map.yaml fanout.model=sonnet >/dev/null +assert_eq "a relative option is refused" 2 "$?" +assert_contains "the refusal asks for an absolute path in /config" "$(cat "$T/user.err")" 'set an absolute path in /config' fixture mig mkdir -p "$T/mig/home/.claude" "$T/mig/repo/.claude"