Implement Feature in ClaudeBar

Implement features using architecture-first design, TDD, rich domain models, and Swift 6.2 patterns.

Workflow Overview

┌─────────────────────────────────────────────────────────────┐
│  1. ARCHITECTURE DESIGN (Required - User Approval Needed)  │
├─────────────────────────────────────────────────────────────┤
│  • Read the design docs — they are the source of truth     │
│  • Place the feature: owner, capability, extension point    │
│  • Write the design change into the docs first              │
│  • Analyze requirements                                     │
│  • Create component diagram                                 │
│  • Show data flow and interactions                          │
│  • Present to user for review                               │
│  • Wait for approval before proceeding                      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (User Approves)
┌─────────────────────────────────────────────────────────────┐
│  2. TDD IMPLEMENTATION                                      │
├─────────────────────────────────────────────────────────────┤
│  • Model tests → models (Quotas / Providers / Domain)       │
│  • Module tests → generic rules and workers (DataSources)   │
│  • Views, reading the domain directly                       │
└─────────────────────────────────────────────────────────────┘

Phase 0: Architecture Design (MANDATORY)

Before writing any code, design it in the docs and get user approval. The design docs are the source of truth (AGENTS.md → Design docs are the source of truth).

Step 0: Read the design docs, and place the feature in them

Read the design in order (ARCHITECTURE.md maps it): USER_JOURNEYS.md (the person and the moment), CANONICAL_MODEL.md (the tree, the words, each law and its owner, owned vs offered), TARGET_ARCHITECTURE.md (the pieces and their one job, the flows), then any docs/features/<context>/<x>/design.md it touches. Then answer:

Question	If yes
Does it answer another question than the product's lifecycle?	it is a capability (CANONICAL §2.1): declared in the definition, its own types, reached through a handle that is nil when not declared — never a flag on Provider, never chosen by a provider's name. A runner outside the modules is supplied by the Engine (TARGET_ARCHITECTURE §10)
Does a provider need something the definition can't say?	a generic rule or worker in DataSources (ENGINE_DESIGN), then a line of JSON — never a Swift line that names the provider
Does it react to a refresh, a selection, a setting?	it observes an extension point (e.g. QuotaMonitor.onRefreshed) — the Monitor is not edited for it
Does it notify?	its own port in Alerting — not a new method on an existing alerter
Does something already decide it? (a threshold crossed, a rate, a unit, the worst quota)	use that owner: the feature is a new destination or a new read of it, never a parallel engine → A new feature next to an old one
Does it ask a type a new kind of question?	a new value built from that type (ModelMix(of: days, in: unit)), not another read on it → question 6
Does it save a choice, or a secret?	settings.json through JSONSettingsRepository; a secret through the one Keychain-with-fallback store (settings.md) — never a feature's own file
Does another open PR touch the same type?	agree on one owner first; the later one rebases on it
Is a law missing, or owned twice?	add it to CANONICAL §5 with one owner

When the docs don't cover it, write the change into them first (tree lines, laws with owners, a pieces table, a TARGET section) — that doc change is the architecture you present in Step 4. Code that disagrees with the docs is behind; don't bend the design to it.

Step 0b: Think the domain first

Before components, ask how the domain should be: from the root problem (the issue, the journey) to the facts it must respect, to the concepts those force, then compare with the code. Ask the seven questions of every type the feature touches, and draw now beside proposed → domain-shape.md. For each new type, write down its one reason to change and which side it lives on (kernel fact, App words or colours, Infrastructure storage, an OS port); a type with two reasons is two types. A new aggregate, a moved law or a changed owner goes into the docs in Step 0's change.

Step 1: Analyze Requirements

Identify:

• What new models/types are needed
• Which existing components will be modified
• Data flow between components
• External dependencies (CLI, API, etc.)

Step 2: Create Architecture Diagram

Use ASCII diagram showing all components and their interactions:

Example: added accounts — a definition change plus generic pieces

