csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📦 deps(skills): sync thirdparty skills

Browse Source
This commit is contained in:
ci[bot]
2026-05-29 08:33:55 +00:00
parent b7eb57f5da
commit b4c88b32be
25 changed files with 3033 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/thirdparty/brooks-audit/SKILL.md
Vendored
+42
View File
@@ -0,0 +1,42 @@
---
name: brooks-audit
description: >
Architecture audit that maps module dependencies, checks layering integrity, and
flags structural decay across a codebase, drawing on twelve classic engineering books.
Triggers when: user asks to audit architecture, review folder/module structure,
check for circular imports, understand how the codebase is organized, or asks
"does this follow clean architecture?", "why does everything depend on everything?",
"are our layers correct?", "where should this code live?".
Also triggers for onboarding requests: "explain this codebase to a new developer"
or "give me a codebase tour" (use onboarding mode).
Do NOT trigger for: PR-level code review (use brooks-review) or line-level refactoring
questions — this skill analyzes structural/module-level concerns, not individual functions.
---
# Brooks-Lint — Architecture Audit
## Setup
1. Read `../_shared/common.md` for the Iron Law, Project Config, Report Template, and Health Score rules
2. Read `../_shared/source-coverage.md` for book-level coverage, exceptions, and tradeoffs
3. Read `../_shared/decay-risks.md` for symptom definitions and source attributions
4. Read `architecture-guide.md` in this directory for the audit framework
## Process
**Onboarding mode:** If the user asks for an onboarding report, codebase tour, or
"explain this codebase to a new developer", read `onboarding-guide.md` from this
directory and follow it instead of `architecture-guide.md`. This mode explains rather
than diagnoses — no Health Score, no Iron Law findings.
**If the user has not specified files or a directory to audit:** apply Auto Scope
Detection from `../_shared/common.md` to determine the audit scope before proceeding.
1. Gather codebase context and draw the module dependency graph as Mermaid (Steps 0–1 of the guide)
2. Scan for each decay risk in the order specified (Steps 2–4 of the guide)
3. Assign node colors in the Mermaid diagram based on findings (red/yellow/green) — after Step 4
4. Run the Testability Seam Assessment (Step 5 of the guide)
5. Run the Conway's Law check (Step 6 of the guide)
6. Output using the Report Template from common.md — Mermaid graph FIRST, then Findings
**Mode line in report:** `Architecture Audit`
skills/thirdparty/brooks-audit/architecture-guide.md
Vendored
+195
View File
@@ -0,0 +1,195 @@
# Architecture Audit Guide — Mode 2
**Purpose:** Analyze the module and dependency structure of a system for decay risks that
operate at the architectural level. Every finding must follow the Iron Law:
Symptom → Source → Consequence → Remedy.
**Monorepo note:** Treat each deployable service or library as a top-level module. Draw
dependencies between services, not between their internal packages. Apply the Conway's Law
check at the service ownership level. Within a single service, apply standard module-level analysis.
---
## Analysis Process
Work through these six steps in order.
### Step 0: Gather Codebase Context
Before drawing anything, establish what you can see.
**If the user provided a full directory tree or pasted relevant file contents:** skip the
proactive reading below and proceed to Step 1.
**Otherwise, proactively read the project using these tools:**
1. **Top-level structure** — glob top two levels to identify module boundaries:
```
Glob: **/*(depth 2, directories only)
```
2. **Entry points** — read the package manifest or main config file (e.g., `package.json`,
`go.mod`, `pom.xml`, `Cargo.toml`, `pyproject.toml`) to confirm language, framework,
and declared dependencies.
3. **Dependency edges** — grep import statements to discover inter-module calls. Run once
per language present; limit to the first 200 matches to avoid token overrun:
```
Grep: "^\s*(import|from|require\(|use )" across *.ts|*.py|*.go|*.rs|*.java
```
4. **Large modules** — for any top-level directory with > 10 files, read the file matching
`index.*`, `main.*`, or `__init__.*` to understand its stated responsibility.
**Stop when you can answer all three:**
- What are the top-level modules (names and count)?
- Which modules import from which other modules?
- Which module has the highest fan-in or fan-out?
If the project has > 100 top-level files or > 4 levels of nesting, note which areas were
sampled vs. inferred, and flag this in the report scope line.
### Step 1: Draw the Module Dependency Graph (Mermaid)
Before evaluating any risk, map the dependencies as a Mermaid diagram. Use this format:
````mermaid
graph TD
subgraph UI
WebApp
MobileApp
end
subgraph Domain
AuthService
OrderService
PaymentService
end
subgraph Infrastructure
Database
MessageQueue
end
WebApp --> AuthService
WebApp --> OrderService
MobileApp --> AuthService
MobileApp --> OrderService
OrderService --> PaymentService
OrderService --> Database
OrderService --> MessageQueue
PaymentService --> Database
AuthService -.->|circular| OrderService
classDef critical fill:#ff6b6b,stroke:#c92a2a,color:#fff
classDef warning fill:#ffd43b,stroke:#e67700
classDef clean fill:#51cf66,stroke:#2b8a3e,color:#fff
class PaymentService critical
class OrderService warning
class Database,MessageQueue,AuthService,WebApp,MobileApp clean
````
Draw the graph structure first — nodes, subgraphs, and edges — without any `classDef` or
`class` lines. You cannot assign colors until you have completed the risk scan in Steps 2–4.
**After completing Step 4**, return to this graph and add the `classDef` and `class` lines
based on findings. The example above shows the final colored output.
Rules:
1. **Nodes** — Use top-level directories or services as nodes, not individual files
2. **Grouping** — One `subgraph` per architectural layer or top-level directory (e.g., UI, Domain, Infrastructure)
3. **Edges** — Solid arrows (`-->`) point FROM the depending module TO the dependency; use dotted arrows with label (`-.->|circular|`) for circular dependencies. If no circular dependencies exist, use only solid arrows
4. **Node limit** — Keep the graph to ~50 nodes maximum; collapse low-risk leaf modules into their parent if needed
5. **Fan-out** — For any node with fan-out > 5, use a descriptive label: `HighFanOutModule["ModuleName (fan-out: 7)"]`
6. **Colors** — Apply `classDef` colors AFTER completing Steps 2-4: `critical` (red `#ff6b6b`) for nodes with Critical findings, `warning` (yellow `#ffd43b`) for Warning findings, `clean` (green `#51cf66`) for nodes with no findings or only Suggestions. If no findings at all, classify all nodes as `clean`
7. **Direction** — Default to `graph TD` (top-down); use `graph LR` only if the architecture is clearly a left-to-right pipeline
### Step 2: Scan for Dependency Disorder
*The most architecturally consequential risk — scan this first.*
Look for:
- Circular dependencies (any `-.->|circular|` edge in the map above)
- Arrows flowing upward (high-level domain depending on low-level infrastructure)
- Stable, widely-depended-on modules that import from frequently-changing modules
- Modules with fan-out > 5
- Absence of a clear layering rule (no consistent answer to "what depends on what?")
### Step 3: Scan for Domain Model Distortion
Look for:
- Do module names match the business domain vocabulary?
- Is there a layer called "services" that contains all the business logic while domain objects
are pure data structures?
- Are there modules that cross bounded context boundaries (e.g., billing logic in the user module)?
- Is there an anti-corruption layer where external systems interface with the domain?
### Step 4: Scan for Remaining Four Risks
Check each in turn:
**Knowledge Duplication:**
- Are there multiple modules implementing the same concept independently?
- Does the same domain concept appear under different names in different modules?
**Accidental Complexity:**
- Are there entire layers in the architecture that do not add value?
- Are there modules whose responsibility cannot be stated in one sentence?
**Change Propagation:**
- Which modules are "blast radius hotspots"? (A change here requires changes in many other modules)
- Does the dependency map reveal why certain features are slow to develop?
**Cognitive Overload:**
- Can the module responsibility of each module be stated in one sentence from its name alone?
- Would a new developer know which module to add a new feature to?
### Step 5: Testability Seam Assessment
A *seam* is a place in the architecture where behavior can be altered without editing source
code — typically an interface, a configuration point, or a dependency injection boundary.
Seam density is a proxy for testability and evolvability.
Scan for:
- **No seam at the infrastructure boundary**: can you replace a real database, file system,
or HTTP client with a test double without editing the module under test? If not, the
architecture forces integration tests where unit tests would suffice.
- **Seam collapse**: a module that was once testable in isolation has had its seams removed
(e.g., direct constructor instantiation replaced a dependency injection point, or a global
singleton replaced an injected collaborator).
- **Missing seam in legacy areas**: modules without an obvious injection point or interface
boundary — any change requires touching the entire call stack to substitute behavior.
If all modules have clear seams at their infrastructure boundaries → no finding.
If seams are absent or collapsed: flag as 🟡 Warning with a Remedy pointing to the specific
module and the injection point that needs to be restored or introduced.
Source: Feathers — Working Effectively with Legacy Code, Ch. 4: The Seam Model
### Step 6: Conway's Law Check
After the six-risk scan, assess the relationship between architecture and team structure:
- Does the module/service structure reflect the team structure?
(Conway's Law: "Organizations design systems that mirror their communication structure")
- If yes: is this intentional design or accidental coupling?
- A mismatch that causes cross-team coordination overhead for every feature is 🔴 Critical.
- A mismatch that is theoretical but not yet causing pain is 🟡 Warning.
- If team structure is unknown, note this as context missing and skip the check.
**Calibration examples:**
- 🔴 Critical: the Payments module is owned by Team A but contains auth logic owned by Team B —
every Payments change requires a sync meeting with Team B
- 🟡 Warning: two separate teams own the `utils/` and `helpers/` directories which do the same
things — theoretically painful but not yet causing release coordination issues
- Not a finding: a single team owns a monorepo with multiple logical modules — Conway's Law
misalignment requires *separate teams* to be meaningful
---
## Output
Use the standard Report Template from `../_shared/common.md`. Mode: Architecture Audit.
Place the Mermaid dependency graph FIRST under "Module Dependency Graph". Reference
relevant node names in findings. Add `classDef` color assignments LAST, after all
findings are identified.
skills/thirdparty/brooks-audit/onboarding-guide.md
Vendored
+89
View File
@@ -0,0 +1,89 @@
# Codebase Onboarding Guide
**Purpose:** Produce a newcomer-friendly tour of the codebase. This is NOT a diagnostic
report — no Health Score, no Iron Law findings. Focus on explanation and orientation.
---
## Process
### Step 1: Map the Territory
- Read top-level structure (same as architecture-guide Step 0)
- Output: a plain-language overview of what each top-level module does (one sentence each)
- Group into layers: "Things users interact with", "Business logic", "Infrastructure"
### Step 2: Draw the Dependency Map
Draw the same Mermaid dependency graph as architecture audit Step 1, but color nodes by
**recommended reading order** using a DISTINCT palette from the severity palette
(which uses red/yellow/green). This avoids confusing "red = danger" with "red = read last":
- 🔵 Blue (`#339af0`): start here — entry points, core domain
- 🟣 Purple (`#9775fa`): read next — supporting modules
- ⚪ Gray (`#ced4da`): read last — infrastructure, generated code, utilities
Add numbered labels: `CoreModule["1. CoreModule"]`
```
classDef start fill:#339af0,color:#fff
classDef next fill:#9775fa,color:#fff
classDef last fill:#ced4da
```
### Step 3: Highlight Key Conventions
Identify and document patterns the codebase follows:
- Naming conventions (file naming, class naming, variable naming)
- Directory organization pattern (feature-based? layer-based? hybrid?)
- Error handling pattern (exceptions? result types? error codes?)
- Testing convention (co-located? separate directory? naming pattern?)
- Dependency injection pattern (if any)
### Step 4: Mark Danger Zones
For each module with known complexity or coupling issues, add a brief warning:
- "OrderService: high complexity, only modify with full test suite running"
- "legacy/: no tests, use Characterization Tests before changing"
Do NOT use Iron Law format — use plain warnings. This is orientation, not diagnosis.
### Step 5: Build a Domain Glossary
Extract 10-15 key domain terms from code (class names, method names, constants) and map
them to plain-language definitions. This applies Evans's Ubiquitous Language as documentation.
### Step 6: Suggest First Tasks
Based on the dependency map, suggest 2-3 low-risk areas where a new developer could make
their first contribution: modules with good test coverage, clear boundaries, low coupling.
---
## Output Template
```
# Codebase Tour: [Project Name]
## Overview
[2-3 sentence summary of what the project does and its tech stack]
## Module Map
[Mermaid graph with reading-order colors]
## Module Guide
[One paragraph per top-level module: what it does, what it depends on, key files to read]
## Conventions
[Bullet list of patterns this codebase follows]
## Danger Zones
[Bullet list of areas to be careful with, or "None identified" if the codebase is clean]
## Domain Glossary
| Term | Meaning |
|------|---------|
## Suggested First Tasks
[2-3 concrete suggestions for a new developer's first PR]
```