Skip to content

fix(planning,guardrails,claude-ops): correct the --config scope reason in setup skills #4651

Description

@kyle-sexton

Problem

plugins/planning/skills/setup/SKILL.md gives a wrong reason for passing the scope
claude plugin list reports when reconfiguring with claude plugin install ... --config. On main
at 946caf1, lines 154-156 read:

-s defaults to user; pass the scope claude plugin list reports, and run from that
project's directory for a project/local scope, or the write lands at a scope that does not load.

The value never lands at another scope: --config always writes pluginConfigs to user settings,
whatever -s says. The real risk is that a rerun at another scope adds a second install record
there and enables the plugin at that scope. The paragraph also omits that a rejected --config
value prints a warning and still exits 0.

(The item cited line 141; #4566 added load-time probes to this file, so the paragraph now sits at
lines 146-160.)

Evidence

Verified this pass:

  • git show origin/main:plugins/planning/skills/setup/SKILL.md, lines 146-160.
  • feat(source-control): pin plugin install --config behaviours and move branch_issue_pattern to the cascade #4581 (merged 2026-09-27) measured the behavior in a sandbox on Claude Code 2.1.283 and recorded
    it as facts 9-12 in docs/conventions/hook-config-delivery/README.md ("Verified upstream
    behavior", per-row Verified column): D1, --config writes pluginConfigs to user settings
    whatever -s says, and -s governs only the install record and enabledPlugins; D2, a
    wrong-type boolean, an undeclared key and an empty value are rejected with a warning and exit 0.
    docs/conventions/plugin-reconfiguration/README.md carries the corrected caveat.
  • feat(source-control): pin plugin install --config behaviours and move branch_issue_pattern to the cascade #4581 fixed the same sentence in the other setup skills (for example
    plugins/actionlint/skills/setup/SKILL.md:86-90, CHANGELOG 0.8.58) and its PR body says: "the
    wrong caveat-2 rationale remains in the setup skills of planning, guardrails, and claude-ops,
    which belong to a different session."
  • git grep "does not load" origin/main -- 'plugins/*/skills/setup/SKILL.md' finds exactly three:
    planning (line 156), guardrails (plugins/guardrails/skills/setup/SKILL.md:79-81) and claude-ops
    (plugins/claude-ops/skills/setup/SKILL.md:158-160).

Proposed approach

In each of plugins/planning/skills/setup/SKILL.md, plugins/guardrails/skills/setup/SKILL.md
and plugins/claude-ops/skills/setup/SKILL.md, replace "or the write lands at a scope that does not
load." with the wording #4581 used elsewhere:

or the rerun adds a second install record at the scope passed and enables the plugin there; the
value itself always lands in user settings. A rejected value prints a warning yet exits 0, so
read the output.

Bump each plugin's patch version and add a ### Fixed CHANGELOG entry matching actionlint
0.8.58's wording.

The claude-ops fix is already written, unreviewed, as commit 697eda5 on the pushed branch
audit-instructions-catalog-surface-gaps (see the claude-config audit-instructions issue that
branch belongs to). Either land it with that branch or cherry-pick it here; do not write it twice.

Acceptance criteria

  • git grep "does not load" -- 'plugins/*/skills/setup/SKILL.md' finds nothing.
  • The paragraph states the second-install-record risk, that the value lands in user settings,
    and that a rejected value warns and exits 0.
  • Each touched plugin's version bumped with a matching CHANGELOG entry; check-changelog-parity.sh --check-bump passes.
  • check-changed-skills.sh passes.

Constraints and gotchas

Context

Requested by the parent session while retiring the local handoff inbox. Related: #4581 (the
measurement and the fleet fix), #4566 (moved the line), #3111 and #3127 (earlier --config claim
fixes).

Activity

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.priority: lowNice-to-have, cosmetic, or speculative; opportunistic.work-class: mechanicalDeterministic, trivially reversible maintenance: dependency bumps, lint/format, sync.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions