Context

SkyTwin v0.3 shipped a production-grade decision pipeline: signals → interpretation → twin query → candidates → risk → policy → routing → execution → learning. 432 tests, 50+ eval scenarios, 13 domains, 7 safety invariants enforced. The engine works.

What's missing is the product. A user can't install SkyTwin, launch it, connect their accounts, and use it daily without touching a terminal. There's no desktop app, no real-time notifications, no mobile access, no process supervision. The dashboard covers the happy path but can't audit, undo, or search. Connectors crash silently on transient errors. The twin doesn't respect quiet hours.

This epic tracks everything needed to go from "engineer's working prototype" to "download it, launch it, use it every day, post it on Hacker News."

PR Workflow

Every child issue PR must pass `/review` before merge. No exceptions.

Current State (verified 2026-04-04)

What's working well (do not break)

What's incomplete

Child Issues

Total serial: ~21-32h Claude Code time

Parallel execution plan (Conductor)

Wave 1 (~4-6h):  #11 + #13 + #10 + #14  (all independent)
Wave 2 (~3-4h):  #8 + #9 + #15          (deps satisfied)
Wave 3 (~5-8h):  #16                     (needs #13 + #15)

Wall time with parallelism: ~12-18h across 3 waves

Dependency Graph

#11 Resilience ──────────────> #8 Live Notifications

#13 Desktop App ──┬──────────> #9 First-Run Experience
                  ├──────────> #15 Mobile Access ──> #16 Cross-Platform
                  └─────────────────────────────────/

#10 Dashboard ────────────── (independent, start anytime)

#14 Engine Gaps ──────────── (independent, start anytime)

Sequencing Rationale

• Local resilience: retry/backoff, process supervision, graceful degradation #11 first: retry/backoff and process supervision are prerequisites for everything else. If the API crashes during onboarding or connectors lose signals, nothing else matters.
• Desktop Electron app: native install, tray, process management #13 early: the desktop app is the product for local-first. It manages processes, hosts the API, and provides the install experience. Guided first-run: connect → see signals → approve → watch twin learn #9 (first-run) and Mobile local access: QR pairing, mDNS, responsive dashboard #15 (mobile) depend on it.
• Live notification layer: SSE, approval expiry cron, push alerts #8 after Local resilience: retry/backoff, process supervision, graceful degradation #11: SSE connections and expiry cron need a process that stays alive.
• Guided first-run: connect → see signals → approve → watch twin learn #9 after Desktop Electron app: native install, tray, process management #13: first-run experience happens inside the Electron app, not a browser tab.
• Dashboard completeness: audit log, rollback UI, decision search #10 and Engine gaps: quiet hours, policy CRUD, type safety, structured logging #14 anytime: dashboard completeness and engine gaps are independent. Good parallel work.
• Mobile local access: QR pairing, mDNS, responsive dashboard #15 after Desktop Electron app: native install, tray, process management #13: mobile access requires the desktop to be serving the API reliably.
• Cross-platform builds: Windows, Linux, native mobile apps #16 after Desktop Electron app: native install, tray, process management #13 + Mobile local access: QR pairing, mDNS, responsive dashboard #15: cross-platform builds extend the macOS desktop app and mobile web to Windows/Linux installers and native iOS/Android apps.

Acceptance Criteria

1. User downloads DMG (macOS), MSI (Windows), or AppImage (Linux), installs and launches SkyTwin — sees onboarding wizard within 10 seconds
2. User connects Google account, sees first signals arrive within 30 seconds
3. User approves 3 actions, sees trust tier progress indicator update
4. Approval notification appears as native OS notification within 5 seconds of creation
5. User opens dashboard on phone via QR scan, approves an action from mobile
6. Native iOS and Android apps connect to desktop via local network
7. Quiet hours prevent auto-execution and suppress non-urgent notifications
8. kill -9 on API process → app restarts it within 5 seconds
9. Gmail returns 429 → connector retries with backoff, signal is not lost
10. User can search decisions by date range, situation type, and text
11. User can undo an executed action from the dashboard with structured reasoning
12. Audit page shows trust tier changes, spend events, and preference evolution
13. All 432 existing tests continue passing
14. No safety invariant regressions in eval suite
15. Every child PR passes `/review` before merge

Out of Scope

• Cloud deployment (future epic)
• Auto-update mechanism
• App store distribution (Apple App Store, Google Play, Microsoft Store)
• Multi-device sync beyond local network
• Off-network mobile access

Note on cloud epic: A separate epic should be created for cloud deployment. This epic is strictly local-first: everything runs on the user's machine.

Definition of Done

1. All 15 acceptance criteria pass
2. A non-technical person can install, onboard, and use SkyTwin daily without opening a terminal — on macOS, Windows, or Linux
3. The system recovers from transient failures (connector errors, process crashes) without user intervention
4. Phone approval workflow works on same WiFi network via native app or mobile browser
5. Eval suite green, no safety regressions
6. Every PR passed `/review`
7. Ready to post on Hacker News: install → connect → first decision in under 5 minutes

Rollback Plan

Each child issue is a separate PR. If a child breaks something:

• Revert the PR
• Existing v0.3 functionality is unaffected (all changes are additive)
• Desktop app is a new entrypoint — doesn't modify existing API/worker/web behavior

Issue Archaeology

Issues #2, #3, and #4 were audited against the v0.2/v0.3 CHANGELOG on 2026-04-04. All three are now closed:

• Make SkyTwin usable by a non-technical person end-to-end #2 (Make SkyTwin usable by a non-technical person): 7/10 sections shipped. Remaining items (confidence dashboard, error handling, mobile responsive, pause twin) migrated to Dashboard completeness: audit log, rollback UI, decision search #10, Local resilience: retry/backoff, process supervision, graceful degradation #11, Desktop Electron app: native install, tray, process management #13, Mobile local access: QR pairing, mDNS, responsive dashboard #15.
• Make SkyTwin actually work end-to-end: adapter layer, execution persistence, safety gaps #3 (Make SkyTwin actually work end-to-end): Phases 1-2 complete. Remaining items (notifications, quiet hours, SSE, policy CRUD, structured logging, type safety) migrated to Live notification layer: SSE, approval expiry cron, push alerts #8, Engine gaps: quiet hours, policy CRUD, type safety, structured logging #14.
• Scope Expansion: Full Build Plan (CEO Review 2026-04-01) #4 (CEO Review build plan): All 5 build phases executed in v0.2/v0.3. Closed as completed planning artifact.