agentleFS
IgorGanapolskyIgorGanapolsky/mac-yolo-safeguards/hermes-mobile/AGENTS.md

mac-yolo-safeguards / hermes-mobile

AGENTS.md3 starsChanged 3 days agoMITView on GitHub

Canonical repo rules: ../AGENTS.md. This file adds mobile-only obligations so agents do not wait for the user to ask.

  • Reads credentials

The file

We split this AGENTS.md into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    North star: Every launch is a stranger who knows nothing.

    line 51

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md — Hermes Mobile

Canonical repo rules: ../AGENTS.md. This file adds mobile-only obligations so agents do not wait for the user to ask.

Standing orders (no reminders)

  1. Before any edit — run ../../bin/agent-loop --health (validates hooks, MCP, skills, E2E, plan claims). Full cycle: ../../bin/agent-loop (Recollect→Plan→Observe→Act→Evaluate→Learn).
  2. Session start — parent repo runs node tools/agent-session-start.js (pairing, LaunchAgent health, continuous E2E status). Do not skip when touching this tree.
  3. After any edit under src/, app.json, or .maestro/ — in the same turn before claiming fixed/shipped:
    • npm test -- --no-coverage --watchman=false
    • Kick autonomous E2E: launchctl kickstart -k "gui/$(id -u)/com.igor.hermes-mobile-continuous-e2e" or npm run e2e:continuous:once
  4. Never ask the user to run Maestro, reload Metro, plug in a phone, or tap Send — use adb, hermes-mobile-pair.js, and scripts.
  5. Read docs/proofs/continuous/latest.json before saying chat/E2E is healthy. If e2e ≠ pass, say so with the JSON — do not claim device UX is verified.
  6. Phone connected (adb devices) → E2E prefers Android automatically via scripts/run-e2e.sh.
  7. Phone install only via release path — npm run android:phone or scripts/install-phone-release.sh; never expo run:android on device (npm run android blocks when adb sees a phone).
  8. RN performance work — read .cursor/skills/react-native-best-practices/SKILL.md first (Callstack 2026 optimization guide skills). Install/refresh: bash ../scripts/install-callstack-agent-skills.sh. Measure before optimizing.
  9. Real users product — Hermes Mobile ships to real users, not Igor-only dogfood. No feature is "done" if it requires adb, dev backdoor, or pre-paired Igor Mac.
  10. Brand-new user testing (permanent) — always treat every test as if it is a brand new user: fresh install, no saved profiles, no developerLeashUnlock, cellular or Wi‑Fi only, release APK. Maestro and manual proofs must reflect that mindset.
  11. Multi-Mac API keys — Mac mini and MacBook Pro can have different API_SERVER_KEY values. Pair mini via node tools/hermes-mobile-pair.js --mini-tailscale (SSH-fetches mini key); never paste the laptop .env key when targeting another machine.
  12. Device/Maestro chat input (permanent) — When testing via Maestro, adb input text, agent-device, or any device/E2E automation that types into the chat composer, use only make money today. Never type gibberish probe strings (typeableProbeB, e2e-chat-send-persist, smoke test message, etc.). Session titles/IDs in URLs are exempt. Enforced by preventRecurrenceContract.test.ts.
  13. Versioning / OTA / store — JS fixes ship via EAS Update (production channel, CI mobile-ota.yml). New store binaries only for native changes or marketing expo.version bumps. Canonical rules: docs/VERSIONING-AND-RELEASES.md. Do not claim “every fix needs the store” or invent semver automation that does not exist.
  14. No production OTA without fresh-user gate (permanent, crisis 2026-07-15) — Never run eas update --channel production / npm run ota:publish unless docs/proofs/continuous/latest.json has e2e=pass or npm run e2e:fresh-user (.maestro/stranger-cold-start.yaml) wrote a pass proof. Gate: npm run ota:gate → scripts/require-fresh-user-ota-gate.sh. CI must not auto-publish production on every main merge. e2e=skipped is not pass.
  15. agent-device (Callstack) — For connection-crisis / Tailscale / fresh-user UI proofs, use agent-device (or bash scripts/agent-device-connection-proof.sh). Install/refresh: bash ../scripts/install-agent-device.sh. Matrix vs Maestro vs adb: docs/AGENT-DEVICE.md. Maestro latest.json remains the ship gate; agent-device alone is not e2e=pass. Do not claim Connected when UI shows Reconnecting.
  16. No desktop hijack — Never drive Igor's interactive Google Chrome, steal macOS focus, or use Computer Use unless he explicitly asked in that message. Parent rule: ../AGENTS.md § No desktop hijack. Prefer gh, Play/ASC APIs, Stripe CLI, adb, SSH. Chrome CDP LaunchAgents stay gated off (HERMES_ALLOW_INTERACTIVE_CHROME default 0).

