Flutter AI Flows

Bộ 43 AI Skills hỗ trợ toàn bộ vòng đời phát triển Flutter: khởi tạo dự án, tiếp nhận Jira, phân tích yêu cầu, triển khai, sửa lỗi, kiểm thử, review và CI/CD.

README này là tài liệu sử dụng duy nhất dành cho developer. Installer chỉ đưa vào project các file phục vụ hoạt động của Agent và skills.

Cài đặt

npx flutter-ai-flows

CLI sẽ yêu cầu chọn:

1. greenfield: dự án mới cần scaffold.
2. mature: dự án đã có code và conventions.
3. Một hoặc nhiều IDE/Agent cần cài skills.

Chạy không tương tác

# Dự án đã có code, dùng Claude Code
npx flutter-ai-flows --mode=mature --ide=claude_code

# Cài đồng thời cho Codex và Cursor
npx flutter-ai-flows --mode=mature --ide=codex,cursor

# Cài cho tất cả IDE và ghi đè file đã tồn tại
npx flutter-ai-flows --ide=all --force

# Cài vào thư mục khác
npx flutter-ai-flows --cwd=/path/to/project

| Flag | Mô tả | |---|---| | --mode=greenfield\|mature | Bỏ qua prompt chọn loại dự án | | --ide=antigravity,cursor,... | Chọn IDE bằng danh sách phân cách bởi dấu phẩy; dùng all cho tất cả | | --force | Ghi đè file đã tồn tại; mặc định installer giữ nguyên | | --cwd=<path> | Chỉ định thư mục đích thay cho thư mục hiện tại |

Các file được cài vào project

your_project/
├── AGENTS.md
├── docs/
│   ├── learnings.md
│   └── ai-flows/
│       ├── project-profile.md
│       ├── priority-rules.md
│       ├── code-patterns.md
│       ├── skill-map.md
│       ├── next-skill-rules.md
│       └── workflow-contract.json
└── <thư mục skills theo IDE>/

| IDE/Agent | Nơi cài 43 skills | Định dạng | |---|---|---| | Google Antigravity | .agents/skills/ | SKILL.md | | Cursor | .cursor/rules/ | .mdc phẳng | | Claude Code | .claude/skills/ | SKILL.md | | Windsurf | .windsurf/rules/ | SKILL.md | | Codex | .codex/skills/ | SKILL.md | | GitHub Copilot / IDE khác | docs/ai_skills/ | SKILL.md |

Không cài thêm README hoặc HDSD vào project đích.

Vai trò của các file runtime

| File | Vai trò | |---|---| | AGENTS.md | Hub chỉ dẫn Agent nạp đúng context | | project-profile.md | Stack, kiến trúc, đường dẫn và conventions của project | | priority-rules.md | Thứ tự ưu tiên khi các nguồn chỉ dẫn xung đột | | code-patterns.md | Pattern sinh code; dự án mature có thể sinh lại từ code thực tế | | skill-map.md | Ánh xạ nhu cầu sang skill | | next-skill-rules.md | Chọn bước tiếp theo sau khi một skill hoàn tất | | workflow-contract.json | State machine và evidence gate của workflow | | learnings.md | Bài học và convention tích luỹ riêng của project |

Các file này là contract ngắn cho Agent, không phải tài liệu hướng dẫn dành cho developer.

Bắt đầu sử dụng

Mở chat AI trong IDE và gọi skill bằng /tên-skill.

| Ngữ cảnh | Skill đầu tiên | |---|---| | Dự án mới, kiến trúc enterprise | /flutter-setup-enterprise-project | | Dự án mới, MVP/PoC | /flutter-setup-basic-project | | Dự án đã có code | /flutter-detect-project-profile | | Chưa biết nên dùng skill nào | /flutter-help |

Với project mature, nên chạy /flutter-detect-project-profile trước khi dùng skill sinh code. Agent sẽ nhận diện state management, routing, DI, repository/model pattern và cập nhật docs/ai-flows/project-profile.md cùng code-patterns.md.

Sáu use case chính

1. Khởi tạo dự án

Enterprise  → /flutter-setup-enterprise-project
MVP/PoC     → /flutter-setup-basic-project

Enterprise orchestrator lần lượt thiết lập dependencies, flavor, DI, Dio, routing, theme, localization, state management, storage, notification, linting và Crashlytics/Analytics.

2. Tiếp nhận và xử lý Jira

/flutter-jira-list
        ↓
/flutter-jira-analyze <JIRA-KEY>
        ↓
Implement / Update / Fix
        ↓
Test → Review → DoD → xin phép cập nhật Jira

Mọi thao tác thay đổi Jira cần người dùng xác nhận rõ ràng.

3. Cập nhật feature hiện hữu

