eryao/AGENTS.md

Project AGENTS Router

Root AGENTS.md is routing + cross-domain policy only. Do not place backend/frontend implementation details here.

Scope

• Applies to repository root and cross-domain tasks.
• Subdomain rules: backend/AGENTS.md, apps/AGENTS.md.
• If rules conflict, use the stricter one.

Rule Order

1. System / developer / platform safety instructions
2. Workspace runtime rules (AGENTS.md + rules/*)
3. This file (routing + project-level constraints)
4. Subdomain rules (backend/apps)

Mandatory Routing

• backend/** must follow backend/AGENTS.md.
• apps/** must follow apps/AGENTS.md.
• Cross-domain changes must satisfy all relevant subdomain rules.
• infra/** follows this file plus infra/ conventions.

Project-Wide Constraints

• Default development branch is dev; do not develop directly on main.
• Never push unless explicitly requested by the user.
• Keep AGENTS layered and lean: shared rules at root, domain rules in sub-AGENTS.
• No Error Swallowing: All exceptions must propagate or be converted to typed errors. Never catch an exception, log it, and silently continue. This destroys debuggability.

Git Safety (CRITICAL)

• NEVER execute git checkout -- <file> or any git command that modifies files without explicit user approval.
• NEVER reset, revert, or discard uncommitted changes without user consent.
• If you need to discard changes, ask the user first and explain exactly what will be lost.
• Before any destructive git operation, list the affected files and get confirmation.
• This rule is non-negotiable. Violation will cause irreversible loss of user work.

Protocol Source of Truth

docs/protocols/ is the single source of truth for protocol and data format.

• Update protocol docs before changing data/API/UI contracts.
• Document compatibility strategy (backward-compatible vs migration).
• Keep frontend/backend implementations aligned with documented protocol.

Database Access

When viewing data in the database, use supabase mcp tools (supabase_execute_sql, supabase_list_tables, etc.) instead of direct queries or other methods.

Trellis Instructions

These instructions are for AI assistants working in this project.

This project is managed by Trellis. The working knowledge you need lives under .trellis/:

• .trellis/workflow.md — development phases, when to create tasks, skill routing
• .trellis/spec/ — package- and layer-scoped coding guidelines (read before writing code in a given layer)
• .trellis/workspace/ — per-developer journals and session traces
• .trellis/tasks/ — active and archived tasks (PRDs, research, jsonl context)

If a Trellis command is available on your platform (e.g. /trellis:finish-work, /trellis:continue), prefer it over manual steps. Not every platform exposes every command.

If you're using Codex or another agent-capable tool, additional project-scoped helpers may live in:

• .agents/skills/ — reusable Trellis skills
• .codex/agents/ — optional custom subagents

Subagents

• ALWAYS wait for every spawned subagent to reach a terminal status before yielding, acting on partial results, or spawning followups.
  • On Codex, this means calling the wait tool with the subagent's thread id (requires multi_agent_v2). Do NOT infer completion from elapsed time.
  • On Claude Code / OpenCode, this means awaiting the Task/agent tool result before continuing.
• NEVER cancel or re-spawn a subagent that hasn't finished. If a subagent appears stuck, raise the wait timeout (Codex default 30s, max 1h) before judging it broken.
• Spawn subagents automatically when:
  • Parallelizable work (e.g., install + verify, npm test + typecheck, multiple tasks from plan)
  • Long-running or blocking tasks where a worker can run independently
  • Isolation for risky changes or checks

Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future trellis update.