feat: add claude-ops plugin

.claude-plugin/marketplace.json

@@ -174,6 +174,12 @@
       "source": "./plugins/tdd",
       "category": "learning",
       "tags": ["knowledge", "skill", "tdd", "testing", "unit-testing", "test-design", "best-practices"]
+    },
+    {
+      "name": "claude-ops",
+      "source": "./plugins/claude-ops",
+      "category": "monitoring",
+      "tags": ["operations", "observability", "otel", "telemetry", "troubleshooting", "changelog", "claude-code", "skill"]
     }
   ]
 }

README.md

@@ -48,6 +48,7 @@ Browse and manage with `/plugin`. To refresh after updates: `/plugin marketplace
 | [`code-tidying`](plugins/code-tidying) | Skills | Structure-only codebase improvement per Beck's *Tidy First?*: `/code-tidying:tidy` proactively hunts a rotated, glob-scoped lane for named tidyings under a research-backed scope budget (consumer-defined lanes in `.claude/tidy-lanes/` override bundled ones) and ships one tight PR; `/code-tidying:batch-simplify` sweeps recently changed files through grouped, dependency-ordered simplification waves with a never-drop deferred-items contract. |
 | [`session-flow`](plugins/session-flow) | Skills | Session-lifecycle toolkit of four skills: `workflow` (navigate a staged dev workflow and suggest the next stage), `handoff` (write a save-point + resume prompt for the `/clear`-and-resume pattern), `retro` (structured retrospective with a bundled transcript-metrics parser and learning codification), and `orchestration-brief` (arm a session or spawned worker with proactive-orchestration imperatives). |
 | [`tdd`](plugins/tdd) | Skill | Ships a TDD knowledge base distilled from Beck's *TDD: By Example* and Khorikov's *Unit Testing: Principles, Practices, and Patterns* — fourteen author-attributed reference files behind a routing table plus a no-load quick decision guide, answering the WHY behind test design decisions. |
+| [`claude-ops`](plugins/claude-ops) | Skills | Claude Code operations toolkit of three skills: `/claude-ops:claude-observability` (read locally captured telemetry — OTEL store, collector, hook-event JSONL, ccusage — with trend reports and store pruning), `/claude-ops:claude-troubleshooting` (search known Claude product bugs, check service health, maintain a persistent tracked-issue registry), and `/claude-ops:claude-code-changelog` (ingest Claude Code changelog entries and integrate them into the current repo). |
 
 Install one: `/plugin install <plugin-name>@melodic-software`.
 

plugins/claude-ops/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "claude-ops",
+  "version": "0.1.0",
+  "description": "Claude Code operations toolkit of three skills: claude-observability (read locally captured telemetry — OTEL store, collector, hook-event JSONL, ccusage — with trend reports and store pruning), claude-troubleshooting (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), and claude-code-changelog (ingest Claude Code changelog entries and integrate them into the current repo).",
+  "author": {
+    "name": "Melodic Software",
+    "email": "info@melodicsoftware.com"
+  },
+  "license": "MIT",
+  "keywords": ["claude-code", "operations", "observability", "otel", "troubleshooting", "changelog", "monitoring"]
+}

plugins/claude-ops/README.md

@@ -0,0 +1,60 @@
+# claude-ops
+
+A Claude Code plugin bundling three operations skills — one cohesive capability:
+running Claude Code well over time. Observability reads what your sessions
+actually did, troubleshooting tracks what upstream has broken, and changelog
+integration keeps your repo current with what upstream has shipped.
+
+## The three skills
+
+| Skill | What it does |
+|---|---|
+| `/claude-ops:claude-observability` | Reads locally captured Claude Code telemetry — OTEL DuckDB store, collector, optional Aspire dashboard, hook-event JSONL, ccusage — and renders cross-session trend reports (`session`/`day`/`week`/`month`/`since:`/`all` scopes). Read-only except the explicit `clean` action, which prunes the JSONL log and OTEL store by age. |
+| `/claude-ops:claude-troubleshooting` | Searches known Claude product GitHub bugs before you build on a feature, checks service health and model quality, and maintains a persistent registry of tracked issues (what they block, workarounds, follow-ups when fixed). Actions: `status` (default), `search`, `check-all`, `scan`, `list`, `quality`, `create`. |
+| `/claude-ops:claude-code-changelog` | Ingests Claude Code changelog entries and integrates them into the current repo: `fetch` (read-only display), `diff` (impact triage, no edits), `status` (applied versions from git history), and `apply` (full explore → research → interview → implement pipeline, explicit user intent only). |
+
+## Install
+
+```shell
+/plugin marketplace add melodic-software/claude-code-plugins
+/plugin install claude-ops@melodic-software
+```
+
+## How the skills adapt to your repo
+
+The defaults are repo-agnostic and everything project-specific routes through
+your own repository's context:
+
+- **Observability data locations.** The OTEL store defaults to
+  `<project-root>/.claude/observability/otel` and is overridable via the
+  `CC_OTEL_STORE` env var (retention windows via `CC_OTEL_RETENTION_DAYS` /
+  `CC_OTEL_BODY_RETENTION_DAYS`). The hook-event JSONL source is read from
+  `<project-root>/.claude/observability/hook-events.jsonl` only when your own
+  hooks emit it; every source degrades gracefully when absent.
+- **Persistent state** lives under the plugin's own data directory
+  (`${CLAUDE_PLUGIN_DATA}`): the troubleshooting issue registry
+  (`registry.json`), `check-all` output, and `--write` observability reports.
+  Nothing is written into your repository.
+- **Work-item and docs integration.** Where the skills propose follow-up work
+  items or cross-reference quirks/workaround docs, they use whatever tracker
+  and docs your project has (e.g. `gh issue create`, your `CLAUDE.md` /
+  `.claude/rules`) and skip silently when there is none.
+
+## Requirements
+
+Core flows need only `git`, `jq`, `gh` (authenticated), and `python3`.
+Optional, for the OTEL pipeline: `otelcol-contrib` (collector), `duckdb`
+(store queries), Docker (Aspire dashboard), and `npx` for ccusage. Every
+skill reports missing optional tooling instead of failing.
+
+## Configuration
+
+This plugin has no `userConfig`. Variability is covered by the env vars above
+and conventional project-relative defaults; the bundled scripts make no
+outbound network calls except `gh`/`curl` reads of GitHub and Claude status
+pages in the troubleshooting skill.
+
+## License
+
+MIT (SPDX-License-Identifier: MIT). See the LICENSE file at the root of the
+melodic-software/claude-code-plugins repository.

plugins/claude-ops/skills/claude-code-changelog/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: claude-code-changelog
+description: "Ingest Claude Code changelog entries and integrate them into the current repo — fetch (read-only display), diff (impact analysis, no edits), status (applied versions), and apply (full integrate pipeline, explicit user intent only). Use when: 'new cc version', 'what changed in claude code', 'apply changelog', a new CC release is mentioned, or the user pastes changelog text."
+argument-hint: "<action> [version|text] — actions: fetch (default on passive mention), diff, status, apply (explicit only)"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## Variables
+
+Arguments: `$ARGUMENTS`
+
+## Scope
+
+Ingests Claude Code changelog entries and integrates them into the repo. Covers the full arc: read upstream changes → orient on repo impact → research new features → triage with user → plan edits → implement → verify → close matching issues.
+
+Distinct from:
+
+- `/claude-troubleshooting` — tracks CC bugs/workarounds. This skill integrates CC feature changes into repo config/docs
+- Any release-triage automation the consumer runs (issue filing per release) — this skill IMPLEMENTS changes, holistically across a release
+
+## Input modes
+
+Three ways to provide changelog content (priority order):
+
+1. **User pastes text** — skill parses inline changelog from conversation context
+2. **Specific version** — `/claude-code-changelog apply v2.1.152` fetches that version from `code.claude.com/docs/en/changelog`
+3. **Auto-detect latest** — `/claude-code-changelog apply` (no version) automatically fetches changelog, identifies latest version, and proceeds
+
+## Version awareness
+
+On every `apply` or `diff` invocation, check the active terminal's CC version:
+
+```bash
+claude --version 2>/dev/null
+```
+
+- If target version > installed version: **warn user** — "You're applying v2.1.152 changes but running v2.1.150. Update CC first (`claude update`) or changes may reference features not yet available in your session."
+- If target version = installed version: proceed normally
+- If target version < installed version: fine — catching up on older release
+
+## Applied-version tracking
+
+No persistent tracking file. Git history IS the tracker — commit messages cite CC versions per Conventional Commits (`chore: address Claude Code v2.1.152 changelog`). The `status` action derives applied versions via `git log --grep`. Avoids drift between tracker file and git state.
+
+## Action Router
+
+Parse `$ARGUMENTS` to extract the action (first token) and remaining arguments.
+
+| Action | Description | Detail |
+|--------|-------------|--------|
+| `apply` | Full pipeline: ingest → explore → research → interview → architect → implement → verify → close issues | See "Action: apply" below |
+| `fetch` | Fetch + display changelog for version(s). Read-only | See "Action: fetch" below |
+| `diff` | Fetch + orient on repo impact. Read-only analysis table | See "Action: diff" below |
+| `status` | Show applied versions, open issues, pending work | See "Action: status" below |
+| `help` | Show action table | *(inline)* |
+
+**Routing (model-invocable):**
+
+- Empty args or passive CC version mention → **`fetch`** or **`diff`** (read-only). Never **`apply`**.
+- Version-only token (`v2.1.152`) without explicit apply intent → **`fetch`** for that version.
+- **`apply`** only when user explicitly requests integration (`apply`, `apply changelog`, `/claude-code-changelog apply`, or unambiguous implement-this-release intent).
+
+If action is unknown, show action table.
+
+## Action: apply — user intent gate
+
+**`apply` mutates the repo.** Run only on explicit user intent per routing above. When the model
+detects a new CC release in conversation, default to `fetch` or `diff` and offer `apply` — do not
+auto-start the pipeline.
+
+The full pipeline runs explore → research → interview → architect → implement → verify as the phases below. If the consumer project ships its own stage skills for these, prefer them at each phase.
+
+### Phase 0 — Ingest
+
+Resolve changelog content and check version alignment:
+
+1. **Check installed CC version:** `claude --version 2>/dev/null`. Compare against target version per "Version awareness" above
+2. **Resolve content** (first match wins):
+   - Changelog text already in conversation → parse it
+   - Version arg provided (e.g., `apply v2.1.152`) → run `fetch` for that version
+   - No text, no version → auto-fetch latest version from changelog URL
+3. **Parse** into structured items. Each item gets: summary, category (feature / fix / UI / internal), affected surface (if identifiable)
+
+### Phase 1 — Explore
+
+Per `context/repo-surfaces.md`, orient on repo impact for EACH changelog item:
+
+1. Grep/Glob each feature name, setting name, hook event, CLI flag across ALL listed surfaces
+2. Classify each item per `context/classification-rubric.md`:
+   - **P1 (requires update)** — repo already uses this feature/surface and changelog changes behavior or adds capability we should document
+   - **P2 (worth considering)** — new capability repo does NOT currently use but SHOULD evaluate for adoption
+   - **P3 (no action)** — UI/cosmetic fix, internal change, or feature irrelevant to repo
+3. For P2 items: do NOT skip. Flag as "New capability — evaluate for adoption" with brief rationale
+
+Output: structured table with item, classification, affected files, rationale.
+
+### Phase 2 — Research
+
+For items needing enrichment (P1 items with behavioral changes, P2 items with unclear scope):
+
+1. Spawn **parallel research subagents** — one per feature cluster (use a Claude Code documentation-focused agent type when available)
+2. Instruct each subagent to ground every claim in a primary source fetched during the task (official docs URL, changelog entry, or GitHub issue) and to return citations with each claim — treat any uncited subagent claim as unverified and re-verify it against official docs before acting on it.
+
+3. Research targets per item type:
+   - New frontmatter field → exact syntax, interaction with existing fields, docs gap
+   - New hook event → schema, sync/async, input/output shape
+   - New CLI flag → syntax, settings.json equivalent (or lack thereof), valid values
+   - Behavioral change → before/after, migration path, breaking implications
+   - Bug fix → what was broken, what surfaces affected, historical data impact
+
+4. Synthesize research into enriched analysis per item
+
+### Phase 3 — Interview
+
+Present triage table to user via `AskUserQuestion` or structured markdown:
+
+```markdown
+| # | Change | Classification | Affected files | Action needed |
+|---|--------|---------------|----------------|---------------|
+| 1 | <summary> | P1 | <files> | <specific update> |
+| 2 | <summary> | P2 | — | <evaluation + recommendation> |
+| N | <summary> | P3 | — | No action |
+```
+
+User picks scope: "all P1+P2", "just P1", or specific items by number.
+
+Lock brief: confirmed scope becomes implementation contract.
+
+### Phase 4 — Architect
+
+Plan concrete edits with cross-cutting awareness:
+
+1. Group changes by file (multiple items may touch same file)
+2. Identify cross-cutting dependencies (e.g., a new hook event may need updates in every surface that documents hook events — rules, hook scripts, and reference docs alike)
+3. Order edits to avoid conflicts
+4. For each file: specific section to edit, old text to replace, new text
+
+### Phase 5 — Implement
+
+Execute plan:
+
+1. Edit files per architect plan
+2. Run the consumer repo's markdown linter on every touched `.md` file (e.g. `npx markdownlint-cli2`), when one is configured
+3. If hook scripts touched: run their tests with the consumer repo's test runner
+4. If settings.json touched: `jq empty .claude/settings.json`
+
+### Phase 6 — Verify
+
+Run the consumer repo's verification workflow (build/test/lint) on affected ecosystems. At minimum: markdown lint on all touched files.
+
+### Phase 7 — Close issues (optional)
+
+If user approves:
+
+1. If the consumer repo files CC-release tracking issues, search for matching open ones using
+   that repo's own convention (label, title marker, or milestone) via `gh issue list --state open --search '...'`
+2. For each issue whose title matches an implemented changelog item: close with comment citing this session's work
+
+---
+
+## Actions: fetch, diff, status (read-only)
+
+The three read-only actions stop short of any edit — **full steps in [context/read-actions.md](context/read-actions.md)**:
+
+- **`fetch`** — WebFetch + display a version (or latest, or a `v.X..v.Y` range) of `code.claude.com/docs/en/changelog`. No edits
+- **`diff`** — dry run of `apply`: Phase 0 (ingest) + Phase 1 (explore) + Phase 2 (research), stops before interview. Emits the triage table only. Answers "is this release worth an `apply`?"
+- **`status`** — applied versions (`git log --grep`), open routine-pipeline issues (`gh issue list`), current `claude --version`, and the gap if installed > last-applied
+
+---
+
+## Cross-references
+
+- `context/repo-surfaces.md` — surface categories to check per changelog item
+- `context/classification-rubric.md` — P1/P2/P3 classification criteria
+- `context/read-actions.md` — full steps for the read-only actions

plugins/claude-ops/skills/claude-code-changelog/context/classification-rubric.md

@@ -0,0 +1,73 @@
+# Classification rubric for CC changelog items
+
+P1/P2/P3 criteria for triaging Claude Code changelog items.
+
+## Three-tier classification
+
+### P1 — Requires update
+
+Repo already uses this CC feature or surface, and the changelog changes behavior, adds capability, or fixes a bug that affects our configuration/documentation.
+
+**Signals:**
+
+- Grep finds the feature name in repo rules/config (already adopted)
+- Behavioral change to something we depend on (hook event schema, permission engine, frontmatter field)
+- Bug fix for a field we read (hook stdin fields, transcript tokens, cache metrics)
+- Breaking change or deprecation of something we use
+- Existing quirks entry becomes stale (bug fixed upstream)
+- Existing recheck trigger fires
+
+**Action:** Update affected files. Document behavioral change.
+
+### P2 — Worth considering
+
+New capability the repo does NOT currently use but SHOULD evaluate for adoption.
+
+**Signals:**
+
+- New frontmatter field that could enforce existing prose conventions mechanically
+- New hook event enabling observability we currently lack
+- New CLI flag solving a pain point documented in quirks or rate-limit workflow
+- New setting enabling automation we currently do manually
+- Platform improvement making a deferred feature tractable
+
+**Action:** Research capability, evaluate fit, recommend adopt/defer with rationale. Do NOT skip because "we don't use it yet" — that's exactly why it needs evaluation.
+
+### P3 — No action
+
+UI/cosmetic fix, internal refactoring, or feature entirely irrelevant to repo.
+
+**Signals:**
+
+- Purely visual change (spinner text, markdown rendering, table borders)
+- Bug fix for feature we don't use and have no plans to use
+- Platform-specific fix for OS we don't target
+- Internal performance optimization with no user-visible behavior change
+
+**Action:** None. List in summary for completeness.
+
+## Edge cases
+
+| Situation | Classification | Rationale |
+|---|---|---|
+| Bug fix for feature we don't use but MIGHT adopt | P2 | Fix may unblock adoption |
+| New feature behind experimental flag | P2 | Worth tracking even if not adoptable yet |
+| Deprecation of something we don't use | P3 | Unless we planned to adopt it |
+| Security fix | P1 always | Security fixes affect trust posture regardless of direct usage |
+| Model-specific change (e.g., "Opus 4.8 now...") | P1 if we use that model | Check any model-routing/tiering docs the repo keeps |
+| Plugin-system change | P1 if we use plugins | Check `enabledPlugins` in settings.json |
+
+## Item categories
+
+Changelog items fall into categories that predict which surfaces to check:
+
+| Category | Typical surfaces (see `repo-surfaces.md`) | Examples |
+|---|---|---|
+| **Hook/event** | Hook scripts, hook-related rules/docs | New event types, schema changes, reliability fixes |
+| **Skill/frontmatter** | `.claude/skills/**/SKILL.md`, skill-authoring docs | New fields, discovery changes |
+| **Settings/permission** | `.claude/settings*.json`, settings-related docs | New keys, permission engine changes |
+| **CLI** | `CLAUDE.md` CLI references, command cheat-sheets | New flags, command changes |
+| **Model/rate-limit** | Model-routing/usage docs | Pricing, limits, model behavior |
+| **Agent/subagent** | `.claude/agents/*.md`, agent conventions docs | Agent frontmatter, isolation changes |
+| **UI/cosmetic** | (none usually) | Visual fixes, spinner text |
+| **Bug fix** | Depends on affected surface | Fix for reported issue |