codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/swiftui-view-refactor/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: swiftui-view-refactor
+description: Refactor SwiftUI views into smaller components with stable, explicit data flow.
+risk: safe
+source: "Dimillian/Skills (MIT)"
+date_added: "2026-03-25"
+---
+
+# SwiftUI View Refactor
+
+## Overview
+Refactor SwiftUI views toward small, explicit, stable view types. Default to vanilla SwiftUI: local state in the view, shared dependencies in the environment, business logic in services/models, and view models only when the request or existing code clearly requires one.
+
+## When to Use
+
+- When cleaning up a large SwiftUI view or splitting long `body` implementations.
+- When you need smaller subviews, explicit dependency injection, or better Observation usage.
+
+## Core Guidelines
+
+### 1) View ordering (top → bottom)
+- Enforce this ordering unless the existing file has a stronger local convention you must preserve.
+- Environment
+- `private`/`public` `let`
+- `@State` / other stored properties
+- computed `var` (non-view)
+- `init`
+- `body`
+- computed view builders / other view helpers
+- helper / async functions
+
+### 2) Default to MV, not MVVM
+- Views should be lightweight state expressions and orchestration points, not containers for business logic.
+- Favor `@State`, `@Environment`, `@Query`, `.task`, `.task(id:)`, and `onChange` before reaching for a view model.
+- Inject services and shared models via `@Environment`; keep domain logic in services/models, not in the view body.
+- Do not introduce a view model just to mirror local view state or wrap environment dependencies.
+- If a screen is getting large, split the UI into subviews before inventing a new view model layer.
+
+### 3) Strongly prefer dedicated subview types over computed `some View` helpers
+- Flag `body` properties that are longer than roughly one screen or contain multiple logical sections.
+- Prefer extracting dedicated `View` types for non-trivial sections, especially when they have state, async work, branching, or deserve their own preview.
+- Keep computed `some View` helpers rare and small. Do not build an entire screen out of `private var header: some View`-style fragments.
+- Pass small, explicit inputs (data, bindings, callbacks) into extracted subviews instead of handing down the entire parent state.
+- If an extracted subview becomes reusable or independently meaningful, move it to its own file.
+
+Prefer:
+
+```swift
+var body: some View {
+    List {
+        HeaderSection(title: title, subtitle: subtitle)
+        FilterSection(
+            filterOptions: filterOptions,
+            selectedFilter: $selectedFilter
+        )
+        ResultsSection(items: filteredItems)
+        FooterSection()
+    }
+}
+
+private struct HeaderSection: View {
+    let title: String
+    let subtitle: String
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            Text(title).font(.title2)
+            Text(subtitle).font(.subheadline)
+        }
+    }
+}
+
+private struct FilterSection: View {
+    let filterOptions: [FilterOption]
+    @Binding var selectedFilter: FilterOption
+
+    var body: some View {
+        ScrollView(.horizontal, showsIndicators: false) {
+            HStack {
+                ForEach(filterOptions, id: \.self) { option in
+                    FilterChip(option: option, isSelected: option == selectedFilter)
+                        .onTapGesture { selectedFilter = option }
+                }
+            }
+        }
+    }
+}
+```
+
+Avoid:
+
+```swift
+var body: some View {
+    List {
+        header
+        filters
+        results
+        footer
+    }
+}
+
+private var header: some View {
+    VStack(alignment: .leading, spacing: 6) {
+        Text(title).font(.title2)
+        Text(subtitle).font(.subheadline)
+    }
+}
+```
+
+### 3b) Extract actions and side effects out of `body`
+- Do not keep non-trivial button actions inline in the view body.
+- Do not bury business logic inside `.task`, `.onAppear`, `.onChange`, or `.refreshable`.
+- Prefer calling small private methods from the view, and move real business logic into services/models.
+- The body should read like UI, not like a view controller.
+
+```swift
+Button("Save", action: save)
+    .disabled(isSaving)
+
+.task(id: searchText) {
+    await reload(for: searchText)
+}
+
+private func save() {
+    Task { await saveAsync() }
+}
+
+private func reload(for searchText: String) async {
+    guard !searchText.isEmpty else {
+        results = []
+        return
+    }
+    await searchService.search(searchText)
+}
+```
+
+### 4) Keep a stable view tree (avoid top-level conditional view swapping)
+- Avoid `body` or computed views that return completely different root branches via `if/else`.
+- Prefer a single stable base view with conditions inside sections/modifiers (`overlay`, `opacity`, `disabled`, `toolbar`, etc.).
+- Root-level branch swapping causes identity churn, broader invalidation, and extra recomputation.
+
+Prefer:
+
+```swift
+var body: some View {
+    List {
+        documentsListContent
+    }
+    .toolbar {
+        if canEdit {
+            editToolbar
+        }
+    }
+}
+```
+
+Avoid:
+
+```swift
+var documentsListView: some View {
+    if canEdit {
+        editableDocumentsList
+    } else {
+        readOnlyDocumentsList
+    }
+}
+```
+
+### 5) View model handling (only if already present or explicitly requested)
+- Treat view models as a legacy or explicit-need pattern, not the default.
+- Do not introduce a view model unless the request or existing code clearly calls for one.
+- If a view model exists, make it non-optional when possible.
+- Pass dependencies to the view via `init`, then create the view model in the view's `init`.
+- Avoid `bootstrapIfNeeded` patterns and other delayed setup workarounds.
+
+Example (Observation-based):
+
+```swift
+@State private var viewModel: SomeViewModel
+
+init(dependency: Dependency) {
+    _viewModel = State(initialValue: SomeViewModel(dependency: dependency))
+}
+```
+
+### 6) Observation usage
+- For `@Observable` reference types on iOS 17+, store them as `@State` in the owning view.
+- Pass observables down explicitly; avoid optional state unless the UI genuinely needs it.
+- If the deployment target includes iOS 16 or earlier, use `@StateObject` at the owner and `@ObservedObject` when injecting legacy observable models.
+
+## Workflow
+
+1. Reorder the view to match the ordering rules.
+2. Remove inline actions and side effects from `body`; move business logic into services/models and keep only thin orchestration in the view.
+3. Shorten long bodies by extracting dedicated subview types; avoid rebuilding the screen out of many computed `some View` helpers.
+4. Ensure stable view structure: avoid top-level `if`-based branch swapping; move conditions to localized sections/modifiers.
+5. If a view model exists or is explicitly required, replace optional view models with a non-optional `@State` view model initialized in `init`.
+6. Confirm Observation usage: `@State` for root `@Observable` models on iOS 17+, legacy wrappers only when the deployment target requires them.
+7. Keep behavior intact: do not change layout or business logic unless requested.
+
+## Notes
+
+- Prefer small, explicit view types over large conditional blocks and large computed `some View` properties.
+- Keep computed view builders below `body` and non-view computed vars above `init`.
+- A good SwiftUI refactor should make the view read top-to-bottom as data flow plus layout, not as mixed layout and imperative logic.
+- For MV-first guidance and rationale, see `references/mv-patterns.md`.
+
+## Large-view handling
+
+When a SwiftUI view file exceeds ~300 lines, split it aggressively. Extract meaningful sections into dedicated `View` types instead of hiding complexity in many computed properties. Use `private` extensions with `// MARK: -` comments for actions and helpers, but do not treat extensions as a substitute for breaking a giant screen into smaller view types. If an extracted subview is reused or independently meaningful, move it into its own file.

