claude-code-plugins

Purpose

Confirm where /bugs:write --file writes reports, and manage the tracked project config
/bugs:scan reads for its lanes and filing posture.

Two surfaces, two owners

Surface	Holds	Written by
output_dir. Native userConfig	one operator's personal --file destination on one machine	Claude Code's own plugin configuration prompt, never this skill
.claude/bugs.md. Tracked, cascade-layered	team policy: /bugs:scan lanes and filing posture	apply here, team layer only

This is the narrow-write setup shape: apply is bounded to the one writable artifact this plugin
owns, and the unwritable surface beside it stays check-only. output_dir is a personal value that
Claude Code prompts for when the plugin is enabled, stores in user settings, and ignores in
pluginConfigs entries under project and local settings on current releases (≥ 2.1.207), so an
apply could only write the pluginConfigs the uniform setup contract forbids, and reconfiguration
routes through the native flow instead.

Official contract: https://code.claude.com/docs/en/plugins-reference#user-configuration.

Keys, layers, merge semantics, the output_dir partition rule, and the file format live in
`${CLAUDE_PLUGIN_ROOT}/reference/config.md`, their single home. Read it
before checking or writing; never restate its keys here, and never let this skill and that reference
disagree.

Both actions are non-interactive when the invocation and the repo make the values unambiguous:
report and recommend, and ask only where a lane genuinely needs the user. No argument runs check.

check (read-only, the default)

Modify nothing. Report both surfaces, then one remediation line per gap.

A. output_dir (native userConfig)

1. Read the rendered ${user_config.output_dir} value from this skill. Do not inspect or edit
   settings.json, settings.local.json, managed settings, or pluginConfigs directly.
2. Explain the effective behavior:
   • empty or unexpanded value: --file uses
     ${CLAUDE_PLUGIN_DATA}/bug-reports/<project-slug>/;
   • configured value: --file uses that directory.
3. State the tradeoff instead of asking: machine-private (the default under
   ${CLAUDE_PLUGIN_DATA}) versus a repository path committed alongside code. For the
   repository option, inspect the consumer's CLAUDE.md, AGENTS.md, and existing report or
   artifact directories and recommend one portable location. Never recommend a machine-absolute
   team path.
4. If the recommended value differs, reconfigure through Claude Code's native flow per the marketplace's
   plugin-reconfiguration convention, which owns the verified-version record: interactive
   /plugin configure bugs@<marketplace> any time, or headless claude plugin install bugs@<marketplace> -s <scope> --config output_dir=<path> — it prints already installed and still writes the value.
   Never uninstall to reconfigure: that drops the whole stored pluginConfigs entry, resetting every
   option to its manifest default. -s defaults to user; pass the scope claude plugin list reports,
   from that project's directory for a project/local scope, 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.
   Rerun check in a fresh session (the rendered value is injected at skill load, so a
   same-session check still reports the OLD value), then report the observed destination. Convention:
   https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/plugin-reconfiguration/README.md.

B. .claude/bugs.md (tracked lane config)

Anchor at the repo root. Use ${CLAUDE_PROJECT_DIR} when set, otherwise git rev-parse --show-toplevel,
never the CWD. Then report each layer separately and the effective merged result:

1. Per-layer presence. Name every layer of the surface (the reference's layer table is
   authoritative) and say for each: absent, present-and-parsed, or malformed. A malformed layer
   degrades soft. Surface the error, name the layer, and resolve as if it were absent.
2. Effective config and provenance. Report the merged lanes and filing_posture and which
   layer supplied each value, honoring the reference's merge semantics, including an explicit
   empty-list opt-out, which is reported as an opt-out, not as a broken layer. All layers absent is
   a valid, fully working state: INFO, never FAIL. /bugs:scan falls through to its bundled
   generic default lanes.
