# AGENTS.md — Build guide for Aight

## Project scope
Pair a phone with a private companion, choose an available coding-agent adapter, start a session, inspect tool events, answer one approval and interrupt the run.

Catalogue verdict: kinda. A focused multi-backend iPhone prototype is a realistic multi-day build when a local companion normalizes each agent protocol, but hardening all four adapters plus Aight's hosted relay, voice, orchestration, sync, and App Store polish is multi-week product work.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Runtime and tools: SwiftUI on iOS and a TypeScript companion service with a versioned authenticated event protocol.
- Before starting: A Mac with Xcode, an iPhone or simulator, a private companion host and pinned documentation for each enabled agent adapter.

## Stack and architecture
- SwiftUI on iOS and a TypeScript companion service with a versioned authenticated event protocol
- Data design: Store BackendCapability, Session, Run, EventSequence and PendingApproval; approval identity includes backend/session/run and expires on disconnect. Replayed events must not create duplicate cards.
- Setup: A Mac with Xcode, an iPhone or simulator, a private companion host and pinned documentation for each enabled agent adapter

## Security and data integrity
- Keep backend credentials on the companion. Pair explicitly, store the bridge credential in Keychain, scope each approval to one run and reject stale or replayed responses.
- Retain separate documented adapters for Codex, Claude, OpenClaw and Hermes with unavailable/unsupported states. Do not infer identical APIs across agents; private relay, push and voice are separate capabilities.
- Keep secrets outside client bundles and exported projects; document what leaves the device and make retention/deletion controls visible.

## Agent implementation rules
- Project rule — domain: Store BackendCapability, Session, Run, EventSequence and PendingApproval; approval identity includes backend/session/run and expires on disconnect. Replayed events must not create duplicate cards.
- Project rule — scope and recovery: Retain separate documented adapters for Codex, Claude, OpenClaw and Hermes with unavailable/unsupported states. Do not infer identical APIs across agents; private relay, push and voice are separate capabilities.
- Project rule — acceptance: Disconnect while a tool awaits approval, reconnect to another session, and attempt the old response; it is rejected and the original run remains denied or waiting explicitly.
- Project rule — delivery: document real setup commands and permissions; do not claim a build, accuracy level, performance result or security certification that has not been demonstrated.

