@leejungkiin/awkit 1.1.1 → 1.1.3

package/skills/symphony-enforcer/SKILL.md

@@ -4,12 +4,13 @@ description: |
   Mandatory Symphony checkpoint system. Ensures AI never forgets to create,
   update, or complete tasks in Symphony. Enforces progress reporting at every
   milestone and auto-detects task completion without waiting for user confirmation.
+  v3.1: Pre-Plan Gate, Auto-Lifecycle, Auto-Next, Atomic Git Commits.
 metadata:
   stage: core
-  version: "2.0"
-  replaces: null
+  version: "3.1"
+  replaces: "v2.0"
   requires: symphony-orchestrator
-  tags: [symphony, enforcement, checkpoint, task-lifecycle, core]
+  tags: [symphony, enforcement, checkpoint, task-lifecycle, core, spec-first, auto-next]
 agent: Symphony Enforcer
 allowed-tools:
   - symphony_create_task
@@ -23,11 +24,15 @@ invocation-type: auto
 priority: 1
 ---
 
-# Symphony Enforcer — Mandatory Task Lifecycle Checkpoints
+# Symphony Enforcer v3.1 — Spec-First + Auto-Lifecycle + Auto-Next + Atomic Commits
 
 > **Purpose:** Đảm bảo AI KHÔNG BAO GIỜ quên cập nhật Symphony.
-> **Method:** Strict sequential protocol + 4 Trigger Points.
-> **Key Principle:** AI tự detect completion — user KHÔNG CẦN nói "xong".
+> **Key Changes v3.1:**
+> - **Pre-Plan Gate**: Đọc spec trước khi plan, hỏi user về constraints
+> - **Auto-Lifecycle**: Liên kết task_boundary ↔ Symphony tự động
+> - **Auto-Next**: BẮT BUỘC gợi ý next steps sau mỗi task done
+> - **Atomic Git Commits**: Tự động commit sau mỗi task done (NEW v3.1)
+> **Principle:** AI tự detect completion — user KHÔNG CẦN nói "xong".
 
 ---
 
@@ -35,34 +40,28 @@ priority: 1
 
 ```
 KHÔNG CÓ NGOẠI LỆ:
-- Mọi code/debug/plan task PHẢI qua STRICT STARTUP PROTOCOL (5 steps)
+- Mọi code/debug/plan task PHẢI qua STRICT STARTUP PROTOCOL
 - Mọi milestone PHẢI report progress
 - AI tự detect completion và auto-complete task
+- Task done → PHẢI atomic git commit trước khi suggest next
+- Kết thúc task PHẢI kèm next suggestion
 - BỎ QUA BẤT KỲ STEP NÀO = VI PHẠM
 ```
 
 ---
 
-## 🔒 STRICT STARTUP PROTOCOL (BẮT BUỘC — KHÔNG ĐƯỢC BỎ QUA)
+## 🔒 STRICT STARTUP PROTOCOL (BẮT BUỘC)
 
-Mỗi khi bắt đầu task code/debug/plan, AI PHẢI đi qua **4 steps tuần tự**.
-KHÔNG được bắt đầu work cho đến khi TẤT CẢ 4 steps đều ✅.
-
-> **Note:** Symphony server + project registration đã được `symphony-orchestrator` xử lý
-> trước khi skill này chạy. Enforcer chỉ lo `.project-identity` → Brain → Task.
+Mỗi khi bắt đầu task code/debug/plan, AI PHẢI đi qua **5 steps tuần tự**.
+KHÔNG được bắt đầu work cho đến khi TẤT CẢ steps ✅.
 
 ### Step 1: Project Identity — `.project-identity`
 
 ```
-→ Kiểm tra: file .project-identity có tồn tại trong project root?
-→ CÓ  → Đọc projectId, projectName từ file
-→ KHÔNG → ⛔ DỪNG LẠI. Hỏi user hoặc tạo .project-identity:
-         {
-           "id": "project-slug",
-           "name": "Project Name",
-           "path": "/absolute/path"
-         }
-→ Output: "📋 Step 1/4: Project Identity ✅ — {projectId}"
+→ Kiểm tra: file .project-identity có tồn tại?
+→ CÓ  → Đọc projectId, projectName
+→ KHÔNG → ⛔ DỪNG. Hỏi user hoặc tạo .project-identity.
+→ Output: "📋 Step 1/5: Project Identity ✅ — {projectId}"
 ```
 
 ### Step 2: NeuralMemory Brain — Switch brain
