AGENTS.md

1# Repository Conventions
2 
3Conventions for human contributors and AI agents working on this repository.
4 
5## Stack
6 
7- Node >=20 runtime.
8- npm package manager.
9- TypeScript 6 strict mode.
10- Biome 2 linting and formatting.
11- Vitest 4 test runner.
12 
13## Forbidden
14 
15- No `as any` or `as unknown`.
16- No `@ts-ignore` or `@ts-expect-error`.
17- No enums.
18- No non-null assertions.
19- No default exports. `vitest.config.ts` is exempt because the framework requires that shape.
20 
21## File Ceiling
22 
23- Keep each `src/` TypeScript file under 250 pure LOC.
24- Split by responsibility before a file reaches the ceiling.
25 
26## Test Discipline
27 
28- Use Vitest with nested `describe` names in `#given`, `#when`, and `#then` form, or inline `// given`, `// when`, and `// then` comments.
29- Never use Arrange-Act-Assert comments.
30- Keep fixtures in `test/fixtures/`.
31 
32## Layout
33 
34- `src/boulder-reader.ts`: reads `.omo/boulder.json`, resolves the active work for the session, re-exports `getPlanChecklist`/`PlanChecklist` from `plan-checklist.ts`. `readContinuationState` returns null only when the plan has no readable top-level checklist (`total === 0`).
35- `src/plan-checklist.ts`: `PlanChecklist` (`completed`/`remaining`/`total`/`nextTaskLabel`) and `getPlanChecklist`/`parsePlanChecklist`. Counts structured `## TODOs` rows (`N. <title>`) and `## Final Verification Wave` rows (`F<number>. <title>`); falls back to simple top-level `- [ ]`/`- [x]` checkboxes. Skips fenced blocks and respects `#`/`##` section boundaries.
36- `src/codex-hook.ts`: Stop/SubagentStop hook; fills `REMAINING_COUNT`/`TOTAL_COUNT`/`NEXT_TASK_LABEL` from the checklist into `directive.md`.
37- `directive.md`: directive template with placeholders, applied per invocation.
38 
39## Build and Hooks
40 
41- Build output goes to `dist/`.
42- `hooks/hooks.json` registers Codex `Stop` and `SubagentStop` hooks.
43- Hook commands run `node ${PLUGIN_ROOT}/components/start-work-continuation/dist/cli.js hook stop` and `node ${PLUGIN_ROOT}/components/start-work-continuation/dist/cli.js hook subagent-stop`.
44 
45## Constraints
46 
47- Never let the hook block a Codex turn because of malformed input.
48- Never make a network call from the hook.
49- Keep the directive in `directive.md`. Do not inline it into TypeScript files.
50- The hook only continues sessions listed in `.omo/boulder.json` as `codex:<session_id>`.
51- The hook continues while the plan has a readable top-level checklist (`total > 0`). A fully-checked plan still blocks Stop until the final gate runs and the Boulder work is marked completed; an unreadable or empty checklist yields no output.
52