tddworks

add-provider

@tddworks/add-provider
tddworks
416
31 forks
Updated 1/18/2026
View on GitHub

Guide for adding new AI providers to ClaudeBar using TDD patterns. Use this skill when: (1) Adding a new AI assistant provider (like Antigravity, Cursor, etc.) (2) Creating a usage probe for a CLI tool or local API (3) Following TDD to implement provider integration (4) User asks "how do I add a new provider" or "create a provider for X"

Installation

$skills install @tddworks/add-provider
Claude Code
Cursor
Copilot
Codex
Antigravity

Details

Path.claude/skills/add-provider/SKILL.md
Branchmain
Scoped Name@tddworks/add-provider

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

skills list

Skill Instructions


name: add-provider description: | Guide for adding new AI providers to ClaudeBar using TDD patterns. Use this skill when: (1) Adding a new AI assistant provider (like Antigravity, Cursor, etc.) (2) Creating a usage probe for a CLI tool or local API (3) Following TDD to implement provider integration (4) User asks "how do I add a new provider" or "create a provider for X"

Add Provider to ClaudeBar

Add new AI providers following established TDD patterns and architecture.

Architecture Overview

Full architecture: docs/ARCHITECTURE.md

ComponentLocationPurpose
AIProviderSources/Domain/Provider/Rich domain model with isEnabled state
UsageProbeSources/Infrastructure/CLI/Fetches quota from CLI/API
TestsTests/InfrastructureTests/CLI/Parsing + behavior tests

TDD Workflow

Phase 1: Parsing Tests (Red → Green)

Create Tests/InfrastructureTests/CLI/{Provider}UsageProbeParsingTests.swift:

import Testing
import Foundation
@testable import Infrastructure
@testable import Domain

@Suite
struct {Provider}UsageProbeParsingTests {

    static let sampleResponse = """
                                { /* sample API/CLI response */ }
                                """

    @Test func `parses quota into UsageQuota`() throws {
        let data = Data(Self.sampleResponse.utf8)
        let snapshot = try {Provider}UsageProbe.parseResponse(data, providerId: "{provider-id}")
        #expect(snapshot.quotas.count > 0)
    }

    @Test func `maps percentage correctly`() throws { /* ... */ }
    @Test func `parses reset time`() throws { /* ... */ }
    @Test func `extracts account email`() throws { /* ... */ }
    @Test func `handles missing data gracefully`() throws { /* ... */ }
}

Phase 2: Probe Behavior Tests (Red → Green)

Create Tests/InfrastructureTests/CLI/{Provider}UsageProbeTests.swift:

import Testing
import Foundation
import Mockable
@testable import Infrastructure
@testable import Domain

@Suite
struct {Provider}UsageProbeTests {

    @Test func `isAvailable returns false when not detected`() async {
        let mockExecutor = MockCLIExecutor()
        given(mockExecutor).execute(...).willReturn(CLIResult(output: "", exitCode: 1))
        let probe = {Provider}UsageProbe(cliExecutor: mockExecutor)
        #expect(await probe.isAvailable() == false)
    }

    @Test func `isAvailable returns true when detected`() async { /* ... */ }
    @Test func `probe throws appropriate error when unavailable`() async { /* ... */ }
    @Test func `probe returns UsageSnapshot on success`() async { /* ... */ }
}

Phase 3: Implement Probe

Create Sources/Infrastructure/CLI/{Provider}UsageProbe.swift:

import Foundation
import Domain

public struct {Provider}UsageProbe: UsageProbe {
    private let cliExecutor: any CLIExecutor
    private let networkClient: any NetworkClient
    private let timeout: TimeInterval

    public init(
        cliExecutor: (any CLIExecutor)? = nil,
        networkClient: (any NetworkClient)? = nil,
        timeout: TimeInterval = 8.0
    ) {
        self.cliExecutor = cliExecutor ?? DefaultCLIExecutor()
        self.networkClient = networkClient ?? URLSession.shared
        self.timeout = timeout
    }

    public func isAvailable() async -> Bool {
        // Detect if provider is available (binary exists, process running, etc.)
    }

