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## Commit Style
33 
34- Use Conventional Commits.
35- Keep commits atomic.
36- Each commit's tests and build must pass on its own.
37 
38## Branding
39 
40- Repo artifacts live under `.omo/ulw-loop/` paths.
41- Environment variables use the `OMO_ULW_LOOP_*` prefix.
42- CLI commands use the `omo ulw-loop` form.
43- Do not use any alternate legacy CLI alias anywhere.
44 
45## Build and Hooks
46 
47- Build output goes to `dist/`.
48- `hooks/hooks.json` wires `hook user-prompt-submit --with-ultrawork` (UserPromptSubmit), `hook pre-tool-use` (create_goal budget), `hook pre-tool-use-spawn` (spawn guards), and `hook stop` (auto-resume).
49