agentic-team 0.0.0-stage → 6.2.0

package/template/.orchestra/stacks/mobile-ios-native/setup.sh

@@ -0,0 +1,468 @@
+#!/usr/bin/env bash
+# Native iOS — SwiftUI, generated from an XcodeGen manifest.
+#
+# The project is generated from project.yml, never hand-edited as a .pbxproj.
+# A binary project file cannot be reviewed in a diff and corrupts under
+# concurrent edits — both fatal for an agent-driven workflow.
+set -euo pipefail
+
+DIR="${1:?usage: setup.sh <target-dir>}"
+RAW_NAME="${2:-$(basename "$DIR")}"
+# Swift type names cannot contain dashes.
+NAME="$(printf '%s' "$RAW_NAME" | sed 's/[^A-Za-z0-9]//g')"
+[ -n "$NAME" ] || NAME="App"
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../_lib" && pwd)"
+# shellcheck source=../_lib/common.sh
+source "$LIB/common.sh"
+
+command -v xcodegen >/dev/null 2>&1 || die "xcodegen not found. Install it first: brew install xcodegen"
+command -v xcodebuild >/dev/null 2>&1 || die "xcodebuild not found. Install Xcode, then: xcode-select --install"
+
+# Resolved now, from each project's latest release. A version written from
+# memory is the single most reliable way to waste a debugging cycle.
+resolve_version() {
+  local repo="$1" fallback="$2" tag
+  tag="$(curl -fsSL "https://api.github.com/repos/${repo}/releases/latest" 2>/dev/null \
+    | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{process.stdout.write(String(JSON.parse(s).tag_name||""))}catch{}})' 2>/dev/null || true)"
+  tag="${tag#v}"
+  case "$tag" in
+    ''|*[!0-9.]*) echo "$fallback" ;;
+    *) echo "$tag" ;;
+  esac
+}
+SENTRY_VERSION="$(resolve_version getsentry/sentry-cocoa 9.26.0)"
+POSTHOG_VERSION="$(resolve_version PostHog/posthog-ios 3.69.10)"
+log "sentry-cocoa ${SENTRY_VERSION}, posthog-ios ${POSTHOG_VERSION}"
+
+log "scaffolding native iOS into $DIR (target $NAME)"
+mkdir -p "$DIR"/Sources/{App,DesignSystem,Observability} "$DIR"/Tests/DesignSystemTests "$DIR"/UITests "$DIR"/Resources
+cd "$DIR"
+
+cat > project.yml <<YML
+name: ${NAME}
+options:
+  bundleIdPrefix: com.example
+  deploymentTarget:
+    iOS: "17.0"
+# Resolved from each project's releases at scaffold time, never recalled.
+# Pinned to a major with upToNextMajor so a patch arrives without a decision
+# and a breaking change does not.
+packages:
+  Sentry:
+    url: https://github.com/getsentry/sentry-cocoa
+    majorVersion: ${SENTRY_VERSION}
+  PostHog:
+    url: https://github.com/PostHog/posthog-ios
+    majorVersion: ${POSTHOG_VERSION}
+targets:
+  ${NAME}:
+    type: application
+    platform: iOS
+    sources: [Sources]
+    resources: [Resources]
+    dependencies:
+      - package: Sentry
+      - package: PostHog
+    info:
+      path: Resources/Info.plist
+      properties:
+        UILaunchScreen: {}
+        # Fed from build settings, which are fed from the environment. Absent
+        # in a checkout with no credentials, and the app says so rather than
+        # crashing or reporting nowhere in silence.
+        SentryDSN: \$(SENTRY_DSN)
+        PostHogAPIKey: \$(POSTHOG_API_KEY)
+        PostHogHost: \$(POSTHOG_HOST)
+        AppEnvironment: \$(APP_ENVIRONMENT)
+    settings:
+      base:
+        SWIFT_STRICT_CONCURRENCY: complete
+        GENERATE_INFOPLIST_FILE: NO
+        SENTRY_DSN: \$(SENTRY_DSN)
+        POSTHOG_API_KEY: \$(POSTHOG_API_KEY)
+        POSTHOG_HOST: \$(POSTHOG_HOST)
+        APP_ENVIRONMENT: \$(APP_ENVIRONMENT)
+  ${NAME}Tests:
+    type: bundle.unit-test
+    platform: iOS
+    sources: [Tests]
+    settings:
+      base:
+        # The test bundle needs its own Info.plist to code sign. Generating
+        # it is correct here — only the app target ships a real one.
+        GENERATE_INFOPLIST_FILE: YES
+    dependencies:
+      - target: ${NAME}
+  ${NAME}UITests:
+    type: bundle.ui-testing
+    platform: iOS
+    sources: [UITests]
+    settings:
+      base:
+        GENERATE_INFOPLIST_FILE: YES
+    dependencies:
+      - target: ${NAME}
+# xcodegen does generate a scheme covering both test bundles on its own, so
+# this is not a fix for anything currently broken. It is written down because
+# the alternative is depending on a default: which targets a generated scheme
+# includes is xcodegen's choice, and a change there would silently stop the
+# UI tests running while the gate kept reporting green.
+schemes:
+  ${NAME}:
+    build:
+      targets:
+        ${NAME}: all
+    test:
+      targets:
+        - ${NAME}Tests
+        - ${NAME}UITests
+YML
+
+cat > Resources/Info.plist <<'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>UILaunchScreen</key>
+  <dict/>
+</dict>
+</plist>
+PLIST
+
+cat > Sources/App/App.swift <<SWIFT
+import SwiftUI
+
+@main
+struct ${NAME}App: App {
+    init() {
+        // Before the first view, so a crash during startup is still reported.
+        Observability.start()
+    }
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+                // Every screen reports a view. At the screen, not in a
+                // wrapper three layers away that eventually fires for the
+                // wrong reason.
+                .onAppear { analytics.capture(.screenViewed(name: "home")) }
+        }
+    }
+}
+
+private let analytics: AnalyticsSink = PostHogSink()
+
+struct ContentView: View {
+    var body: some View {
+        Text("${NAME}")
+            .padding(Tokens.Spacing.gutter)
+    }
+}
+SWIFT
+
+mkdir -p Sources/Observability Tests/ObservabilityTests
+
+cat > Sources/Observability/Events.swift <<'SWIFT'
+import Foundation
+
+/// Every analytics event this app can send, and its payload.
+///
+/// One place, and a closed enum rather than strings at call sites. A string
+/// literal is how analytics quietly rots: the name is changed here, the call
+/// site still compiles, and the funnel goes silent with nobody the wiser.
+///
+/// Naming is `object_action` and never mixes styles. See
+/// .claude/rules/analytics-kpi.orchestra.md.
+public enum AnalyticsEvent: Equatable, Sendable {
+    /// Every screen reports a view. `name` is the screen, not the file.
+    case screenViewed(name: String)
+    /// A critical flow starting, succeeding, and failing — with a reason.
+    /// A funnel that only records success cannot say why people left.
+    case flowStarted(flow: String)
+    case flowCompleted(flow: String)
+    case flowFailed(flow: String, reason: String)
+
+    public var name: String {
+        switch self {
+        case .screenViewed: return "screen_viewed"
+        case .flowStarted: return "flow_started"
+        case .flowCompleted: return "flow_completed"
+        case .flowFailed: return "flow_failed"
+        }
+    }
+
+    /// No PII. No email, no name, nothing the user typed — the reason on a
+    /// failure is a code, not a message.
+    public var properties: [String: String] {
+        switch self {
+        case let .screenViewed(name): return ["screen": name]
+        case let .flowStarted(flow): return ["flow": flow]
+        case let .flowCompleted(flow): return ["flow": flow]
+        case let .flowFailed(flow, reason): return ["flow": flow, "reason": reason]
+        }
+    }
+}
+
+/// The seam. Production sends to PostHog; a test captures instead.
+public protocol AnalyticsSink: Sendable {
+    func capture(_ event: AnalyticsEvent)
+}
+SWIFT
+
+cat > Sources/Observability/Observability.swift <<'SWIFT'
+import Foundation
+import PostHog
+import Sentry
+
+/// Error monitoring and analytics, started once at launch.
+///
+/// Both are configured from Info.plist rather than hardcoded, and both are
+/// skipped when their key is absent — a checkout with no credentials has to
+/// build, run and test, or nobody can work on the app without production
+/// secrets. Absent is logged, not silent: see
+/// .claude/rules/observability.orchestra.md.
+public enum Observability {
+    /// Set by the build. Release tagging is required — an error you cannot
+    /// tie to a build is an error you cannot fix.
+    public static var release: String {
+        let info = Bundle.main.infoDictionary
+        let version = info?["CFBundleShortVersionString"] as? String ?? "0"
+        let build = info?["CFBundleVersion"] as? String ?? "0"
+        return "\(version)+\(build)"
+    }
+
+    private static func setting(_ key: String) -> String? {
+        guard let value = Bundle.main.object(forInfoDictionaryKey: key) as? String,
+              !value.isEmpty,
+              // xcconfig substitutes an empty variable as the literal name.
+              !value.hasPrefix("$(")
+        else { return nil }
+        return value
+    }
+
+    public static func start() {
+        if let dsn = setting("SentryDSN") {
+            SentrySDK.start { options in
+                options.dsn = dsn
+                options.releaseName = release
+                options.environment = setting("AppEnvironment") ?? "development"
+                // Scrub before send, not after. A crash report is not a place
+                // for anything the user typed.
+                options.beforeSend = { event in
+                    event.user?.email = nil
+                    event.user?.username = nil
+                    event.user?.ipAddress = nil
+                    return event
+                }
+            }
+        } else {
+            print("[observability] no SentryDSN in Info.plist — crash reporting is off")
+        }
+
+        if let key = setting("PostHogAPIKey") {
+            let config = PostHogConfig(projectToken: key, host: setting("PostHogHost") ?? "https://eu.i.posthog.com")
+            // Identify with a stable anonymous id; never with an email.
+            config.personProfiles = .identifiedOnly
+            PostHogSDK.shared.setup(config)
+        } else {
+            print("[observability] no PostHogAPIKey in Info.plist — analytics is off")
+        }
+    }
+}
+
+/// Sends to PostHog when it is configured, and nowhere when it is not.
+public struct PostHogSink: AnalyticsSink {
+    public init() {}
+    public func capture(_ event: AnalyticsEvent) {
+        PostHogSDK.shared.capture(event.name, properties: event.properties)
+    }
+}
+SWIFT
+
+cat > Tests/ObservabilityTests/EventsTests.swift <<'SWIFT'
+import XCTest
+@testable import __NAME__
+
+/// Instrumentation is code, so it is tested like code.
+///
+/// The sink is the seam: this drives the real event type through a capturing
+/// implementation, so a renamed case or a changed payload fails here rather
+/// than in a dashboard three weeks later.
+final class CapturingSink: AnalyticsSink, @unchecked Sendable {
+    private(set) var captured: [AnalyticsEvent] = []
+    func capture(_ event: AnalyticsEvent) { captured.append(event) }
+}
+
+final class EventsTests: XCTestCase {
+    func testScreenViewFiresOnceWithTheScreenName() {
+        let sink = CapturingSink()
+        sink.capture(.screenViewed(name: "home"))
+
+        XCTAssertEqual(sink.captured.count, 1)
+        XCTAssertEqual(sink.captured.first?.name, "screen_viewed")
+        XCTAssertEqual(sink.captured.first?.properties, ["screen": "home"])
+    }
+
+    func testEveryEventNameIsObjectAction() {
+        // Boring and consistent, decided once. A mixed convention is
+        // unqueryable six months later.
+        let events: [AnalyticsEvent] = [
+            .screenViewed(name: "home"),
+            .flowStarted(flow: "signup"),
+            .flowCompleted(flow: "signup"),
+            .flowFailed(flow: "signup", reason: "network"),
+        ]
+        for event in events {
+            XCTAssertTrue(
+                event.name.contains("_"),
+                "\(event.name) is not object_action"
+            )
+            XCTAssertEqual(event.name, event.name.lowercased())
+        }
+    }
+
+    func testAFailureCarriesAReasonCode() {
+        // A funnel that only records success cannot tell you why people left,
+        // which is the only thing you actually wanted to know.
+        let event = AnalyticsEvent.flowFailed(flow: "checkout", reason: "card_declined")
+        XCTAssertEqual(event.properties["reason"], "card_declined")
+    }
+
+    func testNoEventCarriesFreeTextTheUserTyped() {
+        // Property values are identifiers, not sentences. The check is crude
+        // on purpose: a space is the cheapest signal that something typed has
+        // leaked into a property.
+        let events: [AnalyticsEvent] = [
+            .screenViewed(name: "home"),
+            .flowFailed(flow: "checkout", reason: "card_declined"),
+        ]
+        for event in events {
+            for (key, value) in event.properties {
+                XCTAssertFalse(value.contains(" "), "\(key) looks like free text: \(value)")
+            }
+        }
+    }
+}
+SWIFT
+sed -i.bak "s/__NAME__/${NAME}/" Tests/ObservabilityTests/EventsTests.swift
+rm -f Tests/ObservabilityTests/EventsTests.swift.bak
+
+cat > Sources/DesignSystem/Tokens.swift <<'SWIFT'
+import SwiftUI
+
+/// Design tokens. Populated from the Claude Design source before any
+/// component is written. Color is one axis of several — do not stop there.
+public enum Tokens {
+    public enum Spacing {
+        public static let gutter: CGFloat = 16
+    }
+    public enum Radius {
+        public static let control: CGFloat = 8
+        public static let surface: CGFloat = 12
+    }
+    public enum Motion {
+        public static let fast: Double = 0.12
+    }
+}
+SWIFT
+
+cat > Tests/DesignSystemTests/TokensTests.swift <<SWIFT
+import XCTest
+@testable import ${NAME}
+
+final class TokensTests: XCTestCase {
+    func testSpacingScaleIsPositive() {
+        XCTAssertGreaterThan(Tokens.Spacing.gutter, 0)
+    }
+
+    func testControlRadiusIsSmallerThanSurface() {
+        XCTAssertLessThan(Tokens.Radius.control, Tokens.Radius.surface)
+    }
+}
+SWIFT
+
+# The highest-value single check on iOS: the app launches.
+#
+# No XCTest sees a missing Info.plist key, an entitlement the profile lacks,
+# a @main that throws before the first view, or a resource that was never
+# copied. The unit suite is green and the app dies on the splash screen.
+cat > UITests/LaunchTests.swift <<'SWIFT'
+import XCTest
+
+final class LaunchTests: XCTestCase {
+    override func setUp() {
+        super.setUp()
+        continueAfterFailure = false
+    }
+
+    func testAppLaunches() {
+        let app = XCUIApplication()
+        app.launch()
+
+        // Not a screenshot and not a copy match — either would need editing
+        // the day the design changes. This asserts the app reached a running
+        // state with a rendered window.
+        XCTAssertTrue(
+            app.wait(for: .runningForeground, timeout: 30),
+            "the app did not reach the foreground"
+        )
+        XCTAssertTrue(app.windows.firstMatch.exists, "no window was rendered")
+    }
+}
+SWIFT
+
+cat > .swift-format <<'JSON'
+{
+  "indentation": { "spaces": 4 },
+  "lineLength": 100
+}
+JSON
+
+cat > verify.sh <<'V'
+#!/usr/bin/env bash
+# Normalised verification gate. Orchestra runs this instead of the npm
+# commands in config.yml, because this app is not npm-based.
+set -euo pipefail
+
+proj="$(find . -maxdepth 1 -name '*.xcodeproj' | head -1)"
+[ -n "$proj" ] || { echo "no .xcodeproj here — run 'xcodegen generate' first" >&2; exit 1; }
+SCHEME="${SCHEME:-$(basename "$proj" .xcodeproj)}"
+DEST="${DEST:-generic/platform=iOS Simulator}"
+
+echo "── build"
+xcodebuild build -scheme "$SCHEME" -destination "$DEST" -quiet
+
+echo "── test"
+# Resolve a concrete simulator by UDID. Grepping the human-readable device
+# list yields names with trailing whitespace, which xcodebuild rejects with
+# "Unable to find a device matching the provided destination specifier".
+if [ -n "${SIM_UDID:-}" ]; then
+  udid="$SIM_UDID"
+else
+  udid="$(xcrun simctl list devices available -j | node -e '
+    let s = "";
+    process.stdin.on("data", (d) => (s += d)).on("end", () => {
+      const j = JSON.parse(s);
+      const all = Object.values(j.devices).flat()
+        .filter((d) => d.isAvailable && /^iPhone/.test(d.name));
+      process.stdout.write(all[0] ? all[0].udid : "");
+    });
+  ')"
+fi
+[ -n "$udid" ] || { echo "no iPhone simulator available — set SIM_UDID" >&2; exit 1; }
+xcodebuild test -scheme "$SCHEME" -destination "id=$udid" -quiet
+
+echo "── format"
+if command -v swift-format >/dev/null 2>&1; then
+  swift-format lint -r Sources Tests
+else
+  echo "swift-format not installed — skipped"
+fi
+V
+chmod +x verify.sh
+
+xcodegen generate
+
+log "mobile-ios-native ready in $DIR"
+warn "verification runs through ./verify.sh, not npm — config.yml reflects that"

