diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 8175039f93..9e0abc9da7 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -128,8 +128,8 @@ "tags": ["guard", "security", "secrets", "hardcoded-paths", "git", "cli-flags", "hook"] }, { - "name": "bug-report", - "source": "./plugins/bug-report", + "name": "bugs", + "source": "./plugins/bugs", "category": "maintenance", "tags": ["bug", "bug-report", "defect", "triage", "issue", "skill"] }, diff --git a/.claude/settings.json b/.claude/settings.json index 9ce917fa43..c85b5c3507 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -29,7 +29,7 @@ "autonomy@melodic-software": true, "bash-format@melodic-software": true, "biome-format@melodic-software": true, - "bug-report@melodic-software": true, + "bugs@melodic-software": true, "claude-config@melodic-software": true, "claude-memory@melodic-software": true, "claude-ops@melodic-software": true, diff --git a/docs/CATALOG.md b/docs/CATALOG.md index 34c0067cf1..e648019b01 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -65,7 +65,7 @@ plugin manifests and kept in sync by CI — never hand-edit it; the category voc ## Maintenance -- [`bug-report`](../plugins/bug-report) — Produces a structured five-field bug report — title, steps to reproduce, expected vs actual, severity with justification, and suggested fix location — from an informal defect description. Read-only by default: it emits the report and never edits code, opens a PR, or files an issue on its own. +- [`bugs`](../plugins/bugs) — Produces a structured five-field bug report — title, steps to reproduce, expected vs actual, severity with justification, and suggested fix location — from an informal defect description. Read-only by default: it emits the report and never edits code, opens a PR, or files an issue on its own. - [`debugging`](../plugins/debugging) — Debug observed failures via a disciplined six-phase loop: build a fast deterministic reproduction signal, reproduce, rank falsifiable hypotheses, instrument, fix with a regression test, then clean up and post-mortem. - [`docs-hygiene`](../plugins/docs-hygiene) — Documentation-hygiene toolkit: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), audit-derivability (classify whether a whole document earns its existence — could a fresh agent re-derive it from the code?), audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects), write-for-agents (authoring-time doctrine that fires while agent-consumed markdown is being written), and write-for-humans (the same moment for the other reader — end-user READMEs, RFCs, release notes and guides — resolving the consuming project's own style guide first). - [`code-tidying`](../plugins/code-tidying) — Code tidying and comment hygiene: /code-tidying:tidy proactively hunts a rotated, glob-scoped lane for Beck-style tidyings under a research-backed scope budget and ships one tight PR; /code-tidying:batch-simplify sweeps a time window, a branch, or an entire repository through grouped, dependency-ordered simplification waves with a never-drop deferred-items contract; /code-tidying:dissolve-comments enforces self-describing expressive code over a diff or target, widening to the branch diff and then the whole repository when the tree is clean — deletes zero-information comments, dissolves code-expressible ones into names and structure behind a tests gate (safe mode restricts applied edits to removals), and keeps only terse load-bearing comments code cannot express; /code-tidying:audit-comment-residue is a read-only classifier that flags history, plan, conversational, and ticket/PR residue in code comments for author-applied deletion. Project-specific tidy lanes are scaffolded into a tracked .claude/tidy-lanes/ config folder by a re-runnable setup skill. diff --git a/docs/SKILL-CHEAT-SHEET.md b/docs/SKILL-CHEAT-SHEET.md index 7711bfcd6e..28f5f7d13e 100644 --- a/docs/SKILL-CHEAT-SHEET.md +++ b/docs/SKILL-CHEAT-SHEET.md @@ -28,7 +28,7 @@ owned by [docs/CATALOG-TAXONOMY.md](CATALOG-TAXONOMY.md). | Skill | Plugin | What it does | | --- | --- | --- | -| [`/bug-report:write`](../plugins/bug-report/skills/write/SKILL.md) | `bug-report` | Turn an informal bug description into a structured 5-field report, read-only | +| [`/bugs:write`](../plugins/bugs/skills/write/SKILL.md) | `bugs` | Turn an informal bug description into a structured 5-field report, read-only | | [`/planning:audit-answers`](../plugins/planning/skills/audit-answers/SKILL.md) | `planning` | Adversarially validate interview answers with fresh-context agents | | [`/planning:brainstorm`](../plugins/planning/skills/brainstorm/SKILL.md) | `planning` | Diverge into codebase-grounded candidate approaches before scoping | | [`/planning:interview`](../plugins/planning/skills/interview/SKILL.md) | `planning` | Interview in frontier rounds until the task contract is locked | @@ -228,7 +228,7 @@ owned by [docs/CATALOG-TAXONOMY.md](CATALOG-TAXONOMY.md). | Skill | Plugin | Cadence | What it does | | --- | --- | --- | --- | -| [`/bug-report:scan`](../plugins/bug-report/skills/scan/SKILL.md) | `bug-report` | daily | Proactively hunt resting code for unobserved bugs, verify adversarially, report read-only | +| [`/bugs:scan`](../plugins/bugs/skills/scan/SKILL.md) | `bugs` | daily | Proactively hunt resting code for unobserved bugs, verify adversarially, report read-only | | [`/claude-ops:audit-install-state`](../plugins/claude-ops/skills/audit-install-state/SKILL.md) | `claude-ops` | weekly | Audit a Claude Code install directory — what is there, what the product manages, what is stale | | [`/claude-ops:audit-native-overlap`](../plugins/claude-ops/skills/audit-native-overlap/SKILL.md) | `claude-ops` | weekly | Map native Claude Code surfaces against this repo's components and record human-gated verdicts | | [`/claude-ops:audit-performance`](../plugins/claude-ops/skills/audit-performance/SKILL.md) | `claude-ops` | continuous | Capture slowness evidence while slow — version, sweep health, tree walk, sessions, fleet | diff --git a/docs/conventions/config-cascade/README.md b/docs/conventions/config-cascade/README.md index 544b33fd93..00f15b2a92 100644 --- a/docs/conventions/config-cascade/README.md +++ b/docs/conventions/config-cascade/README.md @@ -207,7 +207,7 @@ open. | `source-control` | `.claude/source-control.md` | all three | conforms (per-key override, #660); enforcement reads team-tracked only per [`commit-convention`](../commit-convention/README.md); loop-lane keys (`babysit_loop_*`, read by the source-control babysit lane; the work-items lanes tie in via the loop-lane convention only) ride the same surface, with the merge-rung key in the policy-floor class — standing raises bind from the team-tracked layer only, and the one named single-invocation exception is an explicitly typed argument rather than a config value in any layer, per [`loop-lane`](../loop-lane/README.md) | | `toolchain` / `ecosystem-commands` | `.claude/ecosystems/.yaml` | all three | conforms | | `codebase-health` | `.claude/codebase-health.md` | all three | conforms (concatenating, with a declared empty-list opt-out) | -| `bug-report` | `.claude/bug-report.md` | all three | conforms; `lanes` concatenate and deduplicate by lane `name`, with a declared empty-list opt-out that also drops the bundled defaults, and `filing_posture` is a nearest-wins scalar. Keys owned by the plugin's `reference/config.md`, which also partitions them from the plugin's `output_dir` `userConfig` option — that option is never a key in this surface, and a layer declaring it is reported as an inert unknown key. Written (team layer only) by `/bug-report:setup apply`, read by `/bug-report:scan` | +| `bugs` | `.claude/bugs.md` | all three | conforms; `lanes` concatenate and deduplicate by lane `name`, with a declared empty-list opt-out that also drops the bundled defaults, and `filing_posture` is a nearest-wins scalar. Keys owned by the plugin's `reference/config.md`, which also partitions them from the plugin's `output_dir` `userConfig` option — that option is never a key in this surface, and a layer declaring it is reported as an inert unknown key. Written (team layer only) by `/bugs:setup apply`, read by `/bugs:scan` | | `github` | `.claude/github/` (`routing.yaml` per-key override, `conventions.md` concatenating) | all three | conforms; policy-floor inversion on write-posture routing keys, declared in the plugin's `change-routing.md` | | `autonomy` | `.claude/autonomy/binding.json` | all three, plus an org rung | declared deviation | | `standards` (`planning`, `review`) | `/`, rooted by `.claude/standards.yaml` | all three | precedence inversion ratified via policy-floor class (#649); layer location outside `.claude/` still observed, not ratified | diff --git a/docs/conventions/plugin-data-report-keying/README.md b/docs/conventions/plugin-data-report-keying/README.md index ffe5c0f703..b7b85b16ea 100644 --- a/docs/conventions/plugin-data-report-keying/README.md +++ b/docs/conventions/plugin-data-report-keying/README.md @@ -95,7 +95,7 @@ skill's namespace during review. ### 1c — the "looks scoped but isn't" case, named so it is not repeated -`plugins/bug-report/skills/write/SKILL.md:97` keys on the **kebab-cased basename of the project +`plugins/bugs/skills/write/SKILL.md:97` keys on the **kebab-cased basename of the project root**: > `${CLAUDE_PLUGIN_DATA}/bug-reports//` … The plugin data directory is per-plugin, not @@ -108,7 +108,7 @@ duplicate scan cross-matches between them. It escapes *overwrite* only because i timestamped. `plugins/claude-config/skills/unhobble/SKILL.md:53-62` names the same insufficiency in prose: "`${CLAUDE_PLUGIN_DATA}` is machine-global, so two checkouts sharing a basename…". -**This is recorded here as the worked example, not filed as a `bug-report` defect.** A basename is +**This is recorded here as the worked example, not filed as a `bugs` defect.** A basename is not project identity. Nothing here obliges an immediate migration of an existing keyed-by-basename writer; it obliges the next one not to repeat it. @@ -165,8 +165,8 @@ holds every project's artifact under the same deletable root. | `claude-config:audit-prompting-postures` | Keyed (#2250) | | `claude-config:audit-instructions` | Keyed, plus rule 3 on the delta computation | | `claude-memory:audit` | Keyed on write **and** on both read paths (`report`, `fix`), plus rule 3 | -| `bug-report:write` / `bug-report:setup` | Keyed by project-root **basename** — rule 1c's worked example; not migrated | -| `bug-report:scan` | Same key, same tree, one timestamped file per run — it reuses `write`'s Step 4 path precedence rather than resolving its own, so it inherits rule 1c's basename collision unmigrated instead of introducing a second scheme (and, like `write`, lands outside this tree entirely when the operator configures `output_dir`). Its reports carry a cursor metadata block the next bare run reads back to pick a lane: a read-back artifact under rule 2, and a rule 3 surface, since the newest report at the derived key is the cursor's only authority and a colliding key would rotate lanes off another checkout's history. Absent at the key is the documented zero state — rotation falls through to the date-derived lane floor, never to an unkeyed path | +| `bugs:write` / `bugs:setup` | Keyed by project-root **basename** — rule 1c's worked example; not migrated | +| `bugs:scan` | Same key, same tree, one timestamped file per run — it reuses `write`'s Step 4 path precedence rather than resolving its own, so it inherits rule 1c's basename collision unmigrated instead of introducing a second scheme (and, like `write`, lands outside this tree entirely when the operator configures `output_dir`). Its reports carry a cursor metadata block the next bare run reads back to pick a lane: a read-back artifact under rule 2, and a rule 3 surface, since the newest report at the derived key is the cursor's only authority and a colliding key would rotate lanes off another checkout's history. Absent at the key is the documented zero state — rotation falls through to the date-derived lane floor, never to an unkeyed path | | `claude-config:unhobble` | Different solution, same problem: keys by `` whose basename is *a label*, and records the canonical checkout identity (absolute worktree path, and the origin URL when one exists) **in the manifest**, verifying it before every later phase. Verification instead of a keyed path; acceptable because the artifact is never *served* — a mismatch aborts and names the conflicting path | | `docs/conventions/topic-docs/` non-repo fallback | Keyed by **topic slug**, not project (`${CLAUDE_PLUGIN_DATA}/topic-docs//`, the non-interactive branch when no project root resolves) — an instance of the gap, recorded here rather than silently declared conformant | | `machine-health:audit` | Not keyed — roots are passed in by the caller, deliberately, per that skill's own inherited-variable hazard. Cited above for retention shape only | diff --git a/plugins/bug-report/.claude-plugin/plugin.json b/plugins/bugs/.claude-plugin/plugin.json similarity index 93% rename from plugins/bug-report/.claude-plugin/plugin.json rename to plugins/bugs/.claude-plugin/plugin.json index ddae42763d..2a31350750 100644 --- a/plugins/bug-report/.claude-plugin/plugin.json +++ b/plugins/bugs/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", - "name": "bug-report", - "version": "0.8.0", + "name": "bugs", + "version": "0.9.0", "description": "Produces a structured five-field bug report — title, steps to reproduce, expected vs actual, severity with justification, and suggested fix location — from an informal defect description. Read-only by default: it emits the report and never edits code, opens a PR, or files an issue on its own.", "author": { "name": "Melodic Software", @@ -10,7 +10,7 @@ "license": "MIT", "keywords": [ "bug", - "bug-report", + "bugs", "defect", "scan", "bug-hunting", diff --git a/plugins/bug-report/CHANGELOG.md b/plugins/bugs/CHANGELOG.md similarity index 86% rename from plugins/bug-report/CHANGELOG.md rename to plugins/bugs/CHANGELOG.md index c57defb666..f47836dc1a 100644 --- a/plugins/bug-report/CHANGELOG.md +++ b/plugins/bugs/CHANGELOG.md @@ -1,8 +1,27 @@ # Changelog -All notable changes to the `bug-report` plugin are documented here. Format follows +All notable changes to the `bugs` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.9.0] + +### Changed + +- **BREAKING: the plugin is renamed `bug-report` → `bugs`.** With `scan` beside `write`, the plugin's + identity is the full front half of the bug lifecycle — find them, report them — and the old name + described only the second half. Skills are now `/bugs:scan`, `/bugs:write`, `/bugs:setup`; the + tracked team config surface renames with it (`.claude/bug-report.md` → `.claude/bugs.md`, same keys, + same cascade, per `reference/config.md`); the plugin-data root moves with the plugin name, so + previously persisted reports and cursor metadata are not read by the renamed plugin (re-created on + the next run). No aliasing or migration shim is shipped. Migration: the two names are distinct + plugin installations, so install `bugs@` (declare + enable + install), then disable + and uninstall `bug-report@`; and rename every configured cascade layer, not just the + team file — `~/.claude/bug-report.md` → `~/.claude/bugs.md`, `.claude/bug-report.md` → + `.claude/bugs.md`, and `.claude/bug-report.local.md` → `.claude/bugs.local.md`, keeping the + overlay gitignored. Historical entries below retain the old name. + The persisted report frontmatter keeps `type: bug-report` unchanged — storage-format identifiers + stay stable across renames (ADR 0013). + ## [0.8.0] ### Added diff --git a/plugins/bug-report/README.md b/plugins/bugs/README.md similarity index 88% rename from plugins/bug-report/README.md rename to plugins/bugs/README.md index ef2639af43..dd40bf892c 100644 --- a/plugins/bug-report/README.md +++ b/plugins/bugs/README.md @@ -1,4 +1,4 @@ -# bug-report +# bugs A Claude Code plugin for the front of the bug lifecycle — **read-only by default**. It finds defects and captures them in a structured, five-field report; it does not @@ -6,11 +6,11 @@ fix them, open a PR, or file an issue on its own. | Skill | What it does | |---|---| -| `/bug-report:write` | Turns an informal defect description — one you already observed — into the five-field report. | -| `/bug-report:scan` | Hunts for defects **nobody has observed yet** in resting code, verifies each candidate adversarially, and reports what survives. | -| `/bug-report:setup` | `check` inspects both configuration surfaces read-only; `apply` writes the tracked lane config `scan` reads. | +| `/bugs:write` | Turns an informal defect description — one you already observed — into the five-field report. | +| `/bugs:scan` | Hunts for defects **nobody has observed yet** in resting code, verifies each candidate adversarially, and reports what survives. | +| `/bugs:setup` | `check` inspects both configuration surfaces read-only; `apply` writes the tracked lane config `scan` reads. | -Invoke `/bug-report:write ` (or let Claude reach for it +Invoke `/bugs:write ` (or let Claude reach for it when you describe a defect). The five fields are: 1. **Title** — present tense, one line @@ -31,10 +31,10 @@ when you describe a defect). The five fields are: - **Routes non-defects away.** Feature requests, investigations, and generic chores are recognized and pointed elsewhere rather than forced into the bug shape. -## Usage — `/bug-report:write` +## Usage — `/bugs:write` ```text -/bug-report:write [--file] [--quick|--full] [--no-survey] +/bugs:write [--file] [--quick|--full] [--no-survey] ``` | Flag | Effect | @@ -47,12 +47,12 @@ when you describe a defect). The five fields are: ## Hunting bugs nobody has reported yet -`/bug-report:write` needs a defect you already noticed. `/bug-report:scan` needs nothing — +`/bugs:write` needs a defect you already noticed. `/bugs:scan` needs nothing — no diff, no failing test, no stack trace, no comment marker. It reads resting code and looks for what is wrong in it. ```text -/bug-report:scan [] [--lane ] [--track] [--dry-run] +/bugs:scan [] [--lane ] [--track] [--dry-run] ``` | Flag | Effect | @@ -90,14 +90,14 @@ Two surfaces with two different owners. Claude Code owns this value: current releases ignore plugin `userConfig` values placed in project or local settings, and changes route through Claude Code's own configuration prompt. -**Team — the tracked `.claude/bug-report.md`**, which `/bug-report:scan` reads for its lanes +**Team — the tracked `.claude/bugs.md`**, which `/bugs:scan` reads for its lanes (`lanes`) and its filing policy (`filing_posture`). It is layered per the marketplace's config-cascade convention — a user-global file, this tracked team file, and a gitignored local overlay. All layers are optional: with no config at all, `scan` rotates over bundled generic default lanes. Keys, defaults, layer order, and per-key merge semantics live in [`reference/config.md`](reference/config.md), their single home. -Run `/bug-report:setup` to work on either surface. `check` (the default) reports both read-only: +Run `/bugs:setup` to work on either surface. `check` (the default) reports both read-only: the rendered `output_dir` and which layer supplied each lane config value. `apply` writes the tracked file and nothing else — it drafts lane candidates from your repository, confirms them one at a time, and never touches settings, `pluginConfigs`, the local overlay, or your `.gitignore`. @@ -128,7 +128,7 @@ Otherwise the emitted report is the deliverable — copy it into your tracker. ```shell /plugin marketplace add melodic-software/claude-code-plugins -/plugin install bug-report@ +/plugin install bugs@ ``` @@ -148,12 +148,12 @@ reads it from. Three supported routes, in the order most people want them: 1. **Interactively** — Claude Code prompts for declared options when you enable the - plugin. To change them later: `/plugin configure bug-report@`. + plugin. To change them later: `/plugin configure bugs@`. 2. **Headless** — repeat `--config` for each option. Replace `` with the marketplace you installed this plugin from: ```shell - claude plugin install bug-report@ -s --config output_dir= + claude plugin install bugs@ -s --config output_dir= ``` The same command reconfigures a plugin that is **already installed**: it prints @@ -177,7 +177,7 @@ Three supported routes, in the order most people want them: ```json { "pluginConfigs": { - "bug-report@": { + "bugs@": { "options": { "output_dir": } diff --git a/plugins/bug-report/reference/config.md b/plugins/bugs/reference/config.md similarity index 79% rename from plugins/bug-report/reference/config.md rename to plugins/bugs/reference/config.md index e6ceff57cd..c8db3710df 100644 --- a/plugins/bug-report/reference/config.md +++ b/plugins/bugs/reference/config.md @@ -1,9 +1,9 @@ -# bug-report — consumer configuration +# bugs — consumer configuration -The single home for the `bug-report` plugin's config-key contract. The surface is -`.claude/bug-report.md`, layered per the marketplace's config-cascade convention. It is read by -`/bug-report:scan` — lane selection and rotation, plus filing posture — and verified/written by -`/bug-report:setup`. All layers are optional: **zero config is a fully working state**, because +The single home for the `bugs` plugin's config-key contract. The surface is +`.claude/bugs.md`, layered per the marketplace's config-cascade convention. It is read by +`/bugs:scan` — lane selection and rotation, plus filing posture — and verified/written by +`/bugs:setup`. All layers are optional: **zero config is a fully working state**, because rotation falls through to the bundled generic default lanes. ## Layers and resolution order @@ -12,9 +12,9 @@ Three layers, resolved in this order — a later layer refines an earlier one: | Order | Layer | Path | Version control | |---|---|---|---| -| 1 | user-global | `~/.claude/bug-report.md` | outside the worktree — no git verdict applies | -| 2 | team (tracked) | `${CLAUDE_PROJECT_DIR}/.claude/bug-report.md` | must be tracked — it is the only layer teammates receive | -| 3 | local overlay | `${CLAUDE_PROJECT_DIR}/.claude/bug-report.local.md` | must be gitignored, never staged | +| 1 | user-global | `~/.claude/bugs.md` | outside the worktree — no git verdict applies | +| 2 | team (tracked) | `${CLAUDE_PROJECT_DIR}/.claude/bugs.md` | must be tracked — it is the only layer teammates receive | +| 3 | local overlay | `${CLAUDE_PROJECT_DIR}/.claude/bugs.local.md` | must be gitignored, never staged | Resolution anchors at the repo root — `${CLAUDE_PROJECT_DIR}` when set, otherwise `git rev-parse --show-toplevel` — never at the CWD. Every layer that exists is read and merged; @@ -52,7 +52,7 @@ Markdown with a fenced YAML block (human-readable, shell-greppable). Prose outsi consumer's own commentary and is not parsed. ````markdown -# bug-report config +# bugs config ```yaml lanes: @@ -71,7 +71,7 @@ filing_posture: manual-only | Key | Type | Default | Meaning | |---|---|---|---| -| `lanes` | list of lane entries (sub-keys below) | bundled generic default lanes | The rotation set `/bug-report:scan` walks on a bare invocation, in declaration order. Concatenating merge with an empty-list opt-out (above). | +| `lanes` | list of lane entries (sub-keys below) | bundled generic default lanes | The rotation set `/bugs:scan` walks on a bare invocation, in declaration order. Concatenating merge with an empty-list opt-out (above). | | `filing_posture` | `manual-only` \| `allowed` | `manual-only` | Team policy for the explicit filing argument. `manual-only` means `--track` files nothing and prints why — a standing autonomous lane must not file into this tracker. `allowed` permits `--track` to file. Neither value ever makes a bare invocation file: filing always needs the explicit argument as well. Nearest-wins scalar merge. | ### `lanes[]` sub-keys @@ -92,4 +92,4 @@ One recursive line covers the overlay here and every other cascade surface: .claude/**/*.local.* ``` -`/bug-report:setup` recommends this line; no plugin writes the consumer's `.gitignore`. +`/bugs:setup` recommends this line; no plugin writes the consumer's `.gitignore`. diff --git a/plugins/bug-report/skills/scan/SKILL.md b/plugins/bugs/skills/scan/SKILL.md similarity index 93% rename from plugins/bug-report/skills/scan/SKILL.md rename to plugins/bugs/skills/scan/SKILL.md index 48480d6287..dae36a8dc6 100644 --- a/plugins/bug-report/skills/scan/SKILL.md +++ b/plugins/bugs/skills/scan/SKILL.md @@ -1,5 +1,5 @@ --- -description: "Proactively hunt unobserved bugs in resting code: a read-only two-stage scan — recall-biased per-lens hunter subagents, then a separate fresh-context default-refute gate — over a target path/feature/diff or a rotated lane, emitting only verified 5-field findings. Use when: 'find a bug', 'bug hunt', 'scan for bugs', 'hunt for bugs in '. Skip when: reviewing a diff (`review:code-review`); security auditing (`review:security-review`); root-causing an observed failure (`debugging:debug`); doc/config/code/arch claim drift, all dimensions (`codebase-health:audit`); structural tidying (`code-tidying:tidy`); comment markers (`work-items:scan-todos`); coverage gaps (`testing:audit`, `mutation-testing:audit`). Disambiguation: 'scan repo for issues' is the upstream known-issue registry (`claude-ops:known-issues`); 'file a bug' you already observed is `bug-report:write`. Bare invocation neither edits nor files; `--track` files verified findings as raw intake (subject to the team's `filing_posture`)." +description: "Proactively hunt unobserved bugs in resting code: a read-only two-stage scan — recall-biased per-lens hunter subagents, then a separate fresh-context default-refute gate — over a target path/feature/diff or a rotated lane, emitting only verified 5-field findings. Use when: 'find a bug', 'bug hunt', 'scan for bugs', 'hunt for bugs in '. Skip when: reviewing a diff (`review:code-review`); security auditing (`review:security-review`); root-causing an observed failure (`debugging:debug`); doc/config/code/arch claim drift, all dimensions (`codebase-health:audit`); structural tidying (`code-tidying:tidy`); comment markers (`work-items:scan-todos`); coverage gaps (`testing:audit`, `mutation-testing:audit`). Disambiguation: 'scan repo for issues' is the upstream known-issue registry (`claude-ops:known-issues`); 'file a bug' you already observed is `bugs:write`. Bare invocation neither edits nor files; `--track` files verified findings as raw intake (subject to the team's `filing_posture`)." argument-hint: "[] [--lane ] [--track] [--dry-run]" user-invocable: true disable-model-invocation: false @@ -15,7 +15,7 @@ metadata: Current branch: !`git branch --show-current 2>/dev/null || echo "unknown"` Recent commits: !`git log --oneline -10 2>/dev/null || echo "no history (shallow or fresh clone)"` Shallow clone: !`git rev-parse --is-shallow-repository 2>/dev/null || echo "unknown"` -Lane config: !`ls "${CLAUDE_PROJECT_DIR:-.}/.claude/bug-report.md" 2>/dev/null || echo "absent — bundled default lanes apply"` +Lane config: !`ls "${CLAUDE_PROJECT_DIR:-.}/.claude/bugs.md" 2>/dev/null || echo "absent — bundled default lanes apply"` ## Variables @@ -23,7 +23,7 @@ Arguments: `$ARGUMENTS` ## Purpose -`/bug-report:scan` is the front of the bug lifecycle: it hunts defects **nobody has observed yet**, in +`/bugs:scan` is the front of the bug lifecycle: it hunts defects **nobody has observed yet**, in code that is resting. Every other finding-producer in reach needs an oracle first — a diff, a failing test, a stack trace, a factual claim, a comment marker. This one needs none of them. @@ -62,7 +62,7 @@ cursor from rungs 1–3 without it, and never treats a cache note as authority. | `--track` | **Filing** | After reporting, file verified findings as raw intake (see below), subject to the team's `filing_posture`. Composable with any mode. | | `--dry-run` | **Plan-and-report only** | Full hunt + verification, report to stdout, zero persistence and zero cursor advance. Composable with any mode; overrides `--track`. | -Lane definitions (`lanes`, `filing_posture`) resolve from `.claude/bug-report.md` per the cascade +Lane definitions (`lanes`, `filing_posture`) resolve from `.claude/bugs.md` per the cascade contract — keys, layers, and merge semantics live in [`${CLAUDE_PLUGIN_ROOT}/reference/config.md`](../../reference/config.md), which is their single home. When no layer declares lanes, use the bundled generic default lanes in @@ -73,17 +73,17 @@ When no layer declares lanes, use the bundled generic default lanes in Which lane comes next is derived **statelessly**, first rung that answers wins: 1. **Tracker history.** When the `work-items` plugin is installed and a tracker binding resolves, - search items (`--state all`) for the provenance line `Filed by /bug-report:scan (lane: )`. + search items (`--state all`) for the provenance line `Filed by /bugs:scan (lane: )`. The most recently filed lane is the previous lane; take the next one in declaration order. Confirm the search actually ran against a bound tracker before trusting an empty result — an unbound tracker returns nothing, which is not the same answer as "no prior scan filings". 2. **Persisted-report cursor.** Otherwise resolve the report directory by the **same precedence - persistence uses** — Step 4 below defers to `/bug-report:write`'s Step 4, and so does this rung; + persistence uses** — Step 4 below defers to `/bugs:write`'s Step 4, and so does this rung; reading a directory reports no longer land in is how a configured `output_dir` silently strands the cursor. Then search **backward from the newest report** for the newest one carrying a *valid* rotation cursor block — one that names the rotation lane (see [`context/findings-report.md`](context/findings-report.md)) — and use it the same way. Reports - without such a block are skipped, not read as a cursor: `/bug-report:write`'s reports share that + without such a block are skipped, not read as a cursor: `/bugs:write`'s reports share that directory and carry none, and a targeted scan's report must never advance rotation. If no report carries one, fall through to rung 3. 3. **Date-derived floor.** Otherwise pick deterministically: index the declared lane list by @@ -155,14 +155,14 @@ silently dropped. ### Step 4 — Assemble and dedupe the report Format per [`context/findings-report.md`](context/findings-report.md): the five fields per finding -(from `/bug-report:write`'s shape), plus the evidence label and lens id, then the refuted tail and — +(from `/bugs:write`'s shape), plus the evidence label and lens id, then the refuted tail and — on a rotation run — the cursor metadata block; a targeted run emits the no-cursor line in its place. -Before persisting, run the same duplicate scan `/bug-report:write` performs +Before persisting, run the same duplicate scan `/bugs:write` performs over the output directory — see Step 2 ("Survey before you write") in [`${CLAUDE_PLUGIN_ROOT}/skills/write/SKILL.md`](../write/SKILL.md) — and drop or merge findings that restate a prior report. -Persist to the path `/bug-report:write --file` resolves (its Step 4 owns that precedence: +Persist to the path `/bugs:write --file` resolves (its Step 4 owns that precedence: `output_dir`, then `${CLAUDE_PLUGIN_DATA}/bug-reports//`, then a project-local fallback). Do not reinvent either mechanism here. Under `--dry-run`, skip persistence entirely. @@ -185,7 +185,7 @@ Then presence-gated on `work-items`. Follow the dogfood-filing beats by invoking linked from a fresh item. 2. **Categorize as raw intake.** A scan filing records what was observed, not a verified diagnosis. 3. **File** through `track add`, which owns the body template and the argv-safe write. The body - carries the five fields, and a provenance line — `Filed by /bug-report:scan (lane: )` — which + carries the five fields, and a provenance line — `Filed by /bugs:scan (lane: )` — which is what rung 1 of the cursor ladder later recognizes. 4. **Mark `needs-triage` on the right axis, resolved from the live label set.** Priority axis: pass `--priority needs-triage` on the `track add` call, replacing the filing floor (never two @@ -229,7 +229,7 @@ Recommend, do not auto-invoke: wrong kill, and it stops the same dead candidate resurfacing next run. - **`--dry-run` must not advance the cursor.** A dry run that persists a cursor silently skips a lane on the next real run. -- **`--track` is not `--file`.** `--file` is `/bug-report:write`'s flag for persisting a report to +- **`--track` is not `--file`.** `--file` is `/bugs:write`'s flag for persisting a report to disk; the same token here would mean tracker mutation. This skill uses `--track` for filing. - **Shallow clones degrade, they do not fail.** The git-hotspot lens skips with a printed notice when history is absent; the other four lenses are unaffected. @@ -244,7 +244,7 @@ Recommend, do not auto-invoke: the retained-refuted output contract - [`context/findings-report.md`](context/findings-report.md) — report format, evidence labels, refuted tail, cursor metadata block -- [`${CLAUDE_PLUGIN_ROOT}/reference/config.md`](../../reference/config.md) — `.claude/bug-report.md` +- [`${CLAUDE_PLUGIN_ROOT}/reference/config.md`](../../reference/config.md) — `.claude/bugs.md` keys, layers, and merge semantics - [`${CLAUDE_PLUGIN_ROOT}/skills/write/SKILL.md`](../write/SKILL.md) — the five-field report shape, the duplicate scan, and the persistence path precedence this skill reuses diff --git a/plugins/bug-report/skills/scan/context/findings-report.md b/plugins/bugs/skills/scan/context/findings-report.md similarity index 93% rename from plugins/bug-report/skills/scan/context/findings-report.md rename to plugins/bugs/skills/scan/context/findings-report.md index b6cc1e0c39..0ad70a15fa 100644 --- a/plugins/bug-report/skills/scan/context/findings-report.md +++ b/plugins/bugs/skills/scan/context/findings-report.md @@ -1,6 +1,6 @@ -# Findings report format — `/bug-report:scan` +# Findings report format — `/bugs:scan` -Loaded on demand by `/bug-report:scan` Step 4. Defines the emitted and persisted report: per-finding +Loaded on demand by `/bugs:scan` Step 4. Defines the emitted and persisted report: per-finding fields, the refuted tail, and the cursor metadata block that the ladder's middle rung reads back. ## Frontmatter — and the one thing it must never declare @@ -25,7 +25,7 @@ directory, and this line is how a reader tells them apart. ## Per-finding shape -One `##` section per verified finding. The five fields are `/bug-report:write`'s — see +One `##` section per verified finding. The five fields are `/bugs:write`'s — see [`${CLAUDE_PLUGIN_ROOT}/skills/write/context/template.md`](../../write/context/template.md) for the canonical shape and severity rubric; it is not restated here. Scan adds two lines: the evidence label and the lens id. @@ -125,12 +125,12 @@ the zero-state date floor. `--dry-run` writes no report and therefore no cursor Its `lane`, `lane-index`, and `rung` keys have no rotation meaning, and a later run reading it as a cursor would skip a lane. Rung 2 therefore searches backward for the newest report that *does* carry -this block, skipping targeted-run reports and `/bug-report:write`'s reports — which share the +this block, skipping targeted-run reports and `/bugs:write`'s reports — which share the directory and never carry one — rather than trusting the newest file blindly. ## Stdout form -The same document minus the frontmatter, exactly as `/bug-report:write` emits to stdout without +The same document minus the frontmatter, exactly as `/bugs:write` emits to stdout without `--file`. When a report was also persisted, print its absolute path on the last line. ## Zero-findings form diff --git a/plugins/bug-report/skills/scan/context/lenses.md b/plugins/bugs/skills/scan/context/lenses.md similarity index 98% rename from plugins/bug-report/skills/scan/context/lenses.md rename to plugins/bugs/skills/scan/context/lenses.md index 9ec3bb976c..e775ddd67f 100644 --- a/plugins/bug-report/skills/scan/context/lenses.md +++ b/plugins/bugs/skills/scan/context/lenses.md @@ -1,6 +1,6 @@ -# Hunter lenses — the recall stage of `/bug-report:scan` +# Hunter lenses — the recall stage of `/bugs:scan` -Loaded on demand by `/bug-report:scan` Step 2. Each lens below is a **dispatch contract for one +Loaded on demand by `/bugs:scan` Step 2. Each lens below is a **dispatch contract for one fresh-context hunter subagent**, written in the four-part shape that keeps a fan-out from duplicating work or leaving gaps: **objective**, **output format**, **tool and source guidance**, **task boundaries**. diff --git a/plugins/bug-report/skills/scan/context/verification-gate.md b/plugins/bugs/skills/scan/context/verification-gate.md similarity index 96% rename from plugins/bug-report/skills/scan/context/verification-gate.md rename to plugins/bugs/skills/scan/context/verification-gate.md index c359911747..d43b05a874 100644 --- a/plugins/bug-report/skills/scan/context/verification-gate.md +++ b/plugins/bugs/skills/scan/context/verification-gate.md @@ -1,6 +1,6 @@ -# The verification gate — the precision stage of `/bug-report:scan` +# The verification gate — the precision stage of `/bugs:scan` -Loaded on demand by `/bug-report:scan` Step 3. This is the prompt contract for the gate: **one +Loaded on demand by `/bugs:scan` Step 3. This is the prompt contract for the gate: **one separate fresh-context subagent per candidate**, dispatched by the scan skill, never the hunter that produced the candidate. diff --git a/plugins/bug-report/skills/scan/evals/evals.json b/plugins/bugs/skills/scan/evals/evals.json similarity index 89% rename from plugins/bug-report/skills/scan/evals/evals.json rename to plugins/bugs/skills/scan/evals/evals.json index db347d75b4..c1b60eca8f 100644 --- a/plugins/bug-report/skills/scan/evals/evals.json +++ b/plugins/bugs/skills/scan/evals/evals.json @@ -11,7 +11,7 @@ "expectations": [ "The hunt is scoped to src/billing/ only — no lane rotation and no cursor advance for a targeted run", "Candidates are produced by per-lens hunter subagents and then graded by a SEPARATE fresh-context verification subagent, not by the hunter that found them", - "Every reported finding carries the five bug-report fields plus an evidence label of exactly `reproduced` or `verified-by-reading` and a lens id", + "Every reported finding carries the five bugs fields plus an evidence label of exactly `reproduced` or `verified-by-reading` and a lens id", "Every reported finding cites a verbatim quote of the offending source with a path and line", "Refuted candidates are retained in a refuted-candidates section with a refuting argument rather than silently dropped", "No code is modified, no branch or PR is created, and no tracker item is filed" @@ -35,14 +35,14 @@ { "id": 3, "name": "track-flag-files-raw-intake", - "prompt": "Our .claude/bug-report.md declares `filing_posture: allowed`. Hunt the entrypoints lane and file whatever you verify: --lane entrypoints --track", - "expected_output": "The posture gate resolves first — the team layer declares `filing_posture: allowed`, so filing is permitted rather than skipped against the bundled manual-only default. After reporting, verified findings are filed through /work-items:track add: a duplicate search over --state all runs first, each item body carries the five fields plus the provenance line 'Filed by /bug-report:scan (lane: entrypoints)', and the needs-triage marker is applied on the correct axis resolved from the live label set — --priority needs-triage on the priority axis, or a status-axis label applied after creation. No labels are created. If work-items is absent or no tracker binding resolves, filing is skipped with a printed notice and the run degrades to report-only.", + "prompt": "Our .claude/bugs.md declares `filing_posture: allowed`. Hunt the entrypoints lane and file whatever you verify: --lane entrypoints --track", + "expected_output": "The posture gate resolves first — the team layer declares `filing_posture: allowed`, so filing is permitted rather than skipped against the bundled manual-only default. After reporting, verified findings are filed through /work-items:track add: a duplicate search over --state all runs first, each item body carries the five fields plus the provenance line 'Filed by /bugs:scan (lane: entrypoints)', and the needs-triage marker is applied on the correct axis resolved from the live label set — --priority needs-triage on the priority axis, or a status-axis label applied after creation. No labels are created. If work-items is absent or no tracker binding resolves, filing is skipped with a printed notice and the run degrades to report-only.", "files": [], "narration": true, "expectations": [ "`filing_posture` is resolved from the config cascade BEFORE any filing, and filing proceeds only because the team layer declares `allowed` — the bundled default is manual-only", "A duplicate search over --state all runs BEFORE any item is created, and an open match is commented on rather than duplicated", - "Each filed item body contains the provenance line `Filed by /bug-report:scan (lane: entrypoints)`", + "Each filed item body contains the provenance line `Filed by /bugs:scan (lane: entrypoints)`", "The needs-triage marker is resolved from the live label set and applied on one axis only — `--priority needs-triage` replacing the filing floor, or a status-axis label applied after creation", "No new label is created under any circumstance", "Filing routes through /work-items:track add rather than reaching into another plugin's files or reimplementing the tracker seam", @@ -74,7 +74,7 @@ "The known-issue-registry request is routed to claude-ops:known-issues and explicitly distinguished from this skill's proactive hunt of resting code", "The pre-merge diff review is routed to the review lane rather than handled here", "No proactive lane hunt is started to satisfy either request", - "The response distinguishes this skill from bug-report:write, which handles a defect the user has already observed" + "The response distinguishes this skill from bugs:write, which handles a defect the user has already observed" ] }, { diff --git a/plugins/bug-report/skills/setup/SKILL.md b/plugins/bugs/skills/setup/SKILL.md similarity index 81% rename from plugins/bug-report/skills/setup/SKILL.md rename to plugins/bugs/skills/setup/SKILL.md index c4c8111ee2..1b8b2a747c 100644 --- a/plugins/bug-report/skills/setup/SKILL.md +++ b/plugins/bugs/skills/setup/SKILL.md @@ -1,5 +1,5 @@ --- -description: "Verify and configure the bug-report plugin for this repository. check inspects both surfaces read-only — the rendered output_dir userConfig value, and the tracked .claude/bug-report.md lane config across its cascade layers; apply writes or updates that tracked file and nothing else. Use when: 'set up bug-report', 'configure bug-report', 'bug-report setup', 'where do bug reports land', you want --file reports committed alongside code, or '/bug-report:scan' needs project lanes and a filing posture. Actions: check (read-only, default) | apply (creates or updates the tracked lane config; output_dir still routes through Claude Code's own configuration prompt)." +description: "Verify and configure the bugs plugin for this repository. check inspects both surfaces read-only — the rendered output_dir userConfig value, and the tracked .claude/bugs.md lane config across its cascade layers; apply writes or updates that tracked file and nothing else. Use when: 'set up bugs', 'configure bugs', 'bugs setup', 'where do bug reports land', you want --file reports committed alongside code, or '/bugs:scan' needs project lanes and a filing posture. Actions: check (read-only, default) | apply (creates or updates the tracked lane config; output_dir still routes through Claude Code's own configuration prompt)." argument-hint: "check|apply" user-invocable: true disable-model-invocation: true @@ -7,15 +7,15 @@ disable-model-invocation: true ## Purpose -Confirm where `/bug-report:write --file` writes reports, and manage the tracked project config -`/bug-report:scan` reads for its lanes and filing posture. +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/bug-report.md` — tracked, cascade-layered | team policy: `/bug-report:scan` lanes and filing posture | `apply` here, team layer only | +| `.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 @@ -52,8 +52,8 @@ Modify nothing. Report both surfaces, then one remediation line per gap. artifact directories and recommend one portable location. Never recommend a machine-absolute team path. 4. If the recommended value differs from the effective one, direct the user to Claude Code's - plugin configuration prompt for `bug-report` (interactive `/plugin configure bug-report@` any - time; headless, rerun `claude plugin install bug-report@ -s --config + plugin configuration prompt for `bugs` (interactive `/plugin configure bugs@` any + time; headless, rerun `claude plugin install bugs@ -s --config output_dir=` — against an already-installed plugin it prints `already installed` and still writes the value, verified on Claude Code 2.1.240 for a non-sensitive option at `user` scope. Never uninstall to reconfigure: that drops the whole stored `pluginConfigs` entry and @@ -62,7 +62,7 @@ Modify nothing. Report both surfaces, then one remediation line per gap. 5. Tell the user to rerun `check` after reconfiguration — in a fresh session, since the rendered value is injected at load — then verify and report the effective destination. -### B. `.claude/bug-report.md` (tracked lane config) +### B. `.claude/bugs.md` (tracked lane config) Anchor at the repo root — `${CLAUDE_PROJECT_DIR}` when set, otherwise `git rev-parse --show-toplevel` — never at the CWD, then report **each layer separately** and the effective merged result: @@ -73,12 +73,12 @@ Anchor at the repo root — `${CLAUDE_PROJECT_DIR}` when set, otherwise `git rev 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 — `/bug-report:scan` falls through to its bundled + 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/bug-report.md`; a + 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/bug-report.md`; a non-zero exit on a present file is also + `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 @@ -89,7 +89,7 @@ Anchor at the repo root — `${CLAUDE_PROJECT_DIR}` when set, otherwise `git rev 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/bug-report.md`) +## `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 @@ -115,12 +115,12 @@ requested here is routed to the native flow in `check` step A4, never written. 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/bug-report.md` confirms it is not ignored. A file + 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/bug-report.local.md`; recommend the consumer add the recursive `.gitignore` line the + `.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. @@ -136,8 +136,8 @@ a fresh session. ## Boundaries -- Do not produce or file a bug report; invoke `/bug-report:write` via the Skill tool. -- Do not run a hunt; that is `/bug-report:scan`. This skill only verifies and writes its config. +- 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). diff --git a/plugins/bug-report/skills/setup/evals/evals.json b/plugins/bugs/skills/setup/evals/evals.json similarity index 83% rename from plugins/bug-report/skills/setup/evals/evals.json rename to plugins/bugs/skills/setup/evals/evals.json index e7a9c338f3..2512937621 100644 --- a/plugins/bug-report/skills/setup/evals/evals.json +++ b/plugins/bugs/skills/setup/evals/evals.json @@ -4,7 +4,7 @@ { "id": 1, "name": "validates-rendered-option-without-settings-edits", - "prompt": "/bug-report:setup", + "prompt": "/bugs:setup", "expected_output": "Reports the rendered output_dir or the private plugin-data fallback, asks whether reports should remain private or use a portable repository location, and never reads or edits settings files or pluginConfigs.", "files": [], "expectations": [ @@ -16,7 +16,7 @@ { "id": 2, "name": "routes-changes-through-claude-configuration", - "prompt": "/bug-report:setup\n\nCommit --file reports into this repository.", + "prompt": "/bugs:setup\n\nCommit --file reports into this repository.", "expected_output": "Inspects the repository's declared artifact conventions, recommends a portable location, directs the user to Claude Code's plugin configuration prompt, and requires a rerun before claiming the value changed.", "files": [], "expectations": [ @@ -28,13 +28,13 @@ { "id": 3, "name": "apply-scaffolds-the-tracked-lane-config", - "prompt": "/bug-report:setup apply", - "expected_output": "Reports the effective lane config per layer first, drafts lanes from the repository layout, settles filing_posture, writes only .claude/bug-report.md in the documented format, then re-reads it and confirms it is tracked rather than gitignored.", + "prompt": "/bugs:setup apply", + "expected_output": "Reports the effective lane config per layer first, drafts lanes from the repository layout, settles filing_posture, writes only .claude/bugs.md in the documented format, then re-reads it and confirms it is tracked rather than gitignored.", "files": [], "narration": true, "expectations": [ "Runs the check probes before writing anything", - "Writes only the tracked .claude/bug-report.md team layer", + "Writes only the tracked .claude/bugs.md team layer", "Uses the key contract in reference/config.md instead of inventing keys", "Verifies the written file by re-reading it and by git check-ignore" ] @@ -42,7 +42,7 @@ { "id": 4, "name": "apply-stays-off-user-config-and-gitignore", - "prompt": "/bug-report:setup apply\n\nAlso point output_dir at docs/bug-reports/ and add the ignore line for my personal overlay.", + "prompt": "/bugs:setup apply\n\nAlso point output_dir at docs/bug-reports/ and add the ignore line for my personal overlay.", "expected_output": "Writes the lane config only, routes the output_dir change to Claude Code's plugin configuration prompt, and recommends the recursive .claude ignore line for the .local.md overlay without editing .gitignore.", "files": [], "narration": true, @@ -55,7 +55,7 @@ { "id": 5, "name": "check-reports-every-cascade-layer", - "prompt": "/bug-report:setup check\n\nWhich lanes does scan actually use here?", + "prompt": "/bugs:setup check\n\nWhich lanes does scan actually use here?", "expected_output": "Reports each cascade layer separately with the layer that supplied each value, names an empty-list opt-out as an opt-out, treats all layers absent as a working state served by the bundled default lanes, and changes nothing.", "files": [], "narration": true, diff --git a/plugins/bug-report/skills/write/SKILL.md b/plugins/bugs/skills/write/SKILL.md similarity index 97% rename from plugins/bug-report/skills/write/SKILL.md rename to plugins/bugs/skills/write/SKILL.md index f0c56cb8a4..2b8d610bbf 100644 --- a/plugins/bug-report/skills/write/SKILL.md +++ b/plugins/bugs/skills/write/SKILL.md @@ -20,7 +20,7 @@ Arguments: `$ARGUMENTS` ## Purpose -`/bug-report` produces a five-field structured report so the next session (or a human) can act without re-asking on vague repro, missing severity, no fix location, or hand-wavy expected/actual. **Read-only** — it captures, it does not fix, and it does not file (unless you explicitly ask). +`/bugs` produces a five-field structured report so the next session (or a human) can act without re-asking on vague repro, missing severity, no fix location, or hand-wavy expected/actual. **Read-only** — it captures, it does not fix, and it does not file (unless you explicitly ask). This is the **bug-intake** stage. It sits upstream of filing the report into a work-item tracker, and it is independent of any downstream fix workflow — when the report itself is the deliverable (a Slack message, a PR comment, a verbal handoff), that is all this skill needs to do. @@ -46,7 +46,7 @@ Invoke when ANY hold: If it is ambiguous, surface the question once and let the user pick. -## The bug-report process +## The bugs process ### Step 1 — Skip-condition check (MANDATORY) diff --git a/plugins/bug-report/skills/write/context/template.md b/plugins/bugs/skills/write/context/template.md similarity index 91% rename from plugins/bug-report/skills/write/context/template.md rename to plugins/bugs/skills/write/context/template.md index c0e4c995fa..1a020c48c8 100644 --- a/plugins/bug-report/skills/write/context/template.md +++ b/plugins/bugs/skills/write/context/template.md @@ -1,6 +1,6 @@ -# `/bug-report` template and worked examples +# `/bugs` template and worked examples -Loaded on demand by the `bug-report` skill. Contains: the full Markdown template (5 fields), one worked example, the `--file` frontmatter, and the "No bug confirmed" form. +Loaded on demand by the `bugs` skill. Contains: the full Markdown template (5 fields), one worked example, the `--file` frontmatter, and the "No bug confirmed" form. ## Full template @@ -38,7 +38,7 @@ Default emission (stdout) — no frontmatter: --- -*Generated by `/bug-report:write` (stdout mode). To file it as a work item, copy this report into* +*Generated by `/bugs:write` (stdout mode). To file it as a work item, copy this report into* *your tracker, rerun with `--file` and then `gh issue create --type Bug --body-file `* *(org repos; on repos without native Issue Types omit `--type Bug` and add a `type: bug` label when the* *repo defines one) (let `gh` prompt for the title), or use an available tracker MCP tool.* @@ -65,7 +65,7 @@ Append this footer after the report body when writing to a file: ```markdown --- -*Generated by `/bug-report:write` (--file mode). To file it as a work item in a GitHub repo:* +*Generated by `/bugs:write` (--file mode). To file it as a work item in a GitHub repo:* *`gh issue create --type Bug --body-file ` (org repos; on repos without native Issue* *Types omit `--type Bug` and add a `type: bug` label when the repo defines one) (let `gh` prompt for* *the title), or use an available tracker MCP tool.* diff --git a/plugins/bug-report/skills/write/evals/evals.json b/plugins/bugs/skills/write/evals/evals.json similarity index 100% rename from plugins/bug-report/skills/write/evals/evals.json rename to plugins/bugs/skills/write/evals/evals.json diff --git a/plugins/bug-report/skills/write/evals/fixtures/pagination-correct-offset.md b/plugins/bugs/skills/write/evals/fixtures/pagination-correct-offset.md similarity index 100% rename from plugins/bug-report/skills/write/evals/fixtures/pagination-correct-offset.md rename to plugins/bugs/skills/write/evals/fixtures/pagination-correct-offset.md diff --git a/plugins/claude-ops/.claude-plugin/plugin.json b/plugins/claude-ops/.claude-plugin/plugin.json index 8fe2feba50..a45eb59f2a 100644 --- a/plugins/claude-ops/.claude-plugin/plugin.json +++ b/plugins/claude-ops/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "claude-ops", - "version": "0.37.0", + "version": "0.37.1", "description": "Claude Code operations toolkit. Twelve skills: audit-skill-visibility (audit whether each installed skill is actually VISIBLE to the model, and diagnose why most of a fleet never gets used — a skill is invisible when its description is dropped by Claude Code's skill-listing context budget, which drops descriptions least-invoked-first so an unused skill loses the keywords that would let it be matched, from skills genuinely not wanted, from skills the run cannot observe at all; computes whether the listing overflows from documented settings, and withholds every cold verdict the data cannot support rather than reporting absence of data as absence of use), inventory (read-only enumeration of the complete invocable surface — every built-in CLI command with aliases and hidden/gated status, every bundled skill, and every component of every installed plugin across all marketplaces; reads the shipped binary because upstream publishes no built-in command list, and carries an integrity verdict so a drifted build reports counts as floors rather than silently short totals), audit-install-state (read-only audit of the machine-scope ~/.claude installation directory and ~/.claude.json — full inventory split into an authored surface and rolled-up bulk trees, product-managed retention vs genuinely unmanaged state, filename-scheme resolution before any process-liveness check, and deliberate/mid-experiment detection; reports, never deletes), audit-performance (read-only slowness-diagnostic capture run at the moment the machine or a session feels slow — CLI version, retention-sweep health including the silent unparsable-settings pause, a timed census walk of the install tree as a sweep-cost proxy, active-session and plugin-fleet counts, a process census, and a bundled known-performance-issues reference; separates the three documented suspects — accumulated state, version regression, component bloat — and routes remediation out; reports, never mutates), audit-native-overlap (map native Claude Code surfaces — built-in CLI commands, bundled skills, plugin-backed built-ins, session-provided skills — against the current repo's plugin skills and agents, so a custom component never silently duplicates what Claude Code itself ships; bare invocation is a read-only overlap report carrying the extraction's integrity floors and a shared-listing-budget exposure section, verdicts are human-gated in a committed store rendered into a generated registry whose every row carries an observable recheck trigger, and only an explicit apply step bakes presence-gated native references into descriptions and Boundary sections), observability (read locally captured telemetry — OTEL store, collector, hook-event JSONL, ccusage — with trend reports and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand — marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), morning-brief (read-only gh-based operator morning view — queue-label counts, merge-ready PRs, parked decisions with their RECOMMENDED lines, and loop-lane telemetry freshness), lanes (start/restart/stop/status loop lanes as named background Claude Code sessions seeded from canonical prompt files, with per-lane model/effort, a repo-pull + marketplace-refresh launch step, and a consume-restarts action — an OS-schedulable reader that relaunches stopped lanes whose telemetry carries a restart_request), and a re-runnable setup action that settles where the known-issues registry lives. Plus a family of eight advisory *-audit hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures, and unsurfaced hook failures — the last also warns the user via systemMessage, since a hook that fails to launch enforces nothing and Claude Code surfaces the failure to nobody) that emit the shared hook-telemetry envelope, and a reference sink that maps envelopes into the hook-events.jsonl the observability skill reads.", "author": { "name": "Melodic Software", diff --git a/plugins/claude-ops/CHANGELOG.md b/plugins/claude-ops/CHANGELOG.md index 686dbc31bf..d870450f18 100644 --- a/plugins/claude-ops/CHANGELOG.md +++ b/plugins/claude-ops/CHANGELOG.md @@ -3,6 +3,14 @@ All notable changes to the `claude-ops` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.37.1] + +### Changed + +- **`known-issues`: cross-references follow the `bug-report` → `bugs` plugin rename.** The + composition section and evals now name `/bugs:write` and "the `bugs` plugin". Wording only — + no behavior change. + ## [0.37.0] ### Added diff --git a/plugins/claude-ops/skills/known-issues/SKILL.md b/plugins/claude-ops/skills/known-issues/SKILL.md index 9554e04301..24fc3c5201 100644 --- a/plugins/claude-ops/skills/known-issues/SKILL.md +++ b/plugins/claude-ops/skills/known-issues/SKILL.md @@ -145,9 +145,9 @@ now-obsolete workaround. Skip silently when no such doc exists. When stress-testing a plan that builds on a Claude Code mechanism, run `search` for that mechanism first — known bugs reshape plans cheaply before implementation. -### With `/bug-report:write` (if installed) +### With `/bugs:write` (if installed) -For bugs in YOUR code (not Claude Code itself), use the `bug-report` plugin's skill instead; +For bugs in YOUR code (not Claude Code itself), use the `bugs` plugin's skill instead; without it, write up the defect manually. This skill covers Claude product issues only. ## What This Skill Does NOT Do diff --git a/plugins/claude-ops/skills/known-issues/evals/evals.json b/plugins/claude-ops/skills/known-issues/evals/evals.json index 9365c52b79..28ac186704 100644 --- a/plugins/claude-ops/skills/known-issues/evals/evals.json +++ b/plugins/claude-ops/skills/known-issues/evals/evals.json @@ -51,12 +51,12 @@ "id": 5, "name": "own-code-bug-routes-away", "prompt": "I found a bug in my own app's applyLateFee billing function (not a Claude Code bug) — does /claude-ops:known-issues track that, or should I file it elsewhere?", - "expected_output": "This is a defect in the user's own code, not a Claude product issue. The skill declines to add it to the Claude-product registry or search Claude repos for it, and routes to /bug-report:write (or a manual defect write-up when that plugin is absent).", + "expected_output": "This is a defect in the user's own code, not a Claude product issue. The skill declines to add it to the Claude-product registry or search Claude repos for it, and routes to /bugs:write (or a manual defect write-up when that plugin is absent).", "files": [], "expectations": [ "The response recognizes this as a bug in the user's own code, not a Claude product issue", "The response does NOT add the user's own-code bug to the Claude-product registry", - "The response routes to `/bug-report:write` (or a manual defect write-up if that plugin is unavailable)" + "The response routes to `/bugs:write` (or a manual defect write-up if that plugin is unavailable)" ] }, { diff --git a/plugins/work-items/.claude-plugin/plugin.json b/plugins/work-items/.claude-plugin/plugin.json index bc5eefe9a0..f2c8116190 100644 --- a/plugins/work-items/.claude-plugin/plugin.json +++ b/plugins/work-items/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "work-items", - "version": "0.39.18", + "version": "0.39.19", "description": "Manages development work items through a provider-neutral tracker seam that ships with the plugin (bundled dispatcher plus github, local-markdown, jira, gitea, and linear adapters; seam plugin-dir canonical, adapters consumer-local-first): dashboard, taxonomy-labeled creation, a race-safe assignee-plus-lease claim protocol, recurring-schedule checks, TODO scanning, stale-lease auditing, plan decomposition into vertical-slice items, a macro-journey router over spec containers (rollup, per-container execution shape, next-step routing), raw-intake triage (issues and unsolicited PRs through raw, verified, briefed, autonomous-eligible states), plus the two work-items loop lanes of the loop-lane convention: a self-paced autonomous work-loop drain (work-class admission gate, adaptive item cap, PR-only) and an attended attend-queue escalation lane. The re-runnable setup skill binds the provider (.work-item-tracker.json), seeds the recurring-schedule seam (.github/recurring-schedule.json), and remaps canonical role labels.", "author": { "name": "Melodic Software", diff --git a/plugins/work-items/CHANGELOG.md b/plugins/work-items/CHANGELOG.md index 89415238e5..6fd1ba9e6d 100644 --- a/plugins/work-items/CHANGELOG.md +++ b/plugins/work-items/CHANGELOG.md @@ -3,6 +3,13 @@ All notable changes to the `work-items` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.39.19] + +### Changed + +- **`track`: cross-reference follows the `bug-report` → `bugs` plugin rename.** The description's + bug-intake pointer now names `/bugs:write`. Wording only — no behavior change. + ## [0.39.18] ### Fixed diff --git a/plugins/work-items/skills/track/SKILL.md b/plugins/work-items/skills/track/SKILL.md index abf9b2e20e..32e28e3079 100644 --- a/plugins/work-items/skills/track/SKILL.md +++ b/plugins/work-items/skills/track/SKILL.md @@ -1,5 +1,5 @@ --- -description: "Track development work items through the bound tracker (work-item-tracker seam), the backlog-CRUD multi-verb skill. Actions: stats, list, add, start, done, due, recheck, search, audit (default: stats dashboard). Use when: 'add a work item', 'add an issue', 'add a ticket', 'close a work item', 'close a ticket', 'close an issue', 'start a work item', 'start a ticket', 'start an issue', 'claim a work item', 'list work items', 'list tickets', 'list issues', 'what work items are open', 'what's due', 'work-item stats', 'work items dashboard', 'search work items', 'check overdue recurring items', 'recheck a recurring item', 'audit work items', 'audit stale claims'. Not for new bug reports, use /bug-report:write first (read-only report), then chain to /work-items:track add via --context if filing is needed. Sibling skills own the other verbs: /work-items:work (auto-select + execute one), /work-items:triage (raw intake), /work-items:decompose (plan → tickets), /work-items:scan-todos (TODO/FIXME sweep)." +description: "Track development work items through the bound tracker (work-item-tracker seam), the backlog-CRUD multi-verb skill. Actions: stats, list, add, start, done, due, recheck, search, audit (default: stats dashboard). Use when: 'add a work item', 'add an issue', 'add a ticket', 'close a work item', 'close a ticket', 'close an issue', 'start a work item', 'start a ticket', 'start an issue', 'claim a work item', 'list work items', 'list tickets', 'list issues', 'what work items are open', 'what's due', 'work-item stats', 'work items dashboard', 'search work items', 'check overdue recurring items', 'recheck a recurring item', 'audit work items', 'audit stale claims'. Not for new bug reports, use /bugs:write first (read-only report), then chain to /work-items:track add via --context if filing is needed. Sibling skills own the other verbs: /work-items:work (auto-select + execute one), /work-items:triage (raw intake), /work-items:decompose (plan → tickets), /work-items:scan-todos (TODO/FIXME sweep)." argument-hint: " [args]. Actions: stats, list, add, start, done, due, recheck, search, audit (default: stats)" user-invocable: true disable-model-invocation: false diff --git a/scripts/skill-leaf-name-registry.txt b/scripts/skill-leaf-name-registry.txt index 853b087dff..89c34b04f3 100644 --- a/scripts/skill-leaf-name-registry.txt +++ b/scripts/skill-leaf-name-registry.txt @@ -147,6 +147,6 @@ update firecrawl,playbooks # (the noun namespace carries the artifact class, the leaf stays the verb). generate ai-briefing,wizard -# Fixed verb meaning: produces an artifact. bug-report writes a report, testing +# Fixed verb meaning: produces an artifact. bugs writes a report, testing # writes tests. -write bug-report,testing +write bugs,testing