Skip to content

multi-agent: read config from the config-cascade layers, not ~/.claude #17998

Open

Description

@kyle-sexton

Summary

multi-agent still reads its user-global and personal config layers from ~/.claude and .claude/. Move both to the config-cascade layers.

Current behavior

plugins/multi-agent/scripts/resolve-roles.sh reads two old paths as layers:

  • :288 USER_LAYER="$USER_HOME_DIR/.claude/multi-agent.yaml" (user-global file)
  • :302 PERSONAL_OVERRIDE="$ROOT/.claude/multi-agent.local.yaml" (personal override)

plugins/multi-agent/skills/setup/scripts/setup.sh checks and writes the same paths (header comment :16 user <home>/.claude/multi-agent.yaml, :23 local <root>/.claude/multi-agent.local.yaml, :77 gitignore probe for .claude/multi-agent.local.yaml) and reads a legacy team file at :87 and :172 (yaml="$ROOT/.claude/multi-agent.yaml").

The team layer already reads <home>/multi-agent.yaml (resolve-roles.sh:301).

Desired behavior

Per the config-cascade layers:

Old path Layer
~/.claude/multi-agent.yaml userConfig (no user-global file layer)
<root>/.claude/multi-agent.yaml team: <home>/multi-agent.yaml
<root>/.claude/multi-agent.local.yaml personal: <home>/multi-agent.local.yaml

The resolver and setup read and write the contract layers; a file at an old path keeps being read during a dual-read window (see the acceptance criteria) and is reported with a warning. The canonical location list (docs/contracts/config-cascade/locations.md) lands in the docs/config-locations pull request.

Key interfaces

  • resolve-roles.sh layer list and the provenance it prints per value
  • setup.sh check and apply paths

Acceptance criteria

  • The resolver reads the config-cascade layers (the layers).
  • Dual-read window: while an old-path file exists, it is still read and its values still apply where no new-layer file supplies that layer; each run prints one warning naming the old file and the new location to move it to. No setting in an old file is silently dropped.
  • setup.sh (check and apply) names each old file it finds and after a preview and a yes, moves its settings to the new location, checks the new location resolves the same values, then deletes the old file, so migration ends in one home, never two (owner 2026-11-21: "we don't have dual approaches, and that stuff gets cleaned up"); the dual-read warning names that setup command, so normal skill use leads to the migration.
  • Removing the old-path read is a separate later change, made only once no old file is reported.
  • The plugin's tests cover: new layer only; old file only (values apply, warning printed); both present (new wins, warning names both).

Placement rule (owner decisions 2026-11-21, #18000 Q1 and #18009 Q2)

For each key in the old user-global file, choose the new home by what the key is:

  • a per-repo convention (what a repository's commits, PRs or files must look like): the team file <home>/<concern>.yaml, with the personal override for one person in one repo; no new userConfig option;
  • a per-user value userConfig can hold (string, number, boolean, directory, file, list of strings): a userConfig option;
  • a per-user structure userConfig cannot hold (a list of objects, a nested map): one file-typed userConfig option naming the user's file, which keeps the structure as it is.

If a key fits none of these, stop as design-change and name the key.

Out of scope

Other plugins' resolvers (one issue each), and userConfig option names beyond what this plugin needs.

Activity

  1. added
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Nov 21, 2026
  2. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Nov 21, 2026
  3. github-actions commented on Nov 21, 2026

    @github-actions
    Contributor

    Size: Medium
    Complexity: Medium
    Uncertainty: Known
    Flags: none
    Blocked by: none
    Blast radius: multi-agent's resolve-roles.sh, setup.sh and their tests; anyone running the multi-agent resolver or setup skill, plus users with old-path config files.
    Reversible: yes; revert the change, though a file migrated by setup is moved and the old file deleted, so the user would move it back.
    Open questions: none
    I read this as moving the multi-agent resolver and setup from the old ~/.claude and .claude/ config paths to the config-cascade layers. Old files stay readable with a warning during a dual-read window, and setup migrates them. The issue gives the layer mapping, a placement rule and exact acceptance criteria, so I see no open design question. I found no open duplicate and no merged pull request that already does this. The sibling per-plugin issues (e.g. #17999, #18000) cover other plugins' resolvers.

    Automated triage. A maintainer reviews it.

  4. removed
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Nov 21, 2026
  5. melodic-automation-lanes commented on Nov 21, 2026

    @melodic-automation-lanes
    Contributor

    {"v":1,"actor_id":337595936,"title_sha256":"9386da9ce2068014ecfae6ef17c3f1d88fc0ba1ea37b62ced70c663d2547803a","body_sha256":"789384d62757432be77ee90d23aabc3bab9ea1e0217d75c1c3a1098dfde2b14e"}

  6. melodic-automation-lanes commented on Nov 21, 2026

    @melodic-automation-lanes
    Contributor

    This records a re-fire of an earlier stop, not a new one. The start gate stopped run 44949339952, the work-resolve-issue run that agent-ready started, before any model turn, because the GITHUB_TOKEN budget was under its start-gate share, or the window was projected to have under its start-project share of the header's limit left by the run's expected end (github-token start-gate, start-project and start-run-minutes in rate-limits.json; the run's start-gate notice names which); that run ended at 2026-11-21T21:19:19Z. work-unblock has now removed and added agent-ready back to start a fresh run. A budget stop is the lanes' load, not a fault in this issue: it never counts toward limits.limit-stops-per-issue or the kill-switch wait.

  7. github-actions commented on Nov 21, 2026

    @github-actions
    Contributor
    No description provided.
  8. melodic-automation-lanes commented on Nov 21, 2026

    @melodic-automation-lanes
    Contributor

    The work-resolve-issue lane stopped on this issue (issue-edited-trusted): the issue's title or body changed after agent-ready was added, and every change came from a listed human or one of our listed Apps, so intake triage refines and admits the edited text again.
    It set Work status to needs-triage, so the hourly triage sweep sends it back through intake triage, and it waits on no decision from a person.

    In the run's words:

    The run did not start: the issue's title or body changed after agent-ready was added, each change by a listed account, so the runner wrote no issue file for the skill and no model ran.

    Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/44954432186

  9. github-actions commented on Nov 21, 2026

    @github-actions
    Contributor

    The triage sweep dispatched intake triage for this issue (dispatch 1; 2 runs that reach intake, or 6 dispatches, hand it to a maintainer).

  10. melodic-automation-lanes commented on Nov 21, 2026

    @melodic-automation-lanes
    Contributor

    {"v":1,"actor_id":337595936,"title_sha256":"9386da9ce2068014ecfae6ef17c3f1d88fc0ba1ea37b62ced70c663d2547803a","body_sha256":"623ee2e5a932e51fec0a2179eeab04eb85d557dff0572e1da25cf8434590471f"}

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.

    Type

    Fields

    Work status

    agent-ready

    Priority

    medium

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions