@softspark/ai-toolkit 3.0.2 → 3.1.1

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

@@ -0,0 +1,293 @@
+---
+name: swift-rules
+description: "Swift coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .swift, Package.swift, .xcodeproj, SwiftUI, Combine, async/await, XCTest. Load when writing, reviewing, or editing Swift code."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# Swift Rules
+
+These rules come from `app/rules/swift/` in ai-toolkit. They cover
+the project's standards for coding style, frameworks, patterns,
+security, and testing in Swift. Apply them when writing or
+reviewing Swift code.
+
+# Swift Coding Style
+
+## Naming
+- PascalCase: types, protocols, enums, struct, class.
+- camelCase: functions, methods, properties, variables, enum cases.
+- No prefixes: Swift has module namespacing (no `NS` or `UI` prefix for your types).
+- Use descriptive names: `removeElement(at:)` not `remove(i:)`.
+- Boolean properties read as assertions: `isEmpty`, `hasChildren`, `canSubmit`.
+
+## Types
+- Prefer `struct` over `class` by default (value semantics, no reference cycles).
+- Use `class` only when reference semantics or inheritance is required.
+- Use `enum` with associated values for modeling finite states.
+- Use `protocol` for defining capabilities. Prefer protocol composition.
+- Use `typealias` for complex generic signatures for readability.
+
+## Optionals
+- Use `guard let` for early exit on nil. Use `if let` for conditional binding.
+- Never force-unwrap (`!`) unless failure is a programming error.
+- Use `??` for default values: `let name = user?.name ?? "Unknown"`.
+- Use optional chaining: `user?.address?.city`.
+- Use `map` / `flatMap` on optionals for transformations.
+
+## Properties
+- Use `let` by default. Use `var` only when mutation is required.
+- Use computed properties for derived values: `var fullName: String { ... }`.
+- Use property observers (`willSet`, `didSet`) for side effects on change.
+- Use `lazy var` for expensive initialization deferred until first access.
+- Use `@Published` (Combine) for observable properties in classes.
+
+## Functions
+- Use argument labels for clarity: `func move(from source: Int, to destination: Int)`.
+- Omit argument labels when the function name makes the role clear: `func contains(_ element: T)`.
+- Use default parameter values instead of multiple overloads.
+- Use `throws` / `async throws` for fallible operations.
+- Use trailing closure syntax for the last closure parameter.
+
+## Access Control
+- Use `private` for implementation details. Use `fileprivate` sparingly.
+- Use `internal` (default) for module-scoped access.
+- Use `public` for framework API. Use `open` only when subclassing is intended.
+- Prefer `private(set)` for read-only external access with internal mutation.
+
+## Formatting
+- Use SwiftLint for automated style enforcement.
+- Use SwiftFormat for automated code formatting.
+- Commit `.swiftlint.yml` and `.swiftformat` to the repository.
+- Max line length: 120 characters (SwiftLint default).
+- Use trailing commas in multi-line arrays and dictionaries.
+
+# Swift Frameworks
+
+## SwiftUI
+- Use `VStack`, `HStack`, `ZStack` for layout composition.
+- Use `List` with `ForEach` for dynamic content. Use `LazyVStack` for large lists.
+- Use `NavigationStack` (iOS 16+) with `navigationDestination(for:)` for type-safe navigation.
+- Use `.task { }` modifier for async data loading tied to view lifecycle.
+- Use `@ViewBuilder` for conditional view composition in custom containers.
+- Use `PreviewProvider` or `#Preview` macro for rapid UI iteration.
+
+## UIKit (Legacy / Hybrid)
+- Use `UIHostingController` to embed SwiftUI views in UIKit.
+- Use `UIViewRepresentable` to wrap UIKit views in SwiftUI.
+- Use Auto Layout with constraints or `UIStackView` for layout.
+- Use `UICollectionViewCompositionalLayout` for complex collection layouts.
+- Use `Coordinator` pattern for delegate-based UIKit interop in SwiftUI.
+
+## Combine
+- Use `Publisher` / `Subscriber` for reactive data streams.
+- Use `sink` for subscribing. Store cancellables in `Set<AnyCancellable>`.
+- Use `map`, `filter`, `flatMap`, `combineLatest` for stream transformation.
+- Use `@Published` on class properties for automatic publisher generation.
+- Prefer `AsyncSequence` (async/await) over Combine for new code.
+
+## Swift Data
+- Use `@Model` macro for persistent model definitions.
+- Use `@Query` in SwiftUI views for automatic fetching and observation.
+- Use `ModelContext` for CRUD operations: `context.insert(item)`, `context.delete(item)`.
+- Use `#Predicate` macro for type-safe query filtering.
+- Use `ModelConfiguration` for custom store locations and migration options.
+
+## Core Data (Legacy)
+- Use `NSPersistentContainer` for stack setup.
+- Use `NSFetchRequest` with `NSPredicate` for querying.
+- Use `performBackgroundTask` for background context operations.
+- Use lightweight migrations for schema changes when possible.
+- Prefer SwiftData for new projects (iOS 17+).
+
+## Vapor (Server-Side)
+- Use `routes.get("users")` for route definitions.
+- Use `Content` protocol for request/response body codable conformance.
+- Use Fluent ORM with migrations for database access.
+- Use middleware for authentication, CORS, and error handling.
+- Use `async`/`await` natively (Vapor 4+ is fully async).
+
+## Networking
+- Use `URLSession` with `async/await` for HTTP requests.
+- Use `Codable` with `JSONDecoder` for response parsing.
+- Use `URLCache` and `ETag` for response caching.
+- Set `timeoutIntervalForRequest` on `URLSessionConfiguration`.
+- Use `TaskLocal` for request-scoped values (tracing, auth context).
+
+## Package Management
+- Use Swift Package Manager (SPM) for dependency management.
+- Define dependencies in `Package.swift` with exact version or version ranges.
+- Use `Package.resolved` committed to the repository for reproducible builds.
+- Prefer SPM over CocoaPods/Carthage for new projects.
+
+# Swift Patterns
+
+## Error Handling
+- Use `enum AppError: Error` for typed, exhaustive error handling.
+- Use `throws` functions with `do-catch` for recoverable errors.
+- Use `Result<Success, Failure>` for asynchronous error propagation.
+- Use `try?` for optional conversion. Use `try!` only in tests or guaranteed paths.
+- Add `LocalizedError` conformance for user-facing error messages.
+
+## Protocol-Oriented Design
+- Define capabilities as protocols: `protocol Fetchable { func fetch() async throws -> Data }`.
+- Use protocol extensions for default implementations.
+- Use protocol composition: `func process(_ item: Sendable & Codable)`.
+- Use associated types for generic protocols: `associatedtype Output`.
+- Use `some Protocol` (opaque types) for return types hiding concrete implementations.
+
+## Async/Await
+- Use `async` functions for all asynchronous operations.
+- Use `async let` for concurrent, independent operations.
+- Use `TaskGroup` for dynamic parallelism with collected results.
+- Use `Task { }` to bridge sync to async. Avoid `.task { }` in views for complex logic.
+- Use `withThrowingTaskGroup` for concurrent operations that can fail.
+
+## Actors
+- Use `actor` for thread-safe mutable state (replaces manual locks).
+- Use `@MainActor` for UI-related state and methods.
+- Use `nonisolated` for actor methods that do not access mutable state.
+- Use `GlobalActor` for custom isolation domains.
+- Minimize `await` calls on actors to reduce suspension points.
+
+## SwiftUI Patterns
+- Use `@State` for view-local mutable state.
+- Use `@Binding` for child-to-parent state communication.
+- Use `@Observable` (Observation framework) for model objects (preferred over `@ObservedObject`).
+- Use `@Environment` for dependency injection: `@Environment(\.modelContext)`.
+- Use `ViewModifier` for reusable view transformations.
+- Extract subviews into separate structs for readability and performance.
+
+## Codable
+- Use `Codable` for JSON serialization/deserialization.
+- Use `CodingKeys` enum for custom key mapping.
+- Use `JSONDecoder` with `.convertFromSnakeCase` for API compatibility.
+- Use `@propertyWrapper` for custom decoding strategies (e.g., date formats).
+- Use `nestedContainer` for flattening nested JSON structures.
+
+## Dependency Injection
+- Use initializer injection for required dependencies.
+- Use `@Environment` in SwiftUI for framework-provided values.
+- Use `swift-dependencies` library for testable, controlled dependency management.
+- Use `@Dependency(\.apiClient) var apiClient` for automatic resolution.
+
+## Anti-Patterns
+- Force-unwrapping optionals: use `guard let` or `??`.
+- Massive view controllers/views: split into subviews and view models.
+- Reference cycles: use `[weak self]` in closures capturing `self`.
+- Blocking the main thread: use `Task` or `DispatchQueue.global()`.
+- Stringly-typed APIs: use enums, protocols, and strong types.
+
+# Swift Security
+
+## Keychain
+- Use Keychain Services for storing passwords, tokens, and cryptographic keys.
+- Use `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` for sensitive items.
+- Use `KeychainAccess` or similar wrapper libraries for cleaner API.
+- Never store secrets in `UserDefaults` (unencrypted plist on disk).
+- Delete keychain items on user logout.
+
+## App Transport Security (ATS)
+- Use HTTPS for all network connections. ATS enforces this by default.
+- Never add blanket `NSAllowsArbitraryLoads` exception.
+- Use per-domain exceptions only when connecting to legacy servers.
+- Implement certificate pinning for high-security connections.
+- Validate server certificates in `URLSessionDelegate` for custom pinning.
+
+## Input Validation
+- Validate all user input before processing or displaying.
+- Use `NSRegularExpression` or Swift Regex for pattern validation.
+- Sanitize strings before using in URL construction, SQL, or HTML.
+- Validate deep link URL parameters before navigation.
+- Limit input lengths in `UITextField` / `TextField` to prevent abuse.
+
+## Data Protection
+- Use `Data Protection` API: set `FileProtectionType.complete` on sensitive files.
+- Use `CryptoKit` for hashing (`SHA256`), encryption (`AES.GCM`), and signing.
+- Use `SecureEnclave` for hardware-backed key storage on supported devices.
+- Zero sensitive data in memory after use: `withUnsafeMutableBytes { $0.initializeMemory(as: UInt8.self, repeating: 0) }`.
+- Use `@Sendable` closures to prevent data races in concurrent access.
+
+## Authentication
+- Use `AuthenticationServices` for Sign in with Apple and passkeys.
+- Use `LocalAuthentication` (Face ID / Touch ID) for biometric auth.
+- Store authentication tokens in Keychain, not in memory or UserDefaults.
+- Use short-lived access tokens with refresh token rotation.
+- Implement session timeout for inactive users.
+
+## Network Security
+- Use `URLSession` with certificate pinning for sensitive API calls.
+- Validate response `Content-Type` headers before parsing.
+- Use `Codable` for structured deserialization (prevents injection).
+- Set request timeouts to prevent hanging connections.
+- Do not log request/response bodies containing sensitive data.
+
+## Code Security
+- Use `[weak self]` in closures to prevent retain cycles and memory leaks.
+- Use `@Sendable` and actor isolation for thread-safe concurrent code.
+- Avoid `UnsafePointer` / `UnsafeMutablePointer` unless absolutely necessary.
+- Use `#if DEBUG` guards for debug-only code. Never ship debug features.
+- Enable Xcode hardened runtime for macOS apps.
+
+## Dependency Security
+- Audit SPM dependencies before adding. Check maintainer reputation.
+- Pin dependency versions in `Package.resolved`.
+- Review `Package.swift` of dependencies for unusual build plugins.
+- Prefer dependencies with active security response and disclosure processes.
+- Minimize third-party dependencies for security-critical modules.
+
+# Swift Testing
+
+## Framework
+- Use Swift Testing (`import Testing`) for new projects (Swift 5.10+).
+- Use XCTest for existing projects and UIKit-based UI tests.
+- Use swift-snapshot-testing for visual regression testing.
+- Use swift-dependencies for controlled dependency injection in tests.
+
+## File Naming
+- Test files: `FooTests.swift` in `Tests/` target.
+- Mirror source module structure in test target.
+- Use `@Test` attribute (Swift Testing) or `test` prefix (XCTest) for test methods.
+- Use `@Suite` (Swift Testing) for test grouping.
+
+## Structure (Swift Testing)
+- Use `@Test("description")` for individual test cases.
+- Use `@Test(arguments: [...])` for parameterized tests.
+- Use `#expect(condition)` for assertions. Use `#require(condition)` for preconditions.
+- Use `#expect(throws: FooError.self) { try riskyOperation() }` for error testing.
+- Use `@Suite` structs for grouping. Properties serve as shared setup.
+
+## Structure (XCTest)
+- Use `setUp()` / `tearDown()` for per-test initialization and cleanup.
+- Use `setUpWithError()` for throwing setup code.
+- Use `XCTAssertEqual`, `XCTAssertTrue`, `XCTAssertNil` for assertions.
+- Use `XCTAssertThrowsError` for exception testing.
+- Use `expectation(description:)` + `wait(for:timeout:)` for async assertions.
+
+## Async Testing
+- Use `async` test functions: `@Test func fetchUser() async throws { ... }`.
+- Use `confirmation()` (Swift Testing) for event-based async assertions.
+- XCTest: use `XCTestExpectation` with `fulfillment()` for callback-based async.
+- Test `AsyncSequence` with `for await` loops and assertion on collected values.
+
+## Mocking
+- Use protocol-based dependency injection for testability.
+- Create manual mock implementations conforming to protocols.
+- Use `swift-dependencies` for environment-controlled dependency overrides.
+- Use `@Dependency` property wrapper for automatic mock injection in tests.
+- Avoid mocking frameworks when protocol mocks are straightforward.
+
+## UI Testing (XCTest)
+- Use `XCUIApplication` for UI automation tests.
+- Use accessibility identifiers for reliable element lookup.
+- Use `app.buttons["Submit"].tap()` for interaction simulation.
+- Use `waitForExistence(timeout:)` for async UI element appearance.
+- Keep UI tests focused on critical user flows only (slow to run).
+
+## Best Practices
+- Test behavior through public API. Avoid `@testable import` when possible.
+- Use `@testable import Module` only when testing internal members is necessary.
+- Use `withDependencies { }` for scoped dependency overrides in tests.
+- Test on multiple platforms (iOS, macOS) when shipping cross-platform.
+- Run tests with `swift test` or `xcodebuild test` in CI.