package/templates/.agent/skills/swiftui-view-refactor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SwiftUI View Refactor"
+  short_description: "Refactor large SwiftUI view files"
+  default_prompt: "Use $swiftui-view-refactor to clean up and split this SwiftUI view without changing its behavior."

package/templates/.agent/skills/swiftui-view-refactor/references/mv-patterns.md

@@ -0,0 +1,161 @@
+# MV Patterns Reference
+
+Distilled guidance for deciding whether a SwiftUI feature should stay as plain MV or introduce a view model.
+
+Inspired by the user's provided source, "SwiftUI in 2025: Forget MVVM" (Thomas Ricouard), but rewritten here as a practical refactoring reference.
+
+## Default stance
+
+- Default to MV: views are lightweight state expressions and orchestration points.
+- Prefer `@State`, `@Environment`, `@Query`, `.task`, `.task(id:)`, and `onChange` before reaching for a view model.
+- Keep business logic in services, models, or domain types, not in the view body.
+- Split large screens into smaller view types before inventing a view model layer.
+- Avoid manual fetching or state plumbing that duplicates SwiftUI or SwiftData mechanisms.
+- Test services, models, and transformations first; views should stay simple and declarative.
+
+## When to avoid a view model
+
+Do not introduce a view model when it would mostly:
+- mirror local view state,
+- wrap values already available through `@Environment`,
+- duplicate `@Query`, `@State`, or `Binding`-based data flow,
+- exist only because the view body is too long,
+- hold one-off async loading logic that can live in `.task` plus local view state.
+
+In these cases, simplify the view and data flow instead of adding indirection.
+
+## When a view model may be justified
+
+A view model can be reasonable when at least one of these is true:
+- the user explicitly asks for one,
+- the codebase already standardizes on a view model pattern for that feature,
+- the screen needs a long-lived reference model with behavior that does not fit naturally in services alone,
+- the feature is adapting a non-SwiftUI API that needs a dedicated bridge object,
+- multiple views share the same presentation-specific state and that state is not better modeled as app-level environment data.
+
+Even then, keep the view model small, explicit, and non-optional when possible.
+
+## Preferred pattern: local state plus environment
+
+```swift
+struct FeedView: View {
+    @Environment(BlueSkyClient.self) private var client
+
+    enum ViewState {
+        case loading
+        case error(String)
+        case loaded([Post])
+    }
+
+    @State private var viewState: ViewState = .loading
+
+    var body: some View {
+        List {
+            switch viewState {
+            case .loading:
+                ProgressView("Loading feed...")
+            case .error(let message):
+                ErrorStateView(message: message, retryAction: { await loadFeed() })
+            case .loaded(let posts):
+                ForEach(posts) { post in
+                    PostRowView(post: post)
+                }
+            }
+        }
+        .task { await loadFeed() }
+    }
+
+    private func loadFeed() async {
+        do {
+            let posts = try await client.getFeed()
+            viewState = .loaded(posts)
+        } catch {
+            viewState = .error(error.localizedDescription)
+        }
+    }
+}
+```
+
+Why this is preferred:
+- state stays close to the UI that renders it,
+- dependencies come from the environment instead of a wrapper object,
+- the view coordinates UI flow while the service owns the real work.
+
+## Preferred pattern: use modifiers as lightweight orchestration
+
+```swift
+.task(id: searchText) {
+    guard !searchText.isEmpty else {
+        results = []
+        return
+    }
+    await searchFeed(query: searchText)
+}
+
+.onChange(of: isInSearch, initial: false) {
+    guard !isInSearch else { return }
+    Task { await fetchSuggestedFeed() }
+}
+```
+
+Use view lifecycle modifiers for simple, local orchestration. Do not convert these into a view model by default unless the behavior clearly outgrows the view.
+
+## SwiftData note
+
+SwiftData is a strong argument for keeping data flow inside the view when possible.
+
+Prefer:
+
+```swift
+struct BookListView: View {
+    @Query private var books: [Book]
+    @Environment(\.modelContext) private var modelContext
+
+    var body: some View {
+        List {
+            ForEach(books) { book in
+                BookRowView(book: book)
+                    .swipeActions {
+                        Button("Delete", role: .destructive) {
+                            modelContext.delete(book)
+                        }
+                    }
+            }
+        }
+    }
+}
+```
+
+Avoid adding a view model that manually fetches and mirrors the same state unless the feature has an explicit reason to do so.
+
+## Testing guidance
+
+Prefer to test:
+- services and business rules,
+- models and state transformations,
+- async workflows at the service layer,
+- UI behavior with previews or higher-level UI tests.
+
+Do not introduce a view model primarily to make a simple SwiftUI view "testable." That usually adds ceremony without improving the architecture.
+
+## Refactor checklist
+
+When refactoring toward MV:
+- Remove view models that only wrap environment dependencies or local view state.
+- Replace optional or delayed-initialized view models when plain view state is enough.
+- Pull business logic out of the view body and into services/models.
+- Keep the view as a thin coordinator of UI state, navigation, and user actions.
+- Split large bodies into smaller view types before adding new layers of indirection.
+
+## Bottom line
+
+Treat view models as the exception, not the default.
+
+In modern SwiftUI, the default stack is:
+- `@State` for local state,
+- `@Environment` for shared dependencies,
+- `@Query` for SwiftData-backed collections,
+- lifecycle modifiers for lightweight orchestration,
+- services and models for business logic.
+
+Reach for a view model only when the feature clearly needs one.