@@ -70,42 +69,74 @@ KHÔNG được bắt đầu work cho đến khi TẤT CẢ 4 steps đều ✅.
 ```
 → nmem brain use <projectId>
 → nmem_recap(level=1) — load context
-→ Output: "🧠 Step 2/4: Brain ✅ — switched to {projectId}"
+→ Output: "🧠 Step 2/5: Brain ✅ — switched to {projectId}"
+```
+
+### Step 3: Spec Alignment — Đọc Project Spec (NEW v3.0)
+
+```
+→ Kiểm tra: docs/specs/PROJECT.md tồn tại?
+→ CÓ  → Đọc silent: PROJECT.md + TECH-SPEC.md + REQUIREMENTS.md
+       → Extract constraints liên quan đến task hiện tại
+       → NẾU PLANNING mode:
+          - Hỏi user 1-3 câu về constraints/UX cụ thể của feature
+          - Ví dụ: "Feature này cần offline support không?"
+          - Ví dụ: "UI nên dạng list hay cards?"
+       → Output: "📐 Step 3/5: Spec Aligned ✅"
+→ KHÔNG → Skip (project chưa /init) → "📐 Step 3/5: No spec — skipped"
 ```
 
-### Step 3: Symphony Task — Tạo hoặc nhận task
+> **Quan trọng:** Nếu TECH-SPEC.md có "Constraints & Non-Negotiables",
+> AI PHẢI tuân thủ chúng trong implementation_plan.md.
+
+### Step 4: Symphony Task — Tạo hoặc nhận task
 
 ```
 → symphony_available_tasks(filter="my") → check active tasks
 → CÓ task in_progress phù hợp → dùng tiếp
 → CÓ task ready phù hợp → symphony_claim_task
-→ KHÔNG CÓ → symphony_create_task(title, description)
-            → symphony_claim_task(new_task_id)
-→ Lưu task_id cho TP1-TP3
-→ Output: "🎯 Step 3/4: Task ✅ — #sym-XYZ claimed"
+→ KHÔNG CÓ → symphony_create_task(title) → symphony_claim_task(new_id)
+→ Lưu task_id cho TP1-TP4
+→ Output: "🎯 Step 4/5: Task ✅ — #sym-XYZ claimed"
 ```
 
-### Step 4: Confirmation Block — Hiển thị tổng kết
+### Step 5: Confirmation Block
 
 ```
 🚦 STARTUP PROTOCOL COMPLETE
 ══════════════════════════════════════
   Step 1: 📋 Project Identity  ✅  {projectId}
   Step 2: 🧠 NeuralMemory      ✅  brain: {projectId}
-  Step 3: 🎯 Task              ✅  #sym-XYZ — "{title}"
-  Step 4: ✅ READY TO WORK
+  Step 3: 📐 Spec Alignment     ✅  {constraints_count} constraints loaded
+  Step 4: 🎯 Task              ✅  #sym-XYZ — "{title}"
+  Step 5: ✅ READY TO WORK
 ══════════════════════════════════════
 ```
 
