AGENTS.md ยท diff
git:20261016.e77a8bc to git:20261017.91d1380
35 added, 34 removed. Audit A to A.
# AGENTS.md
- `agent-device` is a CLI and daemon for automating devices and web targets.
+ `agent-device` is a CLI and daemon that automates devices and web targets.
The daemon owns sessions. Registry declarations route commands to platform runtimes.
## Task routing
- Read only the row for your current task. Follow further links only when they apply.
+ Read only the row for your current task. Follow other links only when they apply.
| When the task involves | Read |
| --- | --- |
- | Domain vocabulary | `CONTEXT.md`, `docs/agents/domain.md` |
+ | Domain vocabulary | `CONTEXT.md` |
| Architecture decisions | `docs/adr/README.md` |
| Source changes, package boundaries, routing, diagnostics | `docs/agents/code-ownership.md` |
- | Running checks or diagnosing a failed gate | `docs/agents/testing.md` |
- | Writing or changing tests | `docs/agents/test-authoring.md` |
- | Auditing or deleting tests | `docs/agents/test-audit.md` |
+ | Checks or a failed gate | `docs/agents/testing.md` |
+ | New or changed tests | `docs/agents/test-authoring.md` |
+ | Test audits or deletions | `docs/agents/test-audit.md` |
| Mutation experiments or base comparisons | `docs/agents/test-experiments.md` |
- | Changing gate selection, fuzzing, or mutation harnesses | `docs/agents/gates.md` |
+ | Gate selection, fuzzing, or mutation harnesses | `docs/agents/gates.md` |
| Selector capture, polling, interaction fast paths, replay | `docs/agents/selector-capture.md` |
- | Adding or changing a CLI flag | `docs/agents/cli-flags.md` |
- | Opening or updating a PR | `docs/agents/pull-requests.md` |
- | Reviewing a change | `docs/agents/review.md` |
+ | A new or changed CLI flag | `docs/agents/cli-flags.md` |
+ | A PR to open or update | `docs/agents/pull-requests.md` |
+ | A change to review | `docs/agents/review.md` |
| Device-facing changes or manual device verification | `docs/agents/device-verification.md` |
- | Writing issues or PRDs, and triage labels | `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md` |
+ | Issues, PRDs, or triage labels | `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md` |
| Web backend setup or diagnostics | `docs/agents/web-backend.md` |
- Device-facing changes affect live device behavior: dispatch, capture, interaction, app lifecycle, or native execution.
- A daemon edit that changes none of these needs no device run.
+ A device-facing change affects live device behavior: dispatch, capture, interaction, app lifecycle, or native execution.
+ If a daemon edit changes none of these, a device run is not required.
- Versioned CLI help owns command semantics. For app-driving startup, use the skill's routing card.
+ The versioned CLI help owns command semantics. To drive an app, start with the skill's routing card.
## Working rules
- - Keep edits within the requested command family or module group. Inspect other platforms only when the task requires it.
- - Fix recurring failures at the owning type, registry, or construction path. Do not reconstruct another owner's state.
- - Use typed reasons and details for behavior. Never match error text.
- - Add compatibility or fallback behavior only when explicitly requested or approved. Remove superseded paths during migrations.
- - Encode invariants in names, types, and boundaries. Comments explain public APIs, tool directives, or constraints code cannot express.
- - Resolve gate failures at the reported invariant. Do not suppress them or add an allowlist to get a pass.
- - Use `@agent-device/selectors` for selector parsing and matching. See `docs/agents/code-ownership.md` for other shared owners.
- - Keep skills as routing cards. Keep `CONTEXT.md` glossary-only. Update owning help and user docs when behavior changes.
+ - Keep edits in the requested command family or module group. Examine other platforms only when the task requires it.
+ - Fix a recurring failure at the owning type, registry, or construction path. Do not rebuild another owner's state.
+ - Use typed reasons and details for behavior. Do not match error text.
+ - Add compatibility or fallback behavior only on explicit request or approval. During a migration, remove superseded paths.
+ - Encode invariants in names, types, and boundaries. Write comments only for public APIs, tool directives, or constraints that code cannot show.
+ - Resolve a gate failure at the reported invariant. Do not suppress it. Do not add an allowlist to get a pass.
+ - Use `@agent-device/selectors` to parse and match selectors. For other shared owners, see `docs/agents/code-ownership.md`.
+ - Keep skills as routing cards. Keep `CONTEXT.md` as a glossary only. When behavior changes, update the owning help and user docs.
## Worktree setup
- - Use `pnpm`. Use OXC for lint and format. Run `pnpm format` repository-wide.
- - In a fresh worktree, run `pnpm install --frozen-lockfile && pnpm build` before testing.
- - Preserve other worktrees, devices, sessions, dirty files, and experiments.
- - Never copy `.env` into a worktree. For host credentials, source the main checkout's file by absolute path.
- - Give parallel workers disjoint files and distinct devices. `pnpm check:affected --run` and `pnpm check` serialize automatically.
- - The layering scan reads tracked files. Stage new modules before trusting its result.
- - Move a path's Fallow baseline entry when renaming its file. Do not regenerate unrelated baselines.
+ - Use `pnpm`. Use OXC to lint and format. Run `pnpm format` on the full repository.
+ - In a new worktree, run `pnpm install --frozen-lockfile && pnpm build` before you test.
+ - Do not change other worktrees, devices, sessions, dirty files, or experiments. Do not use `git stash`; all worktrees share it.
+ - Do not copy `.env` into a worktree. For host credentials, source the main checkout's file by its absolute path.
+ - Give each parallel worker different files and a different device. `pnpm check:affected --run` and `pnpm check` run one at a time automatically.
+ - The layering scan reads only tracked files. Stage new modules before you trust its result.
+ - When you rename a file, move its Fallow baseline entry. Do not regenerate unrelated baselines.
- The validation lock reclaims provably dead owners automatically. Unknown owners remain blocking.
- If waiting times out, report the printed owner and lock state; do not remove it by hand.
+ The validation lock automatically reclaims owners that are provably dead. An unknown owner continues to block.
+ If the wait times out, report the printed owner and the lock state. Do not remove the lock manually.
## Agent docs
- Write short instructions with one action per sentence. Put the condition before its action.
- Use the same term for the same concept. Keep commands and domain terms exact.
- Route specialized rules to their task document. Delete duplicate or enforced rules before adding reminders.
+ Write agent docs in ASD-STE100. Write one instruction in each sentence.
+ Put the condition before the instruction. Use one term for one concept.
+ Keep commands and domain terms exact. Put specialized rules and new shared constraints in the owning task document, not in agent memory.
+ Before you add a reminder, delete duplicate or enforced rules.