@softspark/ai-toolkit 1.0.0

package/app/skills/swift-patterns/SKILL.md

@@ -0,0 +1,500 @@
+---
+name: swift-patterns
+description: "Loaded when user asks about Swift or iOS development patterns"
+effort: medium
+user-invocable: false
+---
+
+# Swift / iOS Patterns
+
+## Project Structure
+
+### Swift Package (SPM)
+
+```
+MyPackage/
+├── Package.swift
+├── Sources/
+│   ├── MyLibrary/
+│   └── MyExecutable/
+├── Tests/
+│   └── MyLibraryTests/
+└── Plugins/
+```
+
+```swift
+// swift-tools-version: 5.10
+import PackageDescription
+
+let package = Package(
+    name: "MyPackage",
+    platforms: [.iOS(.v17), .macOS(.v14)],
+    products: [
+        .library(name: "MyLibrary", targets: ["MyLibrary"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-algorithms", from: "1.2.0"),
+    ],
+    targets: [
+        .target(name: "MyLibrary",
+                dependencies: [.product(name: "Algorithms", package: "swift-algorithms")]),
+        .testTarget(name: "MyLibraryTests", dependencies: ["MyLibrary"]),
+    ]
+)
+```
+
+### Xcode Project Layout
+
+```
+MyApp/
+├── MyApp/
+│   ├── App/             # Entry point, ContentView
+│   ├── Features/        # Feature modules (Views, ViewModels, Models)
+│   ├── Core/            # Networking, Storage, Extensions
+│   └── Resources/       # Assets.xcassets, Info.plist
+├── MyAppTests/
+└── MyAppUITests/
+```
+
+---
+
+## Idioms / Code Style
+
+### Optionals
+
+```swift
+// guard-let for early exit
+func process(user: User?) {
+    guard let user else { return }
+    print(user.name)
+}
+
+// Optional chaining + nil coalescing
+let name = user?.profile?.displayName ?? "Anonymous"
+
+// map/flatMap on optionals
+let length: Int? = optionalString.map { $0.count }
+// Never force-unwrap in production: user!.name
+```
+
+### Protocol-Oriented Programming
+
+```swift
+protocol Cacheable: Identifiable where ID: Hashable {
+    var cacheKey: String { get }
+}
+
+extension Cacheable where ID == String {
+    var cacheKey: String { id }
+}
+```
+
+### Value Types vs Reference Types
+
+Use structs by default (value semantics, thread-safe). Use classes when identity matters, shared mutable state is intentional, inheritance is needed, or ObjC interop is required.
+
+### Property Wrappers
+
+```swift
+@propertyWrapper
+struct Clamped<Value: Comparable> {
+    var wrappedValue: Value {
+        didSet { wrappedValue = min(max(wrappedValue, range.lowerBound), range.upperBound) }
+    }
+    let range: ClosedRange<Value>
+
+    init(wrappedValue: Value, _ range: ClosedRange<Value>) {
+        self.range = range
+        self.wrappedValue = min(max(wrappedValue, range.lowerBound), range.upperBound)
+    }
+}
+
+struct Volume {
+    @Clamped(0...100) var level: Int = 50
+}
+```
+
+### Result Builders
+
+```swift
+@resultBuilder
+struct ArrayBuilder<Element> {
+    static func buildBlock(_ components: [Element]...) -> [Element] { components.flatMap { $0 } }
+    static func buildExpression(_ expression: Element) -> [Element] { [expression] }
+    static func buildOptional(_ component: [Element]?) -> [Element] { component ?? [] }
+}
+```
+
+---
+
+## Error Handling
+
+### throws / try / catch
+
+```swift
+enum NetworkError: Error, LocalizedError {
+    case invalidURL
+    case timeout(seconds: Int)
+    case serverError(statusCode: Int)
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidURL: "Invalid URL."
+        case .timeout(let s): "Timed out after \(s)s."
+        case .serverError(let code): "Server returned \(code)."
+        }
+    }
+}
+
+do {
+    let user = try fetchUser(id: "123")
+} catch let error as NetworkError {
+    handleNetworkError(error)
+} catch {
+    handleUnexpected(error)
+}
+
+let user = try? fetchUser(id: "123") // nil on error
+```
+
+### Result Type
+
+```swift
+switch fetchData(from: url) {
+case .success(let data): process(data)
+case .failure(let error): showError(error)
+}
+```
+
+### Typed Throws (Swift 6) and Async Throws
+
+```swift
+func load() throws(DatabaseError) -> [Item] { /* compiler-enforced error type */ }
+
+func fetchUser(id: String) async throws -> User {
+    let (data, response) = try await URLSession.shared.data(from: url)
+    guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
+        throw NetworkError.serverError(statusCode: 0)
+    }
+    return try JSONDecoder().decode(User.self, from: data)
+}
+```
+
+---
+
+## Testing
+
+### XCTest
+
+```swift
+final class UserServiceTests: XCTestCase {
+    var sut: UserService!
+    var mockRepo: MockUserRepository!
+
+    override func setUp() {
+        mockRepo = MockUserRepository()
+        sut = UserService(repository: mockRepo)
+    }
+
+    func testFetchUser_success() async throws {
+        mockRepo.stubbedUser = User(id: "1", name: "Alice")
+        let user = try await sut.fetchUser(id: "1")
+        XCTAssertEqual(user.name, "Alice")
+    }
+
+    func testFetchUser_notFound_throws() async {
+        mockRepo.shouldFail = true
+        do {
+            _ = try await sut.fetchUser(id: "999")
+            XCTFail("Expected error")
+        } catch {
+            XCTAssertTrue(error is UserService.Error)
+        }
+    }
+}
+```
+
+### Swift Testing Framework (Swift 6+)
+
+```swift
+import Testing
+
+@Suite("UserService")
+struct UserServiceTests {
+    @Test("fetches user by ID")
+    func fetchUser() async throws {
+        let mockRepo = MockUserRepository()
+        mockRepo.stubbedUser = User(id: "1", name: "Alice")
+        let sut = UserService(repository: mockRepo)
+        let user = try await sut.fetchUser(id: "1")
+        #expect(user.name == "Alice")
+    }
+
+    @Test("throws on missing user", arguments: ["999", ""])
+    func fetchMissingUser(id: String) async {
+        let sut = UserService(repository: MockUserRepository())
+        await #expect(throws: UserService.Error.self) {
+            try await sut.fetchUser(id: id)
+        }
+    }
+}
+```
+
+### Protocol-Based Mocking
+
+```swift
+protocol UserRepository {
+    func fetch(id: String) async throws -> User
+}
+
+final class MockUserRepository: UserRepository {
+    var stubbedUser: User?
+    var shouldFail = false
+    private(set) var fetchCallCount = 0
+
+    func fetch(id: String) async throws -> User {
+        fetchCallCount += 1
+        if shouldFail { throw NSError(domain: "", code: 0) }
+        return stubbedUser ?? User(id: id, name: "Default")
+    }
+}
+```
+
+### UI Testing
+
+```swift
+func testLoginFlow() {
+    let app = XCUIApplication()
+    app.launchArguments = ["--uitesting"]
+    app.launch()
+    app.textFields["email"].tap()
+    app.textFields["email"].typeText("user@example.com")
+    app.secureTextFields["password"].typeText("pass")
+    app.buttons["Sign In"].tap()
+    XCTAssertTrue(app.staticTexts["Welcome"].waitForExistence(timeout: 5))
+}
+```
+
+---
+
+## Common Frameworks
+
+### SwiftUI + @Observable (iOS 17+)
+
+```swift
+@Observable
+final class UserViewModel {
+    var users: [User] = []
+    var isLoading = false
+    private let service: UserService
+
+    init(service: UserService) { self.service = service }
+
+    func load() async {
+        isLoading = true
+        defer { isLoading = false }
+        users = (try? await service.fetchAll()) ?? []
+    }
+}
+
+struct UserListView: View {
+    @State private var vm: UserViewModel
+
+    init(service: UserService) {
+        _vm = State(initialValue: UserViewModel(service: service))
+    }
+
+    var body: some View {
+        NavigationStack {
+            List(vm.users) { user in
+                NavigationLink(value: user) { Text(user.name) }
+            }
+            .navigationTitle("Users")
+            .navigationDestination(for: User.self) { UserDetailView(user: $0) }
+            .task { await vm.load() }
+        }
+    }
+}
+```
+
+### Combine
+
+```swift
+class SearchVM: ObservableObject {
+    @Published var query = ""
+    @Published var results: [Item] = []
+    private var cancellables = Set<AnyCancellable>()
+
+    init(service: SearchService) {
+        $query
+            .debounce(for: .milliseconds(300), scheduler: DispatchQueue.main)
+            .removeDuplicates()
+            .filter { !$0.isEmpty }
+            .flatMap { service.search(query: $0) }
+            .receive(on: DispatchQueue.main)
+            .sink(receiveCompletion: { _ in },
+                  receiveValue: { [weak self] in self?.results = $0 })
+            .store(in: &cancellables)
+    }
+}
+```
+
+### Structured Concurrency
+
+```swift
+func fetchAllProfiles(ids: [String]) async throws -> [Profile] {
+    try await withThrowingTaskGroup(of: Profile.self) { group in
+        for id in ids { group.addTask { try await fetchProfile(id: id) } }
+        return try await group.reduce(into: []) { $0.append($1) }
+    }
+}
+
+// AsyncStream for bridging callbacks
+let locations = AsyncStream<Location> { continuation in
+    manager.onUpdate = { continuation.yield($0) }
+    continuation.onTermination = { _ in manager.stop() }
+}
+```
+
+### SwiftData
+
+```swift
+@Model
+final class Item {
+    var title: String
+    var timestamp: Date
+    @Relationship(deleteRule: .cascade) var tags: [Tag]
+    init(title: String) { self.title = title; self.timestamp = .now; self.tags = [] }
+}
+
+struct ItemListView: View {
+    @Query(sort: \Item.timestamp, order: .reverse) private var items: [Item]
+    @Environment(\.modelContext) private var context
+
+    var body: some View {
+        List(items) { Text($0.title) }
+    }
+}
+```
+
+### Vapor (Server-Side)
+
+```swift
+app.get("users", ":id") { req async throws -> User in
+    guard let id = req.parameters.get("id", as: UUID.self) else { throw Abort(.badRequest) }
+    guard let user = try await User.find(id, on: req.db) else { throw Abort(.notFound) }
+    return user
+}
+```
+
+---
+
+## Performance
+
+### Copy-on-Write
+
+Array, String, Dictionary use COW automatically. For custom value types:
+
+```swift
+struct LargeData {
+    private final class Storage { var buffer: [UInt8]; init(_ b: [UInt8]) { buffer = b } }
+    private var storage: Storage
+
+    var buffer: [UInt8] {
+        get { storage.buffer }
+        set {
+            if !isKnownUniquelyReferenced(&storage) { storage = Storage(newValue) }
+            else { storage.buffer = newValue }
+        }
+    }
+}
+```
+
+### ARC Retain Cycles
+
+```swift
+// weak — closure may outlive self
+service.fetch { [weak self] result in
+    guard let self else { return }
+    self.update(with: result)
+}
+
+// unowned — self guaranteed to outlive closure
+lazy var tick: () -> Void = { [unowned self] in self.count += 1 }
+```
+
+### Sendable and Actors
+
+```swift
+struct Config: Sendable { let apiURL: URL; let timeout: TimeInterval }
+
+actor ImageCache {
+    private var cache: [URL: Data] = [:]
+    func image(for url: URL) -> Data? { cache[url] }
+    func store(_ data: Data, for url: URL) { cache[url] = data }
+}
+```
+
+### Instruments
+
+| Instrument | Use For |
+|---|---|
+| Time Profiler | CPU bottlenecks |
+| Allocations | Memory growth |
+| Leaks | Retain cycles |
+| SwiftUI | View body re-evaluations |
+| Core Animation | FPS, offscreen rendering |
+
+Profile on device (not simulator). Use `os_signpost` for custom spans.
+
+---
+
+## Build / Package Management
+
+### SPM Commands
+
+```bash
+swift package resolve       # Resolve deps
+swift build -c release      # Release build
+swift test --filter MyTests # Filtered test run
+```
+
+### xcconfig
+
+```
+// Shared.xcconfig
+SWIFT_VERSION = 5.10
+IPHONEOS_DEPLOYMENT_TARGET = 17.0
+SWIFT_STRICT_CONCURRENCY = complete
+
+// Debug.xcconfig
+#include "Shared.xcconfig"
+SWIFT_OPTIMIZATION_LEVEL = -Onone
+SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG
+
+// Release.xcconfig
+#include "Shared.xcconfig"
+SWIFT_OPTIMIZATION_LEVEL = -O
+SWIFT_COMPILATION_MODE = wholemodule
+```
+
+### Tuist
+
+Define targets in `Project.swift` using `ProjectDescription`. Map each app, framework, and test target with `bundleId`, `sources`, and `dependencies`. Use `.external(name:)` for SPM deps and `.target(name:)` for internal.
+
+Schemes: separate Debug/Release/Testing. Enable ASan + TSan in test schemes.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Force unwrap `!` | Runtime crash | `guard let`, `if let`, `??` |
+| Massive view controller | Untestable | MVVM, composable views |
+| Stringly-typed APIs | No compiler checks | Enums, phantom types |
+| Ignoring `@MainActor` | Off-main-thread UI | Annotate view models |
+| Retain cycles | Memory leaks | `[weak self]` / `[unowned self]` |
+| Blocking main thread | UI freezes | `async/await`, `Task { }` |
+| `UserDefaults` for secrets | Insecure | Keychain (`SecItemAdd`) |
+| `@ObservedObject` for owned state | Object recreated | `@StateObject` or `@State` + `@Observable` |

