@leejungkiin/awkit 1.4.0 → 1.4.2

package/skills/symphony-enforcer/SKILL.md

@@ -4,13 +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.5: UI-First Three-Phase Execution with User Test Checkpoints.
+  v3.7: UI-First Three-Phase Execution with Auto Device Checkpoints (Maestro).
 metadata:
   stage: core
-  version: "3.6"
-  replaces: "v3.5"
+  version: "3.7"
+  replaces: "v3.6"
   requires: symphony-orchestrator
-  tags: [symphony, enforcement, checkpoint, task-lifecycle, core, spec-first, auto-next, kiro, ui-first, user-test]
+  tags: [symphony, enforcement, checkpoint, task-lifecycle, core, spec-first, auto-next, kiro, ui-first, user-test, maestro, automated-verification]
 agent: Symphony Enforcer
 allowed-tools:
   - symphony_create_task
@@ -24,13 +24,13 @@ invocation-type: auto
 priority: 1
 ---
 
-# Symphony Enforcer v3.6 — UI-First Three-Phase Execution + Legacy Cleanup
+# Symphony Enforcer v3.7 — UI-First Three-Phase Execution + Auto Device Checkpoints
 
 > **Purpose:** Đảm bảo AI KHÔNG BAO GIỜ quên cập nhật Symphony.
-> **Key Changes v3.6:**
+> **Key Changes v3.7:**
 > - **Step 0.5: Legacy Artifact Cleanup**: Auto-detect stale `.symphony/tasks.json` and warn user
-> - **Gate 4 Three-Phase Execution**: Phase A (Infra) → Phase B (UI Shell + User Test) → Phase C (Logic + User Test)
-> - **TP1.7: User Test Checkpoint**: Trigger dừng lại cho user test trên device thật
+> - **Gate 4 Three-Phase Execution**: Phase A (Infra) → Phase B (UI Shell + Auto Check) → Phase C (Logic + Auto Check)
+> - **TP1.7: Auto Device Checkpoint (ADC)**: Tự động build & quét UI bằng Maestro MCP thay vì chờ user test thủ công
 > - **UI-First Task Ordering**: UI tasks PHẢI đi trước logic tasks trong Symphony
 > - Kế thừa tất cả features v3.5 (Kiro, Completion Status, Design Compliance).
 > **Principle:** AI tự detect completion — user KHÔNG CẦN nói "xong".
@@ -163,8 +163,8 @@ LIÊN KẾT TỰ ĐỘNG:
 
 THREE-PHASE MAPPING (Gate 4 — COMPLEX tasks với UI):
 - Phase A done (build OK)     → report_progress(25%) + checkpoint build
-- Phase B done (UI mock)      → report_progress(45%) + TRIGGER TP1.7 (User Test)
-- Phase C per-feature done    → report_progress(50-85%) + TRIGGER TP1.7 (User Test)
+- Phase B done (UI mock)      → report_progress(45%) + TRIGGER TP1.7 (Auto Device Checkpoint)
+- Phase C per-feature done    → report_progress(50-85%) + TRIGGER TP1.7 (Auto Device Checkpoint)
 - Phase C all features done   → report_progress(90%) → Gate 5
 ```
 
@@ -217,10 +217,10 @@ Khi kích hoạt Three-Phase, AI PHẢI hiển thị:
    → {list tasks for Phase A}
 🎨 Phase B: UI Shell (Mock Data)
    → {list tasks for Phase B}
-   → 🧪 USER TEST sau phase này
+   → 🧪 AUTO DEVICE TEST (Maestro) sau phase này
 ⚡ Phase C: Logic Integration
    → {list tasks for Phase C}
-   → 🧪 USER TEST mỗi feature
+   → 🧪 AUTO DEVICE TEST (Maestro) mỗi feature
 ══════════════════════════════════════
 Bắt đầu Phase A...
 ```
@@ -241,13 +241,19 @@ auto_triggers:
   phase_b_to_checkpoint:
     signal: Tất cả [UI] tasks đã done
     action: |
