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.

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.

Image Handling

When reading images, use understand_image tool instead of Read tool, especially when the model supports multimodal capabilities. Only use Read tool for non-image files.

Mobile Automation

Use Midscene Skills for mobile UI automation.

When to trigger

If the user asks to open app, navigate pages, tap, input text, scroll, verify UI, reproduce bug, or run mobile tests → treat as executable automation, not just explanation.

Platform

• iOS → use Midscene iOS (requires WebDriverAgent at http://localhost:8100/status)
• Android → use Midscene Android (requires adb devices available)

If platform not specified:

• Use current project platform if obvious
• Otherwise ask

Preconditions

• iOS: WDA must be ready
• Android: device/emulator must be connected

If not ready → stop and report missing requirement

Execution

• Perform actual UI actions via Midscene Skills
• Do not only describe test plan
• Capture result (screen state / success / failure step)

Output

Return:

• success or failure
• first failing step (if any)
• key observation

Trellis Instructions

These instructions are for AI assistants working in this project.

Use the /trellis:start command when starting a new session to:

• Initialize your developer identity
• Understand current project context
• Read relevant guidelines

Use @/.trellis/ to learn:

• Development workflow (workflow.md)
• Project structure guidelines (spec/)
• Developer workspace (workspace/)

Keep this managed block so 'trellis update' can refresh the instructions.