    public func probe() async throws -> UsageSnapshot {
        // 1. Detect/authenticate
        // 2. Fetch quota data
        // 3. Parse and return UsageSnapshot
    }

    // Static parsing for testability
    static func parseResponse(_ data: Data, providerId: String) throws -> UsageSnapshot {
        // Parse response into domain models
    }
}

Phase 4: Create Provider

Choose Repository Type (ISP):

  • Simple provider (no special config) → Use base ProviderSettingsRepository
  • Provider with config → Create sub-protocol extending base (see ISP section below)

Create Sources/Domain/Provider/{Provider}Provider.swift:

import Foundation
import Observation

@Observable
public final class {Provider}Provider: AIProvider, @unchecked Sendable {
    public let id: String = "{provider-id}"
    public let name: String = "{Provider Name}"
    public let cliCommand: String = "{cli-command}"

    public var dashboardURL: URL? { URL(string: "https://...") }
    public var statusPageURL: URL? { nil }

    /// Whether the provider is enabled (persisted via settingsRepository)
    public var isEnabled: Bool {
        didSet {
            settingsRepository.setEnabled(isEnabled, forProvider: id)
        }
    }

    public private(set) var isSyncing: Bool = false
    public private(set) var snapshot: UsageSnapshot?
    public private(set) var lastError: Error?

    private let probe: any UsageProbe
    private let settingsRepository: any ProviderSettingsRepository  // Or your sub-protocol

    public init(probe: any UsageProbe, settingsRepository: any ProviderSettingsRepository) {
        self.probe = probe
        self.settingsRepository = settingsRepository
        // Default to enabled for most providers (set defaultValue: false for opt-in providers)
        self.isEnabled = settingsRepository.isEnabled(forProvider: "{provider-id}")
    }

    public func isAvailable() async -> Bool {
        await probe.isAvailable()
    }

    @discardableResult
    public func refresh() async throws -> UsageSnapshot {
        isSyncing = true
        defer { isSyncing = false }
        do {
            let newSnapshot = try await probe.probe()
            snapshot = newSnapshot
            lastError = nil
            return newSnapshot
        } catch {
            lastError = error
            throw error
        }
    }
}

Phase 5: Register Provider

Add to Sources/App/ClaudeBarApp.swift:

let settingsRepository = UserDefaultsProviderSettingsRepository.shared

let repository = AIProviders(providers: [
    ClaudeProvider(probe: ClaudeUsageProbe(), settingsRepository: settingsRepository),
    // ... existing providers
    {Provider}Provider(probe: {Provider}UsageProbe(), settingsRepository: settingsRepository),
])

For providers with special settings (ISP pattern):

// ZaiProvider uses ZaiSettingsRepository (sub-protocol)
ZaiProvider(
    probe: ZaiUsageProbe(settingsRepository: settingsRepository),
    settingsRepository: settingsRepository  // Same instance, casted to ZaiSettingsRepository
)

// CopilotProvider uses CopilotSettingsRepository (sub-protocol with credentials)
CopilotProvider(
    probe: CopilotUsageProbe(settingsRepository: settingsRepository),
    settingsRepository: settingsRepository  // Same instance, casted to CopilotSettingsRepository
)

Add visual identity in Sources/App/Views/Theme.swift:

// In AppTheme.providerColor(for:scheme:)
case "{provider-id}": return /* your color */

// In AppTheme.providerName(for:)
case "{provider-id}": return "{Provider Name}"

// In AppTheme.providerSymbolIcon(for:)
case "{provider-id}": return "/* SF Symbol name */"

// In AppTheme.providerIconAssetName(for:)
case "{provider-id}": return "{Provider}Icon"

Domain Model Mapping

Map provider responses to existing domain models:

Source DataDomain Model
Quota percentageUsageQuota.percentRemaining (0-100)
Model/tier nameQuotaType.modelSpecific("name")
Reset timeUsageQuota.resetsAt (Date)
Account emailUsageSnapshot.accountEmail

Error Handling