-      - ⛔ DẪNG CODE NGAY LẬP TỨC
-      - TRIGGER TP1.7 (User Test Checkpoint)
-      - CHỊ user confirm "✅ OK" trước khi làm bất cứ gì khác
-      - KHÔNG được tự ý skip bước này
+      - ⛔ TRIGGER TP1.7 (Checkpoint)
+      - Đọc `.project-identity` -> `autoVerification`
+      - NẾU `true`: 
+        + Chạy Auto Build → check exit code 0
+        + Dùng mcp_maestro_launch_app và take_screenshot
+        + NẾU fail → DỪNG (notify_user BlockedOnUser=true)
+        + NẾU pass → Báo cáo Screenshot (BlockedOnUser=false) và làm tiếp Phase C
+      - NẾU `false` (default):
+        + DỪNG VÀ CHỜ user test thủ công (notify_user BlockedOnUser=true)
+        + CHỜ user xác nhận "OK" mới đi tiếp Phase C
 
   checkpoint_to_phase_c:
-    signal: User confirmed "✅" hoặc "OK"
+    signal: Build success & App launched (autoVerification=true) HOẶC User confirmed "OK" (autoVerification=false)
     action: |
       - Set phase_b_confirmed = true
       - Set current_phase = "C"
@@ -265,16 +271,16 @@ auto_triggers:
 
 ```
 ❌ VI PHạM NẶNG:
-  - Code logic (Phase C) khi phase_b_confirmed = false
+  - Code logic (Phase C) khi phase_b_confirmed = false (chưa pass Phase B checkpoint)
   - Skip Phase Announcement Block
-  - Code UI và Logic lẫn lộn trong cùng 1 lượt (phải tách rõ phase)
-  - Tự giả vờ user confirm để skip checkpoint
-  - Không hiển thị Phase Announcement khi Three-Phase activated
+  - Bỏ qua TP1.7
+  - Chạy Auto-verification khi `autoVerification: false` (bỏ qua thủ công)
+  - Chờ user test thủ công khi `autoVerification: true` (lười setup auto)
 
 ✅ BẮT BUỘC:
   - Luôn announce phase transition rõ ràng
-  - Luôn tạo hướng dẫn test CỤ THỂ (không chung chung)
-  - Luôn dùng notify_user(BlockedOnUser=true) cho checkpoints
+  - Luôn đọc `autoVerification` trong `.project-identity` trước khi trigger check.
+  - Gắn BlockedOnUser = true cho mode manual, false cho mode auto.
   - Ghi lại phase state vào NeuralMemory khi chuyển phase
 ```
 
@@ -360,78 +366,40 @@ File patterns:
 
 ---
 
-### TP1.7: User Test Checkpoint (NEW v3.5 — Gate 4 Three-Phase)
+### TP1.7: Flexible Checkpoint (Manual v/s Auto) (UPDATE v3.7)
 
-**Khi nào:** Trigger ở 2 thời điểm chính trong Gate 4:
+**Cấu hình Mode Verification:**
+Quy trình Verification được quyết định bởi thuộc tính `"autoVerification"` trong `.project-identity`:
+- `{"autoVerification": true}` → **Auto Device Checkpoint (ADC)**: Dùng Maestro tự build & chụp ảnh screenshot. Tiến thẳng sang bước tiếp (BlockedOnUser=false).
+- `{"autoVerification": false}` (hoặc không khai báo) → **Manual Checkpoint**: Dừng lại chờ user test thủ công (BlockedOnUser=true). Đây là **MẶC ĐỊNH an toàn**.
+
+**Khi nào trigger TP1.7:**
 
 1. **Phase B → C Transition (BẮT BUỘC cho COMPLEX):**
-   - ALL UI screens đã code xong với mock data
-   - Navigation hoạt động full flow
-   - App build và chạy OK trên emulator/device
+   - ALL UI screens đã code xong
 
 2. **Sau mỗi feature trong Phase C (COMPLEX tasks):**
