AGENTS.md

Agent instructions for AI coding tools (OpenAI Codex, GitHub Copilot, Cursor, Kilo Code, Google Jules). For Claude Code see CLAUDE.md. For Kilo Code project rules see .kilocode/rules/. For Gemini/Antigravity see .agent/rules/.

Project Overview

[FILL: Project Name] — [FILL: 1-2 sentence project description. What does it do? Who uses it?]

Architecture (Must-Know)

• [FILL: Key architectural constraint 1] — e.g. "No runtime frameworks, vanilla JS only"
• [FILL: Key architectural constraint 2] — e.g. "Config-driven: all data in config/ files, never hardcode in templates"
• [FILL: Key architectural constraint 3] — e.g. "Touch-first: runs in iOS/Android WebView, all interactions are touch gestures"
• Repo-local Git hooks — Use .githooks/ via git config core.hooksPath .githooks and keep hooks executable

File Structure

[FILL: Add your project's key file structure here.
Only include files/folders that agents must know about to work effectively.
Example:

src/
  index.ts              ← Entry point
  api/                  ← API layer
  components/           ← UI components

config/
  app-config.ts         ← Application configuration

tests/
  *.test.ts             ← Unit tests

docs/
  README.md             ← Primary documentation
]

Coding Rules

General

1. [FILL: Rule 1] — e.g. "No runtime frameworks"
2. [FILL: Rule 2] — e.g. "Config as Single Source of Truth"
3. Minimal changes — Only touch files necessary for the task
4. No unsolicited features — Don't add functionality the user didn't ask for

AI Execution & Orchestration

1. No hanging bash loops — Never use fire-and-forget bash scripts for multi-step iteration or orchestration.
2. Agent-Orchestrated Concurrency — For batch tasks, retrieve the list of targets via a native tool, then have the agent iterate with individual tool calls.
3. MCP Server Tools Over CLI — Always prioritize native MCP integrations (e.g., Github MCP Server) over arbitrary CLI commands.
4. Strict Subprocess Timeouts — Every CLI command via child_process must have a strict timeout (e.g., { timeout: 10000 }).

Documentation Hygiene

1. Table Style — Use | --- | --- | separator style for all tables.
2. Fenced Code Language — Every fenced code block must include a language specifier.
3. Heading Quality — Single H1 per file (MD025), logical increments (MD001), unique subheadings within document (MD024).

Immutable Contract — NEVER CHANGE

[FILL: e.g.

• api-variant-id-1 — used in deeplinks
• SCHEMA_VERSION=3 — written to stored data ]

Common Tasks

Agent Skills (via /skill-name in chat) and Prompt Files (via /command) are available for common workflows:

After Every Change

1. Run [FILL: your test command, e.g. npm test]
2. Commit via git commit (hooks run automatically) with format type(scope): description
3. [FILL: Any additional verification steps specific to your project]

Documentation