architecture-builder

name	architecture-builder
description	Use to produce the technical architecture doc and engineering principles for a mobile app. Used primarily by the CTO agent. Triggers on "design the architecture", "pick the stack", or as part of /app-plan.

Architecture builder

Produce docs/20-architecture.md and docs/21-engineering-principles.md from docs/00-vision.md + docs/10-prd.md.

docs/20-architecture.md sections

1. Platform decision — iOS / Android / both, with order if sequential.

2. iOS stack —

   • Swift version (latest stable)
   • Minimum iOS target (set based on the PRD's user, not vanity)
   • UI: SwiftUI by default; UIKit only if PRD demands something SwiftUI struggles with
   • State: ObservableObject + @State, or a documented store pattern
   • Networking: URLSession + async/await, or a named lib
   • Persistence: SwiftData / Core Data / GRDB — pick by PRD complexity
   • DI: lightweight — protocol + initializer injection
   • Testing: XCTest, snapshot lib named, UI test framework named

3. Android stack —

   • Kotlin version
   • minSdk / targetSdk (set based on PRD users)
   • UI: Jetpack Compose
   • Architecture: MVVM or MVI, picked once
   • Networking: Retrofit + OkHttp + Kotlinx Serialization (or named alternative)
   • Persistence: Room (or named alternative)
   • DI: Hilt or Koin
   • Async: Coroutines + Flow
   • Testing: JUnit, Turbine, Compose UI test

4. Shared concerns — auth, analytics, crash reporting, feature flags, remote config, push.

5. Backend interface — sketch the APIs the apps need. If backend is in scope, name the service shape.

6. Repository layout —

   /
   ├── ios/                # Xcode project / SwiftPM workspace
   ├── android/            # Gradle multi-module
   ├── backend/            # if in scope
   ├── docs/               # all team docs
   └── specs/              # ticket-level specs if any
   

7. CI / release — branch model, build pipeline, signing, distribution channel (TestFlight, Play internal track).

8. Non-functional budgets — cold start, memory, payload size, accessibility floor (WCAG 2.1 AA).

9. Risks — top 3 with mitigations.

docs/21-engineering-principles.md

A short rulebook. Examples to include or adapt:

• Every PR ships with tests
• No force-unwraps (iOS) / no !! (Android)
• Every screen has accessibility labels and a snapshot test
• No new third-party dep over 200KB without written exception
• Strings are localized from day one
• Logs go through the named logger; no print / Log.d in shipped code
• Public API for a module is documented in a README.md at the module root

Quality bar

Every decision in §2 and §3 has one paragraph of "why" tied to the PRD. If you can't write the "why", reconsider the choice.