package/templates/.agent/skills/systematic-debugging/SKILL.md

@@ -1,109 +1,202 @@
 ---
 name: systematic-debugging
-description: 4-phase systematic debugging methodology with root cause analysis and evidence-based verification. Use when debugging complex issues.
-allowed-tools: Read, Glob, Grep
+description: "Gunakan skill ini ketika menemukan error, bug, crash, test failure, atau
+  performa yang tidak diharapkan. Skill ini mencakup 3L5W root cause analysis (5 Whys +
+  Search & Destroy + Global Mitigation), 4-level artifact verification, dan silent
+  self-healing protocol agar user tidak terbebani error teknis. Aktifkan secara otomatis
+  saat ada stack trace, TypeScript error, runtime crash, compilation failure, atau saat
+  @lint-and-validate menemukan masalah. Jangan tanya user cara fix — fix sendiri dulu."
+risk: low
+source: internal
+date_added: "2025-04-10"
 ---
 
 # Systematic Debugging
 
-> Source: obra/superpowers
+> Bukan sekadar fix satu file — temukan dan eliminasi akar masalah dari seluruh codebase.
+> Subagent bekerja ~70% kualitas. Gunakan skill ini dalam satu session untuk hasil terbaik.
 
-## Overview
-This skill provides a structured approach to debugging that prevents random guessing and ensures problems are properly understood before solving.
+---
 
