arai
AGENTS.md7 starsChanged 6 months agoApache-2.0View on GitHub
This file contains rules that AI coding agents must follow when working in this repository. These rules exist because mistakes here are expensive (corrupting Taniwha build state, breaking compartmentalization invariants, etc.). arai init registers native hooks for Claude Code (.claude/settings.json), Grok Build (.grok/hooks/arai.json), Codex (.codex/hooks.json), and Cursor (.cursor/hooks.json). - Run arai init in this repo so these rules are enforced on the host you are using. - Codex: after init, enable the project hooks through /hooks. Writing the file does…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository9 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- docs/claude.mdCLAUDE.md
- compositionSkill
- contract-derivationSkill
- design-docSkill
- dispatcherSkill
- leaf-implementationSkill
- orchestratorSkill
- verifierSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
24 rules. About 0 are common, 9 are distinctive, and 15 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
15
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
When using the Taniwha compartmentalized build system (.claude/skills/), always follow the documented process:
- Distinctive: line 17
Use the orchestrator/dispatcher pattern for complex work.
- Distinctive: line 19
Never bypass phases (especially verification).
- Very specific: line 21
Always prefer Kupu MCP tools when available.
- Very specific: line 25
Plan first: Write plans to tasks/todo.md (or the active session plan file) with checkable items before deep implementation.
- Distinctive: line 26
Verify before claiming done: Run tests, benchmarks, and manual verification.
- Distinctive: line 27
Minimal impact: Only touch what is necessary.
- Very specific: line 28
After any correction from the user, update tasks/lessons.md with the pattern and rules to prevent recurrence.
- Very specific: line 32
When working on this repo, prefer using the tools and subagents defined in .claude/skills/.
- Distinctive: line 39
Keep host-integration changes focused.
- Very specific: line 44
Run arai init in this repo so these rules are enforced on the host you are using.
- Very specific: line 46
Treat violations of the rules in this file as high-severity (many are never / must style).
- Very specific: line 47
Use arai why, arai status, and arai audit to inspect and improve compliance.
- Very specific: line 52
When adding new instruction file support (new basenames or directories), update both discovery.rs and hooks.rs::is_instruction_file.
- Distinctive: line 56
All three native PreToolUse paths must remain functional.
- Very specific: line 57
When modifying host detection or response emission, preserve and test Claude (hookSpecificOutput.permissionDecision), Grok (decision + exit …
- Distinctive: line 58
Prefer each host's native registration over relying on another host's compatibility layer.
- Very specific: line 59
Do not bypass Arai hooks when they are active (do not set ARAI_DISABLED=1 or ARAI_DENY_MODE=off without explicit justification and logging).
- Very specific: line 60
When using arai why or arai audit during development, treat the output as authoritative for why a rule fired.
- Very specific: line 61
After landing host-integration changes, run arai init on the affected host and verify the hooks are active (arai status, host /hooks UI, a …
- Very specific: line 62
Keep normalize_tool_name current with live host tool names.
- Distinctive: line 63
Do not let work on one host reduce quality or test coverage of the others.
- Distinctive: line 64
When under high context pressure, treat the rules in this file as more important, not less.
- Very specific: line 65
When Arai fires a rule, treat it as feedback and update AGENTS.md, lessons, or the integration as needed.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — Arai
This file contains rules that AI coding agents must follow when working in this repository.
These rules exist because mistakes here are expensive (corrupting Taniwha build state, breaking compartmentalization invariants, etc.).
Core Discipline (Non-Negotiable)
- Always enter plan mode for any non-trivial task (3+ steps, architectural decisions, or anything that would benefit from user review before coding). Use the
enter_plan_modetool. - Never edit source files while in plan mode except for the plan file itself.
- Exit plan mode with
exit_plan_modeand present the plan for explicit user approval before making implementation changes. - Respect the current plan file as the single source of truth during any planning or implementation phase. Do not improvise outside it.
Taniwha / Subagent Rules
- When using the Taniwha compartmentalized build system (
.claude/skills/), always follow the documented process:- Use the orchestrator/dispatcher pattern for complex work.
- Dispatch the correct role subagents (design-doc, contract-derivation, leaf-implementation, composition, verifier).
- Never bypass phases (especially verification).
- Never manually mutate files under
.taniwha/kupu/except through the approved mechanisms (Kupu MCP tools when available, or the exact bash fallback scripts in.claude/skills/_shared/scripts/util/). - Always prefer Kupu MCP tools when available. When they are not, use the canonical bash scripts (
new_ulid.sh,now.sh,event_path.sh).
Work Style
- Plan first. Write plans to
tasks/todo.md(or the active session plan file) with checkable items before deep implementation. - Verify before claiming done. Run tests, benchmarks, and manual verification. Do not mark tasks complete until they actually work.
- Minimal impact. Only touch what is necessary. Challenge yourself: "Is there a more elegant way with less surface area?"
- After any correction from the user, update
tasks/lessons.mdwith the pattern and rules to prevent recurrence.
Tool Usage
- When working on this repo, prefer using the tools and subagents defined in
.claude/skills/. - For complex multi-step work, use
spawn_subagentwith appropriate types (explore,plan,general-purpose, etc.) rather than trying to do everything in one context.
Git / Branching
- Contribution flow is PR-to-main. Do not push feature work straight to
main. - Grok Build and Codex hook support have shipped (Grok in 1.1.x, Codex in 1.1.2). Do not treat
feat/grok-tui-supportas the live integration branch. - Keep host-integration changes focused. Large new features should be discussed before expanding scope.
Using Arai (Dogfooding)
arai init registers native hooks for Claude Code (.claude/settings.json), Grok Build (.grok/hooks/arai.json), Codex (.codex/hooks.json), and Cursor (.cursor/hooks.json).
- Run
arai initin this repo so these rules are enforced on the host you are using. - Codex: after init, enable the project hooks through
/hooks. Writing the file does not grant host trust. - Treat violations of the rules in this file as high-severity (many are
never/muststyle). - Use
arai why,arai status, andarai auditto inspect and improve compliance.
Changes That Affect Guardrails
- Any change that touches hook handling, tool name normalization, response formats, matching logic, or discovery must include or update tests (especially in
tests/hooks_safety.rsandtests/codex_hooks.rs). - When adding new instruction file support (new basenames or directories), update both
discovery.rsandhooks.rs::is_instruction_file.
Host integrations (Claude Code, Grok Build, Codex, Cursor)
- All three native PreToolUse paths must remain functional. A change that fixes one host must not regress the others.
- When modifying host detection or response emission, preserve and test Claude (
hookSpecificOutput.permissionDecision), Grok (decision+ exit 2), and Codex shapes. - Prefer each host's native registration over relying on another host's compatibility layer.
- Do not bypass Arai hooks when they are active (do not set
ARAI_DISABLED=1orARAI_DENY_MODE=offwithout explicit justification and logging). - When using
arai whyorarai auditduring development, treat the output as authoritative for why a rule fired. - After landing host-integration changes, run
arai initon the affected host and verify the hooks are active (arai status, host/hooksUI, a harmless blocked-rule probe). - Keep
normalize_tool_namecurrent with live host tool names. A missing alias is a silent fail-open. Grok Build:run_terminal_command→Bash. Codex: canonicalBashplus per-fileapply_patch. Cursor:Shell→Bash,Delete→Edit(seesrc/cursor.rs). - Do not let work on one host reduce quality or test coverage of the others.
- When under high context pressure, treat the rules in this file as more important, not less.
- When Arai fires a rule, treat it as feedback and update AGENTS.md, lessons, or the integration as needed.
These rules are here to protect the integrity of the project. Violating them has real downstream cost.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

