agentic-team-templates 0.13.1 → 0.14.0

package/templates/swift-expert/.cursorrules/language-features.md

@@ -0,0 +1,246 @@
+# Swift Language Features
+
+Optionals, value types, enums, generics, and protocol-oriented design. The type system is your strongest tool.
+
+## Optionals
+
+```swift
+// Guard let — early exit pattern (preferred)
+guard let user = fetchUser(id: userId) else {
+    throw AppError.userNotFound(userId)
+}
+// user is non-optional from here
+
+// If let — conditional binding
+if let email = user.email {
+    sendNotification(to: email)
+}
+
+// Optional chaining
+let street = user.address?.street?.uppercased()
+
+// Nil coalescing
+let displayName = user.nickname ?? user.fullName ?? "Anonymous"
+
+// Optional map/flatMap
+let uppercasedEmail = user.email.map { $0.uppercased() }
+let parsed: URL? = urlString.flatMap { URL(string: $0) }
+
+// Never: force-unwrap without proof
+// user.email!  — use guard/if let instead
+// Only acceptable: IBOutlets (UIKit), known-safe literals
+let url = URL(string: "https://api.example.com")! // Known-safe literal
+```
+
+## Value Types vs Reference Types
+
+```swift
+// Prefer structs — value semantics, no shared mutable state
+struct User: Identifiable, Sendable {
+    let id: UUID
+    var name: String
+    var email: String
+    var preferences: Preferences
+}
+
+// Use classes only when you need:
+// 1. Identity (object === object)
+// 2. Reference semantics (shared state)
+// 3. Inheritance from ObjC classes
+// 4. Deinitializers
+class NetworkSession {
+    private var urlSession: URLSession
+    deinit { urlSession.invalidateAndCancel() }
+}
+
+// Copy-on-write for large value types
+struct LargeCollection<Element> {
+    private var storage: Storage // Reference type internally
+    // Implement COW manually only when profiling shows need
+}
+```
+
+## Enums
+
+```swift
+// Enums with associated values — model state precisely
+enum LoadingState<T> {
+    case idle
+    case loading
+    case loaded(T)
+    case failed(Error)
+}
+
+// Exhaustive switch — compiler enforces all cases
+func render(state: LoadingState<[User]>) -> some View {
+    switch state {
+    case .idle:
+        EmptyView()
+    case .loading:
+        ProgressView()
+    case .loaded(let users):
+        UserListView(users: users)
+    case .failed(let error):
+        ErrorView(error: error)
+    }
+    // No default needed — compiler verifies exhaustiveness
+}
+
+// String-backed enums for API
+enum UserRole: String, Codable, CaseIterable {
+    case admin
+    case editor
+    case viewer
+}
+
+// Enums as namespaces
+enum Constants {
+    static let maxRetries = 3
+    static let defaultTimeout: TimeInterval = 30
+}
+```
+
+## Protocols and Extensions
+
+```swift
+// Small, focused protocols
+protocol Identifiable {
+    associatedtype ID: Hashable
+    var id: ID { get }
+}
+
+protocol Displayable {
+    var displayName: String { get }
+}
+
+// Default implementations
+extension Displayable where Self: User {
+    var displayName: String { "\(firstName) \(lastName)" }
+}
+
+// Protocol composition
+func showProfile(for entity: Identifiable & Displayable) {
+    print("\(entity.id): \(entity.displayName)")
+}
+
+// Constrained extensions
+extension Array where Element: Numeric {
+    var sum: Element { reduce(0, +) }
+}
+
+extension Collection where Element: Identifiable {
+    func element(withId id: Element.ID) -> Element? {
+        first { $0.id == id }
+    }
+}
+```
+
+## Generics
+
+```swift
+// Generic functions
+func decode<T: Decodable>(_ type: T.Type, from data: Data) throws -> T {
+    try JSONDecoder().decode(type, from: data)
+}
+
+// Generic types with constraints
+struct Repository<Entity: Identifiable & Codable> {
+    private var storage: [Entity.ID: Entity] = [:]
+
+    mutating func save(_ entity: Entity) {
+        storage[entity.id] = entity
+    }
+
+    func find(by id: Entity.ID) -> Entity? {
+        storage[id]
+    }
+}
+
+// Opaque return types (some)
+func makeView() -> some View {
+    VStack {
+        Text("Hello")
+        Image(systemName: "star")
+    }
+}
+
+// Primary associated types (Swift 5.7+)
+func processCollection(_ items: some Collection<User>) { /* ... */ }
+```
+
+## Property Wrappers
+
+```swift
+// Standard property wrappers
+@Published var users: [User] = []
+@State private var isPresented = false
+@Binding var selectedTab: Tab
+@Environment(\.dismiss) var dismiss
+@AppStorage("darkMode") var isDarkMode = false
+
+// Custom property wrapper
+@propertyWrapper
+struct Clamped<Value: Comparable> {
+    private var value: Value
+    let range: ClosedRange<Value>
+
+    var wrappedValue: Value {
+        get { value }
+        set { value = min(max(newValue, range.lowerBound), range.upperBound) }
+    }
+
+    init(wrappedValue: Value, _ range: ClosedRange<Value>) {
+        self.range = range
+        self.value = min(max(wrappedValue, range.lowerBound), range.upperBound)
+    }
+}
+
+struct AudioSettings {
+    @Clamped(0...100) var volume: Int = 50
+}
+```
+
+## Result Builders
+
+```swift
+// SwiftUI uses @ViewBuilder
+@ViewBuilder
+func content(for state: LoadingState<User>) -> some View {
+    switch state {
+    case .loading:
+        ProgressView()
+    case .loaded(let user):
+        Text(user.name)
+    default:
+        EmptyView()
+    }
+}
+```
+
+## Anti-Patterns
+
+```swift
+// Never: force-unwrapping optionals carelessly
+let name = user.name!  // Crash if nil
+// Use: guard let name = user.name else { return }
+
+// Never: class where struct suffices
+class Point { var x: Double; var y: Double }
+// Use: struct Point { var x: Double; var y: Double }
+
+// Never: stringly-typed APIs
+func fetchData(endpoint: String) { /* ... */ }
+// Use: enum Endpoint { case users; case orders }
+
+// Never: Any/AnyObject without cause
+func process(_ items: [Any]) { /* ... */ }
+// Use: generics or protocols
+
+// Never: deeply nested if/let chains
+if let a = optionalA {
+    if let b = a.optionalB {
+        if let c = b.optionalC { /* ... */ }
+    }
+}
+// Use: guard let with early return, or optional chaining
+```