┌──────────────────────────────────────────────────────────────────────┐
│                            ARCHITECTURE                               │
├──────────────────────────────────────────────────────────────────────┤
│  Resources (data)        Modules (Swift, no vendor names)    App     │
│                                                                      │
│  ┌──────────────┐   ┌─────────────────────────────┐   ┌───────────┐  │
│  │ codex.json   │──▶│ Providers                   │──▶│ Accounts  │  │
│  │  accounts:   │   │  ProviderCatalog.detect()   │   │ card      │  │
│  │  folder, ids │   │  ProviderDefinition.Accounts│   └───────────┘  │
│  │  dataSources │   │  Provider owns its Accounts │                  │
│  └──────────────┘   └──────────────┬──────────────┘                  │
│                                    │                                 │
│                     ┌──────────────▼──────────────┐                  │
│                     │ DataSources                 │                  │
│                     │  identity, requiresFiles,   │                  │
│                     │  JSON-RPC `then`, env       │                  │
│                     └──────────────┬──────────────┘                  │
│                                    ▼                                 │
│                     ┌─────────────────────────────┐                  │
│                     │ Quotas  (UsageSnapshot …)   │                  │
│                     └─────────────────────────────┘                  │
└──────────────────────────────────────────────────────────────────────┘

Step 3: Document Component Interactions

List each component with:

• Purpose: What it does
• Inputs: What it receives
• Outputs: What it produces
• Dependencies: What it needs

Example:

| Component      | Purpose                | Inputs          | Outputs        | Dependencies    |
|----------------|------------------------|-----------------|----------------|-----------------|
| AddedAccounts  | Validate a login folder| folder path     | account config | DataSources     |
| identity rule  | Fail closed on swaps   | credential      | UsageError     | —               |

Step 4: Present for User Approval

IMPORTANT: Always ask user to confirm the design is correct before implementing — the doc change (tree, laws and owners, pieces), the diagram, and for UI a mockup in design-concept/<feature>/ on mock data. A new card, pane or screen has its mockup before any view code; the review looks at the mockup first, then the domain.

Use AskUserQuestion tool with options:

• "Approve - proceed with implementation"
• "Modify - I have feedback on the design"

Do NOT proceed to Phase 1 until user explicitly approves.

---

Core Principles

