wristivo/docs/agents/README.md

Parallel implementation plan

The coordinating engineer is the integration owner. Agents implement focused branches against the shared package and mocks; they do not independently design whole apps. Copy the common brief plus one assignment below into each agent task.

Common brief to give every agent

Implement your assigned workstream for Wristivo. Read AGENTS.md, docs/PRODUCT.md, docs/ARCHITECTURE.md, docs/CONTRACTS.md and the relevant platform, gesture and security documents. Keep to owned paths and use shared domain types. Treat existing app views as explicitly labelled demos. Do not claim TV support or reliable motion recognition without real-device evidence. Propose shared contract/build changes to the integrator before implementing dependent code. Work on your branch, run focused tests, and hand back a reviewable diff, test results, hardware status and integration instructions. Do not push main or publish. No credentials or raw motion captures in git.

Ownership and deliverables

ID / branch	Exclusive paths	Deliverable	Depends on
A / feat/tv-transport	Adapters/TVTransport, package SamsungProtocol sources/tests	TV pairing, bounded socket actor, tested parser and click delivery	Agreed connection/trust contracts; owner TV access
B / feat/watch-relay	Adapters/WatchBridge	WCSession activation, control-plane session handshake, live commands/receipts, failure handling	Frozen envelope + session DTOs
C / feat/wrist-motion	Adapters/MotionCapture, package GestureCore sources/tests	Calibrated four-direction classifier, lifecycle stop, trace tests	Motion/gesture contract; physical Ultra 2
D / feat/phone-experience	Apps/iPhone	Manual setup, permissions, pairing states, accessible remote, forget/troubleshoot	Fake service first, A+E for live integration
E / feat/secure-storage	Adapters/SecureStorage	Keychain token and per-TV trust records, delete/re-pair behavior	Integrator identity/security contract
F / feat/watch-experience	Apps/Watch	Calibration, explicit arm/stop, accessible buttons, status and haptics	Fake service first, B+C for integration
Q / test/hardware-release	Tests/Hardware, docs/test-evidence	Hardware matrix, accessibility, latency/false-positive/battery evidence	Integrated slices
I / integration owner	All shared roots, RemoteCore, Package.swift, Apps/Shared, project, Config, Scripts	Contracts, composition, reviews, CI, combined builds, release gates	Every accepted PR

Package paths in the table mean Packages/WristivoKit/Sources/<module> and Tests/<module>Tests. A new adapter needs tests in an adjacent Tests directory; integrator creates target membership before the implementation branch starts. QA may run acceptance planning immediately, but must not edit another agent's tests or report planned cases as passed.

A — TV transport prompt

Implement an iPhone-only TV connection actor and pure bounded event parser. Use SamsungRemoteEncoder without copying a community implementation. Support explicit connect/pair/deny/timeout/revoke/disconnect, authorize before ready, serialize commands, consume admission once, recheck deadlines before sends, and cancel old-generation operations on TV/session changes. Integrate injected token/trust storage from E. No blanket TLS trust, arbitrary key API, silent plaintext fallback or replay on reconnect. Use synthetic redacted event fixtures for malformed/oversize/unknown/missing-token responses and fake socket tests for deadline, ordering and cancellation. Deliver a manual physical pairing script showing the name Wristivo, reconnect and revoke. Do not mark the TV compatible until the owner runs it. Begin with a hardware feasibility spike for the candidate endpoint and TLS policy before expanding UI dependencies.

B — Watch relay prompt

Implement separate iPhone and watchOS WCSession delegates with explicit main-actor UI updates and an injected reference to the single phone-side command actor owned by A/integration. Negotiate the phone-issued session and selected TV before enabling commands. Use only live sendMessage with bounded JSON payloads and exactly-once reply completion. Implement the documented milliseconds date strategy. Validate container version/types, payload size and structural decoding at the bridge. Delegate semantic version/session/target, expiry, sequence and duplicate admission to that one phone actor; B must not instantiate or consume a second CommandAdmission or maintain an independent authorized session. Do not use transferUserInfo to carry commands. Configuration snapshots may use application context, but carry no token or executable backlog. Provide fake-session tests for reachable/unreachable, activation/deactivation, phone/watch reinstall or switching, duplicate responses, timeouts and lost replies. Verify wake/locked-phone behavior on real hardware; simulator success is insufficient. Do not invent an unlimited iOS background service.

C — Wrist motion prompt

