AGENTS.md

1# Repository Conventions
2 
3Conventions for human contributors and AI agents working on this repository.
4 
5## Style
6 
7- Terse technical prose. No emojis in commits, issues, PR comments, or code.
8- TypeScript strict mode. No `any`, no `@ts-ignore`, no `@ts-expect-error`, no enums, no non-null assertions.
9- ESM modules with `.js` suffix in runtime import paths.
10- Runtime is Node only because Codex launches plugin hooks with Node.
11- Tabs for indentation in JSON, TypeScript, and Markdown tables.
12- Double quotes for JSON strings.
13 
14## Layout
15 
16- `src/cli.ts`: `UserPromptSubmit` hook CLI. Reads JSON on stdin, writes a compact `<ultrawork-mode>` skill pointer to stdout when the keyword matches (full directive as fallback), exits 0 otherwise.
17- `src/codex-hook.ts`: pure detector/hook behavior; skips on context-pressure/recovery transcripts and when the directive is already in the transcript.
18- `src/skill-pointer.ts`: `buildUltraworkAdditionalContext()`: emits the <4096-byte pointer (Codex App truncates large hook output) directing the model to `create_goal` then read the bundled `ultrawork` skill; falls back to the full `ULTRAWORK_DIRECTIVE` when the plugin skills tree is absent. Pointer size + `ulw-loop` mirror byte-identity pinned by `plugin/test/ultrawork-skill-pointer.test.mjs`.
19- `directive.md`: bundled ultrawork directive text.
20- `skills/ultrawork/SKILL.md`: full directive as a skill, generated by `scripts/sync-directive.mjs`; pinned byte-for-byte to `directive.md` by `test/directive-source.test.ts`. `plugin/scripts/sync-skills.mjs` materializes it into the aggregate `plugin/skills/` tree the pointer path targets.
21- `skills/ulw-plan/`: dual-maintained copy of the ulw-plan skill (component copy wins over `packages/shared-skills/skills/ulw-plan/` in sync-skills; keep both in step by hand).
22- `agents/*.toml`: bundled Codex agent role files. Installed as regular files into `CODEX_HOME/agents/` by `src/cli/install-codex/link-cached-plugin-agents.ts` at install time. Public `sisyphuslabs` installs source them from Codex's installed-marketplace snapshot, not the versioned plugin cache, so they survive Codex auto-update cache pruning and temporary snapshot cleanup. No runtime `SessionStart` hook is involved.
23- `hooks/hooks.json`: registers the prompt-detector hook only.
24- `.codex-plugin/plugin.json`: Codex plugin manifest. Marketplace metadata lives here, not in `package.json`.
25 
26## Constraints
27 
28- Never let the hook block a turn. Exit code is always 0.
29- Never make a network call from the hook.
30- Keep the directive in `directive.md`. Do not inline it into TypeScript files.
31- Keep bundled agent role prompts concise and model-specific; measure prompt length when changing them.
32- When editing `directive.md`, apply the `prompt-engineering` skill's entropy gate: every edit must reduce uncertainty per token. Re-measure character count before committing.
33 
34## Commands
35 
36```bash
37# smoke test the hook
38PAYLOAD='{"cwd":"/tmp","hook_event_name":"UserPromptSubmit","model":"gpt-5.5","permission_mode":"default","session_id":"x","transcript_path":"","turn_id":"y","prompt":"please ultrawork"}'
39npm run build
40echo &quot;$PAYLOAD&quot; | node dist/cli.js hook user-prompt-submit | head -3
41 
42# substring check (must print 1)
43echo '{"hook_event_name":"UserPromptSubmit","prompt":"refactor ulw_helper.ts"}' | node dist/cli.js hook user-prompt-submit | grep -c '<ultrawork-mode>'
44```
45