1. Rich Domain Models (User's Mental Model)

Domain models encapsulate behavior, not just data:

// Rich domain model with behavior
public struct UsageQuota: Sendable, Equatable {
    public let percentRemaining: Double

    // Domain behavior - computed from state
    public var status: QuotaStatus {
        QuotaStatus.from(percentRemaining: percentRemaining)
    }

    public var isDepleted: Bool { percentRemaining <= 0 }
    public var needsAttention: Bool { status.needsAttention }
}

2. Swift 6.2 Patterns (No ViewModel/AppState Layer)

Views consume domain models directly from QuotaMonitor:

// QuotaMonitor is the single source of truth
@MainActor @Observable
public final class QuotaMonitor {
    // The providers you keep: add, delete, order, the derived lineup
    public let providers: Providers

    public var logins: [Account]   // every login
    public var lineup: [Account]   // the lineup
    public func login(id: String) -> Account?

    // Selection state
    public var selectedProviderId: String
    public var selectedLogin: Account?
    public var selectedProviderStatus: QuotaStatus
}

// Views consume domain directly - NO AppState layer
struct MenuContentView: View {
    let monitor: QuotaMonitor  // Injected from app

    var body: some View {
        // Use delegation methods, not monitor.providers.enabled
        ForEach(monitor.lineup, id: \.id) { login in
            ProviderPill(provider: login)
        }
    }
}

3. Protocol-Based DI with @Mockable

Ports for what lies outside the app live at a module's root and are @Mockable; their implementations are internal in Internal/:

@Mockable
public protocol NetworkClient: Sendable {
    func request(_ request: URLRequest) async throws -> (Data, URLResponse)
}

Architecture

Reference: MODULAR_DESIGN.md (modules) · TARGET_ARCHITECTURE.md (how a provider runs) · ARCHITECTURE.md (the app layers)

The code is mid-migration from three layers to modules. Find which side the behaviour lives on before you change it:

Where	Holds	Tests
Modules/Providers/Resources/Providers/<id>.json (+ .js)	every built-in provider: where the key is, how to fetch, how to read	Modules/Providers/Tests/ (golden tests over StubbedProvider / ClaudeHarness)
Modules/Providers/Sources	ProviderCatalog (finds every definition), Engine (the shared ports), Provider (the one lifecycle: refresh, fallback chain, accounts), ProviderDefinition, settings and account contracts, the capabilities (UsageHistory, GuestPasses, InUse)	Modules/Providers/Tests/
Modules/DataSources/Sources	DataSource and its workers: credential lookups (environment, login shell, files, Keychain, browser cookies and storage, SQLite) and refreshes; HTTP, steps, JSON-RPC, terminal, command, file, directory, SQLite, local-server and CloudWatch fetches; JSON / text / script mapping; UsageLog and its log readers; the process runners	Modules/DataSources/Tests/
Modules/Quotas/Sources	the usage model: UsageSnapshot, UsageQuota, UsageError, plans, costs, DailyUsageStat / DailyUsageReport (interim shapes, see each type's - Note:)	Tests/DomainTests/ and the tests of the module that uses it
Modules/AWSClients	the AWS SDK behind DataSources' CloudWatchClient and PriceCatalog ports	Modules/AWSClients/Tests/
Sources/Domain	QuotaMonitor, Notify!, sessions, In use's NewSessions	Tests/DomainTests/
Sources/Infrastructure	storage, notifications, hooks, the shell environment, Claude's guest-pass runner	Tests/InfrastructureTests/
Sources/App	SwiftUI views reading the domain directly; ClaudeBarApp.init, the composition root, which builds the Engine and names no provider	Tests/AppTests/, Tests/AcceptanceTests/

Inside Sources/Domain, Infrastructure, App and their tests, put a new file in the folder of the context that owns its question (CANONICAL_MODEL §7): a session rule in Activity/, a destination in Alerting/, a refresh rule in Monitoring/. The feature's docs go in docs/features/<context>/<x>/. A file that fits no context's question is a sign the design is missing a word; ask before inventing a folder.

A bug in a migrated provider is fixed in its JSON, or generically in DataSources, never with vendor-named Swift. Modules never import Domain.

Key patterns:

• Modules by context — the domain at a module's root, its implementation in Internal/, one factory enum per module (DataSources.make, ProviderFactory.make)
• Providers are data — a feature a provider needs becomes a generic rule or worker, then a line of JSON
• Protocol-based DI — @Mockable ports; Chicago-school tests assert on state
• No ViewModel layer — views read QuotaMonitor and Provider directly
• Settings — generic per-provider values (dataSourceKind, isOn) before a new sub-protocol

TDD Workflow (Chicago School)

Name each test should <outcome> [when <situation>], in the person's words, never a method, type or mechanism verb → Naming tests.

We follow Chicago school TDD (state-based testing):

• Test state changes and return values, not interactions
• Focus on the "what" (observable outcomes), not the "how" (method calls)
• Mocks stub dependencies to return data, not to verify calls
• Design emerges from tests (emergent design)

Phase 1: Domain Model Tests

Test state and computed properties:

@Suite
struct FeatureModelTests {
    @Test func `should be normal when half is left`() {
        // Given - set up initial state
        let model = FeatureModel(value: 50)

        // When/Then - verify state/return value
        #expect(model.status == .normal)
    }

    @Test func `should have 70 left and stay healthy after using 30 of 100`() {
        // Given
        var model = FeatureModel(value: 100)

        // When - perform action
        model.consume(30)

        // Then - verify new state
        #expect(model.value == 70)
        #expect(model.status == .healthy)
    }
}

Phase 2: Module Tests (DataSources / Providers)

Stub dependencies to return data, assert on resulting state:

@Suite
struct FeatureServiceTests {
    @Test func `should load three items when the service answers`() async throws {
        // Given - stub dependency to return data (not verify calls)
        let mockClient = MockNetworkClient()
        given(mockClient).fetch(any()).willReturn(validResponseData)

        let service = FeatureService(client: mockClient)

        // When
        let result = try await service.fetch()

        // Then - verify returned state, not interactions
        #expect(result.items.count == 3)
        #expect(result.status == .loaded)
    }
}

Phase 3: Integration

Create the views. ClaudeBarApp.init is the composition root: it builds the Engine (the ports every provider shares) and calls ProviderCatalog().detect(). A provider is never wired there; a new port is a new Engine field, built once in init (keep startup work there, never in ClaudeBarMain). Acceptance specs in Tests/AcceptanceTests/ compose real modules with stubbed ports.

tuist test Providers         # one module's tests while working (schemes: Providers, DataSources, Domain, Infrastructure, AppTests, AcceptanceTests)
# tuist caches results; the final check, and a forced re-run of one suite, use xcodebuild:
xcodebuild test -workspace ClaudeBar.xcworkspace -scheme ClaudeBar-Workspace -destination 'platform=macOS,arch=arm64'
xcodebuild test -workspace ClaudeBar.xcworkspace -scheme ClaudeBar-Workspace \
  -destination 'platform=macOS,arch=arm64' -only-testing:ProvidersTests/ClaudeAPITests

References

• Architecture diagram patterns - ASCII diagram examples for different scenarios
• Swift 6.2 @Observable patterns
• Rich domain model patterns
• Think the domain first - from the root problem to the concepts; seven questions for a domain easy to understand, with one reason to change (SRP) and each concern on its own side; a new feature next to an old one; keeping it in scope
• TDD test patterns

Checklist

Architecture Design (Phase 0)

• Read CANONICAL_MODEL, TARGET_ARCHITECTURE and the feature's design.md
• Place it: owner, capability (handle nil when not declared), extension point
• Thought the domain first: root problem → concepts, the seven questions asked of touched types, now/proposed drawn (domain-shape.md)
• Searched for the rule before writing it: an existing owner is used, not copied (rate, threshold, unit, worst quota)
• Each new type has one reason to change and one side (kernel fact · App words/colours · Infrastructure · OS port)
• Write the design change into the docs first
• Analyze requirements and identify components
• Create ASCII architecture diagram with component interactions
• Document component table (purpose, inputs, outputs, dependencies)
• Get user approval before proceeding

Implementation (Phases 1-3) - Chicago School TDD

• Write failing test asserting expected STATE (Red)
• Write minimal code to pass the test (Green)
• Refactor while keeping tests green
• Put each type in the module MODULAR_DESIGN.md names (never a vendor-named type in a module)
• Test state changes and return values (not interactions)
• Define protocols with @Mockable for external dependencies
• Stub mocks to return data, assert on resulting state
• Implement ports in the module's Internal/
• Create views consuming domain models directly
• Views render and tell only — no comparing, counting or reading quotas to decide; the view passes the unit or login the person chose, it never picks one
• Sentences, labels and colours in the App (QuotaCardText, ModelColors); the kernel answers facts and formats only the amounts it owns, through the shared formatter
• Nothing built that no caller uses yet (no speculative type, case or setting)
• Choices persist in settings.json; secrets in the one Keychain-with-fallback store
• Public surface is tells and answers; rules internal; no Bool flag the caller decides; each aggregate changes only its own state
• Docs updated in the same change (status, build truth, laws)
• Real UI screenshots on mock data (scripts/demo-screenshots.sh) for UI changes
• Full xcodebuild test green (tuist test skips cached targets)