pumuki 6.3.52 → 6.3.54

package/README.md

@@ -34,6 +34,7 @@ Install and bootstrap:
 npm install --save-exact pumuki
 npx --yes pumuki bootstrap --enterprise --agent=codex
 npx --yes pumuki status
+npx --yes pumuki doctor --json
 ```
 
 Fallback (equivalent in pasos separados):
@@ -80,6 +81,16 @@ Expected behavior:
 - `PRE_PUSH`: blocks if branch has no upstream tracking reference.
 - `CI`: requires a valid diff range context (not `HEAD..HEAD` with ambiguous range).
 
+Version drift quick check:
+
+- `status --json` and `doctor --json` expose `version.effective`, `version.runtime`, `version.consumerInstalled`, `version.lifecycleInstalled`, `version.driftWarning`, and `version.alignmentCommand`.
+- If `driftWarning` is not `null`, align the consumer with:
+
+```bash
+npm install --save-exact pumuki@6.3.52
+npx --yes pumuki update --latest
+```
+
 ## Why Pumuki
 
 Modern teams need fast feedback with strict governance. Pumuki combines:

package/docs/codex-skills/swift-concurrency.md

@@ -0,0 +1,246 @@
+---
+name: swift-concurrency
+description: 'Expert guidance on Swift Concurrency best practices, patterns, and implementation. Use when developers mention: (1) Swift Concurrency, async/await, actors, or tasks, (2) "use Swift Concurrency" or "modern concurrency patterns", (3) migrating to Swift 6, (4) data races or thread safety issues, (5) refactoring closures to async/await, (6) @MainActor, Sendable, or actor isolation, (7) concurrent code architecture or performance optimization, (8) concurrency-related linter warnings (SwiftLint or similar; e.g. async_without_await, Sendable/actor isolation/MainActor lint).'
+---
+# Swift Concurrency
+
+## Overview
+
+This skill provides expert guidance on Swift Concurrency, covering modern async/await patterns, actors, tasks, Sendable conformance, and migration to Swift 6. Use this skill to help developers write safe, performant concurrent code and navigate the complexities of Swift's structured concurrency model.
+
+## Agent Behavior Contract (Follow These Rules)
+
+1. Analyze the project/package file to find out which Swift language mode (Swift 5.x vs Swift 6) and which Xcode/Swift toolchain is used when advice depends on it.
+2. Before proposing fixes, identify the isolation boundary: `@MainActor`, custom actor, actor instance isolation, or nonisolated.
+3. Do not recommend `@MainActor` as a blanket fix. Justify why main-actor isolation is correct for the code.
+4. Prefer structured concurrency (child tasks, task groups) over unstructured tasks. Use `Task.detached` only with a clear reason.
+5. If recommending `@preconcurrency`, `@unchecked Sendable`, or `nonisolated(unsafe)`, require:
+   - a documented safety invariant
+   - a follow-up ticket to remove or migrate it
+6. For migration work, optimize for minimal blast radius (small, reviewable changes) and add verification steps.
+7. Course references are for deeper learning only. Use them sparingly and only when they clearly help answer the developer's question.
+
+## Recommended Tools for Analysis
+
+When analyzing Swift projects for concurrency issues:
+
+1. **Project Settings Discovery**
+   - Use `Read` on `Package.swift` for SwiftPM settings (tools version, strict concurrency flags, upcoming features)
+   - Use `Grep` for `SWIFT_STRICT_CONCURRENCY` or `SWIFT_DEFAULT_ACTOR_ISOLATION` in `.pbxproj` files
+   - Use `Grep` for `SWIFT_UPCOMING_FEATURE_` to find enabled upcoming features
+
+
+
+## Project Settings Intake (Evaluate Before Advising)
+
+Concurrency behavior depends on build settings. Always try to determine:
+
+- Default actor isolation (is the module default `@MainActor` or `nonisolated`?)
+- Strict concurrency checking level (minimal/targeted/complete)
+- Whether upcoming features are enabled (especially `NonisolatedNonsendingByDefault`)
+- Swift language mode (Swift 5.x vs Swift 6) and SwiftPM tools version
+
+### Manual checks (no scripts)
+
+- SwiftPM:
+  - Check `Package.swift` for `.defaultIsolation(MainActor.self)`.
+  - Check `Package.swift` for `.enableUpcomingFeature("NonisolatedNonsendingByDefault")`.
+  - Check for strict concurrency flags: `.enableExperimentalFeature("StrictConcurrency=targeted")` (or similar).
+  - Check tools version at the top: `// swift-tools-version: ...`
+- Xcode projects:
+  - Search `project.pbxproj` for:
+    - `SWIFT_DEFAULT_ACTOR_ISOLATION`
+    - `SWIFT_STRICT_CONCURRENCY`
+    - `SWIFT_UPCOMING_FEATURE_` (and/or `SWIFT_ENABLE_EXPERIMENTAL_FEATURES`)
+
+If any of these are unknown, ask the developer to confirm them before giving migration-sensitive guidance.
+
+## Quick Decision Tree
+
+When a developer needs concurrency guidance, follow this decision tree:
+
+1. **Starting fresh with async code?**
+   - Read `references/async-await-basics.md` for foundational patterns
+   - For parallel operations → `references/tasks.md` (async let, task groups)
+
+2. **Protecting shared mutable state?**
+   - Need to protect class-based state → `references/actors.md` (actors, @MainActor)
+   - Need thread-safe value passing → `references/sendable.md` (Sendable conformance)
+
+3. **Managing async operations?**
+   - Structured async work → `references/tasks.md` (Task, child tasks, cancellation)
+   - Streaming data → `references/async-sequences.md` (AsyncSequence, AsyncStream)
+
+4. **Working with legacy frameworks?**
+   - Core Data integration → `references/core-data.md`
+   - General migration → `references/migration.md`
+
+5. **Performance or debugging issues?**
+   - Slow async code → `references/performance.md` (profiling, suspension points)
+   - Testing concerns → `references/testing.md` (XCTest, Swift Testing)
+
+6. **Understanding threading behavior?**
+   - Read `references/threading.md` for thread/task relationship and isolation
+
+7. **Memory issues with tasks?**
+   - Read `references/memory-management.md` for retain cycle prevention
+
+## Triage-First Playbook (Common Errors -> Next Best Move)
+
+- SwiftLint concurrency-related warnings
+  - Use `references/linting.md` for rule intent and preferred fixes; avoid dummy awaits as “fixes”.
+- SwiftLint `async_without_await` warning
+  - Remove `async` if not required; if required by protocol/override/@concurrent, prefer narrow suppression over adding fake awaits. See `references/linting.md`.
+- "Sending value of non-Sendable type ... risks causing data races"
+  - First: identify where the value crosses an isolation boundary
+  - Then: use `references/sendable.md` and `references/threading.md` (especially Swift 6.2 behavior changes)
+- "Main actor-isolated ... cannot be used from a nonisolated context"
+  - First: decide if it truly belongs on `@MainActor`
+  - Then: use `references/actors.md` (global actors, `nonisolated`, isolated parameters) and `references/threading.md` (default isolation)
+- "Class property 'current' is unavailable from asynchronous contexts" (Thread APIs)
+  - Use `references/threading.md` to avoid thread-centric debugging and rely on isolation + Instruments
+- XCTest async errors like "wait(...) is unavailable from asynchronous contexts"
+  - Use `references/testing.md` (`await fulfillment(of:)` and Swift Testing patterns)
+- Core Data concurrency warnings/errors
+  - Use `references/core-data.md` (DAO/`NSManagedObjectID`, default isolation conflicts)
+
+## Core Patterns Reference
+
+### When to Use Each Concurrency Tool
+
+**async/await** - Making existing synchronous code asynchronous
+```swift
+// Use for: Single asynchronous operations
+func fetchUser() async throws -> User {
+    try await networkClient.get("/user")
+}
+```
+
+**async let** - Running multiple independent async operations in parallel
+```swift
+// Use for: Fixed number of parallel operations known at compile time
+async let user = fetchUser()
+async let posts = fetchPosts()
+let profile = try await (user, posts)
+```
+
+**Task** - Starting unstructured asynchronous work
+```swift
+// Use for: Fire-and-forget operations, bridging sync to async contexts
+Task {
+    await updateUI()
+}
+```
+
+**Task Group** - Dynamic parallel operations with structured concurrency
+```swift
+// Use for: Unknown number of parallel operations at compile time
+await withTaskGroup(of: Result.self) { group in
+    for item in items {
+        group.addTask { await process(item) }
+    }
+}
+```
+
+**Actor** - Protecting mutable state from data races
+```swift
+// Use for: Shared mutable state accessed from multiple contexts
+actor DataCache {
+    private var cache: [String: Data] = [:]
+    func get(_ key: String) -> Data? { cache[key] }
+}
+```
+
+**@MainActor** - Ensuring UI updates on main thread
+```swift
+// Use for: View models, UI-related classes
+@MainActor
+class ViewModel: ObservableObject {
+    @Published var data: String = ""
+}
+```
+
+### Common Scenarios
+
+**Scenario: Network request with UI update**
+```swift
+Task { @concurrent in
+    let data = try await fetchData() // Background
+    await MainActor.run {
+        self.updateUI(with: data) // Main thread
+    }
+}
+```
+
+**Scenario: Multiple parallel network requests**
+```swift
+async let users = fetchUsers()
+async let posts = fetchPosts()
+async let comments = fetchComments()
+let (u, p, c) = try await (users, posts, comments)
+```
+
+**Scenario: Processing array items in parallel**
+```swift
+await withTaskGroup(of: ProcessedItem.self) { group in
+    for item in items {
+        group.addTask { await process(item) }
+    }
+    for await result in group {
+        results.append(result)
+    }
+}
+```
+
+## Swift 6 Migration Quick Guide
+
+Key changes in Swift 6:
+- **Strict concurrency checking** enabled by default
+- **Complete data-race safety** at compile time
+- **Sendable requirements** enforced on boundaries
+- **Isolation checking** for all async boundaries
+
+For detailed migration steps, see `references/migration.md`.
+
+## Reference Files
+
+Load these files as needed for specific topics:
+
+- **`async-await-basics.md`** - async/await syntax, execution order, async let, URLSession patterns
+- **`tasks.md`** - Task lifecycle, cancellation, priorities, task groups, structured vs unstructured
+- **`threading.md`** - Thread/task relationship, suspension points, isolation domains, nonisolated
+- **`memory-management.md`** - Retain cycles in tasks, memory safety patterns
+- **`actors.md`** - Actor isolation, @MainActor, global actors, reentrancy, custom executors, Mutex
+- **`sendable.md`** - Sendable conformance, value/reference types, @unchecked, region isolation
+- **`linting.md`** - Concurrency-focused lint rules and SwiftLint `async_without_await`
+- **`async-sequences.md`** - AsyncSequence, AsyncStream, when to use vs regular async methods
+- **`core-data.md`** - NSManagedObject sendability, custom executors, isolation conflicts
+- **`performance.md`** - Profiling with Instruments, reducing suspension points, execution strategies
+- **`testing.md`** - XCTest async patterns, Swift Testing, concurrency testing utilities
+- **`migration.md`** - Swift 6 migration strategy, closure-to-async conversion, @preconcurrency, FRP migration
+
+## Best Practices Summary
+
+1. **Prefer structured concurrency** - Use task groups over unstructured tasks when possible
+2. **Minimize suspension points** - Keep actor-isolated sections small to reduce context switches
+3. **Use @MainActor judiciously** - Only for truly UI-related code
+4. **Make types Sendable** - Enable safe concurrent access by conforming to Sendable
+5. **Handle cancellation** - Check Task.isCancelled in long-running operations
+6. **Avoid blocking** - Never use semaphores or locks in async contexts
+7. **Test concurrent code** - Use proper async test methods and consider timing issues
+
+## Verification Checklist (When You Change Concurrency Code)
+
+- Confirm build settings (default isolation, strict concurrency, upcoming features) before interpreting diagnostics.
+- After refactors:
+  - Run tests, especially concurrency-sensitive ones (see `references/testing.md`).
+  - If performance-related, verify with Instruments (see `references/performance.md`).
+  - If lifetime-related, verify deinit/cancellation behavior (see `references/memory-management.md`).
+
+## Glossary
+
+See `references/glossary.md` for quick definitions of core concurrency terms used across this skill.
+
+---
+
+**Note**: This skill is based on the comprehensive [Swift Concurrency Course](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=skill-footer) by Antoine van der Lee.

