# Frontend Agent Design Pipeline

## Summary
Tạo một “frontend agent” nhẹ trong backend, không thêm LangChain ở v1. Agent vẫn dùng `LLM_CODER_MODEL_NAME=qwen/qwen-vl-plus`, nhưng thay prompt đơn lẻ hiện tại bằng pipeline có design context tốt hơn: chọn template/design reference đã cache local, đọc skill frontend, lập style brief, lập site plan, rồi generate từng file HTML. Mục tiêu là website preview đẹp và nhất quán hơn, đặc biệt cho web app quản lý.

## Key Changes

### Agent Pipeline
- Thêm service mới dạng lightweight agent, ví dụ `frontend_agent_service.py`.
- Agent nhận input:
  - `ba_summary`
  - `additional_prompt`
  - `site_plan`
  - selected template/design reference
  - frontend skill markdown
- Agent chạy theo bước:
  1. Select design source: random hoặc cấu hình cố định.
  2. Build `Design Brief` từ cached template/design md.
  3. Generate site plan nếu chưa có.
  4. Generate từng HTML file theo `site_plan`.
  5. Validate/repair HTML như flow hiện tại.
- Không dùng LangChain ở v1 để tránh thêm dependency và tăng độ phức tạp.

### Template/Design Reference
- Dùng local cache first.
- Tạo thư mục:
  - `backend/app/prompts/frontend_skills/`
  - `backend/app/prompts/design_references/`
  - `backend/app/prompts/template_refs/`
- Giữ `dasher_admin.md` hiện tại, bổ sung thêm:
  - `frontend_agent_skill.md`: quy tắc UI/UX, CRUD fake JS, responsive, dashboard admin.
  - `templates.json`: registry template có `id`, `name`, `url`, `type`, `local_ref_path`, `tags`.
- Với `https://themewagon.github.io/dasher/`, không fetch live mỗi lần generate; lưu một `dasher_template.md` mô tả layout/components/style.
- Hỗ trợ awesome-design-md bằng cách lưu một số file `.md` đã chọn vào local cache; v1 chưa auto clone/fetch GitHub.

### Config
- Thêm env:
  ```env
  FRONTEND_AGENT_ENABLED=true
  FRONTEND_AGENT_MODEL=qwen/qwen-vl-plus
  FRONTEND_AGENT_TEMPLATE_MODE=random
  FRONTEND_AGENT_TEMPLATE_IDS=dasher
  FRONTEND_AGENT_DESIGN_MD_MODE=random
  FRONTEND_AGENT_DESIGN_MD_IDS=
  FRONTEND_AGENT_CACHE_LIVE_FETCH=false
  ```
- Nếu `FRONTEND_AGENT_ENABLED=false`, fallback về prompt/pipeline hiện tại.
- Nếu `FRONTEND_AGENT_TEMPLATE_MODE=random`, chọn ngẫu nhiên trong registry theo tag phù hợp với BA summary, ưu tiên `admin/dashboard` cho web app quản lý.
- Nếu chỉ định `FRONTEND_AGENT_TEMPLATE_IDS=dasher`, luôn dùng Dasher.

### Generation Behavior
- Thay phần `_load_website_design_reference()` bằng bước chọn reference có cấu trúc hơn.
- Khi generate từng file, prompt sẽ gồm:
  - BA summary
  - site plan đầy đủ
  - current file purpose
  - selected template brief
  - selected design md brief nếu có
  - frontend skill
- Mỗi file HTML vẫn phải:
  - dùng Tailwind CDN, Inter, Font Awesome
  - có navigation đúng các file trong site plan
  - có CRUD fake bằng JavaScript nếu là web app quản lý
  - không cần backend/database/localStorage
- Ghi metadata vào `summary.md`:
  - `frontend_agent_enabled`
  - `selected_template_id`
  - `selected_template_url`
  - `selected_design_md_id`
  - `frontend_agent_skill_version`

### Progress UI
- Giữ progress hiện tại.
- Bổ sung message rõ hơn:
  - `Selecting design reference`
  - `Building frontend style brief`
  - `Planning website pages`
  - `Generating employees.html (2/6)`
  - `Validating generated pages`
- Không đổi API lớn; vẫn dùng `GET /recordings/{id}` poll `ai_progress_percent` và `ai_progress_message`.

## Test Plan
- Unit tests:
  - Template registry load đúng.
  - Random selection chỉ chọn template enabled.
  - Fixed template id chọn đúng Dasher.
  - Agent prompt chứa frontend skill + selected template brief.
  - `FRONTEND_AGENT_ENABLED=false` fallback về behavior cũ.
- Backend tests:
  - Generate task ghi `selected_template_id` vào `summary.md`.
  - Progress message cập nhật qua từng bước.
  - Site plan + per-file generation vẫn tạo được manifest hợp lệ.
- Manual acceptance:
  - Generate web app quản lý với Dasher reference tạo UI giống admin dashboard hơn.
  - Sidebar/top nav đẹp và nhất quán giữa các page.
  - Table/card/dashboard nhìn chuyên nghiệp hơn bản cũ.
  - Add/Edit/Delete modal vẫn chạy bằng fake JS.
  - Random mode tạo được các style khác nhau khi có nhiều template/design md.

## Assumptions
- V1 không dùng LangChain thật; dùng lightweight agent bằng OpenAI-compatible client hiện có.
- V1 không fetch URL live trong mỗi lần generate; dùng cache local để nhanh và ổn định.
- `qwen/qwen-vl-plus` tiếp tục là coder model qua `LLM_CODER_MODEL_NAME` hoặc `FRONTEND_AGENT_MODEL`.
- Việc crawl/chụp screenshot template live sẽ để v2 nếu cần.
