---
description: 📐 Thiết kế đặc tả kỹ thuật trước khi code
---

# /create-spec-architect - Spec Designer

> **Role:** Antigravity Architect - Chỉ thiết kế, KHÔNG code.
> **Output:** `docs/specs/[feature]/` với 2 file (requirements.md, design.md) và init tasks script

---

## Phase 1: Context Check

### 1.1. Verify Project Identity
// turbo
```bash
[ -f ".project-identity" ] && echo "✅ Found" || echo "❌ Missing"
```

### 1.2. Check Existing Specs
// turbo
```bash
[ -d "docs/specs" ] && ls docs/specs/ || echo "No specs yet"
```

---

## Phase 2: Gather Requirements

### 2.1. Ask User
Hỏi người dùng các câu hỏi:
1. **Feature name?** (slug format: `user-profile`, `meal-plan`)
2. **User Story?** "As a [who], I want [what], so that [why]"
3. **Key scenarios?** (Happy path + Edge cases)
4. **Platform?** (iOS/Android/Web/Expo)

### 2.2. Analyze Context
- Đọc `.project-identity` để hiểu tech stack
- Đọc `docs/steering/` nếu có
- Xác định patterns hiện có trong codebase

---

## Phase 3: Create Specs

### 3.1. Create Feature Directory
// turbo
```bash
mkdir -p docs/specs/[feature-name]
```

### 3.2. Detailed Concept/Requirements Template (Theo chuẩn Đẹp Tướng)

**File:** `docs/specs/[feature]/requirements.md`

```markdown
# Concept Document — [Tính Năng/Giao Diện]
> "[Slogan hoặc câu định vị ngắn gọn]"

[⚠️ AI INSTRUCTION: BẮT BUỘC sử dụng cấu trúc cực kỳ chi tiết, dùng ASCII Diagram (Plain text) cho các kiến trúc/luồng xử lý và bảng biểu như template chuẩn.]

## 1. Tầm nhìn & Lý do tồn tại
* **Tóm tắt dự án:** ...
* **Vấn đề được giải quyết:** ...
* **Đối tượng người dùng cốt lõi:** ...

## 2. Triết lý cốt lõi
### 2.1 Các lớp phân tích / Nền tảng (Bắt buộc vẽ ASCII logic block)
```text
┌─────────────────────────────────────────────────┐
│                   [LỚP 1]                       │
├─────────────────────────────────────────────────┤
│                   [LỚP 2]                       │
└─────────────────────────────────────────────────┘
                        ↓
              [ĐỘNG CƠ XỬ LÝ CHÍNH]
```
### 2.2 Nguyên tắc thiết kế tính năng (Tối thiểu 5 nguyên tắc)

## 3. Kiến trúc ứng dụng
### 3.1 Stack kỹ thuật (Bảng ánh xạ UI, AI, DB, BaaS)
### 3.2 Cấu trúc màn hình (Vẽ sơ đồ Folder Tree routing)

## 4. Luồng xử lý cốt lõi (Vẽ ASCII Flowchain logic)

## 5. Onboarding — Mindset & Thiết kế
* Triết lý: Value trước, đăng ký sau
* Cấu trúc Slides (Slide 0 -> 3): Chi tiết animation, thông điệp.
* Design Patterns: Count-up, Stagger, v.v.

## 6. Gợi ý tính năng — Mindset (Logic mapping, Không Generic)
* Đưa ví dụ ❌ Text chung chung vs ✅ Text phân tích chiều sâu.

## 7. Design System
* Palette màu (Bảng Hex + Tên)
* Animation & Icon conventions

## 8. Vòng lặp tăng trưởng & Engagement
* Vẽ ASCII Loop tuần hoàn giữ chân user
* Bảng Trigger Notifications

## 9. Mô hình kinh doanh (Cây tính năng Free vs Premium)
## 10. Nguyên tắc kỹ thuật (Performance, Data flow, Error handling)
## 11. Roadmap (Phase MVP -> Depth -> Growth)
## 12. Điều Không Được Làm (Anti-patterns - 7 quy tắc cấm kỵ)
```

### 3.3. Design Template (Theo chuẩn Đồ Họa & UI)

**File:** `docs/specs/[feature]/design.md`

