feat(coupling): add coupling plugin with /coupling:reduce skill

.claude-plugin/marketplace.json

@@ -262,6 +262,12 @@
       "category": "maintenance",
       "tags": ["tidy", "refactoring", "simplify", "boy-scout", "comments", "maintenance", "skill"]
     },
+    {
+      "name": "coupling",
+      "source": "./plugins/coupling",
+      "category": "maintenance",
+      "tags": ["coupling", "cohesion", "decouple", "connascence", "dependency-injection", "refactoring", "skill"]
+    },
     {
       "name": "session-flow",
       "source": "./plugins/session-flow",

.claude/settings.json

@@ -38,6 +38,7 @@
     "computer-use@melodic-software": true,
     "context-guard@melodic-software": true,
     "context7@melodic-software": true,
+    "coupling@melodic-software": true,
     "debugging@melodic-software": true,
     "desktop-notification@melodic-software": true,
     "discipline@melodic-software": true,

docs/CATALOG.md

@@ -67,6 +67,7 @@ plugin manifests and kept in sync by CI — never hand-edit it; the category voc
 - [`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?), and audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects).
 - [`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 recently changed files 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 — 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.
+- [`coupling`](../plugins/coupling) — Iteratively reduces coupling in any repository at any altitude — documents, code modules, applications, or repositories: scans for change-transmitting dependencies typed against a coupling model (strength ladder, connascence, volatility weighting), verifies every finding, applies a budgeted batch of safe behavior-preserving reductions, and keeps a durable ledger so structural candidates route to design lanes and repeated runs continue where the last stopped.
 - [`repo-hygiene`](../plugins/repo-hygiene) — Repo hygiene action-router: /repo-hygiene:clean sweeps reclaimable caches, build artifacts, and stale git metadata, and can realign the working tree to a fresh-pull state — dry-run-first, with destructive tiers gated behind explicit confirmation and a session-scoped destructive-command guard. Ecosystem targets are detected at runtime; secrets, runtime dependencies, and skill data are preserved by default.
 - [`repo-fleet-hygiene`](../plugins/repo-fleet-hygiene) — Cross-repository Git/GitHub fleet discovery, evidence rollup, and a gated apply verb that executes a prior fleet action plan behind one confirmation. Audit stays read-only and confidence-tiered; apply mutates only with --apply plus interactive confirmation or --yes.
 - [`disk-hygiene`](../plugins/disk-hygiene) — Context-aware disk hygiene for arbitrary directory trees: inventories orphaned and temporary artifacts, classifies evidence into review tiers, and offers exact-path cleanup only after a fresh safety preview and explicit per-tier approval. The target is read-only by default; OS-managed paths, links and mount points, VCS-tracked content without the complete checkout evidence bundle, changed entries, and live-handle uncertainty fail closed.

docs/SKILL-CHEAT-SHEET.md

@@ -157,6 +157,7 @@ owned by [docs/CATALOG-TAXONOMY.md](CATALOG-TAXONOMY.md).
 | [`/code-tidying:tidy`](../plugins/code-tidying/skills/tidy/SKILL.md) | `code-tidying` | Proactively hunt one lane for safe structural tidyings and ship a structure-only PR |
 | [`/codebase-health:audit`](../plugins/codebase-health/skills/audit/SKILL.md) | `codebase-health` | Audit for drift between docs, config, code, and architecture via verified findings |
 | [`/computer-use:diagnose`](../plugins/computer-use/skills/diagnose/SKILL.md) | `computer-use` | Resolve computer-use capture, input, and screenshot symptoms to a cause |
+| [`/coupling:reduce`](../plugins/coupling/skills/reduce/SKILL.md) | `coupling` | Scan for change-transmitting coupling, apply safe reductions in a budgeted batch, route the rest |
 | [`/discipline:do-your-research`](../plugins/discipline/skills/do-your-research/SKILL.md) | `discipline` | Re-anchor research discipline, then audit and correct the current work |
 | [`/discipline:do-your-research-deep`](../plugins/discipline/skills/do-your-research-deep/SKILL.md) | `discipline` | Verify every session claim against primary sources in a heavy fan-out |
 | [`/discipline:follow-our-standards`](../plugins/discipline/skills/follow-our-standards/SKILL.md) | `discipline` | Re-anchor to org engineering standards and audit the work in flight |

docs/conventions/topic-docs/README.md

@@ -559,6 +559,7 @@ relationship to the contract is fully stated by their table row.
 | adhd | rendered decision-table HTML view | ephemeral | by reference — the ephemeral row's five rules are its entire relationship |
 | discovery | `EXPLORE.md`, `RESEARCH.md` | memory | delta doc |
 | architecture | `deepening-candidates-<timestamp>.md` (per-lens candidate ledgers); deepening HTML report | memory + ephemeral | delta doc |
+| coupling | `coupling-ledger.md` (repo-scoped finding ledger, updated in place; constant-slug delta) | memory | delta doc |
 | planning | `PRD.md`, `PLAN.md` (Brief), `design/`, opt-in brainstorm persist; five optional rendered HTML views (dense-round decision table, PRD pitch, brainstorm reaction page, plan view, design topology) | contract + memory + ephemeral | delta doc |
 | implementation | `PLAN.md` (Plan/progress), `DEVIATIONS.md`, status summaries | contract + memory | delta doc |
 | verification | `verification/` manifest; baselines, raw captures | contract + memory | delta doc |

plugins/coupling/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "coupling",
+  "version": "0.1.0",
+  "description": "Iteratively reduces coupling in any repository at any altitude — documents, code modules, applications, or repositories: scans for change-transmitting dependencies typed against a coupling model (strength ladder, connascence, volatility weighting), verifies every finding, applies a budgeted batch of safe behavior-preserving reductions, and keeps a durable ledger so structural candidates route to design lanes and repeated runs continue where the last stopped.",
+  "author": {
+    "name": "Melodic Software",
+    "email": "info@melodicsoftware.com"
+  },
+  "license": "MIT",
+  "keywords": [
+    "coupling",
+    "cohesion",
+    "decouple",
+    "connascence",
+    "dependency-injection",
+    "refactoring",
+    "skill"
+  ]
+}

plugins/coupling/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to the `coupling` plugin are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
+
+## [0.1.0]
+
+### Added
+
+- `reduce` skill: iterative coupling reduction at four altitudes (docs, code, application,
+  repository) — model-typed scan with a verification gate, two-lane partition (safe
+  behavior-preserving reductions applied under a scope budget; cross-file and architectural
+  candidates surfaced and routed, never auto-applied), and a durable per-repo ledger via the
+  topic-docs memory tier so successive runs resume instead of restarting.
+- `reference/coupling-model.md`: the assessment model — change-centric coupling definition,
+  structured-design strength ladder, connascence (strength × degree × locality), volatility
+  weighting, per-altitude mechanisms, and the not-a-finding list.
+- `reference/remediations.md`: mechanism catalog (dependency injection, owned interfaces at
+  volatile boundaries, configuration externalization, events/mediator, single-source-of-truth
+  pointers, published contracts) with an explicit over-abstraction counterweight per entry.
+- Topic-docs binding (`reference/topic-docs.md`) for the repo-scoped coupling ledger.

plugins/coupling/README.md

@@ -0,0 +1,64 @@
+# coupling
+
+A Claude Code plugin for iteratively reducing coupling — in any repository, at any altitude.
+One skill, one standing question: which dependency here transmits the most unnecessary
+change, and what is the smallest mechanism that stops the transmission? Each run takes one
+verified, budgeted bite and records the rest, so coupling goes down monotonically across
+runs instead of one heroic rewrite.
+
+| Skill | What it does |
+|---|---|
+| `/coupling:reduce` | Scan for change-transmitting coupling, verify findings, apply a safe budgeted batch, route structural candidates, and resume from a durable ledger |
+
+## The model
+
+Findings are typed, not vibes-based: every one is a directed edge
+(`A --(kind, via mechanism)--> B`) classified on the structured-design strength ladder
+(content, common, external, control, stamp, data, message) and the connascence axes
+(strength × degree × locality), then weighted by volatility — coupling to something that
+never changes costs nothing, so co-change evidence from version-control history outranks
+static impressions. The same model covers four altitudes: documents (duplicated facts, deep
+references), code modules (internals reaching, dependency direction), applications (shared
+databases, implicit contracts, temporal coupling), and repositories (copied content,
+depending on another repo's internals instead of its releases).
+
+Two lanes keep the skill honest:
+
+- **Apply lane** — mechanical, contained, behavior-preserving reductions, applied under a
+  scope budget and verified against the project's own build and tests.
+- **Route lane** — cross-file and architectural findings are surfaced and routed to humans
+  and design tooling, never auto-applied.
+
+The remediation catalog carries an explicit counterweight per mechanism: decoupling's own
+failure mode is speculative abstraction — an interface with one implementation, an event bus
+for a one-to-one call — and the skill is built to refuse it.
+
+```shell
+/coupling:reduce                 # full pass over an inferred scope
+/coupling:reduce src/billing     # narrowed to a path
+/coupling:reduce dry-run docs    # findings and ledger only, no edits
+/coupling:reduce status          # what is open, applied, routed, and recommended next
+```
+
+## Consumer conventions
+
+- **Your standards win.** At orientation the skill discovers the consuming repo's own
+  review criteria and engineering conventions (a review-criteria file, a conventions or
+  standards directory, CLAUDE.md rules) and aligns finding vocabulary and severity with
+  them; the bundled model is the fallback, never an override.
+- **Ledger placement** follows the marketplace topic-docs convention — memory tier, default
+  `.work/<topic-slug>/coupling-ledger.md`, never committed. Deltas in
+  [`reference/topic-docs.md`](reference/topic-docs.md).
+- **Optional collaborators** (`architecture`, `work-items`, `toolchain`, `source-control`,
+  `docs-hygiene`) are presence-gated with documented fallbacks; the skill works alone.
+
+## Install
+
+```shell
+/plugin marketplace add melodic-software/claude-code-plugins
+/plugin install coupling@melodic-software
+```
+
+## License
+
+MIT

plugins/coupling/reference/topic-docs.md

@@ -0,0 +1,40 @@
+# Topic-docs placement — where coupling artifacts land
+
+How the `reduce` skill resolves the destination for its coupling ledger.
+
+Implements the topic-docs convention:
+<https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/topic-docs/README.md#runtime-guards>.
+The contract owns every general rule — tiers, schema, resolution order, slug spec, runtime
+guards, no-project-root fallback, non-interactive/forked mode. This document records only
+this plugin's deltas.
+
+## What this plugin writes, per tier
+
+| Artifact (writer) | Tier | Location (default) |
+|---|---|---|
+| `coupling-ledger.md` (`/coupling:reduce`) | Memory | `.work/<topic-slug>/` — never committed |
+
+Memory tier because the placement questions resolve there: nothing downstream enforces
+against the ledger, and it is read again — by the producer itself on the next run (resume is
+the skill's whole iteration model) and by the user checking `status` — with that reader
+scoped to this checkout. The ledger is a single file updated in place, not a timestamped
+file per run: statuses inside it, not filenames, carry run-to-run history.
+
+## Slug derivation
+
+Delta from the contract's precedence: the slug is the constant `coupling`, always — scoped
+and unscoped runs, and the `status` action, all resolve the same slice. Neither the
+explicit-argument rung nor the branch-name rung is used: coupling reduction is repo-scoped
+and spans many scopes and short-lived branches, and a scope- or branch-derived slug would
+fragment the one ledger successive runs must resume (a `status` call could then never find a
+scoped run's backlog). A run's scope is recorded inside the ledger — in the file header and
+per entry — not in the path. Form and collision rules are the contract's.
+
+## Guards
+
+The memory root's self-ignore guard applies on first write (verify-or-create `.gitignore`
+with `*`, announced). The contract also defines **invalid roots at which the guard does not
+run**; they are enumerated in its
+[Runtime guards](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/topic-docs/README.md#runtime-guards)
+section and deliberately not listed here, so this binding cannot drift from them. Create the
+topic slice directory when absent.