-   - Feature X đã thay mock bằng real data
-   - Feature works end-to-end trên device
-
-**Điều kiện kích hoạt:**
-```
-COMPLEX + có UI component → BẮT BUỘC TP1.7
-MODERATE + có UI component → OPTIONAL (recommend cho hardware features: camera, GPS, sensors)
-TRIVIAL → SKIP
-Backend-only tasks → SKIP
-```
+   - Feature X đã code xong logic
 
-**Action:**
+**Action (Tùy theo Mode):**
 ```
 1. Report progress trước: symphony_report_progress(current_task, progress)
+2. Kiểm tra cờ `autoVerification` trong .project-identity.
 
-2. Present User Test Checkpoint:
-
-   🧪 USER TEST CHECKPOINT #{N}
-   ══════════════════════════════════════
-   📱 Phase: {B|C} — {phase_name}
-   📋 Đã code xong: {summary of completed work}
-   📁 Files changed: {N} files
-   
-   🔍 Hướng dẫn test:
-     1. {step 1 — cụ thể, actionable}
-     2. {step 2 — expected behavior}
-     3. {step 3 — edge case to check}
-   
-   ⏳ Anh test xong reply:
-     ✅ OK — tiếp tục
-     ⚠️ Issue: {mô tả} — tôi sẽ fix trước khi đi tiếp
-   ══════════════════════════════════════
-
-3. Gọi notify_user(BlockedOnUser=true) — DỪNG và CHỜ user response
-
-4. User response handling:
-   → "OK" / "✅" → Tiếp tục phase tiếp / feature tiếp
-   → "Issue: ..." → Fix issue → re-run checkpoint
-   → "Skip" → Ghi note concern, tiếp tục (DONE_WITH_CONCERNS later)
-```
-
-**Test Guidance Generation:**
-```
-AI PHẢI tạo hướng dẫn test CỤ THỂ cho từng checkpoint:
-
-Phase B Examples (UI):
-  - "Mở app → bấm tab Health → xem Dashboard có hiển thị 4 cards không?"
-  - "Quay ngang màn hình → layout có bể không?"
-  - "Bấm nút Camera → xem preview có xuất hiện không?"
+=== TRƯỜNG HỢP 1: autoVerification = false (Default Manual) ===
+   - Announce "🧪 MANUAL USER TEST CHECKPOINT #{N}"
+   - Đưa hướng dẫn test cụ thể (e.g. "Mở app -> Bấm nút A -> Xem kết quả B")
+   - Gọi notify_user(BlockedOnUser=true) — DỪNG và CHỜ user response
+   - Chỉ đi tiếp khi user reply "OK".
 
-Phase C Examples (Logic):
-  - "Mở Health Dashboard → data thật có load lên không? (nếu có wifi)"
-  - "Chụp ảnh thức ăn → kết quả AI có trả về trong 5s không?"
-  - "Bấm Save → quay lại list → record mới có xuất hiện không?"
+=== TRƯỜNG HỢP 2: autoVerification = true (Auto Maestro) ===
+   - Chạy Auto Build
+   - Chạy mcp_maestro_launch_app, mcp_maestro_take_screenshot
+   - Announce "🤖 AUTO DEVICE CHECKPOINT #{N}" + Log + Evidence
+   - NẾU Build/Run Lỗi: BlockedOnUser=true (bắt user xem lỗi).
+   - NẾU Pass: BlockedOnUser=false. Lập tức đi tiếp phase tiếp theo! KHÔNG DỪNG.
 ```
 
-**Enforcement:**
-- ❌ KHÔNG được chuyển từ Phase B → Phase C mà chưa có user confirm (COMPLEX)
-- ❌ KHÔNG được skip checkpoint cho hardware-related features (Camera, GPS, Sensors)
-- ✅ NÊN batch các features nhỏ lại thành 1 checkpoint (tránh quá nhiều interrupt)
-- ✅ Checkpoint cho logic KHÔNG cần nếu feature là pure-backend/invisible
-
 ---
 
 ### TP2: Task Complete — Completion Status Protocol

package/skills/symphony-orchestrator/SKILL.md

