10 — Agent autonomous loop (Cursor)

Mục tiêu: Coding AI làm liên tục theo hàng đợi STUB→IMP: xong 1 WP → tự chuyển WP kế → đến khi queue rỗng hoặc chạm stop-gate. So khớp màn hình / JPG đã cung cấp; sai thì tự sửa; chạy & test local trước khi đánh dấu Done. Không deploy production trong loop này.

Kích hoạt (user nói một trong các câu):

• chạy autonomous · làm đến hết queue · auto loop · làm liên tục đến khi xong
• hoặc gắn prompt §8 bên dưới vào Agent / Cloud Agent

Tắt / dừng:

• User: dừng · stop · pause loop
• Agent tự dừng khi gặp stop-gate (§5)

0. Nguồn sự thật (đọc mỗi vòng)

npm run infra:up
npm run audit:refresh    # audit + gen queue

1. Vòng lặp chính (bắt buộc)

flowchart TD
  S[Start / resume loop] --> Q[Đọc agent-work-queue.json]
  Q --> E{nextRecommended còn?}
  E -->|Không| Z[STOP: queue rỗng · báo cáo tổng]
  E -->|Có| W[Chọn đúng 1 WP / cặp BE+FE cùng domain]
  W --> D[Read design JPG nếu UI]
  D --> I[Implement theo clone hotels/rentals]
  I --> V[Verify local §3]
  V --> C{Pass?}
  C -->|Không| F[Tự sửa · tối đa 3 vòng fix]
  F --> V
  C -->|Có| U[Cập nhật MATRIX + BACKLOG + audit:refresh]
  U --> R[Báo cáo footer WP vừa xong]
  R --> Q
  F -->|Hết 3 lần fail| X[STOP-GATE: báo lỗi · chờ user]

Một vòng = một Domain. Không gộp pharmacy + medical trong cùng turn implement.

2. Checklist trong một WP

2.1 Trước khi code

• Nêu footer dự kiến: Domain · WP · Surfaces · Status: STUB→IMP
• Clone path từ queue (clone: hotels / rentals / …)
• Nếu có design: Read từng JPG (tool Read) — liệt kê section / CTA / copy VI
• Infra sống: GET /api/v1/health + health/deps OK

2.2 Khi code

• BE: bỏ stub() trên tag đang làm · Prisma + seed idempotent · @ApiTags
• Geo mới → cập nhật nearby-postgis.ts ALLOWED
• FE: mobile/src/features/<domain>/ · tokens · services/api.ts · Home navigate
• UI: so lại ảnh (hierarchy, spacing, màu gần tokens, tiếng Việt)
• Không commit .env / secret · không push --force

2.3 Khi lệch design (tự sửa)

Lặp Read ảnh → diff UI → sửa đến khi khớp đủ AC design (không yêu cầu pixel-perfect 100%, nhưng không thiếu block chính).

3. Verify local (bắt buộc trước Done)

Không đánh IMP nếu chưa chạy được trên máy local.

3.1 Infra + API

npm run infra:up
npm run env:check
# terminal riêng
npm run api:dev
curl -s http://localhost:3000/api/v1/health
curl -s http://localhost:3000/api/v1/health/deps

3.2 Module vừa làm

cd api
npx prisma db push
npx prisma db seed
npm run build
# nếu có test domain: npm test -- <pattern>

Smoke tối thiểu (thay path theo WP):

# ví dụ pharmacy sau IMP
curl -s "http://localhost:3000/api/v1/pharmacy/stores/nearby?lat=10.7769&lng=106.7009"
# Swagger: http://localhost:3000/docs — tag không còn stub description

3.3 FE (khi có WP-FE-*)

npm run mobile:start
# Kiểm tra: mở màn từ Home → list → detail → action chính không crash

3.4 Audit

npm run audit:refresh
# Tag vừa làm: stub ops = 0 (hoặc PARTIAL có ghi rõ trong MATRIX)

Chi tiết smoke toàn hệ: LOCAL-TEST.md.

4. Định nghĩa Done → chuyển task

Chỉ khi tất cả đúng:

1. AC trong 09 §3 (hoặc backlog) đã tick
2. Local verify §3 PASS
3. 01-MATRIX + 05-PHASE-BACKLOG cập nhật Status IMP
4. npm run audit:refresh · nextRecommended trỏ WP khác (hoặc rỗng)
5. Footer báo cáo:

Domain: D-…
WP: WP-… (+ WP-FE-… nếu có)
Surfaces: CON|PAR|…
Status: IMP
Local: PASS (health + smoke + audit)
Next: <nextRecommended hoặc DONE_QUEUE>

Ngay sau đó (nếu user đã bật autonomous): đọc lại queue → bắt đầu WP kế không hỏi lại, trừ khi stop-gate.

5. Stop-gate (bắt buộc dừng, báo user)

6. Giới hạn an toàn session

User có thể nói unlimited loop để bỏ cap 3 WP/session (vẫn giữ stop-gate §5).

7. Báo cáo giữa các WP (ngắn)

Sau mỗi WP Done, trước khi sang WP kế, ghi ≤10 dòng:

1. WP vừa xong + Status IMP
2. File chính đụng (3–8 path)
3. Lệnh local đã PASS
4. Lệch design đã sửa (nếu có)
5. Next: WP-…

Không viết essay; không nhắc lại toàn bộ kế hoạch.

8. Prompt kích hoạt (copy vào Cursor Agent)

Chế độ: AUTONOMOUS LOOP theo docs/10-AGENT-AUTONOMOUS-LOOP.md

1. Đọc docs/09-AGENT-AUDIT-QUEUE.md + docs/references/agent-work-queue.json
2. Làm nextRecommended (một Domain/WP mỗi vòng)
3. UI: Read JPG trong design-index / queue; skill image-to-ui; sai thì tự sửa
4. Clone hotels/rentals; bỏ stub(); seed; nearbyPostgis nếu cần
5. Verify local: infra + health + prisma + build + smoke endpoint + audit:refresh
6. Cập nhật 01-MATRIX + 05-PHASE-BACKLOG khi IMP
7. Báo cáo footer → tự chuyển WP kế (tối đa 3 WP/session trừ khi tôi nói unlimited loop)
8. Gặp stop-gate §5 thì dừng và báo rõ

Bắt đầu ngay từ nextRecommended. Không hỏi lại trừ stop-gate.

Biến thể một WP rồi dừng: thêm dòng Chỉ làm 1 WP rồi pause.

Biến thể chỉ FE polish theo ảnh: Chỉ WP-FE-* · so ảnh · không đổi contract BE trừ bug block.

9. Mapping lệnh user → hành vi agent

10. Liên kết