|
1 | 1 | # CLAUDE.md |
2 | 2 |
|
3 | | -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 3 | +Guidance for Claude Code when modifying this repository. For repo layout, install steps, and user-facing usage, see `README.md` — this file covers only what's needed to safely *change* the repo. |
4 | 4 |
|
5 | 5 | ## What This Repo Is |
6 | 6 |
|
7 | | -**brooks-lint** is a Claude Code Plugin for code quality diagnosis using principles from twelve classic software engineering books. It surfaces decay risks across five review modes (PR Review, Architecture Audit, Tech Debt Assessment, Test Quality Review, Health Dashboard). Each mode is an independent skill under `skills/` — installed and used by Claude Code. |
| 7 | +**brooks-lint** is a Claude Code Plugin for code-quality diagnosis grounded in twelve classic software engineering books. Five independent skills under `skills/` (PR Review, Architecture Audit, Tech Debt, Test Quality, Health Dashboard) each produce findings in the Iron Law form: **Symptom → Source → Consequence → Remedy**. |
8 | 8 |
|
9 | | -## Install |
| 9 | +## Workflow Conventions |
10 | 10 |
|
11 | | -```bash |
12 | | -# Via plugin marketplace (recommended) |
13 | | -/plugin marketplace add hyhmrright/brooks-lint |
14 | | -/plugin install brooks-lint@brooks-lint-marketplace |
15 | | - |
16 | | -# Manual |
17 | | -cp -r skills/ ~/.claude/skills/brooks-lint |
18 | | - |
19 | | -# Short-form commands (/brooks-review) are auto-installed by the session-start hook. |
20 | | -# To install manually: cp commands/*.md ~/.claude/commands/ |
21 | | -``` |
22 | | - |
23 | | -## Architecture |
24 | | - |
25 | | -### Structure |
26 | | - |
27 | | -``` |
28 | | -brooks-lint/ |
29 | | -├── .claude-plugin/ # Claude Code plugin metadata |
30 | | -├── .codex-plugin/ # Codex CLI plugin metadata |
31 | | -├── skills/ |
32 | | -│ ├── _shared/ # Shared framework files |
33 | | -│ │ ├── common.md # Iron Law, Project Config, Report Template, Health Score |
34 | | -│ │ ├── source-coverage.md # 12-book coverage matrix + false-positive guards |
35 | | -│ │ ├── decay-risks.md # Six decay risk definitions with symptoms + sources |
36 | | -│ │ ├── test-decay-risks.md # Six test-space decay risks |
37 | | -│ │ ├── remedy-guide.md # --fix mode: actionable Remedy enhancement rules |
38 | | -│ │ └── custom-risks-guide.md # Template for project-specific risk codes |
39 | | -│ ├── brooks-review/ # Mode 1: PR Review |
40 | | -│ │ ├── SKILL.md # Skill entry point |
41 | | -│ │ └── pr-review-guide.md |
42 | | -│ ├── brooks-audit/ # Mode 2: Architecture Audit |
43 | | -│ │ ├── SKILL.md |
44 | | -│ │ └── architecture-guide.md |
45 | | -│ ├── brooks-debt/ # Mode 3: Tech Debt Assessment |
46 | | -│ │ ├── SKILL.md |
47 | | -│ │ └── debt-guide.md |
48 | | -│ ├── brooks-test/ # Mode 4: Test Quality Review |
49 | | -│ │ ├── SKILL.md |
50 | | -│ │ └── test-guide.md |
51 | | -│ └── brooks-health/ # Mode 5: Health Dashboard |
52 | | -│ ├── SKILL.md |
53 | | -│ └── health-guide.md |
54 | | -├── hooks/ # SessionStart hook for session-level awareness |
55 | | -├── commands/ # Short-form command wrappers (auto-installed by hook, or manual copy) |
56 | | -├── evals/ # Benchmark suite (49 scenarios across 5 modes) |
57 | | -├── scripts/ # Repo tooling |
58 | | -│ ├── validate-repo.mjs # Consistency CI gate (versions, descriptions, skills content) |
59 | | -│ ├── frontmatter.mjs # Shared parseFrontmatterBooks() utility |
60 | | -│ ├── run-evals.mjs # Eval structural validator (IDs, fields, risk code refs) |
61 | | -│ ├── run-evals-live.mjs # Live eval runner (calls AI, classifies pass/partial/fail) |
62 | | -│ ├── assemble-prompt.mjs # Builds full skill prompt from SKILL.md + shared files |
63 | | -│ ├── ci-review.mjs # CI integration for PR review workflow |
64 | | -│ ├── cli-utils.mjs # Shared CLI utilities (arg parsing, output formatting) |
65 | | -│ ├── history.mjs # Health Score trend tracking (.brooks-lint-history.json) |
66 | | -│ └── validate-repo.test.mjs # Unit tests for parseFrontmatterBooks |
67 | | -├── docs/gallery.md # Visual output examples (used for README/promotion) |
68 | | -├── AGENTS.md # Codex CLI project instructions |
69 | | -├── GEMINI.md # Gemini CLI project instructions |
70 | | -└── gemini-extension.json # Gemini CLI extension manifest |
71 | | -``` |
| 11 | +- **Direct-to-main workflow:** Pushes go to `main` without a PR. After Edit/Write, the global rule's `simplify` + `pr-review-toolkit:code-reviewer` reviews still run before commit; only the optional PR-only `code-review:code-review` step is skipped. |
| 12 | +- **Doc sources of truth:** `package.json` is canonical for version; book inventory is canonical in `skills/_shared/source-coverage.md` (see Gotchas for derivation). README.md, AGENTS.md, GEMINI.md, and CHANGELOG.md must stay in sync — `npm run validate` enforces this. |
| 13 | +- **VS Code extension is OUT OF SCOPE.** Do not plan, propose, or reference VS Code extension features. |
72 | 14 |
|
73 | | -### How the skills work |
| 15 | +## Critical Gotchas |
74 | 16 |
|
75 | | -1. `hooks/session-start` injects a brief note into every session listing the five available skills |
76 | | -2. When triggered, Claude loads the appropriate skill's `SKILL.md` via the Skill tool |
77 | | -3. Each SKILL.md instructs Claude to read `_shared/common.md` for the Iron Law, Config, and Report Template |
78 | | -4. Claude reads the mode-specific guide and the relevant decay-risks file from `_shared/` |
79 | | -5. Each finding follows the Iron Law: Symptom → Source → Consequence → Remedy |
80 | | -6. Output follows the standard report template with Health Score (base 100, deductions per finding) |
| 17 | +- **Skill sync after edit:** `skills/` (this repo) and the installed copy (`~/.claude/plugins/cache/.../skills/` or `~/.claude/skills/brooks-lint/`) are independent. For local testing of unsubmitted edits: `cp -r skills/* ~/.claude/skills/brooks-lint/`. To refresh the marketplace install after pushing: `/plugin marketplace update` then `/plugin install brooks-lint@brooks-lint-marketplace`. |
| 18 | +- **`_shared/` is not a skill:** It holds shared framework files (Iron Law, Report Template, decay-risk definitions). Skills must explicitly read these via the Read tool — they are NOT auto-loaded. Claude Code ignores directories without `SKILL.md`. |
| 19 | +- **Step numbering alignment:** Convention — every `SKILL.md` Process section must mirror its guide's step count and numbering. `npm run validate` only enforces guide step continuity (no gaps, no duplicates, sequential main steps) and SKILL.md Process-section presence; count parity is on the author. When adding a step to a guide, manually update the SKILL.md Process list. |
| 20 | +- **SKILL.md trigger descriptions:** Every `description:` field MUST include a "Do NOT trigger for:" clause. Without it, false triggering occurs (e.g. `brooks-debt` firing on HTTP `/health` questions). |
| 21 | +- **Book count is derived, never hardcoded:** `validate-repo.mjs` reads `source-coverage.md` frontmatter and derives `sourceCount` from it. Adding a book = update the frontmatter list + add the corresponding section; the validator auto-adapts. |
| 22 | +- **`package.json` is ESM:** `"type": "module"` enables ESM for everything in `scripts/`. Skills are plain markdown — no bundling. |
| 23 | +- **Slash commands:** Plugin skills register as `/brooks-lint:brooks-review`. Short forms (`/brooks-review`) are auto-installed to `~/.claude/commands/` by the session-start hook — they are thin wrappers, not separate definitions. |
| 24 | +- **GitHub Action cache:** `.github/actions/brooks-lint/action.yml` uses `actions/cache@v4` with built-in cache-hit guard — do NOT add a manual directory check. |
| 25 | +- **Custom risks:** Teams add project-specific risk codes via `custom-risks-guide.md` in their project root. Template lives at `skills/_shared/custom-risks-guide.md`. |
81 | 26 |
|
82 | | -### Project Config (`.brooks-lint.yaml`) |
| 27 | +## How the Skills Work |
83 | 28 |
|
84 | | -Teams can place a `.brooks-lint.yaml` in their project root to customize review behavior: |
85 | | -- `disable` — skip specific risk codes (e.g. `T3` for projects without coverage requirements) |
86 | | -- `severity` — override severity tier for a risk (e.g. downgrade `R1` to `suggestion`) |
87 | | -- `ignore` — glob patterns for files to exclude (e.g. `**/vendor/**`) |
88 | | -- `focus` — evaluate only listed risks |
89 | | - |
90 | | -Copy `.brooks-lint.example.yaml` from this repo as a starting template. |
91 | | - |
92 | | -## Multi-Platform Support |
93 | | - |
94 | | -brooks-lint runs on three AI coding platforms: Claude Code, Codex CLI, and Gemini CLI. Each has its own plugin manifest and project instructions file (see Structure above). `package.json` is the canonical version source; manifests and docs must stay in sync with it. |
| 29 | +1. `hooks/session-start` injects a brief skill list into every session |
| 30 | +2. Triggered skill loads its `SKILL.md` via the Skill tool |
| 31 | +3. `SKILL.md` instructs Claude to read `_shared/common.md` (Iron Law, Config, Report Template) |
| 32 | +4. Claude reads the mode-specific guide + relevant decay-risks file |
| 33 | +5. Findings follow the Iron Law: **Symptom → Source → Consequence → Remedy** |
| 34 | +6. Output uses the standard report template with Health Score (base 100; deductions per finding, floor 0) |
95 | 35 |
|
96 | 36 | ## Eval Suite |
97 | 37 |
|
98 | | -`evals/evals.json` contains 49 benchmark scenarios covering R1-R6 (code decay) and T1-T6 (test decay), including false-positive / tradeoff cases that must NOT be flagged. Each scenario is a JSON object with input context and expected findings. To add a scenario, append to the `evals` array with the next sequential `id` and the relevant risk code. Each eval has `id`, `name`, `prompt`, `expected_output`, `mode`, and `files` fields. Optional flags: `no_risk_codes: true` (false-positive scenarios where no risk codes should appear in output), `no_health_score: true` (scenarios testing Health Score suppression) — these two flags are mutually exclusive. |
| 38 | +`evals/evals.json` contains 49 benchmark scenarios covering R1–R6 (code decay) and T1–T6 (test decay), including false-positive / tradeoff cases that must NOT be flagged. Each scenario has `id`, `name`, `prompt`, `expected_output`, `mode`, `files`. Optional flags (mutually exclusive): `no_risk_codes: true` (no risk codes expected in output) or `no_health_score: true` (Health Score suppression test). |
99 | 39 |
|
100 | | -`scripts/run-evals.mjs` validates the structural integrity of evals.json (sequential IDs, required fields, risk code references) — run it with `npm run evals`. `scripts/run-evals-live.mjs` runs the skill against each scenario and classifies output as pass/partial/fail — requires `ANTHROPIC_API_KEY`. |
| 40 | +To add a scenario: append to the `evals` array with the next sequential `id` and the relevant risk code. Validate structure with `npm run evals`; live-test with `npm run evals:live` (requires `ANTHROPIC_API_KEY`). |
101 | 41 |
|
102 | 42 | ## Development Commands |
103 | 43 |
|
104 | 44 | ```bash |
105 | | -# Validate repo consistency (manifests, README, changelog, source inventory, skills structure) |
106 | | -npm run validate # or: node scripts/validate-repo.mjs |
107 | | - |
108 | | -# Unit tests for validate-repo.mjs helper functions |
109 | | -npm test # or: node scripts/validate-repo.test.mjs |
110 | | - |
111 | | -# Validate eval suite structural integrity (IDs, required fields, risk code refs) |
112 | | -npm run evals # or: node scripts/run-evals.mjs |
| 45 | +npm run validate # Repo consistency: manifests, README badge, changelog, source inventory, skills structure |
| 46 | +npm test # Unit tests for validate-repo helpers |
| 47 | +npm run evals # Eval structural validation (IDs, fields, risk-code refs) |
| 48 | +npm run evals:live # Live evals against the AI (requires ANTHROPIC_API_KEY) |
| 49 | +npm run history # View Health Score trend (.brooks-lint-history.json) |
113 | 50 |
|
114 | 51 | # Test hooks locally |
115 | 52 | bash hooks/session-start # local branch |
116 | 53 | CLAUDE_PLUGIN_ROOT=1 bash hooks/session-start # plugin platform branch |
117 | | - |
118 | | -# Run the skills in Claude Code (short form auto-installed by session-start hook) |
119 | | -/brooks-review # Short form (or /brooks-lint:brooks-review) |
120 | | -/brooks-audit # Short form (or /brooks-lint:brooks-audit) |
121 | | -/brooks-debt # Short form (or /brooks-lint:brooks-debt) |
122 | | -/brooks-test # Short form (or /brooks-lint:brooks-test) |
123 | | -/brooks-health # Short form (or /brooks-lint:brooks-health) |
124 | | - |
125 | | -# Run live evals against the AI (requires ANTHROPIC_API_KEY) |
126 | | -npm run evals:live # or: node scripts/run-evals-live.mjs |
127 | | - |
128 | | -# View Health Score trend history (.brooks-lint-history.json) |
129 | | -npm run history # or: node scripts/history.mjs |
130 | 54 | ``` |
131 | 55 |
|
132 | | -After editing skills, reinstall to sync the marketplace copy (see Install section above). |
133 | | - |
134 | 56 | ## Release Process |
135 | 57 |
|
136 | | -1. Bump version in `package.json` |
137 | | -2. Add `## [X.Y.Z] - YYYY-MM-DD` section to `CHANGELOG.md` |
138 | | -3. `npm run validate` — confirms all manifests, README badge, and changelog are in sync |
139 | | -4. Commit, push, create GitHub release tag |
140 | | - |
141 | | -`validate-repo.mjs` will catch any version drift between `package.json`, manifests, |
142 | | -and the changelog before you push. |
143 | | - |
144 | | -## Development Gotchas |
145 | | - |
146 | | -- **Skill sync:** `skills/` and the marketplace install path (`~/.claude/plugins/...`) are two independent copies — reinstall manually after edits. |
147 | | -- **package.json:** `"type": "module"` enables ESM for all scripts in `scripts/`. Skills themselves are plain markdown — no bundling needed. |
148 | | -- **Slash commands:** Plugin skills register as namespaced commands (`/brooks-lint:brooks-review`). Short-form commands (`/brooks-review`) are auto-installed to `~/.claude/commands/` by the session-start hook. These are thin wrappers that delegate to the plugin skills. |
149 | | -- **`_shared/` convention:** `skills/_shared/` holds common framework files (Iron Law, Report Template, decay risk definitions). It is NOT a skill directory — Claude Code ignores directories without `SKILL.md` when registering commands. |
150 | | -- **Version sync:** `package.json` is the canonical version source. `hooks/session-start` reads it dynamically; `validate-repo.mjs` checks all manifests, the README badge, and the changelog for drift. |
151 | | -- **Book count source of truth:** `skills/_shared/source-coverage.md` frontmatter (`books:` list) is the canonical book inventory. `validate-repo.mjs` derives `sourceCount` and all word-based checks from it — do NOT hardcode the count elsewhere. To add a book: update the frontmatter list and add the corresponding section; the validator auto-adapts. |
152 | | -- **Step numbering alignment:** Each skill's `SKILL.md` Process section must list steps that match the guide's step count and numbering. Automated: `npm run validate` checks guide step continuity (no gaps, no duplicates, sequential main steps) and SKILL.md Process section presence. When adding a step to a guide, update the corresponding SKILL.md Process list too. |
153 | | -- **SKILL.md trigger descriptions:** Every `description:` field must include a "Do NOT trigger for:" clause that defines the negative boundary. This prevents false triggering (e.g., `brooks-debt` firing on HTTP health-check questions). |
154 | | -- **GitHub Action:** `.github/actions/brooks-lint/action.yml` provides a reusable action for CI workflows. Deps are cached via `actions/cache@v4` with cache-hit guard — do not add a manual directory check. |
155 | | -- **Custom risks:** Teams can add project-specific risk codes by placing a `custom-risks-guide.md` in their project root. See `skills/_shared/custom-risks-guide.md` for the template. |
156 | | -- **VS Code Extension:** out of scope — do not plan, reference, or propose VS Code extension features. |
| 58 | +Bump `package.json` version → add `## [X.Y.Z] - YYYY-MM-DD` to `CHANGELOG.md` → `npm run validate` (catches drift across manifests, README badge, changelog) → commit, push, tag GitHub release. |
0 commit comments