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

[kyle-sexton]

No linked issue

Summary

Adds a new maintenance-category coupling plugin with one skill, /coupling:reduce — iterative coupling reduction runnable in any repo at four altitudes (documents, code modules, applications, repositories), grounded in the org's standards-repo review and engineering criteria with the bundled model as portable fallback.

Fix

• plugins/coupling/: plugin manifest (0.1.0), README, CHANGELOG, topic-docs binding (repo-scoped coupling-ledger.md, memory tier, constant-slug delta), and the reduce skill: hub SKILL.md (190 lines) + three reference spokes (coupling model with strength ladder/connascence/volatility weighting, remediation catalog with per-mechanism over-abstraction counterweights, ledger schema with resume semantics) + 3 eval cases including an over-abstraction refusal case.
• Two-lane contract: mechanical behavior-preserving reductions apply under a tidy-style scope budget with build/test verification; cross-file and architectural findings surface and route (never auto-applied), per the detector-findings doctrine that coupling detectors inform a human.
• Registrations: marketplace catalog entry, regenerated docs/CATALOG.md + docs/SKILL-CHEAT-SHEET.md, topic-docs Implementers row, dogfooding enabledPlugins entry.
• Frontmatter verified field-by-field against the live official Claude Code skills frontmatter reference and platform skill-authoring best practices (description 936/1024 chars, body <500 lines, TOC added to the >100-line reference file, references one level deep).

Verification

• check-skill.sh --require-evals reduce: PASS, 0 errors, 0 warnings
• check-evals-quality.sh + evals schema validation: PASS
• check-skill-portability.sh --paths over all four skill files: no unexcused coupling tokens
• validate-plugins.sh (contracts, catalog --check, cheatsheet --check, claude plugin validate --strict): PASS; generator test suite 24/24
• Changelog parity, manifest presence, duplicate-key, markdownlint, typos, editorconfig: clean
• Dogfooded: /coupling:reduce dry-run scripts on this repo produced 8 verified findings and a conforming memory-tier ledger; apply-lane follow-up PR and route-lane tracker item are linked below.

Related

N/A (dogfood follow-ups linked in comments once opened)

🤖 Generated with Claude Code

https://claude.ai/code/session_016CWMh6HAsgWWi9tLw76hZR

---

Generated by Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1ca3fd8685

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kyle-sexton]

All three Codex findings addressed in d80d5f1:

• Clean-target guard (P1): Phase E now requires every target file clean in git status --porcelain before editing; a target carrying pre-existing local modifications defers its finding with the reason recorded, and the staged diff is inspected before each commit.
• Default-branch base (P1): the apply batch's branch is now explicitly created from the resolved default branch (remote HEAD, never an assumed name, never the session's current feature branch).
• One repo-scoped ledger (P2): the slug is now the constant coupling for every run — scoped runs, unscoped runs, and status all resolve the same .work/coupling/coupling-ledger.md, with scope recorded inside the file instead of the path.

---

Generated by Claude Code

[claude]

Claude finished @kyle-sexton's task in 3m 44s —— View job

---

Claude finished the code review

• Gather context (PR body, comments, prior Codex review, changed files)
• Run /review:code-review per instructions
• Post inline findings (if any)
• Final summary

Review scope

Ran the review:code-review lane (code-review/design/conventions/maintainability, security out of scope per REVIEW.md since this repo has no claude-security-review workflow file was not checked as this is a docs/skill-only PR with no runtime code). Read all 14 changed files in full: plugins/coupling/skills/reduce/SKILL.md and its three reference spokes (coupling-model.md, remediations.md, ledger.md), plugins/coupling/reference/topic-docs.md, plugin.json, README.md, CHANGELOG.md, evals/evals.json, and the four registration-file diffs (marketplace catalog, CATALOG.md, SKILL-CHEAT-SHEET.md, docs/conventions/topic-docs/README.md).

I was not able to execute the repo's shell scripts (check-skill.sh, check-evals-quality.sh, validate-plugins.sh, etc.) in this sandbox — script execution required an approval step that isn't available in this lane, so the "PASS" results in the PR body are author-claimed and unverified by me, not independently confirmed.

Findings

None. This is a well-structured addition with no correctness or maintainability issues at the code-review bar.

All three findings from the earlier Codex review are verifiably fixed in d80d5f1, confirmed by reading the current file contents (not just the commit message):