Implement Core Motion acquisition and a calibrated normalization/classification layer feeding GestureCore. CMMotionManager hardware availability and permission/error handling are mandatory. Coordinate axes must account for wrist side, crown orientation and neutral pose; don't integrate acceleration to pretend to know absolute hand position. Stop updates when inactive, disconnected, expired or cancelled. Re-arming starts a fresh neutral baseline. Use confidence/ambiguity rejection and one directional event per deliberate excursion. No custom finger pinch/clench or always-on claims. Keep samples in memory by default; use synthetic fixtures and separately consented local physical recordings for evaluation. Report direction-specific precision/recall, incidental-movement false triggers and a confusion matrix. Existing normalized gate is a seam, not proof of a complete classifier.

D — iPhone experience prompt

Build the onboarding/manual-address/pairing/status/remote/forget-TV experience with SwiftUI and injected services. Initially use a clearly named fake and explicit Demo mode. Show truthful success and recoverable permission/network/authorization errors. Keep protocol strings, token handling and network state out of Views. Provide accessible labels, sufficient touch targets, Dynamic Type, VoiceOver order, contrast and layout on iPhone 13 Pro Max plus smallest supported phone and iPad compatibility layouts. Ask for local network permission only when setup needs it. Do not add camera, location, tracking or account prompts. Supply UI checks against fake states and document service wiring for the integrator.

E — Secure storage prompt

Implement injected Keychain persistence scoped to opaque TV ID. Keep tokens, certificate trust material and pairing state on iPhone, not Watch or cloud. Propose the narrowest Keychain accessibility compatible with tested phone-lock relay; do not assume first-unlock access is always available. Test add/read/update/delete/not-found/locked/error cases with a mock Security client; run true Keychain behavior on a signed device. Implement forget-TV and certificate-change reapproval semantics. Never implement accept-all TLS. Initial self-signed certificate trust must be visibly user-approved and pinned per TV, with an honest first-use trust explanation; when no authenticated fingerprint source exists, record that limitation. Pair with A on the security boundary through frozen protocols.

F — Watch experience prompt

Build small-screen setup status, calibration instructions, explicit start/stop, D-pad, Select/Back and haptic feedback. Integrate C's motion service and B's command sink via the integrator's injected view model. Inactive scene/reachability loss/TV switch always stops sensing and disarms. Feedback distinguishes recognized gesture, transmitted command and failed/uncertain send; no false TV confirmation. Touch operation remains usable without motion permission. Add watchOS 11+ system double tap primary Select action only behind availability checks and physical Ultra 2 tests. Avoid arbitrary Action-button or system wrist-flick assumptions. Verify left/right wrists, large text, VoiceOver and the smallest watch supported by the declared deployment target.

Q — Hardware and release prompt

Turn Tests/Hardware/session-template.md and the platform/gesture/release gates into dated evidence for the integrated commit. Record exact devices, OS builds, TV model/firmware and network topology. Test pairing denial/revocation, locked/suspended phone, inactive watch, reboot, time skew, duplicates, packet loss and ordinary movements. Report measured failures as well as successes. Audit privacy declarations against actual APIs/SDKs, labels/assets for rights and accessibility, and release notes for unsupported claims. Do not distribute beta builds until developer membership and signing support are available.

Scheduling and integration

Maximum useful initial parallel work: A, B and C while I freezes seams and validates combined builds. With four total agent slots, do not start six agents at once. E can precede A's production trust/storage phase or replace an idle slot; D and F can develop UI against mocks once seams freeze. Q starts the test plan early and runs physical tests after slices merge. These dependencies are deliberate; "everything in parallel" without fixed contracts increases rework.

Before dispatch, I creates a branch/worktree from the same baseline commit and records owner, base SHA, paths, contract revision, prerequisites and acceptance tests in the coordination table below. Each PR is small enough for one integrated behavior. Merge E/security contracts → A phone slice → B relay slice → C gesture slice → D/F composition → Q release fixes. Pure UI or test fixtures may merge earlier if they do not alter live behavior.

Workstream	Owner/task	Base SHA	State	Evidence / blockers
A–Q implementation	Unassigned	Set at dispatch	Planned	Requires hardware and agreed contracts
I foundation	Coordinating engineer	Initial repository	Prepared	See VALIDATION.md

Merge acceptance

A PR may be merged with explicitly documented hardware gates outstanding, but cannot be tagged as a hardware-complete milestone or release. Required before normal merge: no contract drift, no out-of-scope paths, focused checks pass, no credentials/provenance issues, and the integrator's combined package + both app builds pass. Only the owner and integrator decide product scope changes.