-## 4-Phase Debugging Process
+## Kapan Menggunakan Skill Ini
 
-### Phase 1: Reproduce
-Before fixing, reliably reproduce the issue.
+- Ada error terminal, stack trace, atau crash
+- TypeScript / ESLint melaporkan error
+- Unit test atau E2E test gagal
+- Komponen render salah atau data tidak muncul
+- Performance drastis menurun setelah perubahan
+- `@lint-and-validate` mendeteksi masalah
 
-```markdown
-## Reproduction Steps
-1. [Exact step to reproduce]
-2. [Next step]
-3. [Expected vs actual result]
-
-## Reproduction Rate
-- [ ] Always (100%)
-- [ ] Often (50-90%)
-- [ ] Sometimes (10-50%)
-- [ ] Rare (<10%)
-```
+---
 
-### Phase 2: Isolate
-Narrow down the source.
+## Protokol: 3L5W (3 Legs, 5 Whys)
+
+### LEG 1 — Root Cause via 5 Whys
+
+**Tanya "Kenapa?" minimal 5x berturut-turut sampai ketemu akar masalah struktural.**
 
-```markdown
-## Isolation Questions
-- When did this start happening?
-- What changed recently?
-- Does it happen in all environments?
-- Can we reproduce with minimal code?
-- What's the smallest change that triggers it?
 ```
+Error: Cannot read property 'id' of undefined
 
-### Phase 3: Understand
-Find the root cause, not just symptoms.
+Kenapa 1: Kenapa 'id' undefined? → Object tidak di-return dari query
+Kenapa 2: Kenapa query tidak return? → findFirst() return null jika tidak ada data
+Kenapa 3: Kenapa data tidak ada? → User belum onboarded, field wajib belum diisi
+Kenapa 4: Kenapa bisa sampai ke halaman ini tanpa onboarding? → Guard middleware tidak ada
+Kenapa 5: Kenapa guard tidak ada? → Spec tidak mendefinisikan edge case ini
 