• Default-branch base — SKILL.md Phase E now resolves the repository's default branch explicitly ("remote HEAD or the repo's own convention"), never the session's current feature branch.
• Clean-target guard — SKILL.md Phase E now requires each target clean in git status --porcelain before editing, defers targets with pre-existing local modifications, and inspects the staged diff before each commit.
• One repo-scoped ledger — topic-docs.md and ledger.md now use the constant slug coupling for every run (scoped, unscoped, and status), with scope recorded inside the ledger file rather than the path — matching the argument-hint (status takes no scope argument).

Cross-checked the rest for consistency and found no gaps:

• All cross-plugin references (/toolchain:check, /architecture:improve, /work-items:track add, /source-control:pull-request create, /docs-hygiene:extract-ssot) point to skills that actually exist in this repo, and the composition/fallback table matches the workflow prose.
• Registration entries (marketplace.json, docs/CATALOG.md, docs/SKILL-CHEAT-SHEET.md, docs/conventions/topic-docs/README.md) are consistent with each other and with the plugin's own manifest/README.
• The plugin-root reference/topic-docs.md pattern matches existing precedent (architecture, discovery plugins do the same).
• evals/evals.json conforms to the tracked schema (plugins/skill-quality/reference/evals.schema.json); all three cases carry a valid grading criterion, kebab-case names, and cover the over-abstraction refusal case called out in the PR description.

One pre-existing, out-of-scope observation for the author's awareness only (not a PR defect): the working tree at the reviewed HEAD has an uncommitted local diff removing coupling@melodic-software from .claude/settings.json enabledPlugins — the committed version at 6710240 does include it, so this doesn't affect the PR itself.
· branch claude/reducing-coupling-skill-j8lc99

[claude]

Claude finished @kyle-sexton's task in 1m 53s —— View job

---

🔍 Security review complete

• Gather context (PR diff, changed files, prior Codex review comments)
• Invoke /review:security-review and follow its procedure
• Review skill/reference content for security-relevant issues
• Post findings

Scope: All 14 changed files are new plugin content (skill markdown, reference docs, manifest/CHANGELOG, marketplace/catalog registrations, and one line enabling the plugin in .claude/settings.json). No application code, no GitHub Actions workflow changes, and no secrets/credential handling.

Findings

No security issues found.

This PR is prompt/documentation content that shapes how an agent performs git operations (branch, edit, commit, PR) in a consumer repository. I specifically checked the things that would matter for that kind of skill — unsafe branch basing, mixing in pre-existing local edits, scope creep into sensitive paths, and secret/ledger leakage — and all are handled:

• Default-branch base for the work branch — SKILL.md Phase E explicitly resolves the repo's actual default branch (remote HEAD or the repo's own convention) rather than assuming a name or branching from whatever feature branch the session is on. This closes the Codex P1 finding from the earlier review round.
• Clean-target guard before staging/committing — SKILL.md Phase E requires each target file clean in git status --porcelain before editing, defers targets carrying pre-existing local modifications, and requires inspecting the staged diff before each commit — preventing unrelated/foreign edits from being folded into a commit. This closes the second Codex P1 finding.
• Sensitive-path exclusion is explicit — SKILL.md Phase E hard-excludes CI workflow files, hook/settings surfaces, lint configs, database migrations, and published contract surfaces from the auto-apply lane — those route to a human instead. This is a good containment boundary given the skill can commit and open PRs autonomously.
• One repo-scoped ledger, no fragmentation — reference/topic-docs.md and reference/ledger.md now use a constant coupling slug for scoped runs, unscoped runs, and status, closing the Codex P2 discoverability finding.
• Ledger placement avoids accidental commits — the ledger is written to the memory tier (.work/coupling/coupling-ledger.md), explicitly "never committed," with a self-ignore .gitignore guard verified/created on first write (reference/topic-docs.md). No mechanism writes findings or scan output anywhere that would land in version control unintentionally.
• Pre-computed shell context is static — the ! git commands in the SKILL.md frontmatter (git branch --show-current, git log --oneline -10, git status --porcelain) take no interpolated arguments, so there's no command-injection surface there.
• No workflow/permissions changes — .claude/settings.json only adds "coupling@melodic-software": true to enabledPlugins (dogfooding this plugin, consistent with every other entry in that list); no permission widening, no .github/workflows changes.

Both Codex P1 findings and the P2 finding from the earlier review round are verified fixed at HEAD (6710240), matching the author's changelog comment for commit d80d5f1.
· branch claude/reducing-coupling-skill-j8lc99

[github-actions]

Last security-reviewed head: 6710240adbadf8f84c88509ee77bb9b5ca828c96. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[github-actions]

Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count.