Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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)).
Original file line number Diff line number Diff line change
@@ -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. 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 `<home>/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 `<home>/multi-agent.local.yaml`, and `setup check` recommends the `<home>/**/*.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)).
4 changes: 2 additions & 2 deletions docs/contracts/config-cascade/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -719,7 +719,7 @@ its conformance cell.
| `authoring-formats` | no-floor | convention doc at the consumer's convention home, `<home>/authoring-formats/README.md` (the pointer line binds `<home>`) | 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 `<home>` 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: `<home>/multi-agent.yaml`, `<home>` 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: `<home>/multi-agent.yaml`, `<home>` being the bound convention home, else `docs/conventions`; `userConfig`: the file the `role_map_file` option names; personal override `<home>/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: `<home>/multi-agent.yaml`, the role map's team file (`<home>` 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.<skill>` beats `verification`. `lib/read-verification.sh` (the plugin's copy) reads the file at `origin/<default>` 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` |
Expand Down Expand Up @@ -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` |
Expand Down
6 changes: 1 addition & 5 deletions plugins/discovery/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<!-- BEGIN GENERATED: plugin options. Edit plugin.json, then run scripts/sync-plugin-options-docs.py -->

### Options reference
Expand Down
7 changes: 7 additions & 0 deletions plugins/multi-agent/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -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."
}
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved
}
}
Loading
Loading