-```markdown
-## Root Cause Analysis
-### The 5 Whys
-1. Why: [First observation]
-2. Why: [Deeper reason]
-3. Why: [Still deeper]
-4. Why: [Getting closer]
-5. Why: [Root cause]
+Root Cause: Missing onboarding guard → fix di middleware, bukan di component
 ```
 
-### Phase 4: Fix & Verify
-Fix and verify it's truly fixed.
+**Aturan Leg 1:**
+- Jangan stop di simptom — terus gali sampai structural cause
+- Jika tidak bisa 5x, minimal 3x
+- Catat root cause sebelum lanjut ke Leg 2
 
-```markdown
-## Fix Verification
-- [ ] Bug no longer reproduces
-- [ ] Related functionality still works
-- [ ] No new issues introduced
-- [ ] Test added to prevent regression
+---
+
+### LEG 2 — Search & Destroy
+
+**Cari pattern yang sama di SELURUH codebase — jangan fix hanya satu file.**
+
+```bash
+# Contoh: jika root cause adalah missing null check
+grep -r "\.id" src/ --include="*.ts" | grep -v "?.id"
+
+# Jika root cause adalah missing await
+grep -r "headers()" src/ --include="*.ts" | grep -v "await headers()"
+
+# Jika root cause adalah missing error boundary
+grep -r "fetch(" src/ --include="*.tsx" | grep -v "try {"
 ```
 
-## Debugging Checklist
+**Yang harus dicari:**
+- File lain yang pakai pattern/sintaks yang sama
+- Komponen serupa yang mungkin terkena masalah sama
+- Import yang salah path di seluruh project
+- Environment variable yang missing di tempat lain
+
+**Output Leg 2:** Daftar semua file yang perlu diperbaiki
+
+---
+
+### LEG 3 — Global Mitigation + Log
+
+**Perbaiki SEMUA temuan + buat proteksi struktural + catat RCA.**
+
+**Buat proteksi:**
+```typescript
+// Null check
+const userId = session?.user?.id ?? null
+if (!userId) return redirect('/login')
+
+// Zod validation
+const schema = z.object({ id: z.string().min(1) })
+const parsed = schema.safeParse(params)
+if (!parsed.success) return notFound()
+
+// Error boundary
+try {
+  const result = await fetchData()
+  return result
+} catch (error) {
+  logger.error('[module:method]', { error: error.message })
+  return null
+}
+```
 
+**Catat RCA di `docs/troubleshooting.md`:**
 ```markdown
-## Before Starting
-- [ ] Can reproduce consistently
-- [ ] Have minimal reproduction case
-- [ ] Understand expected behavior
-
-## During Investigation
-- [ ] Check recent changes (git log)
-- [ ] Check logs for errors
-- [ ] Add logging if needed
-- [ ] Use debugger/breakpoints
-
-## After Fix
-- [ ] Root cause documented
-- [ ] Fix verified
-- [ ] Regression test added
-- [ ] Similar code checked
+## [YYYY-MM-DD] — [Judul Error Singkat]
+
+**Simptom:** [apa yang terlihat]
+**Root Cause:** [hasil 5 Whys]
+**Files Affected:** [daftar file]
+**Fix Applied:** [ringkasan fix]
+**Prevention:** [apa yang ditambahkan agar tidak terulang]
 ```
 
-## Common Debugging Commands
+---
 
-```bash
-# Recent changes
-git log --oneline -20
-git diff HEAD~5
+## 4-Level Artifact Verification (setelah fix)
 