3. Per-layer version-control verdict. A present team file must be tracked, which takes two
   probes: not-ignored and actually-tracked. Run git check-ignore -v .claude/bugs.md; a
   non-empty result is FAIL, naming the matching pattern. Teammates would never receive it. Then run
   git ls-files --error-unmatch .claude/bugs.md; a non-zero exit on a present file is also
   FAIL, "present but untracked, commit it so teammates receive it". The ignore probe alone cannot
   see this: an untracked, unignored file returns the same empty output as a healthy tracked one, so
   check would bless a config nobody else ever receives. The .local.md overlay must be
   gitignored; staged or unignored is FAIL. The user-global layer sits outside the worktree, so no git
   verdict applies to it. Say so rather than running a command whose answer is meaningless.
4. Unreachable layers. When a layer cannot be read (the user-global one often is not), WARN that
   it was not considered rather than presenting the rest as the whole effective config.
5. Unknown keys. Report them as inert, naming their layer, including output_dir, which is not
   a recognized key here per the reference's partition rule.

apply (idempotent, bounded to .claude/bugs.md)

Run check first, then converge the team file, the only artifact this action writes. Never
touch settings.json, settings.local.json, managed settings, pluginConfigs, userConfig, the
user-global layer, the .local.md overlay, or the consumer's .gitignore. An output_dir change
requested here is routed to the native flow in check step A4, never written.

1. Read the effective config first, across every layer, and present it. Where a user-global or
   overlay layer changes the team file's effect, adding lanes, replacing one by name, opting out
   with an empty list, or supplying filing_posture nearest-wins, say so explicitly: a team-scope
   edit alone will not account for it, and re-adding a lane an overlay opts out of will not restore
   it on this machine. Prompt the user to also update that layer; do not edit it for them.
2. Draft lanes from the repository. Before asking anything, infer candidates from what exists:
   entrypoint and API directories, the highest-churn source areas in git log, and any subsystem
   the repo's own docs treat as critical. Propose kebab-case lane names with globs relative to the
   repo root. Degrade to the bundled generic default lanes as the proposal when history or layout
   gives nothing to infer from.
3. Confirm, one decision at a time. Present each drafted lane with a recommendation; let the
   user accept, edit, or drop it. Then settle filing_posture, stating what each value permits per
   the reference, and that neither value ever lets a bare invocation file.
4. Write conservatively. Scaffold the file in the reference's documented format when absent; for
   an existing file, make a targeted update. Fill absent keys at their documented defaults,
   preserve prose and keys you do not recognize, and report rather than silently rewrite anything
   you cannot reconcile. Never overwrite blind, and never rewrite a file you did not first read.
5. Verify after writing. Re-run the check B probes against the file on disk: it parses, every
   lane declares name and globs, the globs match real paths (a lane matching nothing is reported
   as skipped), and git check-ignore -v .claude/bugs.md confirms it is not ignored. A file
   just scaffolded here is legitimately untracked until it is staged, so
   git ls-files --error-unmatch will not match yet. That is not a FAIL at this point; state the
   commit obligation instead (step 7). Report the values you observed, never an unobserved change.
6. Recommend the overlay line, do not write it. Personal deviations belong in
   .claude/bugs.local.md; recommend the consumer add the recursive .gitignore line the
   reference names if it is not already covered. Their ignore file is their artifact.
7. Remind them to stage it. The team file only reaches teammates once committed.

Re-running apply when everything already matches changes nothing and reports "already configured".

Output

Report, for each surface: the effective state and the layer that supplied it, the recommended state,
and what changed, the tracked file's path and the keys written, plus whether the user must still
change the Claude-owned output_dir through Claude Code's own flow. Do not claim a configuration
change until it is observed: for the tracked file, by re-reading it; for output_dir, by a rerun in
a fresh session.

Boundaries

• Do not produce or file a bug report; invoke /bugs:write via the Skill tool.
• Do not run a hunt; that is /bugs:scan. This skill only verifies and writes its config.
• Do not write the plugin cache, Claude Code user settings, or pluginConfigs, per the uniform
  setup contract (docs/plugin-philosophy.md "Setup is explicit and repeatable" in the
  marketplace repository).
• Do not delete the tracked config: apply converges to the configured state and never removes.
• Do not invent an organization, repository, marketplace, or environment-variable prefix.