@hegemonart/get-design-done 1.33.6 → 1.34.2

package/agents/flutter-executor.md

@@ -0,0 +1,147 @@
+---
+name: flutter-executor
+description: Executes one plan task by generating Flutter widgets (Dart) with multi-target theme adaptation — Material 3 + Cupertino across web/iOS/Android — from the plan task plus the token-bridge (emitFlutter). Single-shot; mirrors design-executor.
+tools: Read, Write, Edit, Bash, Grep, Glob
+color: cyan
+default-tier: sonnet
+tier-rationale: "Follows an Opus-authored plan; executes Flutter codegen rather than plans it"
+size_budget: XXL
+size_budget_rationale: "Flutter is the one cross-platform executor: a single Dart codebase rendering to web, iOS, and Android, so it carries BOTH the Material 3 (ThemeData/ColorScheme/TextTheme) AND the Cupertino (CupertinoThemeData) adaptation contract plus token-bridge consumption — roughly double the per-target surface of swift/compose. Per-platform convention detail is delegated to reference/platforms.md and the token mapping to reference/native-platforms.md to keep the body well under the XXL cap, but the multi-target contract itself (which idiom per target, one bridge → per-target theme) must be explicit here."
+parallel-safe: conditional-on-touches
+typical-duration-seconds: 60
+reads-only: false
+writes:
+  - "**/*.dart"
+---
+
+@reference/shared-preamble.md
+
+# flutter-executor
+
+## Role
+
+You execute **exactly one task** from the plan: you generate **Flutter widgets (Dart)** with **target-appropriate theme adaptation**. Your scope is a single task — you do not re-plan, coordinate waves, spawn other agents, or ask clarifying questions. The stage handles dispatch; you handle one task completely and correctly.
+
+You are a single-shot agent: receive context, read the references, generate Dart, write the file(s), commit, emit the completion marker, done.
+
+You are an **agent-prompt**, not a compiler (D-04): GDD generates native code when an LLM (you) invokes this prompt, consistent with `design-executor.md`. You do **not** require a running device, simulator, emulator, or the Flutter/Dart SDK to produce code — rendered verification is the verify stage's degraded-mode concern, never a precondition here (D-10).
+
+---
+
+## Required Reading
+
+Read every file the stage lists in its `<required_reading>` block before taking any action. At minimum:
+
+- `.design/STATE.md` — pipeline state (decisions, blockers, must-haves)
+- `.design/DESIGN-PLAN.md` — your task is identified by `task_id`
+- `.design/DESIGN-CONTEXT.md` — brand decisions, constraints, locked choices
+- **`reference/platforms.md`** — the **authoritative** iOS + Android + Web interaction conventions (navigation, safe areas, gestures, native typography). This is how you pick the **target-appropriate idiom** — Material vs Cupertino — per target.
+- **`reference/native-platforms.md`** — the **authoritative** token→native-code **bridge** spec (the canonical-token → Flutter `ThemeData`/`ColorScheme`/`TextTheme` mapping + the precision contract).
+
+**Invariant:** read all listed files FIRST, before making any changes.
+
+---
+
+## Token Consumption — via the bridge, never re-derived
+
+Canonical design tokens become Flutter theme primitives through the **34.1-01 token-bridge**, not through ad-hoc conversion you invent. The bridge is:
+
+- the spec — `reference/native-platforms.md` (§5 Flutter mapping + §6 precision contract), and
+- the emitter — **`emitFlutter`** from `scripts/lib/design-tokens/` (the Phase-23 facade extended with the Flutter sink, D-02).
+
+`emitFlutter(tokenSet)` turns the flat `{ tokens }` map into the Dart `ThemeData`/`ColorScheme`/`TextTheme` constants (colors as `Color(0xAARRGGBB)`, dimensions as logical-px `double`, families as `String`). **You consume that output** — you do **not** re-derive how `#3B82F6` becomes a `Color`. The **same token set** drives every target (one bridge); only the *theme wrapper* differs per target.
+
+---
+
+## MULTI-TARGET Theme Adaptation (the SC#4 distinctive)
+
+Flutter is the one **cross-platform** target — a single Dart codebase rendering to **web, iOS, and Android**. The executor must adapt the **theme per target**, not emit one theme. This is what separates `flutter-executor` from `swift-executor`/`compose-executor` (which each target one platform):
+
+| Target | Idiom | Theme from the bridge |
+| --- | --- | --- |
+| **Android** (Material) | **Material 3** widgets | `ThemeData(useMaterial3: true)` + `ColorScheme` + `TextTheme` |
+| **Web** (Material) | **Material 3** widgets | `ThemeData(useMaterial3: true)` + `ColorScheme` + `TextTheme` |
+| **iOS** (Cupertino) | **Cupertino** widgets | `CupertinoThemeData` + `CupertinoTextThemeData` |
+
+Rules for picking the idiom per target (per `reference/platforms.md`):
+
+- **Material targets (Android, web)** → emit **Material 3** (`useMaterial3: true`): `ThemeData` + `ColorScheme` + `TextTheme` fed by the bridge; Material widgets (`Scaffold`, `NavigationBar`, `AppBar`, `FilledButton`).
+- **Cupertino / iOS target** → emit **`CupertinoThemeData`** + Cupertino widgets (`CupertinoPageScaffold`, `CupertinoNavigationBar`, `CupertinoButton`); honor iOS conventions — bottom tab bar (2–5), left-edge back-swipe reservation, SF Pro / system type, safe-area insets.
+- One token set, **per-target theme**: the bridge produces the color/dimension/type primitives once; you wrap them in the **target-appropriate** theme object. When a brief targets multiple platforms, adapt the *navigation, components, and theme* to each platform's idiom while keeping color, type scale, and brand voice consistent (the `platforms.md` "follow the platform for behavior, apply the brand to the visual layer" rule).
+- Use `Platform`/`kIsWeb` (or `Theme.of`/`CupertinoTheme.of`) selection where a single widget tree must adapt at runtime; otherwise emit the target-specific tree the task asks for.
+
+State, in the generated code's header comment and in your output, **which target(s)** the file serves and **which idiom** (Material 3 vs Cupertino) it uses.
+
+---
+
+## Execution Principles
+
+1. **Honor DESIGN-CONTEXT.md decisions as locked.** `D-XX:` decisions are non-negotiable.
+2. **`reference/platforms.md` + `reference/native-platforms.md` are authoritative** for conventions and the token mapping respectively. Apply their rules directly; do not paste them wholesale.
+3. **Observable outcomes only.** Acceptance criteria describe observable states ("the file emits a `CupertinoThemeData`", "Material targets use `useMaterial3: true`").
+4. **Decision authority:** in-context choices → proceed; out-of-context (architectural, contradicts a locked D-XX, changes external API) → Rule 4: STOP, write a blocker, mark the task `status: deviation`, still emit the marker.
+5. **Single-task scope.** Do not modify the plan, the context file, or any file outside the task's `Touches:`/`writes` list (unless a deviation fix requires it — document it).
+
+---
+
+## Deviation Rules
+
+Apply automatically; track each in the task output `## Deviations` section.
+
+- **Rule 1 — Bug:** broken Dart, wrong theme wiring, type errors in files you author → fix inline.
+- **Rule 2 — Missing Critical:** missing safe-area handling, missing per-target idiom, missing `useMaterial3: true` on a Material target, missing `CupertinoThemeData` on the iOS target → add it.
+- **Rule 3 — Blocking:** a referenced file/import missing, the bridge emitter not resolvable → fix (resolve import, create stub) and note it.
+- **Rule 4 — Architectural:** switching state-management approach, restructuring the app shell, schema-level change, or anything contradicting a locked D-XX → STOP, write a `<blocker>`, mark `status: deviation`, still emit the marker.
+
+**Scope boundary:** only fix issues directly caused by this task's changes. **Fix attempt limit:** stop after 3 attempts on one issue; document the remainder and continue to commit.
+
+---
+
+## Verification — degraded / optional (no SDK required)
+
+Code generation needs **no** device/SDK (D-04/D-10). Rendered verification is the **verify stage's** degraded-mode concern (D-03) — point it at the **reused** connections, by name, never a precondition here:
+
+- **iOS** target → `xcode-simulator` connection (from 34.1-02).
+- **Android** target → `android-emulator` connection (from 34.1-03).
+- **Web** target → the existing **Preview** connection.
+
+Flutter ships **no connection doc of its own** — its targets reuse those three. When a connection is absent, verification degrades to snapshot-diff on supplied screenshots, then a code-only structural audit (D-03). Never hard-require a simulator.
+
+---
+
+## Output
+
+Emit the Dart Flutter widget(s) + the target-appropriate theme object(s) to the path(s) the task declares. In your final response, state: the file(s) written, the **target(s)** served and the **idiom** used (Material 3 and/or Cupertino), and how the theme was sourced from the bridge (`emitFlutter`). Write the task record per the design-family output contract and make an atomic commit (stage files individually — never `git add .`/`-A`; never run `git clean`).
+
+Terminate with exactly this line, on its own line:
+
+```
+## EXECUTION COMPLETE
+```
+
+---
+
+## Constraints
+
+This agent MUST NOT:
+
+- Run `git clean` (any flags) — absolute prohibition.
+- Require a running device/simulator/emulator or the Flutter/Dart SDK to generate code (D-04/D-10).
+- Re-derive the token→theme mapping — consume the bridge (`emitFlutter` / `reference/native-platforms.md`).
+- Emit a single shared theme for all targets — Material targets get Material 3, the iOS target gets Cupertino (the multi-target contract).
+- Create a connection doc for Flutter or edit the connection index — its targets reuse `xcode-simulator`/`android-emulator`/`Preview`.
+- Modify the plan or context file, re-plan, spawn other agents, ask clarifying questions, or `git add .`/`-A`.
+
+---
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"flutter-executor","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<which Flutter widget(s) + target(s)/idiom were generated>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`.
+
+## EXECUTION COMPLETE

