agentleFS
taniwhaaitaniwhaai/arai/AGENTS.md

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.

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
  1. Very specific:

    When using the Taniwha compartmentalized build system (.claude/skills/), always follow the documented process:

    line 16
  2. Distinctive:

    Use the orchestrator/dispatcher pattern for complex work.

    line 17
  3. Distinctive:

    Never bypass phases (especially verification).

    line 19
  4. Very specific:

    Always prefer Kupu MCP tools when available.

    line 21
  5. Very specific:

    Plan first: Write plans to tasks/todo.md (or the active session plan file) with checkable items before deep implementation.

    line 25
  6. Distinctive:

    Verify before claiming done: Run tests, benchmarks, and manual verification.

    line 26
  7. Distinctive:

    Minimal impact: Only touch what is necessary.

    line 27
  8. Very specific:

    After any correction from the user, update tasks/lessons.md with the pattern and rules to prevent recurrence.

    line 28
  9. Very specific:

    When working on this repo, prefer using the tools and subagents defined in .claude/skills/.

    line 32
  10. Distinctive:

    Keep host-integration changes focused.

    line 39
  11. Very specific:

    Run arai init in this repo so these rules are enforced on the host you are using.

    line 44
  12. Very specific:

    Treat violations of the rules in this file as high-severity (many are never / must style).

    line 46
  13. Very specific:

    Use arai why, arai status, and arai audit to inspect and improve compliance.

    line 47
  14. Very specific:

    When adding new instruction file support (new basenames or directories), update both discovery.rs and hooks.rs::is_instruction_file.

    line 52
  15. Distinctive:

    All three native PreToolUse paths must remain functional.

    line 56
  16. Very specific:

    When modifying host detection or response emission, preserve and test Claude (hookSpecificOutput.permissionDecision), Grok (decision + exit …

    line 57
  17. Distinctive:

    Prefer each host's native registration over relying on another host's compatibility layer.

    line 58
  18. Very specific:

    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).

    line 59
  19. Very specific:

    When using arai why or arai audit during development, treat the output as authoritative for why a rule fired.

    line 60
  20. Very specific:

    After landing host-integration changes, run arai init on the affected host and verify the hooks are active (arai status, host /hooks UI, a …

    line 61
  21. Very specific:

    Keep normalize_tool_name current with live host tool names.

    line 62
  22. Distinctive:

    Do not let work on one host reduce quality or test coverage of the others.

    line 63
  23. Distinctive:

    When under high context pressure, treat the rules in this file as more important, not less.

    line 64
  24. Very specific:

    When Arai fires a rule, treat it as feedback and update AGENTS.md, lessons, or the integration as needed.

    line 65

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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_mode tool.
  • Never edit source files while in plan mode except for the plan file itself.
  • Exit plan mode with exit_plan_mode and 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.md with 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_subagent with 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-support as 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 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 not grant host trust.
  • Treat violations of the rules in this file as high-severity (many are never / must style).
  • Use arai why, arai status, and arai audit to 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.rs and tests/codex_hooks.rs).
  • When adding new instruction file support (new basenames or directories), update both discovery.rs and hooks.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=1 or ARAI_DENY_MODE=off without explicit justification and logging).
  • When using arai why or arai audit during development, treat the output as authoritative for why a rule fired.
  • After landing host-integration changes, run arai init on the affected host and verify the hooks are active (arai status, host /hooks UI, a harmless blocked-rule probe).
  • Keep normalize_tool_name current with live host tool names. A missing alias is a silent fail-open. Grok Build: run_terminal_command → Bash. Codex: canonical Bash plus per-file apply_patch. Cursor: Shell → Bash, Delete → Edit (see src/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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.