package/templates/swift-expert/.cursorrules/overview.md

@@ -0,0 +1,88 @@
+# Swift Expert Overview
+
+Principal-level Swift engineering. Deep language mastery, protocol-oriented design, concurrency, and Apple platform expertise.
+
+## Scope
+
+This guide applies to:
+- iOS and iPadOS applications (UIKit, SwiftUI)
+- macOS applications (AppKit, SwiftUI)
+- watchOS and tvOS applications
+- Server-side Swift (Vapor, Hummingbird)
+- Swift packages and frameworks
+- Command-line tools
+
+## Core Philosophy
+
+Swift is a safe, fast, and expressive language. Use its type system to make invalid states unrepresentable.
+
+- **Safety is the foundation.** Optionals, value types, and the compiler are your first line of defense
+- **Protocol-oriented design.** Prefer protocols and composition over class inheritance
+- **Value semantics by default.** Structs over classes unless you need reference semantics
+- **Concurrency is structured.** async/await, actors, and task groups — not GCD callbacks
+- **Expressiveness without obscurity.** Clear is better than clever
+- **If you don't know, say so.** Admitting uncertainty is professional
+
+## Key Principles
+
+1. **Optionals Are Not Enemies** — Embrace `Optional`. Never force-unwrap without proof. Use `guard`, `if let`, `map`, `flatMap`
+2. **Value Types by Default** — Structs, enums, tuples. Classes only when identity or reference semantics are required
+3. **Protocol-Oriented Design** — Small, focused protocols. Default implementations via extensions. Composition over inheritance
+4. **Structured Concurrency** — `async`/`await`, `TaskGroup`, actors. No completion handler callbacks in new code
+5. **Exhaustive Pattern Matching** — `switch` on enums is exhaustive. The compiler enforces completeness
+
+## Project Structure
+
+```
+MyApp/
+├── Sources/
+│   ├── App/
+│   │   ├── MyAppApp.swift
+│   │   └── AppDelegate.swift
+│   ├── Features/
+│   │   ├── Auth/
+│   │   │   ├── Views/
+│   │   │   ├── ViewModels/
+│   │   │   └── Models/
+│   │   └── Home/
+│   ├── Core/
+│   │   ├── Networking/
+│   │   ├── Persistence/
+│   │   └── Extensions/
+│   └── Shared/
+│       ├── Components/
+│       └── Utilities/
+├── Tests/
+│   ├── UnitTests/
+│   ├── IntegrationTests/
+│   └── UITests/
+├── Package.swift (or .xcodeproj)
+└── README.md
+```
+
+## API Design Guidelines
+
+Follow Swift's official API Design Guidelines:
+
+- **Clarity at the point of use** is the most important goal
+- **Omit needless words** — every word should convey information
+- **Name according to roles**, not types: `let greeting: String` not `let greetingString: String`
+- **Label closure parameters**: `func filter(_ isIncluded: (Element) -> Bool)`
+- **Boolean properties** read as assertions: `isEmpty`, `hasChildren`, `canBecomeFirstResponder`
+- **Mutating/nonmutating pairs**: `sort()`/`sorted()`, `append()`/`appending()`
+- **Protocols describing capabilities** end in `-able`, `-ible`, or `-ing`: `Equatable`, `Codable`, `Sendable`
+
+## Definition of Done
+
+A Swift feature is complete when:
+
+- [ ] Compiles with zero warnings
+- [ ] All tests pass (unit + UI)
+- [ ] No force-unwraps (`!`) without documented justification
+- [ ] No `var` where `let` suffices
+- [ ] Proper access control (`private`, `internal`, `public`)
+- [ ] Concurrency code uses structured concurrency (no raw GCD in new code)
+- [ ] SwiftLint reports zero violations
+- [ ] No retain cycles (weak/unowned references verified)
+- [ ] Accessibility labels on all interactive UI elements
+- [ ] Code reviewed and approved