Autonomous infrastructure (already installed on Igor's Mac)

PieceIntervalCheck
LaunchAgent com.igor.hermes-mobile-continuous-e2e15 minnpm run e2e:continuous:status
GitHub mobile-continuous.yml6 hunit + coverage on push schedule

Install/repair: bash ../scripts/install-agent-launchagents.sh (agent runs this if missing — not the user).

Verification ladder

LayerCommand
Unitnpm test / npm run test:ci
Contractnpm run test:release-safety
Connection UI proofbash scripts/agent-device-connection-proof.sh (exploratory; see AGENT-DEVICE.md)
E2E (local)npm run e2e:continuous:once
E2E (fresh-user / OTA gate)npm run e2e:fresh-user then npm run ota:gate
E2E (device release)npm run e2e:device
Accelerated Maestronpm run e2e:accelerated (agent-device test --maestro)

Details: docs/TESTING.md.

Fresh-user onboarding contract (permanent)

North star: Every launch is a stranger who knows nothing. One primary CTA per connection state. Silent auto-heal ~30s before numbered human steps.

StateUser seesMust NOT see
First launch, no saved MacConnectMacGate + numbered steps + Find computers"Pair relay", "gateway", "LAN", competing banners
Disconnected, saved MacSilent heal in CodexCommandCenter; after ~30s ChatConnectionPanel + steps"Connected" + "Can't reach" at once
Choose Mac modalTailscale Add [name] at top when tailnet probe succeedsMac mini buried only in Settings
Cellular, no TailscaleStep 4 + Use Tailscale from cellular titleHome Wi‑Fi IP instructions without context

Infer onboarding complete from valid saved gatewayProfiles (no separate flag required).

Unit tests (required on onboarding copy changes):

  • src/__tests__/freshUserOnboarding.test.ts — step copy, heal timing, jargon-free
  • src/__tests__/FreshUserOnboardingCard.test.tsx — numbered steps render
  • src/__tests__/ChatConnectionPanel.test.tsx — fresh-user card, single CTA, Tailscale chip

Maestro: connect-mac-gate must show connect-mac-onboarding-card on cold start without demo deep link (future flow); demo bootstrap uses hermes://setup?demo=1 and hides the gate.

Copy rules: Say Your Mac, Home Wi‑Fi, Find computers — never "gateway", "LAN", or "Pair relay" in first-run / disconnected primary UI.

Greptile AI PR review

Version-controlled rules: ../.greptile/ + .greptile/. Agent guide: docs/GREPTILE-CODE-REVIEW.md.

On PRs that touch connect, onboarding, pairing, Tailscale, auth probes, OTA, or multi-Mac keys: read Greptile findings before claiming fixed/shipped. Force review with @greptileai review once the GitHub App is installed. Do not treat green CI alone as connect/onboarding proof when Greptile flags a fresh-user or wrong-key regression class.

Prevent recurrence (July 2026)

Playbook: docs/PREVENT-RECURRENCE-JULY-2026.md. Session gates: vault pull + plan.md §2 before parallel work; bash scripts/agent-adb-refresh.sh before phone/pair; bash scripts/agent-pre-asc-edit.sh before ASC review notes; read docs/proofs/continuous/latest.json before device/chat ship claims (e2e=skipped is not pass). Cursor: single-pass — no duplicate subagents on the same file domain or PR.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.