## Optional agent skills and references
- Recommended skill: [swiftui-expert-skill](https://github.com/AvdLee/SwiftUI-Agent-Skill/blob/main/skills/swiftui-expert-skill/SKILL.md) — design native SwiftUI state, accessible controls and permission/error views for the proposed Apple-platform interface. Follow the maintainer's installation instructions and match its requirements to the chosen runtime.
- Recommended skill: [swift-concurrency](https://github.com/AvdLee/Swift-Concurrency-Agent-Skill/blob/main/skills/swift-concurrency/SKILL.md) — isolate capture, background work and UI updates, and make cancellation invalidate late callbacks. Follow the maintainer's installation instructions and match its requirements to the chosen runtime.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this working slice using synthetic or explicitly authorized non-sensitive examples: Pair a phone with a private companion, choose an available coding-agent adapter, start a session, inspect tool events, answer one approval and interrupt the run.
- Share a synthetic example export and the acceptance walkthrough; keep real customer, health, financial and source data private: Disconnect while a tool awaits approval, reconnect to another session, and attempt the old response; it is rejected and the original run remains denied or waiting explicitly.
- State the limits before asking someone to replace their existing tool: Retain separate documented adapters for Codex, Claude, OpenClaw and Hermes with unavailable/unsupported states. Do not infer identical APIs across agents; private relay, push and voice are separate capabilities.

## Engineering roadmap
1. Phase 1 — Pin the working slice and create its example input: Pair a phone with a private companion, choose an available coding-agent adapter, start a session, inspect tool events, answer one approval and interrupt the run. Confirm setup: A Mac with Xcode, an iPhone or simulator, a private companion host and pinned documentation for each enabled agent adapter.
2. Phase 2 — Implement persistence and write-time invariants before decorating the UI: Store BackendCapability, Session, Run, EventSequence and PendingApproval; approval identity includes backend/session/run and expires on disconnect. Replayed events must not create duplicate cards.
3. Phase 3 — Connect the working view to real saved state. Keep backend credentials on the companion. Pair explicitly, store the bridge credential in Keychain, scope each approval to one run and reject stale or replayed responses.
4. Phase 4 — Expose the app-specific limits and recovery path in context: Retain separate documented adapters for Codex, Claude, OpenClaw and Hermes with unavailable/unsupported states. Do not infer identical APIs across agents; private relay, push and voice are separate capabilities.
5. Phase 5 — Walk through this concrete acceptance case and preserve its exported evidence: Disconnect while a tool awaits approval, reconnect to another session, and attempt the old response; it is rejected and the original run remains denied or waiting explicitly. Finish the README and backup/restore instructions; report unfinished capabilities explicitly.

## Paid-product capabilities outside this build
- managed encrypted relay and push notifications
- voice mode with local speech models
- cross-agent teams and group-chat orchestration
- pre-built agent/team templates and community skill browsing
- multi-device sync and App Store polish

## Implementation prompt
Build me a local-first iPhone client for Codex, Claude Code, OpenClaw,
and Hermes. Requirements:

- Use Swift 6, SwiftUI, and iOS 18. Generate Xcode from a checked-in
  XcodeGen project.yml so `xcodegen && xcodebuild` works on a clean clone.
- Build the Node.js 22 TypeScript companion with Fastify and WebSockets. Expose
  start, resume, prompt, event, approval, interrupt, and capability operations;
  session listing is optional and capability-gated.
- Ship real adapters for all four. Disable unavailable agents at runtime; all
  adapters must compile and pass fixture tests without every agent installed.
- Codex: pin the CLI version, run `codex app-server generate-ts`, and supervise
  app-server over stdio using the generated v2 types.
- Claude Code: use `@anthropic-ai/claude-agent-sdk`, its session APIs,
  async-iterable input for interrupt(), and canUseTool for permissions.
- OpenClaw: use the official Gateway WebSocket client, pair once, request only
  read/write/approvals/questions scopes, and store its device token securely.
- Hermes: use /v1/runs and its event, approval, and stop endpoints; use
  session headers for continuity and discover features from /v1/capabilities.
- Keep backend models in the companion and expose one versioned protocol. The
  iOS app stores its wss:// endpoint and bridge bearer token in Keychain.
- Provide backend/session pickers, streamed Markdown and tool events, approval
  cards, Stop, capability-aware controls, and deny approvals on disconnect.
- Bind to 127.0.0.1 and compare the random `.env` token in constant time;
  expose it only through private Tailscale Serve HTTPS, and never enable Funnel.
- Add bounded reconnects and local completion notifications. No app accounts,
  cloud database, analytics, or telemetry; agent model-provider calls remain.
- Out of scope: hosted relay, voice, cross-backend groups, templates, community
  skills, themes, multi-device sync, and a macOS client.
- Test adapter fixtures plus denial, interruption, and reconnection. README:
  setup for all four, `.env.example`, Tailscale, signing, permissions, limits.

Acceptance gate: use fixture-driven adapter sessions to prove start, approval denial, interruption, reconnect, and resume. Assign each event a session ID and monotonic sequence, ignore duplicate events after reconnect, and never replay an approval response into a different run. A disconnected phone must not implicitly approve pending work. Report each adapter capability as available, unavailable, or unsupported; never fabricate a successful tool run.

EDITORIAL IMPLEMENTATION CONTRACT
Working slice: Pair a phone with a private companion, choose an available coding-agent adapter, start a session, inspect tool events, answer one approval and interrupt the run.
Data and invariants: Store BackendCapability, Session, Run, EventSequence and PendingApproval; approval identity includes backend/session/run and expires on disconnect. Replayed events must not create duplicate cards.
Boundary and recovery: Retain separate documented adapters for Codex, Claude, OpenClaw and Hermes with unavailable/unsupported states. Do not infer identical APIs across agents; private relay, push and voice are separate capabilities.
Acceptance walkthrough: Disconnect while a tool awaits approval, reconnect to another session, and attempt the old response; it is rejected and the original run remains denied or waiting explicitly.
Record actual dependency versions, permissions and provider access in setup instructions. Preserve originals, expose partial failures and document backup/restore. These are acceptance requirements, not a claim of a completed or production-certified build. Add the domain, recovery and acceptance rules to AGENTS.md so future edits preserve them.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.