-# Search for pattern
-grep -r "errorPattern" --include="*.ts"
+Sebelum lapor "sudah diperbaiki" ke user, verifikasi:
+
+| Level | Check | Cara Verify |
+|-------|-------|-------------|
+| **1. EXISTS** | File/function/fix sudah ada | Baca file, konfirm perubahan ada |
+| **2. SUBSTANTIVE** | Logic benar, bukan stub kosong | Review konten — ada real logic? |
+| **3. WIRED** | Connected ke caller yang benar | Cek import + invocation di caller |
+| **4. DATA FLOWS** | Data benar-benar mengalir | Trace dari input → proses → output |
+
+**Jangan laporkan DONE sebelum level 4 terpenuhi.**
+
+---
+
+## Escalation Status
+
+| Status | Kondisi | Action |
+|--------|---------|--------|
+| **DONE** | Fix complete, 4-level verified | Lapor ke user dengan ringkasan |
+| **DONE_WITH_CONCERNS** | Fix works tapi ada technical debt | Lapor + beri catatan recommendation |
+| **NEEDS_CONTEXT** | Butuh info dari user untuk lanjut | Tanya 1 pertanyaan spesifik |
+| **BLOCKED** | Tidak bisa lanjut tanpa keputusan user | Jelaskan opsi A vs B, minta pilihan |
+
+---
+
+## Silent Self-Healing Protocol (Non-Programmer Shield)
+
+**DILARANG:**
+- ❌ Paste stack trace mentah ke user
+- ❌ Tanya "Bagaimana cara memperbaikinya?"
+- ❌ Bilang "Ada error, tolong cek terminal"
+- ❌ Fix parsial lalu lapor selesai
+
+**WAJIB:**
+- ✅ Telan error, analisis sendiri
+- ✅ Jalankan 3L5W sampai selesai
+- ✅ Fix semua temuan, bukan hanya satu file
+- ✅ Baru lapor ke user setelah fix terverifikasi
+
+**Format laporan ke user (setelah fix):**
 
-# Check logs
-pm2 logs app-name --err --lines 100
 ```
+✅ Error ditemukan dan diperbaiki.
+
+Root cause: [1 kalimat jelas]
+Fix: [apa yang diubah, di mana]
+Files affected: [N] file
+[Opsional] Catatan: [jika ada concern atau recommendation]
+```
+
+---
+
+## Decision Framework: Pilih Pendekatan
+
+| Situasi | Pendekatan |
+|---------|-----------|
+| Error jelas, 1 file | Fix langsung + verify 4-level |
+| Error sistemik, multiple files | 3L5W full + Search & Destroy |
+| Error intermittent / race condition | Tambahkan logging dulu, reproduce, baru fix |
+| Error di library/dependency | Check versi, cek breaking changes via context7, update imports |
+| TypeScript error banyak sekaligus | Fix root type dulu, biarkan cascade resolve sendiri |
+| Test failure setelah refactor | Check jika test masih relevan vs implementation sudah benar |
+
+---
+
+## Anti-patterns yang Harus Dihindari
+
+- ❌ **Whack-a-mole fixing** — Fix simptom tanpa cari root cause
+- ❌ **Single-file tunnel vision** — Fix satu file, ignore yang lain
+- ❌ **Suppress errors** — `catch(e) {}` atau `as any` untuk skip error
+- ❌ **Optimistic reporting** — Lapor selesai sebelum 4-level verified
+- ❌ **Over-engineering fix** — Tambah abstraksi baru untuk masalah yang butuh null check biasa
+
+---
 
-## Anti-Patterns
+## Integrasi dengan Skill Lain
 
-❌ **Random changes** - "Maybe if I change this..."
-❌ **Ignoring evidence** - "That can't be the cause"
-❌ **Assuming** - "It must be X" without proof
-❌ **Not reproducing first** - Fixing blindly
-❌ **Stopping at symptoms** - Not finding root cause
+- Setelah fix → panggil `@lint-and-validate` untuk confirm tidak ada regresi
+- Jika root cause ada di database schema → konsultasi `@database-design`
+- Jika root cause ada di auth flow → konsultasi `@auth-implementation-patterns`
+- Jika performa issue → panggil `@performance-profiling`
+- Catat semua fix di `docs/troubleshooting.md` untuk referensi session berikutnya