@@ -8,7 +8,7 @@ metadata:
   stage: core
   version: "3.0"
   replaces: null
-  requires: "@leejungkiin/awkit-symphony" (npm i -g @leejungkiin/awkit-symphony)
+  requires: "@leejungkiin/awkit-symphony (npm i -g @leejungkiin/awkit-symphony)"
   tags: [symphony, setup, server, orchestration, core, preflight, multi-project, agent]
 agent: Symphony Conductor
 allowed-tools:

package/skills/trello-sync/SKILL.md

@@ -132,62 +132,61 @@ Mỗi Card chứa:
 
 ---
 
-### TP1: 🚀 Start Task / Start Project (Description + Checklist)
+### ⚡ Delegation Rule: Khi nào dùng CLI, khi nào tự xử lý
 
-**Khi nào:** AI bắt đầu project mới, hoặc chuẩn bị triển khai Specs đã chốt (Gate 3/Gate 4). 
-*(Lưu ý: Không tạo Checklist Items các phase "Gate 1", "Gate 2" - lúc này chỉ dùng Comment hoặc Update Description thôi).*
+> [!IMPORTANT]
+> Gemini/Codex CLI đã có sẵn skill trello-sync. Chỉ delegate cho CLI khi **tác vụ NẶNG** (nhiều bước, cần phân tích). Tác vụ đơn giản thì Antigravity tự gọi `awkit trello` trực tiếp — tránh xử lý 2 lần.
 
-**Action:**
-```bash
-# Update Card Description với thông tin cực kỳ rõ ràng cho Quản lý (PM) dự án
-awkit trello desc "**Trạng thái:** Đang phát triển. **Công nghệ:** Kotlin, Jetpack Compose, Room. **Tiến độ hiện tại:** ... (Tóm tắt sơ lược)"
+| Loại tác vụ | Xử lý | Lý do |
+|-------------|--------|-------|
+| 🔴 **Nặng** — Setup project, tạo nhiều checklists, sync toàn bộ spec | `gemini -p "..." --approval-mode auto` | Nhiều bước, cần phân tích spec → delegate |
+| 🟢 **Nhẹ** — Add 1 item, complete 1 item, comment, block | `awkit trello <cmd>` trực tiếp | 1 lệnh duy nhất → tự gọi, không cần CLI |
 
-# 1. Tạo checklist dựa trên Module/Epic Nghiệp vụ thực tế
-awkit trello checklist "Module: Xác thực Người Dùng"
+---
 
-# 2. Thêm item mới vào checklist (Tuyệt đối KHÔNG ĐẶT TÊN theo Gate/Phase/Scaffolding)
-awkit trello item "Đăng nhập bằng Google"
-awkit trello item "Hồ sơ Người Dùng"
+### TP1: 🚀 Start Task / Start Project (Description + Checklist) — 🔴 DELEGATE
 
-# 3. Comment thông báo cập nhật tiến trình hoặc trạng thái Agent
-awkit trello comment "🤖 AI bắt đầu: Xây dựng giao diện Đăng Nhập | Symphony: #sym-XXX"
+**Khi nào:** AI bắt đầu project mới, hoặc chuẩn bị triển khai Specs đã chốt (Gate 3/Gate 4).
+*(Lưu ý: Không tạo Checklist Items các phase "Gate 1", "Gate 2" - lúc này chỉ dùng Comment hoặc Update Description thôi).*
+
+**Action:** Delegate cho **Gemini CLI** (nhiều bước: update desc + tạo checklists + thêm items + comment):
+```bash
+gemini -p "Phân tích Spec/thiết kế đã chốt của dự án. Tạo các checklists và checklist items trên Trello card theo quy tắc Granularity (PM View). Cập nhật description card với tổng quan dự án. Comment thông báo bắt đầu. Dùng awkit trello." --approval-mode auto
 ```
 
 ---
 
-### TP2: 📈 Report Progress (Comment Milestone)
+### TP2: 📈 Report Progress (Comment Milestone) — 🟢 TRỰC TIẾP
 
 **Khi nào:** AI đạt milestone quan trọng (40%, 60%, 80%) hoặc hoàn thành cụm tính năng.
 
-**Action:** Cung cấp thông tin CHUYÊN MÔN nhưng RÕ RÀNG cho PM:
+**Action:** Gọi trực tiếp (1 lệnh duy nhất):
 ```bash