Use existing ProbeError enum:

ProbeError.cliNotFound("{Provider}")      // Binary/process not found
ProbeError.authenticationRequired          // Auth token missing/expired
ProbeError.executionFailed("message")      // Runtime errors
ProbeError.parseFailed("message")          // Parse errors

ISP: Creating Provider-Specific Repository Sub-Protocols

If your provider needs special configuration or credentials, create a sub-protocol following ISP:

Step 1: Define Sub-Protocol in Domain

Add to Sources/Domain/Provider/ProviderSettingsRepository.swift:

/// {Provider}-specific settings repository, extending base ProviderSettingsRepository.
public protocol {Provider}SettingsRepository: ProviderSettingsRepository {
    // Configuration
    func {provider}ConfigPath() -> String
    func set{Provider}ConfigPath(_ path: String)

    // Credentials (if needed)
    func save{Provider}Token(_ token: String)
    func get{Provider}Token() -> String?
    func has{Provider}Token() -> Bool
}

Step 2: Implement in Infrastructure

Add to Sources/Infrastructure/Storage/UserDefaultsProviderSettingsRepository.swift:

extension UserDefaultsProviderSettingsRepository: {Provider}SettingsRepository {
    public func {provider}ConfigPath() -> String {
        userDefaults.string(forKey: Keys.{provider}ConfigPath) ?? ""
    }

    // ... other methods
}

Step 3: Update Provider and Probe

// Provider
private let settingsRepository: any {Provider}SettingsRepository

// Probe (if needs settings)
public init(settingsRepository: any {Provider}SettingsRepository) {
    self.settingsRepository = settingsRepository
}

Existing Examples:

  • ZaiSettingsRepository - config path + env var
  • CopilotSettingsRepository - env var + GitHub credentials

Reference Implementation

See references/antigravity-example.md for a complete working example showing:

  • Full parsing test suite
  • Probe behavior tests with mocking
  • Probe implementation with process detection
  • Provider class pattern

Provider Icon

See references/provider-icon-guide.md for creating provider icons:

  • SVG template with rounded rectangle background
  • PNG generation at 1x/2x/3x sizes
  • Asset catalog setup
  • ProviderVisualIdentity extension

Checklist

  • Parsing tests created and passing
  • Probe behavior tests created and passing
  • Probe implementation complete
  • Provider class created
  • Provider registered in ClaudeBarApp
  • Visual identity added to Theme.swift (color, name, icons)
  • Provider icon SVG created with rounded rect background
  • Icon PNGs generated (64, 128, 192px)
  • All 300+ existing tests still pass

More by tddworks

View all
implement-feature
416

Guide for implementing features in ClaudeBar following architecture-first design, TDD, rich domain models, and Swift 6.2 patterns. Use this skill when: (1) Adding new functionality to the app (2) Creating domain models that follow user's mental model (3) Building SwiftUI views that consume domain models directly (4) User asks "how do I implement X" or "add feature Y" (5) Implementing any feature that spans Domain, Infrastructure, and App layers

improvement
416

Guide for making improvements to existing ClaudeBar functionality using TDD. Use this skill when: (1) Enhancing existing features (not adding new ones) (2) Improving UX, performance, or code quality (3) User asks "improve X", "make Y better", or "enhance Z" (4) Small enhancements that don't require full architecture design For NEW features, use implement-feature skill instead.

fix-bug
416

Guide for fixing bugs in ClaudeBar following Chicago School TDD and rich domain design. Use this skill when: (1) User reports a bug or unexpected behavior (2) Fixing a defect in existing functionality (3) User asks "fix this bug" or "this doesn't work correctly" (4) Correcting behavior that violates the user's mental model

implement-feature
42

Guide for implementing features following architecture-first design, TDD, rich domain models, and Swift 6.2 patterns. Use this skill when: (1) Adding new functionality to a Swift app (2) Creating domain models that follow user's mental model (3) Building SwiftUI views that consume domain models directly (4) User asks "how do I implement X" or "add feature Y" (5) Implementing any feature that spans Domain, Infrastructure, and App layers