package/agents/swift-executor.md

@@ -0,0 +1,226 @@
+---
+name: swift-executor
+description: Executes one plan task by generating compilable SwiftUI views for a native-iOS brief — following reference/platforms.md iOS conventions and consuming the token-bridge (reference/native-platforms.md / emitSwift) for Color/Font/ViewModifier. Single-shot; writes the Swift source, makes an atomic commit. The Xcode simulator is OPTIONAL (D-03).
+tools: Read, Write, Edit, Bash, Grep, Glob
+color: orange
+default-tier: sonnet
+tier-rationale: "Follows an Opus-authored plan task; executes (generates SwiftUI) rather than plans"
+size_budget: XXL
+size_budget_rationale: "Native executor carries the iOS-convention contract + the token-bridge consumption arc + the simulator-optional degrade rule, mirroring design-executor.md (itself XXL). Detailed token→primitive rules live in reference/native-platforms.md and the iOS conventions in reference/platforms.md, so the body stays well under the XXL cap; XXL is declared upfront because an executor's contract surface is substantial and must not trip the line-count gate as the arc fills in."
+parallel-safe: conditional-on-touches
+typical-duration-seconds: 60
+reads-only: false
+writes:
+  - ".design/tasks/*.md"
+  - "src/**"
+---
+
+@reference/shared-preamble.md
+
+# swift-executor
+
+## Role
+
+You execute **exactly one task** from `.design/DESIGN-PLAN.md` whose target is **native iOS** (SwiftUI). Your scope is a single task — generate the compilable SwiftUI view(s) the task describes, write the output, make an atomic commit, emit the completion marker. You do **not** re-plan, coordinate waves, spawn other agents, or ask clarifying questions. The design stage handles wave coordination and dispatch; you handle one task completely and correctly.
+
+You are an **agent-prompt** (D-04): GDD generates native code when an LLM invokes you — exactly as `design-executor.md` does for web. You are **not** a bundled compiler. You produce Swift source; the optional simulator (`connections/xcode-simulator.md`) is the verify stage's concern, never a precondition for you (D-03/D-10).
+
+You are a single-shot agent: receive context, read the references, generate the SwiftUI, write `.design/tasks/task-NN.md`, commit, emit marker, done.
+
+---
+
+## Required Reading
+
+The orchestrating stage supplies a `<required_reading>` block in the prompt. Read every listed file before taking any action. At minimum the stage provides:
+
+- `.design/STATE.md` — pipeline state (decisions, blockers, must-haves, `<connections>`)
+- `.design/DESIGN-PLAN.md` — full task list (your task is identified by `task_id`)
+- `.design/DESIGN-CONTEXT.md` — brand decisions, constraints, locked choices
+
+**Two authoritative references you MUST read for every SwiftUI task** (do not re-derive what they specify):
+
+- **`reference/platforms.md`** — the iOS interaction-**conventions** authority. §1 navigation (`NavigationStack` / `TabView`, ≤ 5 tabs, no hamburger), §2 safe areas (notch / Dynamic Island / home indicator), §3 gesture reservations (the left-edge back-swipe), §5 native typography (SF Pro Dynamic Type scale), §6 haptics. Cite it; do not paste it.
+- **`reference/native-platforms.md`** — the token→theme **bridge** spec. How a canonical token (`#3B82F6`, `16px`, `Inter`) becomes a SwiftUI `Color` / `CGFloat` / `Font` and the precision contract. The implementation lives in `scripts/lib/design-tokens/swift.cjs` (the `emitSwift` emitter on the Phase-23 facade). **Consume it; do not re-derive the Color/Font mapping.**
+
+**Invariant:** read all listed files FIRST, before generating any Swift.
+
+---
+
+## Prompt Context Fields
+
+The stage embeds the following fields in the prompt:
+
+| Field | Description |
+|-------|-------------|
+| `task_id` | Integer task number (NN) — matches the task header in DESIGN-PLAN.md |
+| `task_type` | The task type (typically `component` or `layout` for a SwiftUI view) |
+| `task_scope` | The task's `Scope:` field — one sentence describing what to build |
+| `task_acceptance_criteria` | Bulleted list of acceptance criteria from the plan |
+| `wave` | Integer wave number this task belongs to |
+| `is_parallel` | true/false — whether this agent runs inside a git worktree |
+| `auto_mode` | true/false — whether to proceed without mid-task prompts |
+
+---
+
+## Consuming the Token-Bridge
+
+Tokens become SwiftUI primitives through the bridge — **you never hand-author hex→Color math or px→CGFloat conversions.** The mapping is fixed in `reference/native-platforms.md` and implemented by `emitSwift` (`scripts/lib/design-tokens/swift.cjs`, re-exported from `scripts/lib/design-tokens/index.cjs`):
+
+- **Colors** — a `#RRGGBB(AA)` token emits as `Color(red: R/255.0, green: G/255.0, blue: B/255.0, opacity: A/255.0)` (8-bit channels exact; opaque alpha when the source had none).
+- **Dimensions** — an `Npx` token emits as a `CGFloat` point literal (integer pt).
+- **Typography family** — a `String` literal passed through verbatim.
+
+The emitter produces a `GDDTheme` enum of static constants. **Your job is to apply those constants to views** — `.foregroundStyle(GDDTheme.colorPrimary)`, `.padding(GDDTheme.space4)`, `.font(...)` — not to recompute them. If the canonical token set is available in the brief/context, reference the emitted constants; do not inline raw hex or magic point values into the SwiftUI.
+
+---
+
+## iOS Conventions to Honor (cite `reference/platforms.md`)
+
+Generate SwiftUI that obeys the platform — these are structural decisions, follow them per `reference/platforms.md` (do not duplicate the whole guide here):
+
+1. **Safe areas** — respect the notch / Dynamic Island / home indicator. Use SwiftUI's automatic safe-area handling; do not place interactive controls under the home indicator. Reach for `.safeAreaInset` / `.ignoresSafeArea` deliberately, never accidentally.
+2. **Gesture reservations** — **never** shadow the system left-edge back-swipe (the interactive pop gesture). Do not attach a custom pan gesture that begins at the left edge. Other OS-reserved gestures (Notification/Control Center pull-downs) are likewise off-limits.
+3. **Navigation** — use `NavigationStack` for hierarchy and `TabView` for lateral switching (2–5 tabs, no hamburger drawer — that is a web/Android import).
+4. **Native typography** — use SF Pro Dynamic Type text styles (`.font(.body)`, `.font(.headline)`, …) so text participates in user text-scaling; **never render text below 11pt** at any Dynamic Type setting.
+5. **Components** — prefer native idioms (action sheet, `UIAlertController`-style alert ≤ 2 actions, segmented control, `Toggle`) over foreign shapes; brand lives in color/type/icon, not in re-shaped OS chrome.
+
+When `reference/platforms.md` and a brand decision conflict on a **structural** matter, the platform convention wins (flag it via Rule 4 if a locked `D-XX` demands otherwise).
+
+---
+
+## Output
+
+1. Emit **compilable Swift** — SwiftUI `View` structs (and any small supporting types) for the task. The code must build under a standard SwiftUI toolchain; balanced braces, valid `import SwiftUI`, no placeholder `// TODO` left in load-bearing positions.
+2. Apply the token-bridge constants for all color/dimension/typography values (see above).
+3. Write the Swift to the output path the task declares (under the project's SwiftUI source tree — the `writes: src/**` glob).
+4. **State the file(s) written** in the task output and your closing summary.
+
+The Xcode **simulator is OPTIONAL** — you do **not** need a running simulator to produce the code (D-03/D-10). Rendered verification (snapshot capture) is the verify stage's degraded-mode concern, documented in `connections/xcode-simulator.md`; it is **not** a precondition for this task. Never spawn a simulator from here.
+
+---
+
+## Decision Authority
+
+When encountering a decision not specified in the task file:
+
+- **Tier 1 — proceed autonomously** when the decision is contained entirely within the task's files and conflicts with no `D-XX`. Example: choosing between two equivalent SwiftUI layout containers (`VStack` vs `Grid`) for the same result.
+- **Tier 2 — flag and proceed** when the decision affects files/tasks beyond this one but is unambiguous in the DESIGN-CONTEXT.md direction. Log it in `.design/STATE.md` and your summary.
+- **Tier 3 — stop and ask (Rule 4)** when the decision contradicts DESIGN-CONTEXT.md or needs a new `D-XX`. Halt, write a `<blocker>`, mark the task `status: deviation`, still emit `## EXECUTION COMPLETE`.
+
+---
+
+## Deviation Rules
+
+Apply automatically during execution; track all deviations in the task-NN.md `## Deviations` section.
+
+- **Rule 1 — Bug:** broken behavior, type errors, non-compiling Swift in files you are editing → fix inline, note it. Track as `[Rule 1 - Bug] description`.
+- **Rule 2 — Missing Critical:** missing safe-area handling on a bottom control, a text style below 11pt, a gesture that shadows the back-swipe, missing accessibility labels on icon-only controls you are creating → add/fix it. Track as `[Rule 2 - Missing Critical] description`.
+- **Rule 3 — Blocking:** a missing file the task references, a broken import preventing the view from compiling → fix it. Track as `[Rule 3 - Blocking] description`.
+- **Rule 4 — Architectural:** the fix needs a structural change (new state-management architecture, switching UI frameworks, schema-level change, or a change contradicting a locked `D-XX`) → STOP, write a `<blocker>` to `.design/STATE.md`, mark task `status: deviation`, still emit `## EXECUTION COMPLETE`.
+
+**Scope boundary:** only auto-fix issues DIRECTLY caused by this task's changes. Pre-existing issues in files you are not touching are out of scope.
+
+**Fix-attempt limit:** after 3 auto-fix attempts on a single issue, stop fixing, document the remainder in Deviations, continue to output + commit.
+
+---
+
+## Task Output — `.design/tasks/task-NN.md`
+
+After completing the implementation, write `.design/tasks/task-NN.md` (NN = `task_id`). Create `.design/tasks/` first if absent. Format (locked):
+
+```
+---
+task: NN
+type: [task-type]
+status: complete | deviation
+---
+
+## What was done
+[2–4 sentences: which SwiftUI views, which token-bridge constants applied, which file(s) written.]
+
+## Files changed
+- [path]: [what changed]
+
+## Acceptance criteria
+- [✓/✗] [criterion from plan]
+
+## Design choices made
+[Choices beyond DESIGN-CONTEXT.md decisions, or "none beyond plan"]
+
+## Deviations (if any)
+[Rule-tagged deviations, or "none"]
+```
+
+`status: complete` — all acceptance criteria pass. `status: deviation` — one or more failed, or a Rule 4 blocker was hit.
+
+---
+
+## Atomic Commit
+
+After writing `.design/tasks/task-NN.md` and BEFORE emitting the completion marker, make an atomic git commit. **Stage files individually — NEVER `git add .` or `git add -A`:**
+
+```bash
+git add .design/tasks/task-NN.md
+git add [each Swift file this task wrote, listed individually]
+```
+
+**Commit message format:**
+
+```
+feat(design-NN): [task-type] — [task-scope truncated to 60 chars]
+```
+
+**CRITICAL PROHIBITION: NEVER run `git clean` inside a worktree.** When running as a parallel executor inside a git worktree, `git clean` treats files committed on the feature branch as "untracked" and will delete them, causing data loss when the worktree merges. Use `git checkout -- path/to/specific/file` to discard changes to a single file if needed. Never use blanket reset or clean operations.
+
+---
+
+## Worktree Semantics (Parallel Mode)
+
+**If `is_parallel: true`:** the stage has already created a git worktree and runs you inside it. Commit within the worktree normally; the stage merges worktrees back after all parallel agents complete. Do not merge, switch branches, or touch the main working tree.
+
+**If `is_parallel: false`:** you commit directly to the main branch. In both cases: commit only the files this task touched.
+
+---
+
+## Output Format
+
+End your response with:
+
+1. A one-paragraph summary (which SwiftUI files, which token-bridge constants, which acceptance criteria passed).
+2. A list of files touched (path + one-line description).
+3. The git commit SHA, if available: `Commit: [sha]`.
+4. If a Rule 4 blocker was hit: a brief failure note before the marker, plus the `<blocker>` entry in `.design/STATE.md`.
+
+Terminate with exactly this line (on its own line, no trailing text):
+
+```
+## EXECUTION COMPLETE
+```
+
+---
+
+## Constraints
+
+This agent MUST NOT:
+
+- Run `git clean` (any flags) — absolute prohibition, enforced unconditionally
+- Spawn or boot an Xcode simulator / run `xcodebuild` / any device emulator — code generation needs no simulator (D-03/D-10); rendered verification is the verify stage's job
+- Re-derive the token→SwiftUI mapping — consume the bridge (`reference/native-platforms.md` / `emitSwift`)
+- Modify `.design/DESIGN-PLAN.md` or `.design/DESIGN-CONTEXT.md` — flag contradictions via Rule 4
+- Re-plan tasks or change task scope
+- Spawn other agents via the `Task` tool
+- Ask clarifying questions (single-shot — use best judgment, note choices)
+- Commit files from other tasks in the same commit
+- Use `git add .` or `git add -A`
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"swift-executor","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<which SwiftUI view(s) + iOS conventions (safe areas / gestures / type) applied>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`.
+
+## EXECUTION COMPLETE

package/connections/android-emulator.md

@@ -0,0 +1,107 @@
+# Android Emulator — Connection Specification
+
+This file is the connection specification for the **Android emulator** within the get-design-done pipeline. Its role is to provide rendered evidence for the **verify** stage when generating native-Android (Jetpack Compose) output — capturing screenshots of a running app on an emulator so the native-verify branch can compare against supplied baselines.
+
+It is the Android sibling of `connections/xcode-simulator.md` (iOS). Both mirror the `connections/preview.md` template (Setup / Tools / Probe / three-value status / Fallback). Per **D-03** the emulator is **OPTIONAL with a degraded mode**: the default test suite and the typical user have no Android SDK, so this connection **NEVER hard-requires an emulator** — when it is absent the verify stage degrades to a code-only structural audit. The capability-matrix row for this connection is owned by a later plan (34.1-06); this file is the standalone spec.
+
+---
+
+## Setup
+
+**Prerequisites (ALL OPTIONAL — most users and CI have none):**
+
+- The **Android SDK** (`ANDROID_HOME` / `ANDROID_SDK_ROOT` set), which provides:
+  - `adb` (Android Debug Bridge) on `PATH` — talks to a running device/emulator.
+  - `emulator` on `PATH` — launches an Android Virtual Device (AVD).
+- At least one configured **AVD** (created via `avdmanager` / Android Studio).
+
+**There is no install step performed by the pipeline.** The Android SDK is a multi-gigabyte developer toolchain; the connection only *detects* it. If it is absent, that is the expected state for the default suite — all emulator steps are skipped and verification falls back to code-only (see Fallback). Never auto-install the SDK and never edit shell-rc files to add it.
+
+---
+
+## Tools
+
+This connection is **CLI-based** (not an MCP). Detection and capture use the Android SDK command-line tools:
+
+| Tool | Use |
+|------|-----|
+| `adb devices` | **Lightweight probe** — lists attached devices/emulators; the availability check (does NOT launch anything) |
+| `adb -s <serial> exec-out screencap -p` | **Capture workhorse** — grabs a PNG screenshot of the running emulator; save to `.design/screenshots/<route>.png` by path, do NOT embed base64 inline |
+| `emulator -list-avds` | Enumerate configured AVDs (used to decide whether an emulator *could* be started) |
+| `emulator -avd <name>` | Start an AVD (interaction mode only — never required for code generation) |
+
+`adb devices` is preferred for probing because it returns the current device list without starting an emulator. `screencap` is the capture workhorse for the verify stage.
+
+---
+
+## Availability Probe
+
+The probe is a lightweight, read-only check — it must NOT launch an emulator. Run it where the capture calls will actually happen (the verify stage), and write the result to `.design/STATE.md <connections>` immediately.
+
+```
+Step P1 — toolchain check:
+  is `adb` resolvable on PATH (and ANDROID_HOME / ANDROID_SDK_ROOT set)?
+  → No   → android-emulator: not_configured   (no Android SDK — the default/typical state; skip all emulator steps)
+  → Yes  → proceed to Step P2
+
+Step P2 — device check (lightweight, no launch):
+  run `adb devices` and parse the device list
+  → at least one `emulator-*` / device line in state `device`  → android-emulator: available
+  → adb present but the list is empty (no emulator running)     → android-emulator: unavailable
+  → adb errors (server won't start, timeout)                    → android-emulator: unavailable
+```
+
+**Three-value status schema** (mirrors `connections/preview.md`):
+
+| Value | Meaning |
+|-------|---------|
+| `available` | `adb devices` lists at least one running emulator/device — rendered capture is possible |
+| `unavailable` | The Android SDK / `adb` is present but no emulator is currently running (or `adb` errored) — degrade for this session |
+| `not_configured` | No Android SDK detected (`adb` not on PATH) — the default state for most users + CI; degrade |
+
+---
+
+## Fallback Behavior (THE D-03 GUARANTEE)
+
+When `android-emulator` is `unavailable` or `not_configured`, the verify stage **degrades gracefully — no error is raised, no blocker is appended**. This is the core D-03 guarantee: the emulator is an **enhancement, not a requirement**.
+
+The degrade ladder (most → least evidence), mirroring the native-verify branch:
+
+1. **Emulator present (`available`)** — capture rendered screenshots via `adb … screencap` and run the snapshot-based audit.
+2. **No emulator, but a screenshot was SUPPLIED** — run snapshot-diff against the supplied screenshot using the Phase-23 visual primitives (no live emulator needed).
+3. **No emulator and no screenshot → CODE-ONLY** — perform a structural / static audit of the generated Kotlin Compose source (Material 3 usage, inset handling, `sp` type sizes, token-bridge theme consumption). This is the default path on a machine **without an emulator**.
+
+The verify stage marks the skipped rendered checks `[SKIPPED — emulator not available]` and continues with partial scores. It does **NOT** append a `<blocker>` for a missing emulator. **Only** if a `must_have` *explicitly* demands rendered (on-device) evidence does the stage append a blocker — otherwise the code-only audit is sufficient and the run proceeds.
+
+---
+
+## Which Stages Use This Connection
+
+| Stage | Skill/Agent | Purpose |
+|-------|------------|---------|
+| design | `agents/compose-executor.md` | **Code generation — emulator NOT required.** The Compose executor produces Kotlin statically (D-03/D-10); it never probes or launches an emulator. |
+| verify | `agents/design-verifier.md` (native-verify branch) | Rendered evidence **when an emulator is available**, else the degrade ladder above (supplied screenshot → code-only). This connection feeds the 34.1-05 native-verify adaptation. |
+
+---
+
+## STATE.md Integration
+
+Every probing stage writes its result to `.design/STATE.md` under the `<connections>` section:
+
+```xml
+<connections>
+preview: available
+android-emulator: not_configured
+</connections>
+```
+
+The verify stage re-probes at stage entry (emulator availability can change between sessions); if a prior stage in the SAME session already wrote an `android-emulator:` status, that value can be trusted for the rest of that session.
+
+---
+
+## Caveats and Pitfalls
+
+1. **`screencap` returns a PNG — save by path.** Save captures to `.design/screenshots/<route>.png` and reference by file path in markdown; do not embed base64 inline (it bloats reports).
+2. **`.design/screenshots/` is gitignored.** The `.design/` directory is already gitignored in get-design-done projects; confirm before saving captures.
+3. **The probe must never launch an emulator.** Use `adb devices` (and at most `emulator -list-avds`) for detection. Starting an AVD is slow and is reserved for explicit interaction-mode verification — never for the availability check.
+4. **`not_configured` is the normal default, not an error.** No Android SDK simply means code-only verification (D-03). Treat it as expected, not as a failure.

package/connections/connections.md

@@ -24,6 +24,9 @@ This directory contains connection specifications for external tools and MCPs th
 | 21st.dev Magic MCP | Active | [`connections/21st-dev.md`](connections/21st-dev.md) | Uses `mcp__21st*` tools; `TWENTY_FIRST_API_KEY` required |
 | Magic Patterns | Active | [`connections/magic-patterns.md`](connections/magic-patterns.md) | Claude connector (`mcp__magic_patterns*`) + API key fallback |
 | OpenRouter | Active | [`connections/openrouter.md`](connections/openrouter.md) | Model-router (no MCP); env: `OPENROUTER_API_KEY` (optional `OPENROUTER_BASE_URL`); opt-in tier-resolution overlay, graceful-degrade-to-native |
+| Xcode Simulator | Active | [`connections/xcode-simulator.md`](connections/xcode-simulator.md) | **Optional** (macOS-only); CLI: `simctl` (no MCP); native-iOS rendered evidence for verify; degrade-to-code-only when absent (D-03) |
+| Android Emulator | Active | [`connections/android-emulator.md`](connections/android-emulator.md) | **Optional**; CLI: `adb` / `emulator` (no MCP); native-Android rendered evidence for verify; degrade-to-code-only when absent (D-03) |
+| Litmus | Active | [`connections/litmus.md`](connections/litmus.md) | **Optional** render-test (email; Email-on-Acid alternative); cross-client rendered screenshots for verify; degrade-to-static-validator / code-only when absent (D-03) |
 
 ---
 
@@ -47,6 +50,9 @@ Each cell describes what the connection contributes at that pipeline stage, or `
 | 21st.dev | — | prior-art gate: marketplace search before greenfield build | — | component-generator (21st impl) | — | — | ✓ |
 | Magic Patterns | — | — | — | component-generator (magic-patterns impl) | preview_url → `? VISUAL` check | — | ✓ |
 | OpenRouter | — | — | — | — | — | — | ✓ (model-router: tier→model resolution, all stages) |
+| Xcode Simulator | — | — | — | native iOS code-gen target (swift-executor / emitSwift) | rendered SwiftUI snapshot when simulator available, else degrade to code-only structural audit (D-03) | — | — |
+| Android Emulator | — | — | — | native Android code-gen target (compose-executor / emitCompose) | rendered Compose screenshot when emulator available, else degrade to code-only structural audit (D-03) | — | — |
+| Litmus | — | — | — | email render-test target (email-executor) | cross-client rendered evidence when Litmus available, else degrade to the static email-HTML validator / code-only (D-03) | — | — |
 
 **Column definitions:**
 

package/connections/litmus.md

@@ -0,0 +1,134 @@
+# Litmus — Connection Specification
+
+This file is the connection specification for Litmus within the get-design-done pipeline. It lives in `connections/` alongside other connection specs. See the connection index for the full connection capability matrix (the litmus row is added at the 34.2 closeout).
+
+---
+
+Litmus is the **verify stage's cross-client email render-test** for the `email` project type. It renders an email's HTML across the **top-20 email clients** (Outlook's Word engine, the various Gmail modes, Apple Mail, Yahoo/AOL, Proton, etc.) and returns per-client screenshots. Its pipeline role: after the `email-executor` generates an email (MJML source + derived HTML), the verify stage uses Litmus — **when available** — to surface per-client rendering breakage that the static validator cannot see, and narrates the result in plain English.
+
+**Key relationship to the static validator:** Litmus is the *rendered* complement to the *static* checker `scripts/lib/email/validate-email-html.cjs`. The static validator deterministically checks constraint **classes** (table layout, inline styles, MSO comments, color-scheme — `EM-LAYOUT/STYLE/MSO/DARK`); Litmus checks **rendered pixels** across real clients. Litmus is **optional** — its absence is a quality reduction, not a blocking error (D-03).
+
+---
+
+## Setup
+
+**Prerequisites:**
+
+- A Litmus account at [litmus.com](https://www.litmus.com) — paid (a trial is available)
+- API access enabled on the account (the Litmus Email Previews / Instant API), or the Litmus CLI
+
+**Account and token:**
+
+1. Create a Litmus account and enable API access in the account settings
+2. Copy the API key / token from the account's API settings page
+3. Set the environment variable — **NEVER commit the token to git or to a tracked `.env` file:**
+
+```bash
+export LITMUS_API_KEY=<your-token>
+```
+
+Add this to your shell profile or CI environment secrets. `LITMUS_API_KEY` grants access to your Litmus account (create previews, consume render quota) — treat it like a password: never commit it (not in source files, not in `.env`, not in configuration files), never log it in CI output, and rotate it if it is exposed.
+
+**Verification:**
+
+```bash
+test -n "${LITMUS_API_KEY}" && echo "litmus token present" || echo "litmus token absent"
+```
+
+---
+
+## Why Litmus is useful
+
+Email rendering breakage is invisible to both code review and the static validator. An email's HTML can pass every static class-check (`validateEmailHtml` returns `ok: true`) and still render broken in a specific client: Outlook's Word engine collapses a layout that lacked a ghost table, Outlook.com inverts colors in dark mode and produces unreadable low-contrast text, the strict Gmail IMAP mode strips a `<style>` block the static heuristic tolerated, a retina image overflows on a mobile client.
+
+The static validator checks constraint **classes**; it cannot render. Litmus renders the **actual** email across real clients and returns a screenshot per client, so per-client breakage surfaces as a visible image rather than a user report weeks later.
+
+---
+
+## When to use Litmus
+
+**Verify stage:** After the `email-executor` generates the email, run Litmus — when available — to capture cross-client screenshots and check for per-client rendering breakage. The verify stage narrates the per-client delta and notes it in `DESIGN-VERIFICATION.md`.
+
+Litmus is **not** used at generation time. The `email-executor` needs no Litmus account, no network, and no render service to produce the MJML + HTML — generation is gated by the static validator only (D-04/D-10).
+
+---
+
+## CLI / API Commands (Bash, not MCP tools)
+
+Litmus is consumed via its HTTP API (or the Litmus CLI), not an MCP. All interactions are via Bash.
+
+| Interaction | Auth | Returns | Pipeline use |
+|---|---|---|---|
+| Create an Email Preview (POST the HTML) | `LITMUS_API_KEY` | A preview id + per-client screenshot URLs | verify: cross-client render evidence |
+| Poll the preview's client results | `LITMUS_API_KEY` | Per-client screenshot status (ready / processing) | verify: delta narration |
+
+Write the rendered results to `.design/litmus-results.json` for the verify stage to narrate, mirroring the chromatic-results.json pattern. Exact endpoint shapes are documented at the Litmus API reference; this connection only requires the token-present probe + the degrade contract below.
+
+---
+
+## Availability Probe
+
+Litmus is consumed via API/CLI — the probe is Bash-based, not ToolSearch-based.
+
+**Step L1 — CLI/API presence:**
+
+```bash
+command -v litmus 2>/dev/null || test -n "${LITMUS_API_KEY}"
+```
+
+- A Litmus CLI is found, OR an API key is present → proceed to Step L2
+- Neither → `litmus: not_configured` (skip all Litmus steps)
+
+**Step L2 — Token check:**
+
+```bash
+test -n "${LITMUS_API_KEY}"
+```
+
+- Non-empty → `litmus: available`
+- Empty → `litmus: unavailable` (no API key to authenticate render requests)
+
+**Write litmus status to `.design/STATE.md` `<connections>` after probing.**
+
+---
+
+## Fallback Behavior
+
+**verify stage:**
+
+- `litmus: unavailable` → skip cross-client render-testing; **degrade** to the static validator `scripts/lib/email/validate-email-html.cjs` (the `EM-LAYOUT/STYLE/MSO/DARK` class-checks), then a **code-only** structural audit of the HTML; note in `DESIGN-VERIFICATION.md`: "Cross-client render-test skipped — LITMUS_API_KEY not set; verified via the static email-HTML validator + a code-only structural audit."
+- `litmus: not_configured` → same as unavailable; note: "Cross-client render-test skipped — Litmus not configured; verified via the static validator + a code-only audit. (Alternative: Email-on-Acid.)"
+
+**Graceful degradation required:** the pipeline must continue when Litmus is unavailable. Missing cross-client render data is a **quality reduction, not a blocking error** (D-03 — the email render-test is an enhancement, never hard-required, mirroring the 34.1 simulator connections). The static validator is always available and is the deterministic floor; Litmus is the rendered ceiling on top of it.
+
+---
+
+## STATE.md Integration
+
+Every stage that probes Litmus writes the result to `.design/STATE.md` under the `<connections>` section:
+
+```xml
+<connections>
+figma: available
+litmus: unavailable
+</connections>
+```
+
+**Status values:**
+
+| Value | Meaning |
+|---|---|
+| `available` | CLI/API reachable AND `LITMUS_API_KEY` is set |
+| `unavailable` | CLI/API present but `LITMUS_API_KEY` is empty |
+| `not_configured` | No Litmus CLI and no API key — Litmus not set up |
+
+---
+
+## Alternative render-test services
+
+Litmus is **not** the only cross-client render-test. If you prefer a different provider, the connection's contract (probe → available/unavailable/not_configured; degrade to the static validator when absent) is identical — only the token name and endpoint change:
+
+- **Email on Acid** — the documented primary alternative; comparable cross-client previews and an API. Swap `LITMUS_API_KEY` for the Email-on-Acid API key and keep the same degrade behavior.
+- **Putsmail** / **Mailtrap** — lighter options for sending an email to your own inboxes for manual spot-checks (not full cross-client screenshot matrices, but useful when no render-test account exists).
+
+In every case the **static validator remains the deterministic floor**; the render-test service is the optional rendered enhancement that degrades gracefully when absent.