From ae25260ba55e73cee419e2b4dcd3b5c8d0b93459 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 4 Jul 2026 21:36:14 +0200 Subject: [PATCH 1/2] docs: tighten agent operating guide --- AGENTS.md | 45 ++++++++++++--------------------------------- 1 file changed, 12 insertions(+), 33 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ba33b77c5..3b920ce05 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -Minimal operating guide for AI coding agents in this repo. +AGENTS.md is this repo's README for coding agents: project context, commands, conventions, non-obvious traps, and PR expectations in one predictable place. Keep it high-signal and living; prefer durable source-of-truth pointers over file inventories that drift. ## Agent skills @@ -97,13 +97,8 @@ Keep `src/daemon.ts` a thin router and `src/daemon/request-router.ts` orchestrat - If lint failures appear after toolchain edits, check whether the rule is from `eslint/*`, `typescript/*`, `import/*`, or `node/*` in `.oxlintrc.json` before assuming source bugs. ## Apple Runner Seams -- The OS-agnostic Apple XCTest runner lives under `src/platforms/apple/core/runner/`. Keep dependency direction clean: - - `runner-client.ts`: command execution + retry behavior - - `runner-transport.ts`: connection/probing/HTTP transport - - `runner-contract.ts`: shared `RunnerCommand` type and runner connect/error helpers - - `runner-session.ts`: session lifecycle and request/response execution - - `runner-xctestrun.ts`: xctestrun preparation/build/cache logic -- `runner-transport.ts` must not import back from `runner-client.ts`. +- The OS-agnostic Apple XCTest runner lives under `src/platforms/apple/core/runner/`; use `rg --files src/platforms/apple/core/runner` and read the seam you are changing before editing. +- Keep dependency direction clean: transport stays below client/session behavior, shared command/error contracts stay in the runner contract module, and xctestrun preparation/build/cache logic stays isolated from request execution. - If changing runner connect errors, retry policy, or command typing, start in `src/platforms/apple/core/runner/runner-contract.ts` before touching client/transport files. ## Adding a New CLI Flag @@ -201,15 +196,9 @@ This repo encodes invariants as self-declaring gates. The correct response to a - Prefer selector or `@ref` interactions over raw x/y commands in tests and docs, especially on macOS where window position can vary across runs. ## Shared Test Utilities -- Before writing a new test, check `src/__tests__/test-utils/` for existing helpers: - - `device-fixtures.ts`: canonical `DeviceInfo` constants (`ANDROID_EMULATOR`, `IOS_SIMULATOR`, `IOS_DEVICE`, `MACOS_DEVICE`, `LINUX_DEVICE`, etc.) - - `session-factories.ts`: `makeSession`, `makeIosSession`, `makeAndroidSession`, `makeMacOsSession` - - `store-factory.ts`: `makeSessionStore` (creates temp `SessionStore` instances) - - `snapshot-builders.ts`: `buildNodes`, `makeSnapshotState` - - `mocked-binaries.ts`: `withMockedAdb`, `withMockedXcrun` (stub CLI binaries for dispatch tests) -- Use `import { ... } from '/__tests__/test-utils/index.ts'` for convenient barrel imports. -- Prefer shared fixtures over inlining new `DeviceInfo` or `SessionState` objects in tests. -- Do not duplicate `makeSessionStore`, `makeSession`, or device constants when a shared helper already exists. +- Before writing a new test, inspect `src/__tests__/test-utils/index.ts` and search for existing factories, fixtures, and mocked binaries with `rg -n "export .*make|export .*DEVICE|withMocked" src/__tests__/test-utils`. +- Use the test-utils barrel for imports and prefer named shared fixtures over inlining new `DeviceInfo`, `SessionState`, snapshot, store, or mocked-binary objects. +- Do not duplicate session/store/device helpers when a shared helper already exists; if a helper is missing, add it near the concept it serves and export it through the barrel. ## Testing Matrix - Docs/skills only: no tests required unless a more specific rule below applies. @@ -275,22 +264,12 @@ This repo encodes invariants as self-declaring gates. The correct response to a - why it blocks completion - exact next command/action needed to unblock -## Key Files -- CLI parse + formatting: `src/bin.ts`, `src/cli.ts`, `src/cli/parser/args.ts` -- CLI help + option metadata: `src/cli/parser/cli-help.ts`, `src/cli/parser/cli-flags.ts`, `src/utils/cli-command-overrides.ts`, `src/utils/command-schema.ts`, `src/utils/cli-option-schema.ts` -- Daemon client transport: `src/daemon-client.ts` -- Daemon state/store: `src/daemon/session-store.ts` -- Selector DSL and matching: `src/daemon/selectors.ts` -- `is` predicate evaluation: `src/daemon/is-predicates.ts` -- Shared action helpers: `src/daemon/action-utils.ts` -- Snapshot shaping + labels: `src/daemon/snapshot-processing.ts` -- Handler context helpers: `src/daemon/context.ts`, `src/daemon/device-ready.ts` -- Request routing/policy: `src/daemon/daemon-command-registry.ts`, `src/daemon/request-router.ts`, `src/daemon/request-admission.ts`, `src/daemon/request-generic-dispatch.ts` -- Dispatcher + capability map: `src/core/dispatch.ts`, `src/core/dispatch-context.ts`, `src/core/dispatch-interactions.ts`, `src/core/capabilities.ts` -- Command identity + command surface: `src/command-catalog.ts`, `src/commands/command-surface.ts`, `src/commands/command-contract.ts`, `src/commands/client-command-contracts.ts` -- CLI grammar: `src/commands/cli-grammar.ts`, `src/commands/cli-grammar/*` -- Daemon request projection: `src/commands/command-projection.ts` -- Platform backends: `src/platforms/apple/*`, `src/platforms/ios/*`, `apple-runner/*`, `src/platforms/android/*` +## Finding Source Owners +- Do not turn this file into a source tree map. For implementation work, identify owner modules from the durable registries and then follow imports/tests from there. +- Command identity and projection: search command descriptors and command contracts first with `rg -n "|CommandDescriptor|defineCommand" src/core/command-descriptor src/command-catalog.ts src/commands`. +- Daemon routing and policy: start with `src/daemon/daemon-command-registry.ts`, then trace to the named handler/request module with `rg -n "|route|policy" src/daemon`. +- Platform behavior and capabilities: start with `src/core/capabilities.ts` and the relevant platform under `src/platforms/`; use `rg`, not broad directory reads. +- CLI help and command-planning guidance: source of truth is `src/cli/parser/cli-help.ts`, `src/cli/parser/cli-flags.ts`, `src/utils/cli-command-overrides.ts`, and `src/utils/command-schema.ts`. ## Pull Requests - Before opening PR: ensure no conflict markers/unmerged paths. From 355c823ba41b9e9f20cdb9df0b41e6e51ac94390 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 4 Jul 2026 21:39:41 +0200 Subject: [PATCH 2/2] docs: update agent guide cli paths --- AGENTS.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3b920ce05..eb9cf64dc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -92,7 +92,7 @@ Keep `src/daemon.ts` a thin router and `src/daemon/request-router.ts` orchestrat - read `.oxlintrc.json` before treating lint output as source-level bugs - For files over 500 LOC, search for the relevant type/function/section first, then read a bounded range. - Do not run integration tests by default. -- Keep long help prose in `src/cli/parser/cli-help.ts`, flag definitions in `src/cli/parser/cli-flags.ts`, and CLI-specific usage/flag metadata in `src/utils/cli-command-overrides.ts`. +- Keep long help prose in `src/cli/parser/cli-help.ts`, flag definitions in `src/cli/parser/cli-flags.ts`, and command-specific usage/flag metadata with the command family metadata that owns the command. - If build/type errors mention declaration generation, inspect `tsconfig.lib.json` before reading platform code. - If lint failures appear after toolchain edits, check whether the rule is from `eslint/*`, `typescript/*`, `import/*`, or `node/*` in `.oxlintrc.json` before assuming source bugs. @@ -105,12 +105,12 @@ Keep `src/daemon.ts` a thin router and `src/daemon/request-router.ts` orchestrat A new snapshot/command flag touches only the layers that need to understand it. Follow this checklist in order: -1. `src/cli/parser/cli-flags.ts`: add to `CliFlags`, `FLAG_DEFINITIONS`, and the relevant exported flag group (e.g. `SNAPSHOT_FLAGS`). Add the flag to `CLI_COMMAND_OVERRIDES` in `src/utils/cli-command-overrides.ts` for each command that supports it; command names/descriptions come from command contracts unless CLI help needs a specific override. +1. `src/cli/parser/cli-flags.ts`: add to `CliFlags`, `FLAG_DEFINITIONS`, and the relevant exported flag group (e.g. `SNAPSHOT_FLAGS`). Then update the command family metadata/schema that exposes the flag; find the owner with `rg -n "|supportedFlags|allowedFlags" src/commands src/cli/parser`. 2. `src/commands/cli-grammar/*`: read the CLI flag into command input when the CLI accepts it. 3. `src/commands/command-projection.ts` and command-family projection helpers: write the input into the daemon request only if the flag affects daemon execution. 4. `src/commands/*-command-contracts.ts`: add or update the command input schema only if the option should be available through Node.js or MCP as structured input. -5. `src/client-types.ts`: update the public typed client option only when the Node.js interface exposes the option. -6. `src/client-normalizers.ts`: update daemon flag normalization only when the request still needs a public-to-internal option translation. +5. `src/client/client-types.ts`: update the public typed client option only when the Node.js interface exposes the option. +6. `src/client/client-normalizers.ts`: update daemon flag normalization only when the request still needs a public-to-internal option translation. 7. `src/daemon/context.ts` and `src/core/dispatch-context.ts`: add the field only when it flows into platform dispatch. 8. Handler/platform modules: thread the option only after the command surface, grammar, and projection prove it belongs there. @@ -247,8 +247,8 @@ This repo encodes invariants as self-declaring gates. The correct response to a - Changing `tsconfig.lib.json`/build tooling without running `pnpm check:tooling`; declaration generation is stricter than a plain typecheck. ## Docs & Skills -- Versioned CLI help is the agent-facing source of truth. Put workflow guidance/help topics in `src/cli/parser/cli-help.ts`, flags in `src/cli/parser/cli-flags.ts`, CLI command overrides in `src/utils/cli-command-overrides.ts`, and assertions for important copy in `src/cli/parser/__tests__/cli-help-topics.test.ts` / `cli-help-command-usage.test.ts`. -- Keep parser schema and help rendering separate: `src/utils/command-schema.ts` composes contract-derived command schemas with CLI overrides; `src/cli/parser/cli-help.ts` owns help topics and usage rendering. +- Versioned CLI help is the agent-facing source of truth. Put workflow guidance/help topics in `src/cli/parser/cli-help.ts`, flags in `src/cli/parser/cli-flags.ts`, command-specific schema/help metadata with the owning command family, and assertions near the focused CLI parser/help tests. +- Keep parser schema and help rendering separate: parser/help rendering lives in `src/cli/parser/`, while command schema metadata is derived from command metadata and command family declarations. - Before planning device automation commands, read `agent-device help workflow`; then read topic help such as `debugging`, `react-native`, `react-devtools`, `physical-device`, `macos`, or `dogfood` when relevant. This is required even when local agent skills are unavailable. - Skills are thin routers. Keep `skills/**/SKILL.md` focused on when to use the skill, version gating, which `agent-device help ` page to read, and a short default loop. Do not duplicate full CLI manuals in skills. - For behavior/CLI surface changes, update help/metadata, README or `website/docs/**` when user-facing, and a SkillGym case in `test/skillgym/suites/agent-device-smoke-suite.ts` when command-planning guidance changes. @@ -269,7 +269,7 @@ This repo encodes invariants as self-declaring gates. The correct response to a - Command identity and projection: search command descriptors and command contracts first with `rg -n "|CommandDescriptor|defineCommand" src/core/command-descriptor src/command-catalog.ts src/commands`. - Daemon routing and policy: start with `src/daemon/daemon-command-registry.ts`, then trace to the named handler/request module with `rg -n "|route|policy" src/daemon`. - Platform behavior and capabilities: start with `src/core/capabilities.ts` and the relevant platform under `src/platforms/`; use `rg`, not broad directory reads. -- CLI help and command-planning guidance: source of truth is `src/cli/parser/cli-help.ts`, `src/cli/parser/cli-flags.ts`, `src/utils/cli-command-overrides.ts`, and `src/utils/command-schema.ts`. +- CLI help and command-planning guidance: start with `src/cli/parser/cli-help.ts` and `src/cli/parser/cli-flags.ts`; for command-specific schema, search `rg -n "helpDescription|summary|supportedFlags|allowedFlags" src/commands src/cli/parser`. ## Pull Requests - Before opening PR: ensure no conflict markers/unmerged paths.