-> ⛔ **Nếu KHÔNG hiển thị confirmation block = VI PHẠM — KHÔNG ĐƯỢC BẮT ĐẦU WORK**
+> ⛔ **Nếu KHÔNG hiển thị confirmation block = VI PHẠM**
+
+---
+
+## Auto-Lifecycle: task_boundary ↔ Symphony (NEW v3.0)
+
+```
+LIÊN KẾT TỰ ĐỘNG:
+- task_boundary(PLANNING)  → symphony_create_task (nếu chưa có)
+- task_boundary(EXECUTION) → symphony_report_progress(40%)
+- task_boundary(VERIFICATION) → symphony_report_progress(80%)
+- notify_user(BlockedOnUser=false) → TRIGGER TP2 (completion check)
+```
+
+AI PHẢI giữ `current_task_id` xuyên suốt session.
+Mỗi lần gọi `task_boundary` với mode mới → đồng thời report progress.
 
 ---
 
-## Trigger Points (Trong quá trình làm việc)
+## Trigger Points
 
-### TP1: Progress Milestone — Tại mỗi giai đoạn quan trọng
+### TP1: Progress Milestone
 
-**Khi nào:** Bất kỳ milestone nào xảy ra:
+**Khi nào:** Milestone xảy ra:
 - Chuyển mode: PLANNING → EXECUTION → VERIFICATION
 - Gọi `notify_user` (TRƯỚC khi gọi)
 - Hoàn thành 1 component/file lớn
@@ -116,11 +147,11 @@ KHÔNG được bắt đầu work cho đến khi TẤT CẢ 4 steps đều ✅.
 symphony_report_progress(
   task_id=current_task,
   progress=estimated_percentage,
-  last_action="mô tả ngắn milestone"
+  last_action="mô tả ngắn"
 )
 ```
 
-**Progress Estimation Guide:**
+**Progress Guide:**
 ```
   10% — Task created, đang research/đọc code
   25% — Implementation plan approved