-awkit trello comment "⏳ Progress: Login Flow (60%) — UI hoàn thiện. QUYẾT ĐỊNH KỸ THUẬT: Đã chọn SQLite/Room thay vì Firebase để đảm bảo Offline-first theo spec."
+awkit trello comment "⏳ Progress: [Tính năng] ([X]%) — [Chi tiết kỹ thuật]. Symphony: #sym-XXX"
 ```
 
 ---
 
-### TP3: 🛑 Blocked
+### TP3: 🛑 Blocked — 🟢 TRỰC TIẾP
 
 **Khi nào:** Task bị chặn, cần human input.
 
+**Action:** Gọi trực tiếp:
 ```bash
-# Label + Comment
-awkit trello block "API 500 on /auth/login. Cần Backend check."
+awkit trello block "[Lý do block chi tiết]"
 ```
 
 ---
 
-### TP4: ✅ Task Done (Đánh dấu Item Complete)
+### TP4: ✅ Task Done (Đánh dấu Item Complete) — 🟢 TRỰC TIẾP
 
-**Khi nào:** Toàn bộ cụm Tính năng Nghiệp vụ (Epic/Feature bao gồm nhiều sub-tasks) đã hoàn thành và sẵn sàng test.
-*(Lưu ý: Không check item nếu chỉ mới xong 1 task code con lập trình)*
+**Khi nào:** Toàn bộ cụm Tính năng Nghiệp vụ đã hoàn thành và sẵn sàng test.
+*(Lưu ý: Không check item nếu chỉ mới xong 1 task code con)*
 
+**Action:** Gọi trực tiếp:
 ```bash
-# 1. Đánh dấu checklist item đại diện cho tính năng ✅
-awkit trello complete "Đăng nhập bằng Google"
-
-# 2. Comment kết quả
-awkit trello comment "✅ DONE Feature: Đăng nhập bằng Google | Commit: #$(git rev-parse --short HEAD)"
+awkit trello complete "[Tên tính năng]"
+awkit trello comment "✅ DONE: [Tên tính năng] | Commit: #$(git rev-parse --short HEAD)"
 ```
 
 ---

package/skills/verification-gate/SKILL.md

@@ -31,6 +31,10 @@ BEFORE claiming any status or expressing satisfaction:
    - If NO: State actual status with evidence
    - If YES: State claim WITH evidence
 5. ONLY THEN: Make the claim
+6. AUTO-COMMIT: Build 0 errors → git add → git commit → git push (non-force)
+   - Do NOT ask user permission for regular commits
+   - Use conventional commit message (fix:/feat:/refactor:)
+   - If push fails → git pull --rebase && git push (retry once)
 
 Skip any step = lying, not verifying
 ```
@@ -53,7 +57,7 @@ Skip any step = lying, not verifying
 | Linter clean | Linter output: 0 errors | Partial check, extrapolation |
 | Build succeeds | Build command: exit 0 | Linter passing, looks good |
 | Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
-| Feature works | Demo/run showing behavior | Code written, assumed works |
+| Feature works | Maestro MCP auto run/Screenshot | Code written, assumed works |
 | Requirements met | Line-by-line checklist | Tests passing |
 | Deploy succeeded | Health check: 200 OK | Deploy command completed |
 
@@ -93,8 +97,9 @@ If you catch yourself thinking any of these, STOP and run verification:
 
 **Build:**
 ```
-✅ [Run build] → [See: BUILD SUCCEEDED] → "Build passes"
+✅ [Run build] → [See: BUILD SUCCEEDED] → auto git add+commit+push → "Build passes, committed & pushed"
 ❌ "Linter passed so build is fine"
+❌ Build succeeded but forgot to commit
 ```
 
 **Bug Fix:**
