Skip to content

Commit 4bb18b6

Browse files
committed
docs(agents): add director extract review bar
1 parent 798ff34 commit 4bb18b6

1 file changed

Lines changed: 27 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,33 @@ Touch only code directly related to the task. No drive-by renames, reformatting,
2828

2929
When refactoring replaces an old path, delete the old one. No back-compat shims, re-exports, or `_unused` renames for callers you own.
3030

31+
## Director extract review bar
32+
33+
A new or changed `@corbits/code-agent-*` workspace package (`agents/<id>/`) must
34+
survive review against three hard failures, regardless of how the app consumes it:
35+
36+
1. **No dead re-exports.** `agents/<id>/src/index.ts` may only re-export names
37+
that have a production importer. Do not add a barrel or test-only consumer to
38+
launder a dead name past the dead-export guard. The app's single closed fan-in
39+
is `DIRECTOR_REGISTRY` (`src/agent/directors/registry.ts`); there is no second
40+
fleet barrel, and an extract branch has no other in-repo consumer to justify a
41+
name.
42+
2. **No "what this file is" narration.** Do not paste file-summary or
43+
ticket-restating JSDoc into the package. Comment _why_, never _what_
44+
(Conventions above); a module that restates its own exports in prose is noise,
45+
not documentation.
46+
3. **No whole-surface allowlisting without naming the API.** Every export left on
47+
`scripts/dead-export-allowlist.txt` (the `agents/<id>/src/index.ts` six-name
48+
surface) must say which names are the public API and why. A blanket entry that
49+
lists the whole surface without per-name reasons fails review; remove each
50+
entry with the export it covers as the closed fan-in (`DIRECTOR_REGISTRY`)
51+
consumes it.
52+
53+
An extract lands only when the names it keeps are real public API backed by a
54+
production importer, the code reads why-not-what, and the allowlist entry names
55+
the API surface. Failing any of these means reworking the extract, not a new
56+
barrel or an allowlist band-aid.
57+
3158
## Tests
3259

3360
- Add or update tests with every behavior change.

0 commit comments

Comments
 (0)