# Agent Instructions

This project uses **Symphony** for task management and issue tracking.

## Quick Reference

```bash
symphony_available_tasks          # Find available work
symphony_claim_task <id>          # Claim a task
symphony_report_progress <id>     # Report progress
symphony_complete_task <id>       # Complete work
symphony_status                   # Check system status
```

## Landing the Plane (Session Completion)

**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.

**MANDATORY WORKFLOW:**

1. **File issues for remaining work** — Create tasks for anything that needs follow-up
2. **Run quality gates** (if code changed) — Tests, linters, builds
3. **Update task status** — Complete finished work, update in-progress items
4. **PUSH TO REMOTE** — This is MANDATORY:
   ```bash
   git pull --rebase
   git push
   git status  # MUST show "up to date with origin"
   ```
5. **Clean up** — Clear stashes, prune remote branches
6. **Verify** — All changes committed AND pushed
7. **Hand off** — Provide context for next session

**CRITICAL RULES:**
- Work is NOT complete until `git push` succeeds
- NEVER stop before pushing — that leaves work stranded locally
- NEVER say "ready to push when you are" — YOU must push
- If push fails, resolve and retry until it succeeds
- **Project Constitution (`Docs/CONSTITUTION.md`):** Ngoài việc đọc `CODEBASE.md`, AI bắt buộc phải đọc hiến pháp tại [Docs/CONSTITUTION.md](file:///Users/trungkientn/Dev/NodeJS/main-awf/docs/CONSTITUTION.md) (nếu chưa có thì phải tạo mới, sau khi confirm người dùng). Mọi quyết định lập trình và thay đổi mã nguồn phải tuân thủ nghiêm ngặt hiến pháp này.
- **Codebase Indexing (`/codebase-sync`):** If `CODEBASE.md` is outdated or when receiving `/codebase-sync` request, trigger codebase-sync workflow: run git status/log to detect changed/added files, examine their context, and update `CODEBASE.md`'s layout, Last Updated timestamp, and changelog delta directly.

## AUTO-COMMIT RULE

**After a successful build (0 errors)** (or after static checks/manual validation succeed if build is disabled via `automation.build.enabled: false`), commit immediately — do NOT wait for session end.

```bash
git add -A
git commit -m "fix: <concise description>"   # conventional commit format
git push                                       # non-force push, safe to auto-run
```

**Rules:**
- Commit NGAY sau build 0 errors hoặc sau khi static check (TypeScript/Lint) / verify thủ công OK (nếu build bị tắt) — không gom lại cuối session.
- `git push` (non-force) được phép chạy tự động.
- Push fail → `git pull --rebase && git push` (retry 1 lần).
- Vẫn fail → báo user, KHÔNG force push.
- **Quy tắc gọi Sub-agent theo Alias:** Khi user yêu cầu gọi cụ thể một sub-agent hoặc mô hình (ví dụ: *sol*, *fable 5*, *terra*, *luna*, *qwen*, *spark*...), Agent phải tự động phân giải alias (ví dụ: *sol* -> CLI `codex` / model `gpt-5.6-sol`, *fable 5* -> CLI `claude` / model `fable`, *terra* -> CLI `codex` / model `gpt-5.6-terra`, *luna* -> CLI `codex` / model `gpt-5.6-luna`) và uỷ nhiệm (delegate) việc thực hiện task đó qua CLI tương ứng thay vì tự thực thi trực tiếp.
- **Nhiệm vụ tạo hình ảnh:** Tất cả các nhiệm vụ tạo hình ảnh (như mockup UI, thiết kế assets, tạo spritesheet, pet animation, hoặc hình ảnh minh họa) bắt buộc phải do vai trò `models.designer` (sử dụng CLI `codex` với mô hình `gpt-5.6-luna`) đảm nhiệm.
  - **Quy trình chuẩn hóa khâu thiết kế:**
    1. **Yêu cầu đính kèm Skill:** Khi Orchestrator gọi designer (gpt-5.6-luna), hệ thống sẽ tự động đính kèm chỉ thị và tiêu chuẩn kỹ thuật từ skill `hatch-pet` hoặc `generate-gui-assets` vào prompt/context.
    2. **Lưu trữ bản thiết kế:** Designer thiết kế và lưu toàn bộ file thô/bản nháp vào thư mục thiết kế chung của dự án tại [docs/design/](file:///Users/trungkientn/Dev/NodeJS/main-awf/docs/design/).
    3. **Lọc và Cập nhật Code:** Orchestrator chọn ra 5 bản vẽ tốt nhất từ [docs/design/](file:///Users/trungkientn/Dev/NodeJS/main-awf/docs/design/), chạy script xử lý tách nền trong suốt, đưa vào thư mục assets chính thức và cập nhật mapping trong code.