@@ -103,6 +108,12 @@ If you catch yourself thinking any of these, STOP and run verification:
 ❌ "I've changed the code, bug should be fixed"
 ```
 
+**UI/Feature Verification:**
+```
+✅ Run Automated App Build → Run mcp_maestro_launch_app → Take mcp_maestro_take_screenshot → "UI renders correctly and no crash"
+❌ "Code looks good, layouts conform to specs, should render fine."
+```
+
 **Requirements:**
 ```
 ✅ Re-read plan → Create checklist → Verify each → Report gaps or completion

package/skills/xcode-build-benchmark/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: xcode-build-benchmark
+description: Benchmark Xcode clean và incremental builds với đầu vào có thể lặp lại, xuất timing summaries và lưu timestamped `.build-benchmark/` artifacts. Sử dụng khi lập trình viên muốn đo lường baseline, so sánh trước và sau khi tối ưu, hoặc khi phàn nàn về việc build chậm và muốn đo chính xác build mất bao lâu.
+---
+
+# Xcode Build Benchmark
+
+Use this skill to produce a repeatable Xcode build baseline before anyone tries to optimize build times.
+
+## Core Rules
+
+- Measure before recommending changes.
+- Capture clean and incremental builds separately.
+- Keep the command, destination, configuration, scheme, and warm-up rules consistent across runs.
+- Write a timestamped JSON artifact to `.build-benchmark/`.
+- Do not change project files as part of benchmarking.
+
+## Inputs To Collect
+
+Confirm or infer:
+
+- workspace or project path
+- scheme
+- configuration
+- destination
+- whether the user wants simulator or device numbers
+- whether a custom `DerivedData` path is needed
+
+If the project has both clean-build and incremental-build pain, benchmark both. That is the default.
+
+## Worktree Considerations
+
+When benchmarking inside a git worktree, SPM packages with `exclude:` paths that reference gitignored directories (e.g., `__Snapshots__`) will cause `xcodebuild -resolvePackageDependencies` to crash. Create those missing directories before running any builds.
+
+## Default Workflow
+
+1. Normalize the build command and note every flag that affects caching or module reuse.
+2. Run one warm-up build if needed to validate that the command succeeds.
+3. Run 3 clean builds.
+4. If `COMPILATION_CACHING = YES` is detected, run 3 cached clean builds. These measure clean build time with a warm compilation cache -- the realistic scenario for branch switching, pulling changes, or Clean Build Folder. The script handles this automatically by building once to warm the cache, then deleting DerivedData (but not the compilation cache) before each measured run. Pass `--no-cached-clean` to skip.
+5. Run 3 zero-change builds (build immediately after a successful build with no edits). This measures the fixed overhead floor: dependency computation, project description transfer, build description creation, script phases, codesigning, and validation. A zero-change build that takes more than a few seconds indicates avoidable per-build overhead. Use the default `benchmark_builds.py` invocation (no `--touch-file` flag).
+6. Optionally run 3 incremental builds with a file touch to measure a real edit-rebuild loop. Use `--touch-file path/to/SomeFile.swift` to touch a representative source file before each build.
+7. Save the raw results and summary into `.build-benchmark/`.
+8. Report medians and spread, not just the single fastest run.
+
+## Preferred Command Path
+
+Use the shared helper when possible:
+
+```bash
+python3 scripts/benchmark_builds.py \
+  --workspace App.xcworkspace \
+  --scheme MyApp \
+  --configuration Debug \
+  --destination "platform=iOS Simulator,name=iPhone 16" \
+  --output-dir .build-benchmark
+```
+
+If you cannot use the helper script, run equivalent `xcodebuild` commands with `-showBuildTimingSummary` and preserve the raw output.
+
+## Required Output
+
+Return:
+
+- clean build median, min, max
+- cached clean build median, min, max (when COMPILATION_CACHING is enabled)
+- zero-change build median, min, max (fixed overhead floor)
+- incremental build median, min, max (if `--touch-file` was used)
+- biggest timing-summary categories
+- environment details that could affect comparisons
+- path to the saved artifact
+
+If results are noisy, say so and recommend rerunning under calmer conditions.
+
+## When To Stop
+
+Stop after measurement if the user only asked for benchmarking. If they want optimization guidance, hand off the artifact to the relevant specialist by reading its SKILL.md and applying its workflow to the same project context:
+
+- [`xcode-compilation-analyzer`](../xcode-compilation-analyzer/SKILL.md)
+- [`xcode-project-analyzer`](../xcode-project-analyzer/SKILL.md)
+- [`spm-build-analysis`](../spm-build-analysis/SKILL.md)
+- [`xcode-build-orchestrator`](../xcode-build-orchestrator/SKILL.md) for full orchestration
+
+## Additional Resources
+
+- For the benchmark contract, see [references/benchmarking-workflow.md](references/benchmarking-workflow.md)
+- For the shared artifact format, see [references/benchmark-artifacts.md](references/benchmark-artifacts.md)
+- For the JSON schema, see [schemas/build-benchmark.schema.json](schemas/build-benchmark.schema.json)

