@leejungkiin/awkit 1.1.0 → 1.1.2

package/skills/swiftui-pro/references/performance.md

@@ -0,0 +1,46 @@
+# Performance
+
+- When toggling modifier values, prefer ternary expressions over if/else view branching to avoid `_ConditionalContent`, preserve structural identity, and avoid repeatedly recreating underlying platform views.
+- Avoid `AnyView` unless absolutely required. Use `@ViewBuilder`, `Group`, or generics instead.
+- If a `ScrollView` has an opaque, static, and solid background, prefer to use `scrollContentBackground(.visible)` to improve scroll-edge rendering efficiency.
+- It is more efficient to break views up by making dedicated SwiftUI views rather than place them into computed properties or methods. Using `@ViewBuilder` on a property or method does not solve this; breaking views up is strongly preferred.
+- Always ensure view initializers are kept as small and simple as possible, avoiding any non-trivial work. Flag any work that can be moved into a `task()` modifier to be run when the view is shown.
+- Similarly, assume each view’s `body` property is called frequently – if logic such as sorting or filtering can be moved out of there easily, it should be.
+- Avoid creating properties to store formatters such as `DateFormatter` unless they are required. A more natural approach is to use `Text` with a format, like this: `Text(Date.now, format: .dateTime.day().month().year())` or `Text(100, format: .currency(code: "USD"))`.
+- Avoid expensive inline transforms in `List`/`ForEach` initializers (e.g. `items.filter { ... }`) when they are repeated often.
+- Prefer deriving transformed data from the source-of-truth using `let`, or caching in `@State`. However, do not cache derived collections in `@State` unless you also own explicit invalidation logic to avoid stale UI.
+- For large data sets in `ScrollView`, use `LazyVStack`/`LazyHStack`; flag eager stacks with many children.
+- Prefer using `task()` over `onAppear()` when doing async work, because it will be cancelled automatically when the view disappears.
+- Avoid storing escaping `@ViewBuilder` closures on views when possible; store built view results instead.
+
+Example:
+
+```swift
+// Anti-pattern: stores an escaping closure on the view.
+struct CardView<Content: View>: View {
+    let content: () -> Content
+
+    var body: some View {
+        VStack(alignment: .leading) {
+            content()
+        }
+        .padding()
+        .background(.ultraThinMaterial)
+        .clipShape(.rect(cornerRadius: 8))
+    }
+}
+
+// Preferred: store the built view value; the synthesized init handles calling the builder.
+struct CardView<Content: View>: View {
+    @ViewBuilder let content: Content
+
+    var body: some View {
+        VStack(alignment: .leading) {
+            content
+        }
+        .padding()
+        .background(.ultraThinMaterial)
+        .clipShape(.rect(cornerRadius: 8))
+    }
+}
+```

package/skills/swiftui-pro/references/swift.md