```markdown
# UI/Visual Design Document — [Tính Năng/Giao Diện]
> "[Slogan hoặc Nguyên tắc chủ đạo của giao diện: "Ví dụ: Mỗi tab một sứ mệnh – không overlap"]"

## 1. Tổng Quan & Metadata
* **Phiên bản & Thời gian:** ...
* **Mục tiêu:** [Lý do thay đổi/Kết quả đồ họa mong muốn]

## 2. Nguyên Tắc Thiết Kế (Design Principles)
1. [Tình trạng hiển thị / Phân cấp Animation theo tier]
2. [Sử dụng hệ thống thông báo/Badge thông minh]

## 3. Đặc Tả Hình Ảnh (Component Specs)
### 3.1 Thông số kỹ thuật (Thẩm mỹ)
* **Kích thước:** [Ví dụ: Height: 60px + SafeArea]
* **Màu sắc & Shadow:** [Mã màu Hex, Elevation, Border]
* **Trạng thái:** [Màu Active/Inactive, Font Weight]

### 3.2 Danh sách Element
* Mô tả chi tiết Icon, Label, Mức hiển thị.

## 4. Chi Tiết Các Màn Hình (Screen Breakdown)
### 4.1 Layout: [Tên Màn Hình]
* Theo chiều dọc:
  - Header / Hero Section
  - Grid / Danh sách
  - Action Buttons (Bottom)
### 4.2 Component Hierarchy (Cấu trúc giao diện)
```text
FeatureView (Root)
├── HeaderComponent
├── ContentSection
└── ActionButtons
```

## 5. Đặc Tả Chuyển Động (Animation & Graphic Logic)
* **Animation Spec:** [Kiểu: Spring, Ease. Damping/Duration cụ thể]
* **Haptic:** [Rung khi chạm/thành công]
* **Badge Graphic Logic:** [Vị trí chấm đỏ, điều kiện nhấp nháy/biến mất]

## 6. Sơ Đồ Routing (Màn Hình)
* **Cấu trúc Thư mục UI:** [Sơ đồ App Router, ví dụ: app/(tabs)/explore]
* Không đi sâu vào Database. Chỉ liệt kê File UI mới.
```
### 3.4. Task Generation (Symphony)
 
**Script:** `docs/specs/[feature]/init_tasks.sh`
 
```bash
#!/bin/bash
 
# Phase A: Foundation
symphony_create_task(title= "Implement [Feature] - A1: Models" --body "File: Domain/Models/[Feature].swift\nValidates: RQ-01"
symphony_create_task(title= "Implement [Feature] - A2: Repository" --body "File: Data/Repositories/[Feature]Repository.swift\nValidates: RQ-01, RQ-02"
 
# Phase B: UI
symphony_create_task(title= "Implement [Feature] - B1: Main View" --body "File: Presentation/[Feature]/[Feature]View.swift\nValidates: RQ-01"
symphony_create_task(title= "Implement [Feature] - B2: Components" --body "File: Presentation/[Feature]/Components/\nValidates: RQ-01"
 
# Phase C: Logic
symphony_create_task(title= "Implement [Feature] - C1: ViewModel" --body "File: Presentation/[Feature]/[Feature]ViewModel.swift\nValidates: RQ-01, RQ-02"
 
# Phase D: Polish
symphony_create_task(title= "Implement [Feature] - D1: Localization" --body "Type: i18n"
symphony_create_task(title= "Implement [Feature] - D2: Accessibility" --body "Type: a11y"
 
# Phase E: Verify
symphony_create_task(title= "Implement [Feature] - E1: Unit Tests" --body "Type: test"
symphony_create_task(title= "Implement [Feature] - E2: Final Review" --body "Type: checkpoint"
```

---

## Phase 4: Review & Confirm

### 4.1. Summary
Sau khi tạo xong, trình bày:
```
📁 Created: docs/specs/[feature]/
├── requirements.md (X requirements, Y criteria)
├── design.md (Component hierarchy, Models, UI specs)
└── init_tasks.sh (Script to create Symphony tasks)

Ready for implementation with /auto-implement
```

### 4.2. Next Steps
- **Implement now:** `/auto-implement docs/specs/[feature]`
- **Review specs:** Người dùng đọc và chỉnh sửa nếu cần
- **Add more detail:** Bổ sung edge cases, security requirements

---

## Rules

1. **NO CODE** - Chỉ viết documentation
2. **COMPLETE** - Đủ 3 files, không thiếu
3. **TRACEABLE** - Mỗi task link về requirement
4. **ACTIONABLE** - Task đủ chi tiết để AI khác execute

---

**Success:** Bộ specs đầy đủ, sẵn sàng cho `/auto-implement`.