@softspark/ai-toolkit 1.2.1 → 1.3.0

package/app/rules/swift/frameworks.md

@@ -0,0 +1,63 @@
+---
+language: swift
+category: frameworks
+version: "1.0.0"
+---
+
+# 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.

package/app/rules/swift/patterns.md

@@ -0,0 +1,63 @@
+---
+language: swift
+category: patterns
+version: "1.0.0"
+---
+
+# 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.

package/app/rules/swift/security.md

@@ -0,0 +1,63 @@
+---
+language: swift
+category: security
+version: "1.0.0"
+---
+
+# 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.

package/app/rules/swift/testing.md

@@ -0,0 +1,60 @@
+---
+language: swift
+category: testing
+version: "1.0.0"
+---
+
+# 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/rules/typescript/coding-style.md

@@ -0,0 +1,51 @@
+---
+language: typescript
+category: coding-style
+version: "1.0.0"
+---
+
+# 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.

package/app/rules/typescript/frameworks.md

@@ -0,0 +1,51 @@
+---
+language: typescript
+category: frameworks
+version: "1.0.0"
+---
+
+# 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:*"`.

package/app/rules/typescript/patterns.md

@@ -0,0 +1,51 @@
+---
+language: typescript
+category: patterns
+version: "1.0.0"
+---
+
+# 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.

package/app/rules/typescript/security.md

@@ -0,0 +1,55 @@
+---
+language: typescript
+category: security
+version: "1.0.0"
+---
+
+# 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.

package/app/rules/typescript/testing.md

@@ -0,0 +1,52 @@
+---
+language: typescript
+category: testing
+version: "1.0.0"
+---
+
+# 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/app/skills/app-builder/SKILL.md

@@ -18,7 +18,7 @@ allowed-tools: Read
 | mobile, ios, android | Mobile App | mobile-developer |
 | cli, command, terminal | CLI Tool | backend-specialist |
 | game, unity, godot | Game | game-developer |
-| ai, ml, rag | AI/ML | rag-engineer |
+| ai, ml, rag | AI/ML | ai-engineer |
 | e-commerce, shop, store | E-commerce | backend + frontend |
 
 ---

package/app/skills/brand-voice/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: brand-voice
+description: "Loaded when writing documentation, content, README, or user-facing text. Prevents generic LLM rhetoric and enforces direct, technical voice."
+effort: medium
+user-invocable: false
+allowed-tools: Read
+---
+
+# Brand Voice
+
+Auto-loaded when writing documentation, content, or user-facing text. Enforces consistent, direct voice and eliminates LLM rhetoric.
+
+## Anti-Trope List (Banned Phrases)
+
+### Opening Tropes (Never Start With)
+
+- "In today's fast-paced world..."
+- "In the ever-evolving landscape of..."
+- "Let's dive into..."
+- "Let's explore..."
+- "Welcome to this comprehensive guide..."
+- "Are you looking for...?"
+- "Whether you're a beginner or an expert..."
+
+### Filler Adjectives (Remove or Replace)
+
+| Banned | Replacement |
+|--------|------------|
+| "cutting-edge" | Describe what it does |
+| "game-changer" | State the specific impact |
+| "revolutionary" | State the concrete improvement |
+| "robust" | Describe what makes it reliable |
+| "seamless" | Describe the integration mechanism |
+| "state-of-the-art" | Cite specific capabilities |
+| "leveraging" | "using" |
+| "harnessing" | "using" |
+| "utilizing" | "using" |
+| "delve" / "delve into" | "examine" / "look at" |
+| "holistic" | "complete" / "full" |
+| "synergy" | Describe the actual interaction |
+| "paradigm shift" | Describe the change |
+| "best-in-class" | Cite the benchmark or drop it |
+| "empower" | Say what it enables |
+| "streamline" | Say what step it removes |
+| "elevate" | Say what improves and by how much |
+| "unlock" | Say what becomes possible |
+
+### Closing Tropes (Never End With)
+
+- "Happy coding!"
+- "And that's it! You're all set!"
+- "I hope this helps!"
+- "Feel free to reach out if you have any questions"
+- "Now go build something amazing!"
+
+### Structural Tropes
+
+- Do not number every single point when prose works better
+- Do not use headers for 2-sentence sections
+- Do not add a "Conclusion" section that restates the intro
+- Do not add "Overview" sections that say nothing the title didn't already say
+- Do not pad lists to look longer than they are
+
+## Voice Principles
+
+| Principle | Rule |
+|-----------|------|
+| **Direct over diplomatic** | Say what you mean. "This function is slow" not "This function could potentially benefit from optimization." |
+| **Specific over general** | Numbers, names, versions. "Reduces cold start by 40ms" not "Improves performance significantly." |
+| **Evidence over assertion** | Show, don't tell. Include benchmarks, examples, or code. |
+| **Short over long** | One sentence beats three. Cut filler words on every pass. |
+| **Active over passive** | "The function returns X" not "X is returned by the function." |
+| **Technical over casual** | Match the audience's expertise. Never dumb down for developers. |
+| **Honest over promotional** | State limitations alongside strengths. |
+
+## Sentence-Level Rules
+
+- **Lead with the action or outcome**, not the context. Bad: "In order to configure X, you need to..." Good: "Configure X by..."
+- **Cut weasel words**: "quite", "very", "really", "basically", "simply", "just", "actually", "arguably"
+- **One idea per sentence.** If a sentence has "and" linking two distinct ideas, split it.
+- **Use concrete subjects.** Bad: "It is important to note that..." Good: (delete the phrase, state the fact)
+
+## Before Publishing Checklist
+
+- [ ] No banned phrases from anti-trope list?
+- [ ] Opening sentence provides value (not filler)?
+- [ ] Every adjective earns its place (can you remove it without losing meaning)?
+- [ ] No "comprehensive guide" or "complete overview" unless it truly is?
+- [ ] Consistent terminology throughout?
+- [ ] Active voice used by default?
+- [ ] No weasel words remaining?
+- [ ] Technical claims backed by evidence or examples?