Setup

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

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 write lands at a scope that does not load. 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.