Setup

Purpose

Verify and manage the consuming repo's tracked audit-dimension config at .claude/codebase-health.md so /codebase-health:audit runs deterministically instead of re-inferring targets every run.

The config is optional: with none, the audit re-infers its targets each run, so its absence is a reported INFO, never a FAIL. check inspects the effective merged config read-only; apply interviews and writes it, then re-runs check. No argument or check runs the check; apply runs the check first, then the interview-and-write flow. Idempotent: re-running reads the existing config and offers updates rather than overwriting blind.

The config merge model

The audit config resolves as an additive merge of the documented layers. User-global (~/.claude/codebase-health.md) → team (.claude/codebase-health.md) → local overlay (.claude/codebase-health.local.md), where a later layer's globs union with (not replace) the earlier layer's and example-claims concatenate, except that a later layer declaring a dimension with empty source lists is an explicit opt-out that removes that inherited dimension. This skill writes only the team file; changes to a higher overlay are the user's to make.

check (read-only)

Inspect the effective merged config and report a PASS/FAIL/INFO table with one remediation line per FAIL. Modify nothing, and do NOT run an audit. That is /codebase-health:audit.

1. Config presence (effective, across layers). Load every layer you can access and report the effective merged result honoring opt-outs (dimensions present, glob counts, example-claim counts), and which layer contributes what. No layer readable and no team file → INFO: the audit re-infers targets each run; apply writes .claude/codebase-health.md to make the run deterministic. When a higher layer (a user-global base outside the repo) cannot be read, WARN it was not considered rather than presenting the team file alone as the effective config.
2. Dimension source lists. For each dimension present in the team file, its declared source lists parse and name real paths/globs. A dimension whose source list is malformed or fails to parse is FAIL, naming it. A dimension deliberately zeroed (empty source lists) by an overlay is INFO (an opt-out), reported as removed, not broken.
3. Tracked, not ignored, a present team file must be committed to be team-shared: run git check-ignore -v .claude/codebase-health.md; a non-empty result is FAIL with the matching pattern. The .local.md overlay is expected to be ignored. INFO, not FAIL.
4. Overlay divergence. INFO: when a local or user-global overlay changes the team file's effect (adds globs, or opts a dimension out with empty source lists), say so explicitly, since apply writes only the team file.

apply (idempotent)

Run check, then interview and write the config. Proceed non-interactively where the invocation and the repo make the values unambiguous; ask only where a dimension's targets genuinely need the user.

1. Start from the effective config check just reported. This step writes only the team file, so name what a higher overlay contributes. When a local or user-global opt-out zeroes a dimension, a team-scope re-enable will not restore it on this machine, because the overlay keeps removing it; prompt the user to remove or update the opt-out in that overlay too. The interview proposes changes against that baseline, and nothing is dropped without the user confirming.
2. Explore the repo to draft defaults. Before asking anything, infer candidates:
   • documentation primary-sources: doc directories (docs/, README.md), agent-instruction files (AGENTS.md, CLAUDE.md), ADR directories, convention docs.
   • configuration primary-sources: build config, lint config, CI workflows, git-hook config, detected from what actually exists (e.g. Directory.Build.props, pyproject.toml, package.json, .github/workflows/, lefthook.yml, .editorconfig).
   • code-quality primary-sources: source roots; verification-sources: test roots plus the same source roots, a cross-file DRY/SOLID claim is validated by reading peer source files, which a discovery agent can only read when they are in verification-sources (the fence forbids the other primary-source files). Omitting them makes cross-file findings unreachable.
   • architecture primary-sources: dependency manifests + architecture docs; verification-sources: analyzers / architecture tests where present plus the dependency manifests and source roots. Dependency-direction and boundary claims need peer manifests readable, for the same fence reason.
3. Interview, one decision at a time. Present each dimension's drafted globs with a recommendation; let the user accept, edit, or remove the dimension. Offer custom dimensions last ("anything else this repo should audit as its own lane?").
4. Draft example-claims. For each accepted dimension, read one or two representative primary-source files and propose 2–4 concrete { claim, verify-via } rows drawn from real sentences in them. Concrete rows teach the discovery pass what drift looks like in THIS repo, the highest-value part of the config. The user approves or edits each row.
5. Write the config. Materialize .claude/codebase-health.md following the structure in ${CLAUDE_PLUGIN_ROOT}/skills/setup/templates/config-template.md (replace every placeholder comment with real values; drop unused placeholder rows).
6. Verify after remediation. Re-run the check probes on the written file. Dimension source lists parse and name real paths, and both halves of the tracked-file pair hold: git check-ignore -v .claude/codebase-health.md reports no match (a match is FAIL; surface the pattern and offer to fix .gitignore before reporting success) AND git ls-files --error-unmatch .claude/codebase-health.md exits 0 (non-zero means un-ignored but still untracked, the guaranteed state right after a fresh write, so report "written but untracked: commit it to share with the team", never success). Then offer the overlay convention: personal overrides go in .claude/codebase-health.local.md; recommend the consumer add the recursive .claude/**/*.local.* line to .gitignore if not already covered. A user-global base at ~/.claude/codebase-health.md is also honored. Layers resolve user-global → team → local overlay, additively.

Re-running apply after everything passes changes nothing and reports "already configured".

Output

A tracked .claude/codebase-health.md in the consuming repo, plus a one-paragraph summary of what was written and how to re-run this setup to reconfigure.

What this skill does NOT do

• Run an audit. That is /codebase-health:audit. check only inspects config.
• Write machine-local state. Configuration lives in the consumer's tracked file, never in the plugin directory or the plugin data directory.