ZL-Q
90 lines
4.0 KiB
Markdown
90 lines
4.0 KiB
Markdown
# 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.
|
|
|
|
## Test
|
|
- test_user_email: test@example.com
|
|
- test_code: 123456
|
|
- login directly, do not send verfiy code
|
|
|
|
<!-- TRELLIS:START -->
|
|
# 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`.
|
|
|
|
<!-- TRELLIS:END -->
|