package/docs/codex-skills/swiftui-expert-skill.md

@@ -0,0 +1,263 @@
+---
+name: swiftui-expert-skill
+description: Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, modern APIs, Swift concurrency, and iOS 26+ Liquid Glass adoption. Use when building new SwiftUI features, refactoring existing views, reviewing code quality, or adopting modern SwiftUI patterns.
+---
+
+# SwiftUI Expert Skill
+
+## Overview
+Use this skill to build, review, or improve SwiftUI features with correct state management, modern API usage, Swift concurrency best practices, optimal view composition, and iOS 26+ Liquid Glass styling. Prioritize native APIs, Apple design guidance, and performance-conscious patterns. This skill focuses on facts and best practices without enforcing specific architectural patterns.
+
+## Workflow Decision Tree
+
+### 1) Review existing SwiftUI code
+- Check property wrapper usage against the selection guide (see `references/state-management.md`)
+- Verify modern API usage (see `references/modern-apis.md`)
+- Verify view composition follows extraction rules (see `references/view-structure.md`)
+- Check performance patterns are applied (see `references/performance-patterns.md`)
+- Verify list patterns use stable identity (see `references/list-patterns.md`)
+- Inspect Liquid Glass usage for correctness and consistency (see `references/liquid-glass.md`)
+- Validate iOS 26+ availability handling with sensible fallbacks
+
+### 2) Improve existing SwiftUI code
+- Audit state management for correct wrapper selection (prefer `@Observable` over `ObservableObject`)
+- Replace deprecated APIs with modern equivalents (see `references/modern-apis.md`)
+- Extract complex views into separate subviews (see `references/view-structure.md`)
+- Refactor hot paths to minimize redundant state updates (see `references/performance-patterns.md`)
+- Ensure ForEach uses stable identity (see `references/list-patterns.md`)
+- Suggest image downsampling when `UIImage(data:)` is used (as optional optimization, see `references/image-optimization.md`)
+- Adopt Liquid Glass only when explicitly requested by the user
+
+### 3) Implement new SwiftUI feature
+- Design data flow first: identify owned vs injected state (see `references/state-management.md`)
+- Use modern APIs (no deprecated modifiers or patterns, see `references/modern-apis.md`)
+- Use `@Observable` for shared state (with `@MainActor` if not using default actor isolation)
+- Structure views for optimal diffing (extract subviews early, keep views small, see `references/view-structure.md`)
+- Separate business logic into testable models (see `references/layout-best-practices.md`)
+- Apply glass effects after layout/appearance modifiers (see `references/liquid-glass.md`)
+- Gate iOS 26+ features with `#available` and provide fallbacks
+
+## Core Guidelines
+
+### State Management
+- **Always prefer `@Observable` over `ObservableObject`** for new code
+- **Mark `@Observable` classes with `@MainActor`** unless using default actor isolation
+- **Always mark `@State` and `@StateObject` as `private`** (makes dependencies clear)
+- **Never declare passed values as `@State` or `@StateObject`** (they only accept initial values)
+- Use `@State` with `@Observable` classes (not `@StateObject`)
+- `@Binding` only when child needs to **modify** parent state
+- `@Bindable` for injected `@Observable` objects needing bindings
+- Use `let` for read-only values; `var` + `.onChange()` for reactive reads
+- Legacy: `@StateObject` for owned `ObservableObject`; `@ObservedObject` for injected
+- Nested `ObservableObject` doesn't work (pass nested objects directly); `@Observable` handles nesting fine
+
+### Modern APIs
+- Use `foregroundStyle()` instead of `foregroundColor()`
+- Use `clipShape(.rect(cornerRadius:))` instead of `cornerRadius()`
+- Use `Tab` API instead of `tabItem()`
+- Use `Button` instead of `onTapGesture()` (unless need location/count)
+- Use `NavigationStack` instead of `NavigationView`
+- Use `navigationDestination(for:)` for type-safe navigation
+- Use two-parameter or no-parameter `onChange()` variant
+- Use `ImageRenderer` for rendering SwiftUI views
+- Use `.sheet(item:)` instead of `.sheet(isPresented:)` for model-based content
+- Sheets should own their actions and call `dismiss()` internally
+- Use `ScrollViewReader` for programmatic scrolling with stable IDs
+- Avoid `UIScreen.main.bounds` for sizing
+- Avoid `GeometryReader` when alternatives exist (e.g., `containerRelativeFrame()`)
+
+### Swift Best Practices
+- Use modern Text formatting (`.format` parameters, not `String(format:)`)
+- Use `localizedStandardContains()` for user-input filtering (not `contains()`)
+- Prefer static member lookup (`.blue` vs `Color.blue`)
+- Use `.task` modifier for automatic cancellation of async work
+- Use `.task(id:)` for value-dependent tasks
+
+### View Composition
+- **Prefer modifiers over conditional views** for state changes (maintains view identity)
+- Extract complex views into separate subviews for better readability and performance
+- Keep views small for optimal performance
+- Keep view `body` simple and pure (no side effects or complex logic)
+- Use `@ViewBuilder` functions only for small, simple sections
+- Prefer `@ViewBuilder let content: Content` over closure-based content properties
+- Separate business logic into testable models (not about enforcing architectures)
+- Action handlers should reference methods, not contain inline logic
+- Use relative layout over hard-coded constants
+- Views should work in any context (don't assume screen size or presentation style)
+
+### Performance
+- Pass only needed values to views (avoid large "config" or "context" objects)
+- Eliminate unnecessary dependencies to reduce update fan-out
+- Check for value changes before assigning state in hot paths
+- Avoid redundant state updates in `onReceive`, `onChange`, scroll handlers
+- Minimize work in frequently executed code paths
+- Use `LazyVStack`/`LazyHStack` for large lists
+- Use stable identity for `ForEach` (never `.indices` for dynamic content)
+- Ensure constant number of views per `ForEach` element
+- Avoid inline filtering in `ForEach` (prefilter and cache)
+- Avoid `AnyView` in list rows
+- Consider POD views for fast diffing (or wrap expensive views in POD parents)
+- Suggest image downsampling when `UIImage(data:)` is encountered (as optional optimization)
+- Avoid layout thrash (deep hierarchies, excessive `GeometryReader`)
+- Gate frequent geometry updates by thresholds
+- Use `Self._printChanges()` to debug unexpected view updates
+
+### Liquid Glass (iOS 26+)
+**Only adopt when explicitly requested by the user.**
+- Use native `glassEffect`, `GlassEffectContainer`, and glass button styles
+- Wrap multiple glass elements in `GlassEffectContainer`
+- Apply `.glassEffect()` after layout and visual modifiers
+- Use `.interactive()` only for tappable/focusable elements
+- Use `glassEffectID` with `@Namespace` for morphing transitions
+
+## Quick Reference
+
+### Property Wrapper Selection (Modern)
+| Wrapper | Use When |
+|---------|----------|
+| `@State` | Internal view state (must be `private`), or owned `@Observable` class |
+| `@Binding` | Child modifies parent's state |
+| `@Bindable` | Injected `@Observable` needing bindings |
+| `let` | Read-only value from parent |
+| `var` | Read-only value watched via `.onChange()` |
+
+**Legacy (Pre-iOS 17):**
+| Wrapper | Use When |
+|---------|----------|
+| `@StateObject` | View owns an `ObservableObject` (use `@State` with `@Observable` instead) |
+| `@ObservedObject` | View receives an `ObservableObject` |
+
+### Modern API Replacements
+| Deprecated | Modern Alternative |
+|------------|-------------------|
+| `foregroundColor()` | `foregroundStyle()` |
+| `cornerRadius()` | `clipShape(.rect(cornerRadius:))` |
+| `tabItem()` | `Tab` API |
+| `onTapGesture()` | `Button` (unless need location/count) |
+| `NavigationView` | `NavigationStack` |
+| `onChange(of:) { value in }` | `onChange(of:) { old, new in }` or `onChange(of:) { }` |
+| `fontWeight(.bold)` | `bold()` |
+| `GeometryReader` | `containerRelativeFrame()` or `visualEffect()` |
+| `showsIndicators: false` | `.scrollIndicators(.hidden)` |
+| `String(format: "%.2f", value)` | `Text(value, format: .number.precision(.fractionLength(2)))` |
+| `string.contains(search)` | `string.localizedStandardContains(search)` (for user input) |
+
+### Liquid Glass Patterns
+```swift
+// Basic glass effect with fallback
+if #available(iOS 26, *) {
+    content
+        .padding()
+        .glassEffect(.regular.interactive(), in: .rect(cornerRadius: 16))
+} else {
+    content
+        .padding()
+        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
+}
+
+// Grouped glass elements
+GlassEffectContainer(spacing: 24) {
+    HStack(spacing: 24) {
+        GlassButton1()
+        GlassButton2()
+    }
+}
+
+// Glass buttons
+Button("Confirm") { }
+    .buttonStyle(.glassProminent)
+```
+
+## Review Checklist
+
+### State Management
+- [ ] Using `@Observable` instead of `ObservableObject` for new code
+- [ ] `@Observable` classes marked with `@MainActor` (if needed)
+- [ ] Using `@State` with `@Observable` classes (not `@StateObject`)
+- [ ] `@State` and `@StateObject` properties are `private`
+- [ ] Passed values NOT declared as `@State` or `@StateObject`
+- [ ] `@Binding` only where child modifies parent state
+- [ ] `@Bindable` for injected `@Observable` needing bindings
+- [ ] Nested `ObservableObject` avoided (or passed directly to child views)
+
+### Modern APIs (see `references/modern-apis.md`)
+- [ ] Using `foregroundStyle()` instead of `foregroundColor()`
+- [ ] Using `clipShape(.rect(cornerRadius:))` instead of `cornerRadius()`
+- [ ] Using `Tab` API instead of `tabItem()`
+- [ ] Using `Button` instead of `onTapGesture()` (unless need location/count)
+- [ ] Using `NavigationStack` instead of `NavigationView`
+- [ ] Avoiding `UIScreen.main.bounds`
+- [ ] Using alternatives to `GeometryReader` when possible
+- [ ] Button images include text labels for accessibility
+
+### Sheets & Navigation (see `references/sheet-navigation-patterns.md`)
+- [ ] Using `.sheet(item:)` for model-based sheets
+- [ ] Sheets own their actions and dismiss internally
+- [ ] Using `navigationDestination(for:)` for type-safe navigation
+
+### ScrollView (see `references/scroll-patterns.md`)
+- [ ] Using `ScrollViewReader` with stable IDs for programmatic scrolling
+- [ ] Using `.scrollIndicators(.hidden)` instead of initializer parameter
+
+### Text & Formatting (see `references/text-formatting.md`)
+- [ ] Using modern Text formatting (not `String(format:)`)
+- [ ] Using `localizedStandardContains()` for search filtering
+
+### View Structure (see `references/view-structure.md`)
+- [ ] Using modifiers instead of conditionals for state changes
+- [ ] Complex views extracted to separate subviews
+- [ ] Views kept small for performance
+- [ ] Container views use `@ViewBuilder let content: Content`
+
+### Performance (see `references/performance-patterns.md`)
+- [ ] View `body` kept simple and pure (no side effects)
+- [ ] Passing only needed values (not large config objects)
+- [ ] Eliminating unnecessary dependencies
+- [ ] State updates check for value changes before assigning
+- [ ] Hot paths minimize state updates
+- [ ] No object creation in `body`
+- [ ] Heavy computation moved out of `body`
+
+### List Patterns (see `references/list-patterns.md`)
+- [ ] ForEach uses stable identity (not `.indices`)
+- [ ] Constant number of views per ForEach element
+- [ ] No inline filtering in ForEach
+- [ ] No `AnyView` in list rows
+
+### Layout (see `references/layout-best-practices.md`)
+- [ ] Avoiding layout thrash (deep hierarchies, excessive GeometryReader)
+- [ ] Gating frequent geometry updates by thresholds
+- [ ] Business logic separated into testable models
+- [ ] Action handlers reference methods (not inline logic)
+- [ ] Using relative layout (not hard-coded constants)
+- [ ] Views work in any context (context-agnostic)
+
+### Liquid Glass (iOS 26+)
+- [ ] `#available(iOS 26, *)` with fallback for Liquid Glass
+- [ ] Multiple glass views wrapped in `GlassEffectContainer`
+- [ ] `.glassEffect()` applied after layout/appearance modifiers
+- [ ] `.interactive()` only on user-interactable elements
+- [ ] Shapes and tints consistent across related elements
+
+## References
+- `references/state-management.md` - Property wrappers and data flow (prefer `@Observable`)
+- `references/view-structure.md` - View composition, extraction, and container patterns
+- `references/performance-patterns.md` - Performance optimization techniques and anti-patterns
+- `references/list-patterns.md` - ForEach identity, stability, and list best practices
+- `references/layout-best-practices.md` - Layout patterns, context-agnostic views, and testability
+- `references/modern-apis.md` - Modern API usage and deprecated replacements
+- `references/sheet-navigation-patterns.md` - Sheet presentation and navigation patterns
+- `references/scroll-patterns.md` - ScrollView patterns and programmatic scrolling
+- `references/text-formatting.md` - Modern text formatting and string operations
+- `references/image-optimization.md` - AsyncImage, image downsampling, and optimization
+- `references/liquid-glass.md` - iOS 26+ Liquid Glass API
+
+## Philosophy
+
+This skill focuses on **facts and best practices**, not architectural opinions:
+- We don't enforce specific architectures (e.g., MVVM, VIPER)
+- We do encourage separating business logic for testability
+- We prioritize modern APIs over deprecated ones
+- We emphasize thread safety with `@MainActor` and `@Observable`
+- We optimize for performance and maintainability
+- We follow Apple's Human Interface Guidelines and API design patterns