package/template/.orchestra/stacks/mobile-ios-native/stack.md

@@ -0,0 +1,130 @@
+# Mobile — Native iOS (Swift)
+
+## Who you are
+
+You are a **senior native iOS engineer**. Not a web developer writing
+Swift. You know the platform's conventions and you follow them, because an
+app that ignores them feels wrong to users in ways they cannot name.
+
+You think in value types, you understand the main actor, and you treat
+retain cycles and unstructured concurrency as bugs you catch yourself —
+not things review finds for you.
+
+SOLID, KISS, YAGNI. No overengineering: no protocol with one conformer, no
+coordinator for two screens.
+
+## Project generation
+
+The Xcode project is **generated from `project.yml` by XcodeGen**. Never
+hand-edit a `.pbxproj`.
+
+This is not a style preference. A binary project file cannot be reviewed in
+a diff, and it corrupts when two changes land at once — both fatal when
+agents are doing the editing. If the project needs a new target or setting,
+edit `project.yml` and regenerate.
+
+## Structure
+
+```
+Sources/
+├── App/                    # features, screens, navigation
+└── DesignSystem/           # the UI kit. no business logic. ever.
+    ├── Tokens.swift
+    └── Button/
+        ├── Button.swift
+        └── ButtonStyle.swift
+Tests/
+├── AppTests/
+└── DesignSystemTests/
+```
+
+Every component gets its own folder under `DesignSystem/`, mirroring the
+web and Expo stacks — one mental model across the repo.
+
+`DesignSystem/` contains nothing that is not design. A view may hold logic
+about itself; never about your product.
+
+## Order of work
+
+Tokens before components. Extract every axis from the design source —
+color, spacing, typography, radii, shadows, motion — into `Tokens.swift`
+and the asset catalog. Semantic colors resolve per theme; views reference
+`Color.surface`, never a raw hex or palette entry.
+
+A view with a hardcoded `Color(hex:)` or `padding(13)` is a bug.
+
+## No ready-made components
+
+The kit is built from SwiftUI primitives. No third-party UI package.
+
+SwiftUI is the platform, the way UIKit was — it is the substrate, not a UI
+kit. Wrapping its primitives in our own `DesignSystem` components is the
+job; adopting an outside component library is not.
+
+## Swift rules
+
+- Value types by default. Reach for a class when identity or reference
+  semantics are genuinely required.
+- Strict concurrency is on. Fix the warnings; do not silence them with
+  `@unchecked Sendable`.
+- UI work on the main actor, explicitly.
+- No force unwrap and no `try!` outside tests. Model absence honestly.
+- `weak self` in escaping closures that capture self.
+
+## Memory — ARC does not collect cycles
+
+There is no tracing collector here. A reference cycle is never freed, and
+nothing warns you. So:
+
+- A closure stored by an object — a handler, a callback, a Combine sink —
+  captures `self` weakly. The rule above, applied wherever the closure
+  outlives the call.
+- Delegates and parent references are `weak`. The child never owns the
+  parent.
+- A `Task` stored in a property is cancelled in `deinit`. A detached task
+  that captures `self` strongly keeps the object alive until the task ends.
+- Combine subscriptions live in a `Set<AnyCancellable>` owned by the
+  subscriber, so they end when it does.
+- **Every view model has a `deinit` test**: create it, hold it weakly,
+  release the strong reference, assert nil. It is five lines, and it is the
+  only thing that catches a cycle before a user does.
+- Instruments' Leaks and the memory graph debugger before a release — a
+  simulator run with the debugger attached, not an audit from reading.
+
+## SwiftUI
+
+- Small views. A body longer than a screen wants decomposing.
+- State at the lowest level that can own it.
+- `@Observable` over `ObservableObject` on modern deployment targets.
+- Do not fight the framework with `GeometryReader` where a layout modifier
+  exists.
+
+## Testing
+
+Coverage target is effectively total. The deciding rule:
+
+> If one of our functions calls into a third-party library, that function
+> has a test. When a dependency updates and behavior changes, the test
+> must fail.
+
+- XCTest for logic. Snapshot tests (`swift-snapshot-testing`) for views.
+- Snapshots catch visual drift and nothing else. Behavior needs its own
+  tests — a snapshot passes while a button stops responding.
+- Test both light and dark, and the largest Dynamic Type size.
+
+## Accessibility
+
+Structural. Every interactive view has a label, a trait, and a value where
+one applies. VoiceOver navigation must be sensible in order, not just
+present. Dynamic Type must not break layout. Minimum touch target 44×44pt.
+
+## Tooling
+
+`swift-format` with the checked-in configuration. Verification runs through
+`xcodebuild`, not npm — `.orchestra/config.yml` reflects that.
+
+## Toolchain
+
+Xcode and XcodeGen (`brew install xcodegen`). The scaffold builds and tests
+as generated — `./verify.sh` runs build, test on a simulator, and format.
+Verified against a real simulator run.

package/template/.orchestra/stacks/web-nextjs/claude/commands/component.md

@@ -0,0 +1,12 @@
+Scaffold a new design system component.
+
+Usage: `/web:component {Name}`
+
+1. Load the `design-component` skill and follow it exactly.
+2. Confirm every value the component needs has a token. If one is missing,
+   add it to `src/design/tokens.css` first — do not hardcode.
+3. Create `src/design/{Name}/` with the component, types, tests, fixture,
+   and `index.ts`.
+4. Export it from `src/design/index.ts`.
+5. Run `npm run typecheck && npm test && npm run lint`.
+6. Report the a11y checklist with each item explicitly checked or flagged.