package/skills/xcode-build-benchmark/references/benchmark-artifacts.md

@@ -0,0 +1,94 @@
+# Benchmark Artifacts
+
+All skills in this repository should treat `.build-benchmark/` as the canonical location for measured build evidence.
+
+## Goals
+
+- Keep build measurements reproducible.
+- Make clean and incremental build data easy to compare.
+- Preserve enough context for later specialist analysis without rerunning the benchmark.
+
+## Wall-Clock vs Cumulative Task Time
+
+The `duration_seconds` field on each run and the `median_seconds` in the summary represent **wall-clock time** -- how long the developer actually waits. This is the primary success metric.
+
+The `timing_summary_categories` are **aggregated task times** parsed from Xcode's Build Timing Summary. Because Xcode runs many tasks in parallel across CPU cores, these totals typically exceed the wall-clock duration. A large cumulative `SwiftCompile` value is diagnostic evidence of compiler workload, not proof that compilation is blocking the build. Always compare category totals against the wall-clock median before concluding that a category is a bottleneck.
+
+## File Layout
+
+Recommended outputs:
+
+- `.build-benchmark/<timestamp>-<scheme>.json`
+- `.build-benchmark/<timestamp>-<scheme>-clean-1.log`
+- `.build-benchmark/<timestamp>-<scheme>-clean-2.log`
+- `.build-benchmark/<timestamp>-<scheme>-clean-3.log`
+- `.build-benchmark/<timestamp>-<scheme>-cached-clean-1.log` (when COMPILATION_CACHING is enabled)
+- `.build-benchmark/<timestamp>-<scheme>-cached-clean-2.log`
+- `.build-benchmark/<timestamp>-<scheme>-cached-clean-3.log`
+- `.build-benchmark/<timestamp>-<scheme>-incremental-1.log`
+- `.build-benchmark/<timestamp>-<scheme>-incremental-2.log`
+- `.build-benchmark/<timestamp>-<scheme>-incremental-3.log`
+
+Use an ISO-like UTC timestamp without spaces so the files sort naturally.
+
+## Artifact Requirements
+
+Each JSON artifact should include:
+
+- schema version
+- creation timestamp
+- project context
+- environment details when available
+- the normalized build command
+- separate `clean` and `incremental` run arrays
+- summary statistics for each build type
+- parsed timing-summary categories
+- free-form notes for caveats or noise
+
+## Clean, Cached Clean, And Incremental Separation
+
+Do not merge different build type measurements into a single list. They answer different questions:
+
+- **Clean builds** show full build-system, package, and module setup cost with a cold compilation cache.
+- **Cached clean builds** show clean build cost when the compilation cache is warm. This is the realistic scenario for branch switching, pulling changes, or Clean Build Folder. Only present when `COMPILATION_CACHING = YES` is detected.
+- **Incremental builds** show edit-loop productivity and script or cache invalidation problems.
+
+## Raw Logs
+
+Store raw `xcodebuild` output beside the JSON artifact whenever possible. That allows later skills to:
+
+- re-parse timing summaries
+- inspect failed builds
+- search for long type-check warnings
+- correlate build-system phases with recommendations
+
+## Measurement Caveats
+
+### COMPILATION_CACHING
+
+`COMPILATION_CACHING = YES` stores compiled artifacts in a system-managed cache outside DerivedData so that repeated compilations of identical inputs are served from cache. The standard clean-build benchmark (`xcodebuild clean` between runs) may add overhead from cache population without showing the corresponding cache-hit benefit.
+
+The benchmark script automatically detects `COMPILATION_CACHING = YES` and runs a **cached clean** benchmark phase. This phase:
+
+1. Builds once to warm the compilation cache.
+2. Deletes DerivedData (but not the compilation cache) before each measured run.
+3. Rebuilds, measuring the cache-hit clean build time.
+
+The cached clean metric captures the realistic developer experience: branch switching, pulling changes, and Clean Build Folder. Use the cached clean median as the primary comparison metric when evaluating `COMPILATION_CACHING` impact.
+
+To skip this phase, pass `--no-cached-clean`.
+
+### First-Run Variance
+
+The first clean build after the warmup cycle often runs 20-40% slower than subsequent clean builds due to cold OS-level caches (disk I/O, dynamic linker cache, etc.). The benchmark script mitigates this by running a warmup clean+build cycle before measured runs. If variance between the first and later clean runs is still high, prefer the median or min over the mean, and note the variance in the artifact's `notes` field.
+
+## Shared Consumer Expectations
+
+Any skill reading a benchmark artifact should be able to identify:
+
+- what was measured
+- how it was measured
+- whether the run succeeded
+- whether the results are stable enough to compare
+
+For the authoritative field-level schema, see [../schemas/build-benchmark.schema.json](../schemas/build-benchmark.schema.json).