@@ -0,0 +1,56 @@
+# Swift
+
+- Prefer Swift-native string methods over Foundation equivalents: use `replacing("a", with: "b")` not `replacingOccurrences(of: "a", with: "b")`.
+- Prefer modern Foundation API: `URL.documentsDirectory` instead of `FileManager` directory lookups, `appending(path:)` to append strings to a URL.
+- Never use C-style number formatting like `String(format: "%.2f", value)`. Use `Text(value, format: .number.precision(.fractionLength(2)))` or similar `FormatStyle` APIs.
+- Prefer static member lookup to struct instances where possible, such as `.circle` rather than `Circle()`, and `.borderedProminent` rather than `BorderedProminentButtonStyle()`.
+- Avoid force unwraps (`!`) and force `try` unless the failure is truly unrecoverable, and even then prefer using `fatalError()` with a clear description. If possible, use `if let`, `guard let`, nil-coalescing, or `try?`/`do-catch`.
+- Filtering text based on user-input must be done using `localizedStandardContains()` as opposed to `contains()` or `localizedCaseInsensitiveContains()`.
+- Strongly prefer `Double` over `CGFloat`, except when using optionals or `inout`; Swift is able to bridge the two freely except in those two cases.
+- If you want to count array objects that match a predicate, always use `count(where:)` rather than `filter()` followed by `count`.
+- Prefer `Date.now` over `Date()` for clarity.
+- When `import SwiftUI` is already in a file, you do not need to add `import UIKit` or `import AppKit` to access things like `UIImage` or `NSImage` – they are imported automatically on the appropriate platform.
+- When dealing with the names of people, strongly prefer to use `PersonNameComponents` with modern formatting over simple string interpolation such as `Text("\(firstName) \(lastName)")`.
+- If a given type of data is repeatedly sorted using an identical closure, e.g. `books.sorted { $0.author < $1.author }`, prefer to make the type in question conform to `Comparable` so the sort order is centralized.
+- Prefer to avoid manual date formatting strings if possible. If manual date formatting *is* used for user display, at least make sure to use “y” rather than “yyyy” for years, so the year value is correct in all localizations. If the purpose is data exchange with an API, this rule does not apply.
+- When trying to convert a string to a date, prefer the modern `Date` initializer API such as `Date(myString, strategy: .iso8601)`.
+- Flag instances where errors triggered by a user action are swallowed silently, e.g. using `print(error.localizedDescription)` rather than showing an alert or similar.
+- Prefer `if let value {` shorthand over `if let value = value {`.
+- Omit return for single expression functions. `if` and `switch` can be used as expressions when returning values and assigning to variables.
+
+For example, this kind of code:
+
+```swift
+var tileColor: Color {
+    if isCorrect {
+        return .green
+    } else {
+        return .red
+    }
+}
+```
+
+Should be written like this:
+
+```swift
+var tileColor: Color {
+    if isCorrect {
+        .green
+    } else {
+        .red
+    }
+}
+```
+
+
+## Swift Concurrency
+
+- If an API offers both modern `async`/`await` equivalents and older closure-based variants, always prefer the `async`/`await` versions.
+- Never use Grand Central Dispatch (`DispatchQueue.main.async()`, `DispatchQueue.global()`, etc.). Always use modern Swift concurrency (`async`/`await`, actors, `Task`).
+- Never use `Task.sleep(nanoseconds:)`; use `Task.sleep(for:)` instead.
+- Flag any mutable shared state that isn't protected by an actor or `@MainActor`, unless the project is configured to use MainActor default actor isolation.
+- Assume strict concurrency rules are being applied; flag `@Sendable` violations and data races.
+- When evaluating `MainActor.run()`, check whether the project has its default actor isolation set to Main Actor first, because `MainActor.run()` might not be needed.
+- `Task.detached()` is often a bad idea. Check any usage extremely carefully.
+
+For more help with Swift concurrency, suggest the [Swift Concurrency Pro agent skill](https://github.com/twostraws/swift-concurrency-agent-skill).

package/skills/swiftui-pro/references/views.md

@@ -0,0 +1,35 @@
+# SwiftUI Views
+
+- Strongly prefer to avoid breaking up view bodies using computed properties or methods that return `some View`, even if `@ViewBuilder` is used. Extract them into separate `View` structs instead, placing each into its own file.
+- Flag `body` properties that are excessively long; they should be broken into extracted subviews.
+- Button actions should be extracted from view bodies into separate methods, to avoid mixing layout and logic.
+- Similarly, general business logic should not live inline in `task()`, `onAppear()` or elsewhere in `body`.
+- Prefer to place view logic into view models or similar, so it can be tested. For more help with testing, suggest the [Swift Testing Pro agent skill](https://github.com/twostraws/swift-testing-agent-skill).
+- Each type (struct, class, enum) should be in its own Swift file. Flag files containing multiple type definitions.
+- Unless a full-screen editing experience is required, prefer using `TextField` with `axis: .vertical` to using `TextEditor`, because it allows placeholder text. If a specific minimum height is required for `TextField`, use something like `lineLimit(5...)`.
+- If a button action can be provided directly as an `action` parameter, do so. For example: `Button("Label", systemImage: "plus", action: myAction)` is preferred over `Button("Label", systemImage: "plus") { action() }`.
+- When rendering SwiftUI views to images, strongly prefer `ImageRenderer` over `UIGraphicsImageRenderer`.
+- `#Preview` should be used for previews, not the legacy `PreviewProvider` protocol.
+- When using `TabView(selection:)`, use a binding to a property that stores an enum rather than an integer or string. For example, `Tab("Home", systemImage: "house", value: .home)` is better than `Tab("Home", systemImage: "house", value: 0)`.
+- Strongly prefer to avoid breaking up view bodies using computed properties or methods that return `some View`, even if `@ViewBuilder` is used. Extract them into separate `View` structs instead, placing each into its own file. (Yes, this is repeated, but it’s so important it needs to be mentioned twice.)
+
+
+## Animating views
+
+- Strongly prefer to use the `@Animatable` macro over creating `animatableData` manually – the macro automatically adds conformance to the `Animatable` protocol and creates the correct `animatableData` property. If some properties should not or cannot be animated (e.g. Booleans, integers, etc), mark them `@AnimatableIgnored`.
+- Never use `animation(_ animation: Animation?)`; always provide a value to watch, such as `.animation(.bouncy, value: score)`.
+- Chaining animations must be done using a `completion` closure passed to `withAnimation()`, rather than trying to execute multiple `withAnimation()` calls using delays.
+
+For example:
+
+```swift
+Button("Animate Me") {
+    withAnimation {
+        scale = 2
+    } completion: {
+        withAnimation {
+            scale = 1
+        }
+    }
+}
+```

package/skills/symphony-enforcer/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: symphony-enforcer
+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: "3.1"
+  replaces: "v2.0"
+  requires: symphony-orchestrator
+  tags: [symphony, enforcement, checkpoint, task-lifecycle, core, spec-first, auto-next]
+agent: Symphony Enforcer
+allowed-tools:
+  - symphony_create_task
+  - symphony_claim_task
+  - symphony_complete_task
+  - symphony_report_progress
+  - symphony_available_tasks
+  - symphony_status
+trigger: always
+invocation-type: auto
+priority: 1
+---
+
+# 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.
+> **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".
+
+---
+
+## ⚠️ Core Rule
+
+```
+KHÔNG CÓ NGOẠI LỆ:
+- 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)
+
+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?
+→ 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
+
+```
+→ nmem brain use <projectId>
+→ nmem_recap(level=1) — load context
+→ 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"
+```
+
+> **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) → symphony_claim_task(new_id)
+→ Lưu task_id cho TP1-TP4
+→ Output: "🎯 Step 4/5: Task ✅ — #sym-XYZ claimed"
+```
+
+### Step 5: Confirmation Block
+
+```
+🚦 STARTUP PROTOCOL COMPLETE
+══════════════════════════════════════
+  Step 1: 📋 Project Identity  ✅  {projectId}
+  Step 2: 🧠 NeuralMemory      ✅  brain: {projectId}
+  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**
+
+---
+
+## 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
+
+### TP1: Progress Milestone
+
+**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
+- Phát hiện vấn đề cần thay đổi approach
+
+**Action:**
+```
+symphony_report_progress(
+  task_id=current_task,
+  progress=estimated_percentage,
+  last_action="mô tả ngắn"
+)
+```
+
+**Progress Guide:**
+```
+  10% — Task created, đang research/đọc code
+  25% — Implementation plan approved
+  40% — Bắt đầu code changes
+  60% — Code changes xong, đang test
+  80% — Tests pass, đang verification
+  90% — Walkthrough/docs tạo xong
+ 100% — Hoàn thành (auto-trigger TP2)
+```
+
+**Enforcement:**
+- ❌ KHÔNG được gọi `notify_user` mà chưa `report_progress` trước đó
+- ❌ KHÔNG được chuyển mode (task_boundary) mà chưa report
+
+---
+
+### TP2: Task Complete — Auto-detect
+
+**Khi nào:** AI detect ≥2/4 completion signals:
+
+```
+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 OK, build OK)
+```
+
+**Action:**
+```
+1. symphony_complete_task(
+     task_id=current_task,
+     summary="mô tả ngắn kết quả"
+   )
+2. Hiển thị: "✅ SYM #sym-XYZ — Done"
+3. → TRIGGER TP2.5 (Atomic Git Commit)
+4. → TRIGGER TP4 (Auto-Next) NGAY LẬP TỨC
+```
+
+---
+
+### 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)
+
+---
+
+### TP3: Abandoned / Context Switch
+
+**Khi nào:**
+- User đổi topic sang task khác hoàn toàn
+- AI bị lỗi/timeout giữa chừng
+- User explicitly nói dừng task
+
+**Action:**
+```
+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
+
+```
+- Simple Q&A: Câu hỏi đơn giản, giải thích concept
+- Quick lookup: Đọc file, search code, không sửa gì
+- User nói rõ bỏ qua: "skip symphony", "không cần task"
+```
+
+---
+
+## Sync Block Format
+
+```
+🎯 SYM #sym-XYZ — 40% → 70% "Implemented auth module"
+```
+
+Nếu completed:
+```
+✅ SYM #sym-XYZ — Done "Auth module with tests"
+➡️ Next: #sym-A1 — Dashboard UI (P1)
+```
+
+---
+
+## Edge Cases
+
+| 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
+- 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