/flutter-update-feature <JIRA-KEY hoặc context-path>

Skill thực hiện impact analysis, xác định phạm vi ảnh hưởng, sửa code tương thích với kiến trúc hiện tại và chuyển tiếp sang Test Gate.

4. Chẩn đoán và sửa bug

Logic, crash, state, API  → /flutter-fix-bug
Overflow, constraints     → /flutter-fix-layout-issues

Sau khi sửa phải có regression verification, test evidence, code review và DoD.

5. Phát triển feature mới

Yêu cầu thô → /flutter-get-and-convert-to-standard-rsd
RSD/story   → /flutter-implement-feature

Với RSD lớn cần đầy đủ sáu approval gate, có thể dùng Core /dev-orchestrator nếu đã cài BIDV Core skills.

6. Tiện ích chuyên biệt

| Nhu cầu | Skill | |---|---| | Sinh API layer từ cURL | /flutter-implement-api-from-curl | | Wire API từ Swagger client | /flutter-implement-api-from-swagger | | Tạo data layer | /flutter-implement-data-layer | | Tạo UseCase | /flutter-implement-usecase | | Tạo BLoC feature | /flutter-implement-bloc-feature | | Form và validation | /flutter-building-forms | | Responsive layout | /flutter-build-responsive-layout | | Animation | /flutter-animating-apps | | Cache/offline-first | /flutter-caching-data | | Background task/Isolate | /flutter-handling-concurrency |

Skill chuyên biệt có sửa source vẫn phải đi qua Test → Review → DoD.

Workflow chất lượng bắt buộc

Readiness PASS
      ↓
Implement / Update / Fix
      ↓
Test Evidence PASS
      ↓
Code Review CLEAN
      ↓
Definition of Done DONE
      ↓
User approval
      ↓
Jira transition / Release

Quy tắc chính:

• Code review là read-only; finding phải quay về skill fix/update.
• Mọi source change cần test evidence hoặc lý do N/A được phê duyệt kèm verification thay thế.
• Thay đổi local, rủi ro thấp có thể thực hiện trực tiếp.
• Thay đổi kiến trúc, contract, migration, security, dependency/native/build config hoặc phạm vi lớn phải trình plan và chờ duyệt.
• Không deploy hoặc chuyển Jira sang trạng thái cuối trước khi DoD hoàn tất và người dùng đồng ý.

Tra cứu nhanh

| Nhu cầu | Skill | |---|---| | Xem Jira task | /flutter-jira-list | | Phân tích Jira task | /flutter-jira-analyze | | Nhận diện project hiện hữu | /flutter-detect-project-profile | | Triển khai feature mới | /flutter-implement-feature | | Cập nhật feature | /flutter-update-feature | | Sửa bug | /flutter-fix-bug | | Viết/chạy test và tạo evidence | /flutter-write-unit-test | | Review code | /flutter-code-review | | Kiểm tra Definition of Done | /flutter-dod-check | | Tối ưu hiệu năng | /flutter-review-optimize | | Cấu hình CI/CD | /flutter-ci-cd-deployment | | Ghi nhận convention mới | /flutter-learn |

Danh mục đầy đủ nằm tại skills_template/_meta/skill-map.md.

Greenfield và mature

| | Greenfield | Mature | |---|---|---| | Khi nào | Dự án mới | Dự án đã có code | | Bước đầu | Setup enterprise/basic | Detect project profile | | Code patterns | Preset theo lựa chọn setup | Sinh từ code lân cận và conventions thực tế | | File đã tồn tại | Giữ nguyên nếu không có --force | Giữ nguyên nếu không có --force |

Không chạy enterprise setup end-to-end trên project mature trừ khi thực sự muốn thay đổi kiến trúc và đã duyệt phạm vi tác động.

Cập nhật và gỡ cài đặt

Cài lại phiên bản mới:

npx flutter-ai-flows@latest

Mặc định installer chỉ thêm file còn thiếu. Dùng --force khi muốn đồng bộ lại toàn bộ runtime contracts và skills; lưu ý kiểm tra thay đổi local trong AGENTS.md, profile hoặc learnings trước.

Gỡ thủ công đúng các thư mục đã chọn khi cài, ví dụ:

rm -rf .agents/skills/flutter-*
rm -rf docs/ai-flows

Không xoá AGENTS.md hoặc docs/learnings.md nếu project đang lưu chỉ dẫn riêng trong đó.

Phát triển package

npm install

# Kiểm tra skill references, manifest và workflow contract
npm run verify

# Build bundle, smoke-install đa IDE và chạy toàn bộ test
npm test

Mỗi skill nằm trong skills_template/<skill-name>/SKILL.md; payload riêng nằm trong references/, scripts/ hoặc assets/. Runtime contracts dùng chung nằm trong skills_template/_meta/.