package/skills/xcode-build-benchmark/references/benchmarking-workflow.md

@@ -0,0 +1,67 @@
+# Benchmarking Workflow
+
+Use this reference when you need the full operational contract for collecting Xcode build measurements.
+
+## Goal
+
+Produce a benchmark artifact that another skill can trust without rerunning the same setup discovery.
+
+## Benchmark Contract
+
+- Measure both clean and incremental builds unless the user narrows the scope.
+- Use the same scheme, configuration, destination, and command flags for all measured runs.
+- Record the exact command and any environment overrides.
+- Keep clean and incremental runs in separate arrays in the artifact.
+- Save wall-clock timing plus any parsed timing-summary categories.
+
+## Suggested Run Counts
+
+- Clean builds: 3 measured runs
+- Incremental builds: 3 measured runs
+- Warm-up: 0 to 1 validation run, excluded from the summary unless the user explicitly wants it included
+
+## Clean Build Rules
+
+- Clear build products with `xcodebuild clean` or an equivalent clean-build-folder step before each measured clean run.
+- Do not change scheme, destination, or configuration between runs.
+- If the command fails, store the failure and stop rather than mixing failed and successful runs.
+
+## Incremental Build Rules
+
+- Use the same build command after a successful baseline build.
+- Do not clean between incremental runs.
+- If the user wants edit-loop benchmarking, note the file change strategy explicitly in the artifact.
+- If there are no source edits between runs, label the result as no-edit incremental timing.
+
+## What To Capture
+
+At minimum, keep:
+
+- timestamp
+- host machine info if available
+- Xcode version if available
+- workspace or project path
+- scheme, configuration, destination
+- exact `xcodebuild` command
+- duration per run
+- success or failure
+- parsed timing-summary categories
+- notes on warm-up behavior or unusual noise
+
+## Reporting Guidance
+
+Use medians for the headline number. Also include:
+
+- min and max
+- range
+- category totals from the timing summary
+- obvious outliers or instability
+
+## Handoff Expectations
+
+The next optimization skill should be able to answer:
+
+- Is the main problem clean, incremental, or both?
+- Which build categories dominate time?
+- Which command produced the evidence?
+- Is the baseline trustworthy enough to compare before and after changes?