claude-code-plugins

Repository context. Gather first

Collect these with individual Bash calls, one command per call, never combined into a single
invocation:

• Current branch, git branch --show-current
• Recent commits, git log --oneline -20
• Working tree status (empty = clean), git status --porcelain | head -10

The pipe is the bound and belongs in the command. A read-time cap ("read only the first 10 entries")
bounds nothing: the Bash tool returns the command's complete output into context before there is
anything to decide about.

Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as
separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute
block as one shell invocation, and a worktree-isolated session refuses a compound command that
contains git. The dated record for that composition claim is the source-control plugin's
worktree/reference/gather-block.md,
"The pre-compute block runs as one shell invocation".

Variables

Arguments: $ARGUMENTS

Purpose

Improvement is distinct from review and planning. Review evaluates a DIFF against criteria (reactive). Planning designs NEW work (forward-looking). This skill scans EXISTING code for friction and proposes candidates for improvement (proactive).

The scan-present-pick process generalizes across improvement lenses. Each lens (action) brings its own analysis method and vocabulary via an actions/<lens>.md playbook plus a research/<lens>/ reference set, loaded only when that lens runs. The first lens, deepening, implements Ousterhout's deep-module concept: finding shallow modules (interface nearly as complex as implementation) and proposing how to deepen them. The aim is testability and AI/agent-navigability (AX): a deep module's small interface lets a reader, human or agent, grasp its purpose without traversing the whole import graph.

This finds existing friction. It does not plan new work, apply mechanical code-level tidyings, enforce rules on a diff, or review changes before a PR. Those are separate concerns handled by planning, tidying, rule-enforcement, and review tools respectively (see "Composition").

Actions

Argument	Action	What it does
(empty)	Defaults to deepening	Runs the deepening lens
deepening	Deepening (Ousterhout)	Shallow→deep module scan → HTML report → interview loop on each selected candidate (with a Design-It-Twice branch for parallel interface exploration) → hand off the agreed candidates for planning, never implementing them. Full process: actions/deepening.md

One lens per invocation. Lenses don't chain implicitly. Read the action's playbook for its full process.

Adding a lens

A new improvement lens (e.g. coupling, testability, dependency-direction review) is a pure ADD. Never edit an existing lens's contract to add one (open for extension, closed for modification):

• actions/<lens>.md. The lens playbook (phases, gates, output shape)
• research/<lens>/. Reference for that lens, loaded only when its action runs (per-action progressive disclosure)
• one row in the Actions table above, plus one row per new reference file in the reference index below

Reference index. Load on demand

File	Load when
research/deepening/scan-briefing.md	Before briefing the Phase 1 scan subagents. It is the canonical prompt (vocabulary primer, friction checklist, dependency categories, the two badge-acceptance heuristics, per-candidate return schema), so scan quality does not vary run-to-run
research/deepening/vocabulary.md	Applying the deletion test, or naming anything in a candidate, report, or interview turn. The terms are used exactly, not paraphrased
research/deepening/dependencies.md	Classifying a candidate's dependencies, where the category chooses the testing strategy
research/deepening/html-report.md	Writing the HTML report: scaffold, diagram patterns, and the report's two additions to the rendered-views security baseline (which strings are repository-derived, no script inside SVG)
research/deepening/interface-design.md	Entering the Design-It-Twice branch, or a single proposed shape is not converging in the interview loop

What this skill does NOT do

• Does not plan implementation. Produces candidates + agreed shape; a planning step plans the work
• Does not enforce rules. A rule-enforcement reviewer does that reactively on a diff
• Does not apply mechanical tidyings. Code-level tidyings (rename, extract, inline) are a separate, smaller-grained concern
• Does not review a diff. Pre-merge review tools do that
• Does not write code. Discovery and design skill only
• Does not brainstorm a rough problem. This skill hunts architecture friction on its own lenses; open-ended "how could we approach X" divergence is a brainstorming concern
• Does not render another repository's files to HTML until the rendered-views escape helper ships. A scan of a repository that is not the user's own delivers the durable candidate artifact and says in one line why no page was produced (actions/deepening.md, Phase 2)

Composition

Graceful degradation: where a named step below is not available in the consuming project, inline the equivalent work in this session instead of blocking on it.

When	Then	How
A debugging pass finds an architectural root cause	Run this skill's deepening lens	Structured deepening review of the affected module
A candidate shape is agreed	Hand off to a planning skill if the project has one; else summarize the agreed shape for planning	Consumes the agreed-shape entry from the candidate artifact (see actions/deepening.md)
During the interview loop	Maintain resolved project vocabulary	Invoke /domain-driven-design:curate-language via the Skill tool when available in the current session; otherwise update an existing consumer-declared glossary in its own shape
Post-improvement	Review the implemented changes with the project's review tool	Standard diff review

Gotchas

Failure modes this lens runs into, each stated as the rule it implies.

• The durable candidate artifact is a per-project memory-tier file, never ${CLAUDE_PLUGIN_DATA}. Even resolved it points at a plugin-global dir with no project dimension that collides candidates across projects, and uninstalling from the last remaining scope deletes the directory. The documented use is deps/caches/generated code, not per-project artifacts. The artifact resolves through the marketplace topic-docs convention (the plugin's topic-docs binding): memory tier, default .work/<topic-slug>/. A ${CLAUDE_PROJECT_DIR}/.claude/... path is also wrong: .claude/ generated output is reserved for observability, and an unignored artifact there leaks scan output into git.
• Scan-agent claims are shipped only after Phase 1.5 reproduction. Exploration subagents infer from partial reads, so a claim that a service is unused or a call path is dead can be wrong in a way a single grep settles. Any candidate headed for a Strong badge and any runtime-bug / dead-code claim is reproduced against the actual code before it reaches the user-facing report. The report lends every claim its authority, so an unreproduced overstatement is cheap to make and expensive to reputation.