hermes-mobile/PROJECT_PLAN.md

Hermes Mobile — Delivery Plan

Operational contract: Codex must read this file before each work loop. Work exactly one coherent milestone at a time. Move completed items to the completed section in the same commit that implements them. Add a concise entry to CHANGELOG.md in the same commit. Never mark work complete without running its listed verification.

Product guardrails

• Native Android client for upstream Hermes Agent: Kotlin + Jetpack Compose.
• Material 3 base, deliberately customized through a reusable design system.
• Thin client: Hermes remains the authority for auth, sessions, streaming, tool semantics, and backend behavior.
• No WebView-first app, no cloned Hermes backend, no embedded credentials.
• Adaptive, accessible, compact-but-readable UI: phone, tablet, light/dark, font scaling, IME/keyboard, long code/output must remain safe.
• Keep DTO/transport, domain/UI models, repositories, view models/state, and composables separated.
• Never commit APKs, build outputs, credentials, or generated local environment files.

Release policy

• Start artifacts at v0.1.0-beta.1.
• Patch: compatible fixes/polish. Minor: a coherent feature milestone. Major: stable v1.0.0+ only.
• A release requires a pushed source commit, passing relevant checks, a versioned APK artifact, and a Telegram release post.

---

Now — finish the foundation already in progress

• F1 — Compose design system extraction

  • Extract tokens for color, spacing, typography, shape, elevation, motion, and semantic status colors.
  • Implement light/dark themes with readable contrast; eliminate default-sample styling.
  • Split oversized UI into clear design, feature, and reusable component packages.
  • Add Compose previews: small phone, normal phone, tablet width, light, dark.
  • Verification: Android compile/build plus visual preview review.

• F2 — Polished fake-data chat proving ground

  • Session rail/list, conversation screen, context controls, keyboard-safe composer, send/cancel/retry behavior.
  • Render assistant/user/system/error/streaming messages from UI models.
  • Add markdown-friendly surfaces, selectable long text, code blocks with horizontal scroll + copy, compact expandable tool results.
  • Cover empty/loading/reconnecting/error states without clipped/overlapping content.
  • Verification: focused UI tests where practical; Android debug build.

Beta path — upstream-connected MVP

• B1 — Transport/domain contracts

  • Define transport DTOs and a repository interface for server profiles, authentication, sessions, messages, stream events, tool results, and artifacts.
  • Map DTOs to stable UI models; fake repository powers previews/tests.
  • Keep the existing companion as an optional adapter only; do not change upstream Hermes semantics.
  • Verification: unit tests for mapping/state reducers; build/typecheck.

• B2 — Connection and authentication UX

  • Server connection screen with validation, health, auth/session configuration, offline/unauthorized/retry states.
  • Store sensitive values using Android-appropriate secure storage; never log secrets.
  • Verification: connection-state tests and manual unhappy-path walkthrough.

• B3 — Session list and durable chat state

  • Fetch/list/search/select/create sessions through repository contracts.
  • Restore selected session and protect against duplicate sends / lost drafts.
  • Verification: fake-repository UI tests; companion/integration checks where available.

• B4 — Streaming, reconnects, and resilient long-running work

  • Stream event reducer: token deltas, tool lifecycle, final/error/cancel, reconnect/backoff.
  • Preserve partial output and make recovery obvious and safe.
  • Verification: deterministic fake stream tests and real upstream-compatible exercise.

• B5 — Tool, artifact, and output experience

  • Compact tool cards with lifecycle/status, expandable output, copy/share/save affordances.
  • Safe rendering for large logs and code; no unbounded nested scroll failures.
  • Artifact/file handoff only where upstream capability is actually supported.
  • Verification: large-output and rotation/resume checks.

Beta hardening and release

• R1 — Adaptive/accessibility quality pass

  • Small phone, normal phone, tablet/two-pane behavior; portrait/landscape.
  • Font scaling, TalkBack semantics, contrast, touch targets, reduced motion, IME behavior.
  • Verification: emulator/device matrix evidence documented in docs/ROADMAP.md.

• R2 — Beta packaging and install guide

  • Version v0.1.0-beta.1, reproducible debug/beta APK build, install/run guide, known limitations.
  • Publish source commit, APK, release notes, and verification result.
  • Verification: clean install on a real device or emulator plus full required checks.

V2 backlog

• Multiple server profiles and fast switching.
• Rich file/artifact workflows based on upstream capability.
• Notifications for task completion.
• Mature tablet/two-pane session + optional terminal/log pane.
• Offline cache/search and diagnostic export with privacy controls.

---

Completed

Move finished items here with date, commit, and verification. Keep this section factual; do not claim unverified work.

• F0 — Audit and safely land existing work — 2026-07-24, commit da79d48 (feat: land native mobile foundation).
  • Reviewed existing Android and companion edits; preserved the native Android chat/workspace/settings work and companion chat hardening.
  • Confirmed generated build outputs are ignored and added ignores for .gradle-user/ and .dev/.
  • Reconciled docs/ROADMAP.md to the actual native Android beta state and remaining validation gaps.
  • Verification: git diff --check passed; npm run typecheck --workspace @hermes-mobile/companion passed; npm run lint --workspace @hermes-mobile/companion passed; npm run build --workspace @hermes-mobile/companion passed; npm run typecheck passed; npm run lint passed; npm run build passed.
  • Android debug build attempted with GRADLE_USER_HOME=/root/hermes-mobile/.gradle-user ./gradlew :app:assembleDebug from apps/mobile/android; blocked before compilation because network socket creation is not permitted while downloading Gradle 8.11.1.

Work-loop checklist

Before coding:

1. Read PROJECT_PLAN.md, CHANGELOG.md, docs/ROADMAP.md, git status, and the prior commit.
2. Choose the single highest-value unchecked item or a narrowly scoped sub-item.
3. Inspect existing implementation before rewriting it.

Before committing:

1. Run relevant checks; record exact pass/fail scope in the changelog.
2. Update this plan: check the completed item, move it into Completed, and leave the next executable item unchecked.
3. Add a concise CHANGELOG.md entry under Unreleased.
4. Commit using Conventional Commits and push origin/main.
5. Do not claim a release without an uploaded, verified versioned APK.