package/app/skills/tdd/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: tdd
+description: "Test-driven development with red-green-refactor loop and vertical slices. Use when user wants TDD, test-first development, red-green-refactor, or building features with tests driving the implementation."
+user-invocable: true
+effort: high
+argument-hint: "[feature or behavior to implement]"
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
+---
+
+# Test-Driven Development
+
+$ARGUMENTS
+
+Build features using strict RED → GREEN → REFACTOR cycles with vertical slices.
+
+## Usage
+
+```
+/tdd [feature or behavior to implement]
+```
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? **Delete it. Start over.**
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Don't look at it
+- Delete means delete
+
+Implement fresh from tests. Period.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## Philosophy
+
+**Core principle**: Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests**: Integration-style, exercise real code paths through public APIs. Describe _what_ the system does, not _how_. Read like specifications. Survive refactors.
+
+**Bad tests**: Coupled to implementation. Mock internal collaborators, test private methods, verify through external means. Warning sign: test breaks on refactor but behavior is unchanged.
+
+See [reference/tests.md](reference/tests.md) for examples, [reference/mocking.md](reference/mocking.md) for mocking guidelines.
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.**
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+```
+
+Tests written in bulk test _imagined_ behavior. Vertical slices let each test respond to what you learned from the previous cycle.
+
+## Workflow
+
+### 1. Planning
+
+Before writing any code:
+
+- [ ] Confirm with user what interface changes are needed
+- [ ] Confirm which behaviors to test (prioritize — you can't test everything)
+- [ ] Identify opportunities for [deep modules](reference/deep-modules.md)
+- [ ] Design interfaces for [testability](reference/interface-design.md)
+- [ ] List behaviors to test (not implementation steps)
+- [ ] Get user approval
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing:
+
+```
+RED:   Write test for first behavior → test fails
+GREEN: Write minimal code to pass → test passes
+```
+
+This proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test → fails
+GREEN: Minimal code to pass → passes
+```
+
+| Rule | Description |
+|------|-------------|
+| One at a time | One test per cycle |
+| Minimal | Only enough code to pass current test |
+| No anticipation | Don't code for future tests |
+| Behavioral | Tests focus on observable behavior |
+
+### 4. Refactor
+
+After all tests pass, look for [refactor candidates](reference/refactoring.md):
+
+- [ ] Extract duplication
+- [ ] Deepen modules (complexity behind simple interfaces)
+- [ ] Apply SOLID where natural
+- [ ] Run tests after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+```
+
+## Rules
+
+- One RED→GREEN cycle at a time — never batch
+- Tests assert on observable outcomes, not internal state
+- Mock only at system boundaries (see [reference/mocking.md](reference/mocking.md))
+- Each cycle leaves the codebase in a working state
+
+## Red Flags — STOP and Start Over
+
+If you catch yourself doing ANY of these, **delete the code and restart with TDD**:
+
+- Writing production code before a failing test
+- Writing tests after implementation
+- Test passes immediately (you're testing existing behavior — fix the test)
+- Can't explain why the test failed
+- Tests added "later"
+- Rationalizing "just this once"
+- "I already manually tested it"
+- "Keep as reference" or "adapt existing code"
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing. |
+| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
+| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
+| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
+| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
+| "This is different because..." | No. Apply the Iron Law. |
+
+## Verification Checklist
+
+Before marking work complete:
+
+- [ ] Every new function/method has a test
+- [ ] Watched each test fail before implementing
+- [ ] Each test failed for expected reason (feature missing, not typo)
+- [ ] Wrote minimal code to pass each test
+- [ ] All tests pass
+- [ ] Output pristine (no errors, warnings)
+- [ ] Tests use real code (mocks only at system boundaries)
+- [ ] Edge cases and errors covered
+
+Can't check all boxes? You skipped TDD. Start over.

package/app/skills/tdd/reference/deep-modules.md

@@ -0,0 +1,32 @@
+# Deep Modules
+
+From "A Philosophy of Software Design" (John Ousterhout):
+
+**Deep module** = small interface + lots of implementation
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid)
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing interfaces, ask:
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?