csh
/
playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
playbook/brooks-lint/GEMINI.md

4.0 KiB
Raw Blame History

GEMINI.md

This repository is an AI-powered code quality tool grounded in twelve classic engineering books (e.g., The Mythical Man-Month, Code Complete, A Philosophy of Software Design, Software Engineering at Google).

Core Purpose

brooks-lint is a Gemini CLI extension used to diagnose code quality across six "decay risk" dimensions: Cognitive Overload, Change Propagation, Knowledge Duplication, Accidental Complexity, Dependency Disorder, and Domain Model Distortion.

Skill Integration

  • Auto-trigger: You must proactively activate the appropriate skill whenever discussing code quality, PR reviews, architecture health, test quality, or technical debt.
  • Command Mapping:
    • /brooks-review: PR Review (loads skills/brooks-review/)
    • /brooks-audit: Architecture Audit (loads skills/brooks-audit/)
    • /brooks-debt: Tech Debt Assessment (loads skills/brooks-debt/)
    • /brooks-test: Test Quality Review (loads skills/brooks-test/)
    • /brooks-health: Health Dashboard (loads skills/brooks-health/)
    • /brooks-sweep: Full Sweep & Auto-Fix (loads skills/brooks-sweep/)
  • After activation (CRITICAL): Once a skill is activated via slash command, you MUST immediately read the skill's SKILL.md and follow every step in its Setup and Process sections — do NOT wait for additional user input. Treat the slash command as the trigger to start the review right away.

Engineering Standards

  • Language: Repo source and configuration stay in English for international consistency. Review output follows the user's language — see the "Language rule" in skills/_shared/common.md (Iron Law field labels, book titles, and smell names stay in English even when the prose is translated).
  • The Iron Law: NEVER suggest fixes before completing risk diagnosis. Every finding MUST follow: Symptom → Source → Consequence → Remedy.
  • Scoring System: Base score 100. Deductions: 🔴 Critical (−15), 🟡 Warning (−5), 🟢 Suggestion (−1). Floor is 0.
  • Project Config: If a .brooks-lint.yaml exists in the project root, read and apply it before running any review mode.
  • SKILL.md Process vs guide steps: SKILL.md Process is a high-level skeleton (3–6 items) that cites guide Step ranges inline (e.g. Scan decay risks (Steps 1–7 of the guide)); the guide owns the detailed numbered steps. Counts do NOT need to match 1:1. Automated: npm run validate checks guide step continuity (sub-steps like 2a/6b allowed) and SKILL.md Process-section presence.
  • Trigger descriptions: Every SKILL.md description: field must include a "Do NOT trigger for:" clause defining the negative boundary to prevent false triggering.

Project Structure

  • skills/brooks-review/: PR Review skill and guide.
  • skills/brooks-audit/: Architecture Audit skill and guide.
  • skills/brooks-debt/: Tech Debt Assessment skill and guide.
  • skills/brooks-test/: Test Quality Review skill and guide.
  • skills/brooks-health/: Health Dashboard skill and guide.
  • skills/brooks-sweep/: Full Sweep & Auto-Fix skill and guide.
  • skills/_shared/: Shared framework (common.md, source-coverage.md, decay-risks.md, test-decay-risks.md, remedy-guide.md, custom-risks-guide.md).
  • commands/: Short-form command wrappers (used by Claude Code, not Gemini CLI).
  • hooks/: SessionStart hook for Claude Code session-level awareness.
  • evals/: Performance benchmark test cases across R1–R6 and T1–T6, including false-positive and tradeoff checks. Structural validation: npm run evals. Live evals against the AI: npm run evals:live (requires ANTHROPIC_API_KEY).

Development & Debugging

  • Skill Testing: After modifying skills/ locally, exit the Gemini CLI (/quit) and relaunch to pick up the changes.
  • Extension Installation: Users can install the extension in the current workspace via /extensions install ..

Note: Gemini CLI should prioritize instructions found in GEMINI.md when operating in this repository.