package/templates/swift-expert/.cursorrules/performance.md

@@ -0,0 +1,260 @@
+# Swift Performance
+
+Profile first. Understand ARC, value types, and Instruments. Optimize what matters.
+
+## Profile Before Optimizing
+
+```bash
+# Instruments — always profile before optimizing
+# Time Profiler: CPU hotspots
+# Allocations: memory usage and leaks
+# Leaks: retain cycles
+# Network: request analysis
+# Core Animation: rendering performance
+
+# Xcode: Product → Profile (⌘I)
+```
+
+## Value Types and Copy-on-Write
+
+```swift
+// Structs are stack-allocated (when possible) and value-copied
+// But Swift uses COW for standard library collections
+var array1 = [1, 2, 3]
+var array2 = array1 // No copy yet — shared storage
+array2.append(4)    // Copy happens here (COW trigger)
+
+// Custom COW for large value types
+struct LargeStruct {
+    private final class Storage {
+        var data: [Int]
+        init(data: [Int]) { self.data = data }
+    }
+
+    private var storage: Storage
+
+    var data: [Int] {
+        get { storage.data }
+        set {
+            if !isKnownUniquelyReferenced(&storage) {
+                storage = Storage(data: newValue)
+            } else {
+                storage.data = newValue
+            }
+        }
+    }
+}
+```
+
+## ARC and Retain Cycles
+
+```swift
+// Weak references — break retain cycles
+class ViewController: UIViewController {
+    private var cancellable: AnyCancellable?
+
+    func subscribe() {
+        cancellable = publisher
+            .sink { [weak self] value in  // weak self!
+                self?.handleValue(value)
+            }
+    }
+}
+
+// Unowned — when you guarantee the reference outlives the closure
+class Parent {
+    let child: Child
+
+    init() {
+        child = Child()
+        child.onComplete = { [unowned self] in
+            self.handleCompletion() // Crashes if self is deallocated
+        }
+    }
+}
+
+// Capture lists — be explicit
+Task { [weak self, userId = self.user.id] in
+    guard let self else { return }
+    let data = try await self.fetch(userId: userId)
+}
+```
+
+## Collection Performance
+
+```swift
+// Reserve capacity for known sizes
+var results: [ProcessedItem] = []
+results.reserveCapacity(items.count)
+
+// Use lazy for chained operations on large collections
+let names = users.lazy
+    .filter { $0.isActive }
+    .map { $0.fullName }
+    .prefix(10)
+// Operations only execute when iterated
+
+// ContiguousArray for non-class element types
+let numbers = ContiguousArray<Int>(repeating: 0, count: 1000)
+// Guaranteed contiguous memory layout — better cache performance
+
+// Set for membership tests
+let activeIds = Set(activeUsers.map(\.id)) // O(1) lookup
+let filtered = orders.filter { activeIds.contains($0.userId) }
+
+// Dictionary for keyed access
+let userById = Dictionary(uniqueKeysWithValues: users.map { ($0.id, $0) })
+```
+
+## String Performance
+
+```swift
+// String is a value type with COW
+// UTF-8 encoded internally — character access is O(n)
+
+// Prefer Substring over creating new Strings
+let greeting = "Hello, World!"
+let hello = greeting.prefix(5) // Substring — shares storage
+
+// Convert to String only when needed for storage
+let stored = String(hello) // Creates independent copy
+
+// Use string interpolation — optimized by compiler
+let message = "User \(user.name) logged in" // Efficient
+
+// For heavy concatenation
+var result = ""
+result.reserveCapacity(estimatedLength)
+for item in items {
+    result += item.description
+}
+```
+
+## SwiftUI Performance
+
+```swift
+// Avoid unnecessary view recomputation
+struct UserRow: View {
+    let user: User // Prefer let over @State for display-only data
+
+    var body: some View {
+        HStack {
+            AvatarView(url: user.avatarURL)
+            Text(user.name)
+        }
+    }
+}
+
+// Equatable conformance to skip redundant diffs
+struct ExpensiveView: View, Equatable {
+    let data: ChartData
+
+    static func == (lhs: Self, rhs: Self) -> Bool {
+        lhs.data.id == rhs.data.id && lhs.data.version == rhs.data.version
+    }
+
+    var body: some View {
+        ChartRenderer(data: data) // Expensive
+    }
+}
+
+// Use @Observable over ObservableObject (iOS 17+)
+// @Observable tracks property-level access — fewer view updates
+
+// Lazy stacks for large lists
+ScrollView {
+    LazyVStack { // Only creates visible views
+        ForEach(items) { item in
+            ItemRow(item: item)
+        }
+    }
+}
+```
+
+## Concurrency Performance
+
+```swift
+// Limit concurrent work
+func processImages(_ urls: [URL]) async throws -> [UIImage] {
+    try await withThrowingTaskGroup(of: UIImage.self) { group in
+        let maxConcurrency = ProcessInfo.processInfo.activeProcessorCount
+
+        var results: [UIImage] = []
+        results.reserveCapacity(urls.count)
+
+        for (index, url) in urls.enumerated() {
+            if index >= maxConcurrency {
+                if let image = try await group.next() {
+                    results.append(image)
+                }
+            }
+            group.addTask { try await downloadImage(from: url) }
+        }
+
+        for try await image in group {
+            results.append(image)
+        }
+        return results
+    }
+}
+
+// Avoid unnecessary actor hops
+actor DataStore {
+    private var items: [Item] = []
+
+    // Batch operations reduce actor hops
+    func addAll(_ newItems: [Item]) {
+        items.append(contentsOf: newItems) // Single hop
+    }
+    // Instead of calling add(_:) in a loop — one hop per call
+}
+```
+
+## Memory Management
+
+```swift
+// Autoreleasepool for tight loops with ObjC objects
+func processLargeDataset() {
+    for batch in dataset.chunks(ofCount: 100) {
+        autoreleasepool {
+            let processed = batch.map { transform($0) }
+            save(processed)
+        }
+        // Memory released each iteration
+    }
+}
+
+// Avoid strong reference cycles in closures
+class NetworkManager {
+    var onComplete: ((Result<Data, Error>) -> Void)?
+
+    deinit {
+        onComplete = nil // Break cycle on dealloc
+    }
+}
+```
+
+## Anti-Patterns
+
+```swift
+// Never: premature optimization without profiling
+// "I think this allocation is slow" — prove it with Instruments
+
+// Never: using classes where structs work
+class Point { var x: Double; var y: Double } // Heap allocation
+// Use: struct Point — stack allocation, no ARC overhead
+
+// Never: force-unwrapping in hot paths
+array[index]! // Hidden crash waiting to happen
+
+// Never: string concatenation with + in loops
+var result = ""
+for item in items { result = result + item.name } // O(n²)
+// Use: reserveCapacity + append, or joined()
+
+// Never: capturing self strongly in long-lived closures
+timer = Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { _ in
+    self.update() // Retain cycle
+}
+// Use: [weak self]
+```