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