@@ -137,7 +168,7 @@ symphony_report_progress(
 
 ---
 
-### TP2: Task Complete — AI tự detect hoàn thành
+### TP2: Task Complete — Auto-detect
 
 **Khi nào:** AI detect ≥2/4 completion signals:
 
@@ -145,7 +176,7 @@ symphony_report_progress(
 Signal 1: Final notify_user với BlockedOnUser=false
 Signal 2: Walkthrough artifact đã tạo
 Signal 3: Tất cả checklist items trong task.md đã [x]
-Signal 4: Verification pass (tests chạy OK, build thành công)
+Signal 4: Verification pass (tests OK, build OK)
 ```
 
 **Action:**
@@ -155,12 +186,55 @@ Signal 4: Verification pass (tests chạy OK, build thành công)
      summary="mô tả ngắn kết quả"
    )
 2. Hiển thị: "✅ SYM #sym-XYZ — Done"
-3. KHÔNG cần chờ user confirm
+3. → TRIGGER TP2.5 (Atomic Git Commit)
+4. → TRIGGER TP4 (Auto-Next) NGAY LẬP TỨC
 ```
 
-**Nếu user thấy chưa xong:**
-- User chỉ cần nói → AI reopen task và tiếp tục
-- Không phải lỗi — đây là flow bình thường
+---
+
+### TP2.5: Atomic Git Commit (NEW v3.1 — BẮT BUỘC)
+
+**Khi nào:** Ngay sau TP2 (task completed), TRƯỚC TP4 (Auto-Next).
+Chỉ trigger khi task có code changes (có files_changed).
+
+**Action:**
+```
+1. Kiểm tra: git status --porcelain
+   → Nếu KHÔNG CÓ changes → skip ("📝 No code changes to commit")
+   → Nếu CÓ changes → tiếp tục
+
+2. Xác định commit type từ task context:
+   → PLANNING/EXECUTION mới → "feat"
+   → Debug/fix → "fix"
+   → Refactor/cleanup → "refactor"
+   → Docs/specs → "docs"
+
+3. Tạo commit message theo Conventional Commits:
+   → Format: "{type}({scope}): {task_summary_ngắn}"
+   → scope = module/feature name (từ task title)
+   → Ví dụ: "feat(auth): implement login with Firebase"
+   → Ví dụ: "fix(camera): resolve 10s delay on tab switch"
+
+4. Stage & commit:
+   → git add <files_changed từ symphony_complete_task>
+   → Nếu không rõ files → git add -A (thận trọng)
+   → git commit -m "{message}"
+
+5. Hiển thị:
+   🔀 Atomic Commit: {short_hash} — "{message}"
+   📁 {N} files changed
+
+6. ⚠️ KHÔNG AUTO-PUSH:
+   → Chỉ commit local
+   → Push = yêu cầu user confirm hoặc dùng /smart-git-ops
+```
+
+**Enforcement:**
+- ❌ KHÔNG được auto-push (chỉ commit local)
+- ❌ KHÔNG được commit nếu có unresolved merge conflicts
+- ❌ KHÔNG được commit files ngoài scope task
+- ✅ NÊN commit ngay khi task done — đừng để accumulate
+- ✅ Mỗi task = 1 commit (atomic, traceable)
 
 ---
 
@@ -173,14 +247,69 @@ Signal 4: Verification pass (tests chạy OK, build thành công)
 
 **Action:**
 ```
-symphony_abandon_task(
-  task_id=current_task,
-  reason="mô tả lý do"
-)
+symphony_abandon_task(task_id=current_task, reason="...")
 ```
 
 ---
 
+### TP4: Auto-Next Suggestion (NEW v3.0 — BẮT BUỘC)
+
+**Khi nào:** Ngay sau TP2 (task completed). KHÔNG ĐƯỢC BỎ QUA.
+
+**Action:**
+```
+1. ĐỌC projectId từ .project-identity (đã có từ Step 1)
+2. symphony task list -P <projectId> -s ready (CHỈ tasks cùng project)
+   ⚠️ TUYỆT ĐỐI KHÔNG dùng filter="ready" không có project filter
+   ⚠️ Dùng CLI: symphony task list -P <projectId> -s ready
+   ⚠️ Hoặc MCP: symphony_available_tasks + parse project field
+3. Lọc top 2-3 ready tasks theo priority
+4. Present cho user:
+
+   ➡️ NEXT STEPS ({projectName})
+   ─────────────────────────────────
+   📋 #sym-A1 — Auth Module (P0, ready)
+   📋 #sym-A2 — Dashboard UI (P1, ready)
+   
+   Bạn muốn tiếp tục với task nào?
+
+5. Nếu KHÔNG CÓ ready tasks trong project hiện tại:
+   "✨ Không còn task ready cho {projectName}! Tạo task mới hoặc chuyển phase."
+```
+
+**Enforcement:**
+- ❌ KHÔNG được kết thúc conversation mà KHÔNG present next suggestion
+- ❌ KHÔNG được show tasks từ project khác
+- Nếu quên filter projectId → vi phạm nghiêm trọng (cross-project contamination)
+
+---
+
+## XML Task Spec trong Implementation Plans (NEW v3.0)
+
+Khi PLANNING mode tạo `implementation_plan.md`, MỖI task NÊN dùng XML format:
+
+```xml
+<task type="auto">
+  <name>Task name</name>
+  <files>file1.swift, file2.swift</files>
+  <spec_ref>REQUIREMENTS.md § R1</spec_ref>
+  <depends_on>none</depends_on>
+  <action>Specific instructions</action>
+  <verify>How to verify completion</verify>
+  <done>Expected final state</done>
+</task>
+```
+
+Template đầy đủ: `~/.gemini/antigravity/templates/specs/task-spec-template.xml`
+
+Lợi ích:
+- AI parse chính xác hơn markdown
+- `<spec_ref>` ép buộc liên kết với project spec
+- `<depends_on>` cho phép wave grouping (parallel execution)
+- `<verify>` built-in verification step
+
+---
+
 ## Ngoại lệ — Khi nào KHÔNG cần Startup Protocol
 
 ```
@@ -193,8 +322,6 @@ symphony_abandon_task(
 
 ## Sync Block Format
 
-Mỗi khi sync, AI hiển thị dòng ngắn:
-
 ```
 🎯 SYM #sym-XYZ — 40% → 70% "Implemented auth module"
 ```
@@ -202,6 +329,7 @@ Mỗi khi sync, AI hiển thị dòng ngắn:
 Nếu completed:
 ```
 ✅ SYM #sym-XYZ — Done "Auth module with tests"
+➡️ Next: #sym-A1 — Dashboard UI (P1)
 ```
 
 ---
@@ -211,17 +339,24 @@ Nếu completed:
 | Tình huống | Xử lý |
 |-----------|--------|
 | Project chưa có .project-identity | ⛔ Dừng, tạo file trước |
+| Project chưa có docs/specs/ | Skip Step 3, tiếp tục |
 | Symphony server down | Start server, retry. Nếu fail → warning + tiếp tục |
 | User follow-up nhỏ sau task done | ≤2 file changes → không cần task mới |
 | Nhiều task cùng lúc | Track task_id riêng, report đúng task |
 | User reopen task đã complete | Claim lại, resume từ progress cuối |
+| Không có ready tasks cho TP4 | Gợi ý tạo phase tiếp theo |
 
 ---
 
 ## Learnings
 
 - AI quên Symphony vì nó là "side task" — strict protocol biến nó thành MAIN flow
-- Step-by-step sequential = AI không thể skip — mỗi step phụ thuộc step trước
-- Confirmation block = visual proof cho user thấy đã qua protocol
-- User KHÔNG muốn nói "xong" — AI phải tự detect completion signals
-- Progress % không cần chính xác — rough estimate đủ tốt
+- Step-by-step sequential = AI không thể skip
+- Confirmation block = visual proof cho user
+- User KHÔNG muốn nói "xong" — AI phải tự detect completion
+- Pre-Plan Discussion giúp plan đúng hướng từ đầu (learned from GSD)
+- XML task format chính xác hơn markdown cho AI parsing (learned from GSD)
+- Auto-Next giữ momentum — user không cần tự tìm task tiếp theo
+- Spec alignment tránh plan bị lệch khỏi project constraints
+- Atomic commits giúp rollback chính xác — 1 task = 1 commit (learned from GSD)
+- KHÔNG auto-push — chỉ commit local, push cần user confirm

package/templates/specs/PROJECT.md

@@ -0,0 +1,50 @@
+# {{PROJECT_NAME}} — Project Spec
+
+> Created: {{DATE}} | Last Updated: {{DATE}}
+
+## Vision
+
+[1-2 sentences describing the core purpose and value proposition of this project.]
+
+## Goals
+
+1. **Primary Goal:** [What is the #1 thing this project must achieve?]
+2. **Secondary Goal:** [What else matters?]
+3. **Stretch Goal:** [Nice-to-have if time permits]
+
+## Target Audience
+
+| Segment | Description | Pain Point |
+|---------|-------------|------------|
+| Primary | [Who is the main user?] | [What problem do they face?] |
+| Secondary | [Other user group] | [Their specific need] |
+
+## Success Metrics
+
+- [ ] **Metric 1:** [e.g., 1000 DAU within 3 months]
+- [ ] **Metric 2:** [e.g., 4.5+ App Store rating]
+- [ ] **Metric 3:** [e.g., < 2s cold start time]
+
+## Scope
+
+### In Scope (v1)
+- Feature A
+- Feature B
+- Feature C
+
+### Out of Scope (v1)
+- Feature X (deferred to v2)
+- Feature Y (requires further research)
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| [e.g., Backend] | [e.g., Firebase] | [Why this choice] |
+| [e.g., State Mgmt] | [e.g., SwiftUI @Observable] | [Why] |
+
+## References
+
+- [Design inspiration link]
+- [Competitor analysis link]
+- [Technical reference]

package/templates/specs/ROADMAP.md

@@ -0,0 +1,79 @@
+# {{PROJECT_NAME}} — Roadmap
+
+> Created: {{DATE}} | Last Updated: {{DATE}}
+> Source of truth: PROJECT.md
+
+## Overview
+
+| Phase | Title | Status | Priority |
+|-------|-------|--------|----------|
+| 1 | [Phase title] | 🔲 Not Started | P0 |
+| 2 | [Phase title] | 🔲 Not Started | P1 |
+| 3 | [Phase title] | 🔲 Not Started | P2 |
+
+---
+
+## Phase 1: [Title] — [Target Date]
+
+**Goal:** [What this phase delivers in 1 sentence]
+
+**Requirements Covered:** REQUIREMENTS.md § R1, R2
+
+### Features
+- [ ] Feature 1.1 — [Short description]
+- [ ] Feature 1.2 — [Short description]
+- [ ] Feature 1.3 — [Short description]
+
+### Dependencies
+- [External service / API / library needed]
+
+### Definition of Done
+- [ ] All features functional
+- [ ] Core tests passing
+- [ ] No P0 bugs
+
+---
+
+## Phase 2: [Title] — [Target Date]
+
+**Goal:** [What this phase delivers]
+
+**Requirements Covered:** REQUIREMENTS.md § R3, R4
+
+### Features
+- [ ] Feature 2.1
+- [ ] Feature 2.2
+
+### Dependencies
+- Phase 1 complete
+
+### Definition of Done
+- [ ] All features functional
+- [ ] Integration tests passing
+
+---
+
+## Phase 3: [Title] — [Target Date]
+
+**Goal:** [What this phase delivers]
+
+**Requirements Covered:** REQUIREMENTS.md § R5+
+
+### Features
+- [ ] Feature 3.1
+- [ ] Feature 3.2
+
+### Definition of Done
+- [ ] All features functional
+- [ ] Performance benchmarks met
+- [ ] Ready for production release
+
+---
+
+## Milestone Tracking
+
+| Milestone | Target | Actual | Status |
+|-----------|--------|--------|--------|
+| MVP (Phase 1) | [Date] | — | 🔲 |
+| Beta (Phase 2) | [Date] | — | 🔲 |
+| Launch (Phase 3) | [Date] | — | 🔲 |

package/templates/specs/TECH-SPEC.md

@@ -0,0 +1,81 @@
+# {{PROJECT_NAME}} — Technical Specification
+
+> Created: {{DATE}} | Last Updated: {{DATE}}
+> Companion to: PROJECT.md, REQUIREMENTS.md
+
+## Architecture Overview
+
+[1-2 sentences describing the high-level architecture pattern being used.]
+
+```
+[Simple ASCII diagram of the system architecture]
+```
+
+## Tech Stack
+
+| Layer | Technology | Version | Rationale |
+|-------|-----------|---------|-----------|
+| Language | [e.g., Swift] | [e.g., 6.0] | [Why] |
+| Framework | [e.g., SwiftUI] | [e.g., iOS 17+] | [Why] |
+| Backend | [e.g., Firebase] | [e.g., v11] | [Why] |
+| Database | [e.g., GRDB] | [e.g., 7.x] | [Why] |
+| AI/ML | [e.g., Gemini 2.5] | — | [Why] |
+| Analytics | [e.g., Firebase Analytics] | — | [Why] |
+
+## Architecture Decisions
+
+### AD-1: [Decision Title]
+
+**Context:** [What problem or question prompted this decision?]
+**Decision:** [What was decided]
+**Consequences:** [What trade-offs or implications does this have?]
+**Alternatives Considered:** [What else was evaluated?]
+
+### AD-2: [Decision Title]
+
+**Context:** [...]  
+**Decision:** [...]  
+**Consequences:** [...]
+
+## Patterns & Conventions
+
+### Code Organization
+```
+[Folder structure with descriptions]
+```
+
+### Naming Conventions
+- Files: [e.g., PascalCase for types, camelCase for functions]
+- Modules: [e.g., feature-based grouping]
+- Tests: [e.g., Test suffix, describe/it pattern]
+
+### Error Handling
+[Standard error handling approach for the project]
+
+### State Management
+[How state is managed across the app]
+
+## Constraints & Non-Negotiables
+
+> [!CAUTION]
+> These constraints MUST be followed in ALL implementation plans.
+
+1. **[Constraint 1]:** [e.g., All network calls must have offline fallback]
+2. **[Constraint 2]:** [e.g., No hardcoded strings — use localization]
+3. **[Constraint 3]:** [e.g., All AI calls must respect quota limits]
+4. **[Constraint 4]:** [e.g., Minimum iOS 17 / Android 14 support]
+
+## Security Requirements
+
+- Authentication: [e.g., Firebase Auth with Apple/Google Sign-In]
+- Data at rest: [e.g., Keychain for sensitive data]
+- API keys: [e.g., Firebase Remote Config, never hardcoded]
+
+## Performance Targets
+
+| Metric | Target | How to Measure |
+|--------|--------|----------------|
+| Cold start | < [X]s | Instruments / Profiler |
+| API response | < [X]ms | Network logs |
+| Memory | < [X]MB | Memory profiler |
+| App size | < [X]MB | Archive build |

package/templates/specs/task-spec-template.xml

@@ -0,0 +1,65 @@
+<!-- 
+  AWF Task Spec Template (XML Format)
+  
+  Usage: Copy this structure into implementation_plan.md for each task.
+  AI parses these blocks precisely during EXECUTION mode.
+  
+  Attributes:
+    type="auto"   → AI executes without user interaction
+    type="manual" → Requires user action (e.g., config, credentials)
+    
+  Elements:
+    <name>       → Short task title
+    <files>      → Comma-separated list of files to create/modify
+    <spec_ref>   → Reference to REQUIREMENTS.md or TECH-SPEC.md section
+    <depends_on> → Task names this depends on (for wave grouping)
+    <action>     → Specific implementation instructions
+    <verify>     → Command or check to verify task completion
+    <done>       → Expected final state description
+-->
+
+<!-- Example: Single independent task -->
+<task type="auto">
+  <name>Create User model</name>
+  <files>Models/User.swift, Models/UserRepository.swift</files>
+  <spec_ref>REQUIREMENTS.md § R1, TECH-SPEC.md § AD-1</spec_ref>
+  <depends_on>none</depends_on>
+  <action>
+    Create User struct with Codable conformance.
+    Implement UserRepository with GRDB persistence.
+    Follow offline-first pattern from TECH-SPEC.md.
+  </action>
+  <verify>Unit test: UserRepositoryTests — insert, fetch, delete pass</verify>
+  <done>User model persists to local DB with full CRUD</done>
+</task>
+
+<!-- Example: Dependent task -->
+<task type="auto">
+  <name>Create login endpoint</name>
+  <files>Services/AuthService.swift, ViewModels/LoginViewModel.swift</files>
+  <spec_ref>REQUIREMENTS.md § R2</spec_ref>
+  <depends_on>Create User model</depends_on>
+  <action>
+    Use Firebase Auth for authentication.
+    Store session in Keychain per TECH-SPEC.md § Security.
+    Handle offline: queue login attempt, retry on connectivity.
+  </action>
+  <verify>Login with test credentials returns valid session token</verify>
+  <done>User can log in; session persists across app restarts</done>
+</task>
+
+<!-- Example: Manual task -->
+<task type="manual">
+  <name>Configure Firebase project</name>
+  <files>GoogleService-Info.plist</files>
+  <spec_ref>TECH-SPEC.md § Tech Stack</spec_ref>
+  <depends_on>none</depends_on>
+  <action>
+    User must:
+    1. Create Firebase project at console.firebase.google.com
+    2. Download GoogleService-Info.plist
+    3. Add to Xcode project root
+  </action>
+  <verify>FirebaseApp.configure() succeeds without crash</verify>
+  <done>Firebase SDK initialized on app launch</done>
+</task>