package/app/skills/typescript-rules/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: typescript-rules
+description: "TypeScript/JavaScript coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .ts, .tsx, .js, .jsx, package.json, tsconfig.json, React, Next.js, Vue, Vite, Vitest, Jest, ESLint. Load when writing, reviewing, or editing TypeScript/JavaScript code."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# TypeScript/JavaScript Rules
+
+These rules come from `app/rules/typescript/` in ai-toolkit. They cover
+the project's standards for coding style, frameworks, patterns,
+security, and testing in TypeScript/JavaScript. Apply them when writing or
+reviewing TypeScript/JavaScript code.
+
+# TypeScript Coding Style
+
+## Strict Mode
+- Always use `strict: true` in tsconfig.json.
+- Never use `any` -- use `unknown` + type guards instead.
+- Prefer `interface` over `type` for object shapes (extendable).
+- Use `as const` for literal types and readonly tuples.
+
+## Naming
+- PascalCase: types, interfaces, enums, classes, components.
+- camelCase: variables, functions, methods, properties.
+- UPPER_SNAKE: constants, env vars.
+- Prefix interfaces with `I` only if project convention requires it.
+
+## Functions
+- Prefer arrow functions for callbacks and inline.
+- Use `function` declarations for hoisted, named functions.
+- Max 3 parameters -- use options object beyond that.
+- Always type return values for public/exported functions.
+
+## Imports
+- Group: node builtins, external, internal, relative.
+- Use `type` imports: `import type { Foo } from './foo'`.
+- No barrel exports unless at package boundary.
+- Prefer named exports over default exports.
+
+## Types
+- Use discriminated unions over class hierarchies for state.
+- Use `readonly` for arrays and objects that should not be mutated.
+- Use `satisfies` operator to validate types without widening.
+- Prefer `unknown` over `any` at API boundaries.
+- Use template literal types for string patterns.
+
+## Avoid
+- `enum` -- use `as const` objects or union types.
+- `namespace` -- use ES modules.
+- `private` keyword -- use `#` private fields.
+- Non-null assertion `!` -- use proper type narrowing.
+- `as` type casting -- use type guards and narrowing.
+
+## Configuration
+- Enable `noUncheckedIndexedAccess` for safer array/object access.
+- Enable `exactOptionalPropertyTypes` to distinguish `undefined` from missing.
+- Use `moduleResolution: "bundler"` for modern projects.
+- Set `isolatedModules: true` for bundler compatibility.
+
+# TypeScript Frameworks
+
+## React
+- Use function components exclusively. No class components.
+- Colocate state with the component that owns it. Lift only when needed.
+- Use `useCallback` and `useMemo` only when profiling shows a need.
+- Use `React.lazy()` + Suspense for code-splitting routes.
+- Avoid prop drilling past 2 levels -- use Context or state management.
+
+## Next.js (App Router)
+- Default to Server Components. Add `"use client"` only when needed.
+- Use Server Actions for mutations. Never expose internal APIs to client.
+- Use `loading.tsx` and `error.tsx` for streaming and error boundaries.
+- Fetch data in Server Components, not in useEffect on client.
+- Use `revalidatePath` / `revalidateTag` for cache invalidation.
+
+## Express / Fastify / Hono
+- Use layered architecture: route -> controller -> service -> repository.
+- Validate request body/params/query with Zod middleware.
+- Centralize error handling in a single error middleware.
+- Use async route handlers with proper error forwarding.
+- Return consistent response shapes: `{ data }` or `{ error }`.
+
+## State Management
+- Use Zustand or Jotai for client state. Redux only for complex existing apps.
+- Use TanStack Query (React Query) for server state.
+- Separate server state (fetched data) from client state (UI state).
+- Never duplicate server data in client state stores.
+
+## ORM / Database
+- Use Drizzle for new projects (SQL-like, type-safe, lightweight).
+- Use Prisma for rapid prototyping (schema-first, great DX).
+- Always use migrations. Never modify schema manually in production.
+- Use transactions for multi-table operations.
+
+## Node.js Runtime
+- Use `node:` prefix for built-in modules: `import { readFile } from 'node:fs/promises'`.
+- Prefer `fetch` (built-in since Node 18) over axios/node-fetch.
+- Use `structuredClone()` for deep cloning.
+- Set `"type": "module"` in package.json for ESM.
+
+## Monorepo
+- Use Turborepo or Nx for monorepo orchestration.
+- Share types via internal packages, not copy-paste.
+- Use workspace protocols: `"@org/shared": "workspace:*"`.
+
+# TypeScript Patterns
+
+## Error Handling
+- Use Result type pattern: `{ success: true; data: T } | { success: false; error: E }`.
+- Use Zod `.safeParse()` for validation -- returns typed result, never throws.
+- Create domain-specific error classes extending `Error` with error codes.
+- Centralize error handling in middleware, not in each handler.
+- Never catch errors silently. Log or rethrow with context.
+
+## Discriminated Unions
+- Use discriminated unions for state machines and polymorphic data.
+- Always include a `type` or `kind` literal field as discriminant.
+- Use `switch` with exhaustive checking (`never` in default) on unions.
+- Prefer unions over optional fields for mutually exclusive states.
+
+## Async Patterns
+- Use `async/await` everywhere. Never use raw `.then()` chains.
+- Use `Promise.all()` for independent concurrent operations.
+- Use `Promise.allSettled()` when some failures are acceptable.
+- Implement cancellation with `AbortController` for long operations.
+- Wrap callbacks in Promises at the boundary, then use async/await.
+
+## Validation
+- Validate at API boundaries with Zod, Valibot, or ArkType.
+- Derive TypeScript types from schemas: `z.infer<typeof Schema>`.
+- Never trust runtime data to match TypeScript types without validation.
+- Use branded types for domain primitives: `UserId`, `Email`, `Slug`.
+
+## Dependency Injection
+- Use constructor injection for services and repositories.
+- Accept interfaces, not concrete classes, in constructors.
+- Use factory functions for creating configured instances.
+- Avoid service locator pattern and global singletons.
+
+## Immutability
+- Use `readonly` on interface properties by default.
+- Use `Readonly<T>`, `ReadonlyArray<T>` for function parameters.
+- Use `Object.freeze()` only for runtime safety in config objects.
+- Prefer spread/map/filter over mutating methods (push, splice).
+
+## Type Guards
+- Use `is` return type for custom type guards: `(x: unknown): x is User`.
+- Use `in` operator for discriminating object shapes.
+- Prefer `satisfies` over `as` for type validation without casting.
+- Use assertion functions (`asserts x is T`) for preconditions.
+
+# TypeScript Security
+
+## Input Validation
+- Validate ALL request data with Zod/Valibot at API boundary.
+- Use `.strip()` / `.strict()` to reject unexpected fields.
+- Validate URL params and query strings, not just request bodies.
+- Never pass raw user input to `eval()`, `Function()`, or template literals in SQL.
+
+## XSS Prevention
+- Use framework auto-escaping (React JSX, Angular templates).
+- Never use `dangerouslySetInnerHTML` without DOMPurify sanitization.
+- Sanitize user content before storing, not just before rendering.
+- Set CSP headers: `default-src 'self'; script-src 'self'`.
+
+## Authentication
+- Use `httpOnly`, `secure`, `sameSite: 'strict'` for auth cookies.
+- Implement CSRF protection for cookie-based auth (double-submit or token).
+- Use short-lived JWTs (15min) with refresh token rotation.
+- Validate JWT signature, expiration, issuer, and audience on every request.
+
+## SQL / NoSQL Injection
+- Use parameterized queries with Drizzle/Prisma/TypeORM. Never concatenate.
+- For raw queries, use tagged template literals: `sql\`SELECT * FROM users WHERE id = ${id}\``.
+- Validate and cast IDs to expected types (UUID, integer) before queries.
+- Use ORM query builders for dynamic filters.
+
+## Dependency Security
+- Run `npm audit` in CI. Fail on high/critical vulnerabilities.
+- Use `npm audit signatures` to verify package provenance.
+- Pin exact versions with lockfile. Review lockfile changes in PRs.
+- Avoid packages with postinstall scripts unless trusted.
+
+## Secrets
+- Use `process.env` with Zod validation for env vars.
+- Never import `.env` files in production -- use platform env injection.
+- Never log `req.headers.authorization` or session tokens.
+- Use `crypto.timingSafeEqual()` for comparing secrets.
+
+## Server Hardening
+- Set security headers: HSTS, X-Content-Type-Options, X-Frame-Options.
+- Use `helmet` middleware in Express, built-in security in Fastify.
+- Implement rate limiting on all endpoints (`express-rate-limit`, `@fastify/rate-limit`).
+- Disable `X-Powered-By` header. Do not expose server technology.
+
+## File Uploads
+- Validate file type by magic bytes, not just extension or MIME type.
+- Set maximum file size limits on the server.
+- Store uploads outside the web root. Serve through a proxy with CDN.
+- Generate random filenames. Never use user-provided filenames for storage.
+
+# TypeScript Testing
+
+## Framework
+- Use Vitest for new projects (faster, native ESM, TypeScript-first).
+- Use Jest only for existing projects already using it.
+- Use Playwright for E2E browser testing.
+- Use Supertest or built-in fetch for API integration tests.
+
+## File Naming
+- Test files: `*.test.ts` or `*.spec.ts` colocated with source.
+- Test utilities: `tests/helpers/` or `tests/utils/`.
+- Fixtures: `tests/fixtures/` with typed factory functions.
+
+## Structure
+- Use `describe` for grouping by function/class/feature.
+- Use `it` with behavior descriptions: `it('returns 404 when user not found')`.
+- Avoid deeply nested `describe` blocks (max 2 levels).
+- Use `beforeEach` for setup, avoid `beforeAll` for mutable state.
+
+## Type-Safe Mocking
+- Use `vi.fn()` with type parameters: `vi.fn<[string], Promise<User>>()`.
+- Use `vi.mock()` for module-level mocking.
+- Prefer dependency injection over module mocking for testability.
+- Use `vi.spyOn()` for partial mocks on existing objects.
+
+## React/Component Testing
+- Use React Testing Library. Query by role, label, text -- not test IDs.
+- Use `userEvent` over `fireEvent` for realistic user interactions.
+- Test behavior and rendered output, not component internals.
+- Use `renderHook` for testing custom hooks in isolation.
+
+## Assertions
+- Use `expect().toBe()` for primitives, `expect().toEqual()` for objects.
+- Use `expect().toMatchInlineSnapshot()` for complex output verification.
+- Avoid `toBeTruthy/toBeFalsy` -- use specific matchers.
+- Use `expect().rejects.toThrow()` for async error testing.
+
+## Async Testing
+- Always `await` async operations. Never use `done` callback.
+- Use `vi.useFakeTimers()` for timer-dependent code.
+- Use `waitFor` from Testing Library for async DOM updates.
+
+## Performance
+- Run tests in parallel (Vitest default). Isolate state to enable this.
+- Use `vi.mock()` for heavy dependencies (DB, network) in unit tests.
+- Keep unit test suite under 30 seconds.

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-04-24T08:04:02Z",
+  "last_run": "2026-04-28T09:44:52Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "5754553b0e436fd7",
+      "docs_hash": "7e632fc04e405f60",
       "headings": [
         "Agent",
         "Code Completions",
@@ -57,7 +57,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "0c111b1b1f28960d",
+      "docs_hash": "e51d7d44c72cd522",
       "headings": [
         "Claude Code overview",
         "\u200bGet started",
@@ -102,10 +102,10 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.119 (Claude Code)"
+      "version": "2.1.121 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "17c24d27216f70cf",
+      "docs_hash": "0c69984492abf906",
       "headings": [
         "Cline CLI",
         "Cline Documentation",
@@ -135,7 +135,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "7a7f5cdf9411c5e2",
+      "docs_hash": "9e188e7e454523b6",
       "headings": [
         "About",
         "Contributing",
@@ -154,7 +154,7 @@
         "Packages 0",
         "Provide feedback",
         "Quickstart",
-        "Releases 735",
+        "Releases 744",
         "Repository files navigation",
         "Resources",
         "Saved searches",
@@ -168,7 +168,7 @@
         "openai/codex"
       ],
       "markers": {
-        ".codex/skills": true,
+        ".agents/skills": false,
         "AGENTS.md": true,
         "config.toml": false,
         "hook event: PermissionRequest": false,
@@ -184,10 +184,10 @@
         "mcp_servers": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.124.0"
+      "version": "codex-cli 0.125.0"
     },
     "cursor": {
-      "docs_hash": "a94b8e8f685b0831",
+      "docs_hash": "56983669e33487e2",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -203,7 +203,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "9415ea08e344013d",
+      "docs_hash": "fa8989b65df2bb73",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -242,7 +242,7 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "8bcd2db0db925807",
+      "docs_hash": "c2100e9dca8dce0d",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot integrations",
@@ -290,7 +290,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "760fbf466036892f",
+      "docs_hash": "5c0f3f9c9b031f49",
       "headings": [
         "Add features",
         "Ask questions",
@@ -351,7 +351,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "81d0aafbf97b18c8",
+      "docs_hash": "9cadd867b0cec6da",
       "headings": [
         "Advanced",
         "App Deploys",

package/kb/history/completed/deep-coverage-v3-20260423.md

@@ -33,7 +33,7 @@ Definition of "100% coverage" chosen: **each editor works at 100% of its native
 
 | # | Decision | Rule |
 |---|----------|------|
-| 1 | Skill propagation | `.claude/skills/` canonical. Cursor/Windsurf/opencode → compat-read (nothing). Augment/Gemini/Antigravity → **pointer skill** (1 file per editor). Codex → opt-in `--codex-skills` flag emits full mirror |
+| 1 | Skill propagation | `.claude/skills/` canonical. Cursor/Windsurf/opencode → compat-read (nothing). Augment/Gemini/Antigravity → **pointer skill** (1 file per editor). Codex → native `.agents/skills/` mirror |
 | 2 | Global writes | Only `~/.claude/`. Cursor/Windsurf/opencode get global coverage via compat-read. Augment/Gemini/Roo require `--local` |
 | 3 | Surface activation | **`--profile full`** turns on every native surface. `standard` stays close to today's defaults but adds niepodważalne wypełnienia (Copilot wiring + Gemini hooks). `minimal` unchanged |
 | 4 | Default behavior | `--editors <name>` alone uses `standard`. Users who want the full stack pass `--profile full` |
@@ -77,13 +77,13 @@ Definition of "100% coverage" chosen: **each editor works at 100% of its native
 **Owned files**
 - New: `scripts/generate_gemini_skills.py` (`.gemini/skills/ai-toolkit-skill-catalogue/SKILL.md` — pointer)
 - New: `scripts/generate_augment_skills.py` (`.augment/skills/ai-toolkit-skill-catalogue/SKILL.md` — pointer)
-- New: `scripts/generate_codex_skills.py` (full mirror to `.codex/skills/<name>/SKILL.md` — gated by `--codex-skills` flag)
+- New: `scripts/generate_codex_skills.py` (Codex-native mirror to `.agents/skills/<name>/SKILL.md`)
 - New: `tests/test_skills_native.bats` (≥15 tests)
 
 **Must-haves**
 - Pointer pattern same as Antigravity: 1 file per editor referencing `~/.claude/skills/<name>` and listing the catalogue.
 - Codex mirror respects `user-invocable: false` (knowledge skills stay, task skills stay — Codex reads them all).
-- `--codex-skills` must be opt-in; default OFF.
+- Codex skills use the upstream `.agents/skills` discovery path.
 
 ### Bucket 4 — Install wiring + profile full + docs (devops-implementer)