Skip to content

Commit 8cec04a

Browse files
committed
docs(agents): write agent docs in ASD-STE100 and anchor issue decisions in comments
- Require ASD-STE100 for agent docs; rewrite AGENTS.md, issue-tracker, device-verification, and test-experiments in it. - Record issue decisions as `Decision:` comments and umbrella progress as `Current state:` comments; read them before resuming work. - Route new shared constraints to task docs, not private agent memory. - Warn that all worktrees share `git stash`. - Delete duplicated rules to stay inside the guidance byte budgets.
1 parent 5007540 commit 8cec04a

4 files changed

Lines changed: 104 additions & 101 deletions

File tree

‎AGENTS.md‎

Lines changed: 34 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,62 @@
11
# AGENTS.md
22

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.
44
The daemon owns sessions. Registry declarations route commands to platform runtimes.
55

66
## Task routing
77

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.
99

1010
| When the task involves | Read |
1111
| --- | --- |
1212
| Domain vocabulary | `CONTEXT.md`, `docs/agents/domain.md` |
1313
| Architecture decisions | `docs/adr/README.md` |
1414
| 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` |
1818
| 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` |
2020
| 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` |
2424
| 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` |
2626
| Web backend setup or diagnostics | `docs/agents/web-backend.md` |
2727

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.
3030

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.
3232

3333
## Working rules
3434

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.
4343

4444
## Worktree setup
4545

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.
5353

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.
5656

5757
## Agent docs
5858

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.

‎docs/agents/device-verification.md‎

Lines changed: 33 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -4,59 +4,59 @@ Use this for Apple runner changes or manual device runs. For foldables, also rea
44

55
## Prepare
66

7-
1. Build runtime changes with `pnpm build`.
7+
1. To build runtime changes, run `pnpm build`.
88
2. For Android source verification, run `pnpm build:android`.
99
3. For Swift runner changes, run `pnpm build:xcuitest`.
10-
Graceful shutdown can hand off an active runner; a new daemon can adopt the old binary.
11-
4. Run `pnpm clean:daemon` after the builds. The daemon does not reload code.
12-
5. Use distinct devices for parallel worktrees. Inspect worktree-scoped state with `pnpm daemon:state-dir`.
10+
A graceful shutdown can hand off an active runner. A new daemon can adopt the old binary.
11+
4. After the builds, run `pnpm clean:daemon`. The daemon does not reload code.
12+
5. To examine the worktree-scoped state, run `pnpm daemon:state-dir`.
1313
6. For `Agent Device Tester`, follow `examples/test-app/README.md` for the build, Metro, and expected app surface.
14-
An installed `com.callstack.agentdevicelab` alone is insufficient.
15-
7. For Android apps using Metro, run `adb reverse tcp:<port> tcp:<port>` before opening the app or URL.
14+
An installed `com.callstack.agentdevicelab` alone is not sufficient.
15+
7. For Android apps that use Metro, run `adb reverse tcp:<port> tcp:<port>` before you open the app or URL.
1616

1717
## Prove the path
1818

19-
Run the exact changed route. Record commands, device, source SHA, and observable results.
20-
For Android, require `snapshot -i --json` to show `androidSnapshot.backend: android-helper`
21-
and `helperVersion` matching `package.json`. UIAutomator fallback proves only that fallback.
19+
Run the exact route that changed. Record the commands, device, source SHA, and observable results.
20+
For Android, `snapshot -i --json` must show `androidSnapshot.backend: android-helper`.
21+
Its `helperVersion` must match `package.json`. A UIAutomator fallback proves only that fallback.
2222

2323
For Apple connection failures, start at `packages/platform-apple/src/runner/runner-startup-transport.ts`.
24-
Retry policy belongs in `runner-error-classification.ts`; command typing belongs in `runner-contract.ts`.
25-
Keep transport below session/client behavior. Keep xctestrun preparation outside request execution.
26-
After signing, warm Node with `node -e 0` before measuring Gatekeeper-sensitive startup.
24+
Retry policy belongs in `runner-error-classification.ts`. Command typing belongs in `runner-contract.ts`.
25+
Keep the transport below session and client behavior. Keep xctestrun preparation outside request execution.
26+
After signing, run `node -e 0` before you measure Gatekeeper-sensitive startup.
2727

2828
## Ownership and cleanup
2929

30-
Use purpose-specific sessions. For extra isolation, use a separate `--state-dir` under `/private/tmp`.
31-
Close every manually opened session, including failed attempts, with its original session, platform, UDID, and state directory.
30+
Use one session for each purpose. For more isolation, use a separate `--state-dir` under `/private/tmp`.
31+
Close each session that you opened manually, also failed attempts, with its original session, platform, UDID, and state directory.
3232

3333
For `DEVICE_IN_USE`:
3434

35-
- "already in use by session X": follow this daemon's `close --session` hint.
36-
- "owned by session X in workspace Y": inspect `device status`; follow `device release --stale` only for provably dead owners.
37-
A live or uncertain owner blocks `open` unless the device rebooted after the claim.
38-
With reboot evidence, `open` settles old resources, takes the claim, and reports release in `warnings`.
39-
Do not hunt PIDs or steal the claim.
35+
- "already in use by session X": follow the `close --session` hint of this daemon.
36+
- "owned by session X in workspace Y": examine `device status`. Use `device release --stale` only for provably dead owners.
37+
A live or uncertain owner blocks `open`, unless the device rebooted after the claim.
38+
With reboot evidence, `open` settles old resources, takes the claim, and reports the release in `warnings`.
39+
Do not search for PIDs. Do not steal the claim.
4040

41-
For stuck cleanup, run `agent-device device status --stale`.
42-
Stop the owning daemon with `agent-device daemon stop --state-dir <dir>`; add `--clean` for retained runners.
43-
Release dead owners with `agent-device device release --stale`.
44-
If blocked, report the session, state directory, and status output. Never hide incomplete cleanup.
45-
The physical runner handoff checklist lives in `docs/evidence/ios-physical-runner-handoff-2026-09-19.md`.
41+
If cleanup is stuck, run `agent-device device status --stale`.
42+
To stop the owning daemon, run `agent-device daemon stop --state-dir <dir>`. For retained runners, add `--clean`.
43+
To release dead owners, run `agent-device device release --stale`.
44+
If you are blocked, report the session, state directory, and status output. Always report incomplete cleanup.
45+
The physical runner handoff checklist is in `docs/evidence/ios-physical-runner-handoff-2026-09-19.md`.
4646

4747
## Platform policy
4848

49-
Apple runner changes run `pnpm check:xctest-selection` and build the affected target.
50-
Swift `#if` guards own XCTest classification. Do not maintain a second test-name list.
51-
Use macOS host lanes for pure decisions and simulator lanes for iOS/XCTest semantics.
49+
For Apple runner changes, run `pnpm check:xctest-selection` and build the affected target.
50+
Swift `#if` guards own the XCTest classification. Do not keep a second list of test names.
51+
Use macOS host lanes for pure decisions. Use simulator lanes for iOS and XCTest semantics.
5252
If system policy rejects an unsigned host bundle, rebuild with `CODE_SIGN_IDENTITY="Apple Development"`
53-
or select an identity from `security find-identity -v -p codesigning`.
54-
First runs need XCUITest automation permission.
53+
or an identity from `security find-identity -v -p codesigning`.
54+
The first run needs XCUITest automation permission.
5555

56-
Keep Apple target changes synchronized across the kernel model, runtime-fact admission, dispatch,
56+
When you change Apple targets, synchronize the kernel model, runtime-fact admission, dispatch,
5757
discovery, and xctestrun preparation. Simulator-set scoping must not hide the host macOS target.
5858
HarmonyOS has no provisioned CI device or HDC. Mocked tests do not replace local hardware evidence.
59-
Read live smoke harnesses before running them; their environment contracts live in their entry files under `test/integration/`.
59+
Before you run a live smoke harness, read it. Its environment contract is in its entry file under `test/integration/`.
6060

61-
If a sandbox rejects localhost with `listen EPERM`, use host access when permitted.
62-
Inspect the underlying error first. A generic startup or cleanup failure does not prove a sandbox cause.
61+
If a sandbox rejects localhost with `listen EPERM`, use host access, if permitted.
62+
First, examine the underlying error. A generic startup or cleanup failure does not prove a sandbox cause.

‎docs/agents/issue-tracker.md‎

Lines changed: 19 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,34 @@
11
# Issue Tracker: GitHub
22

3-
Issues and PRDs for this repo live as GitHub issues in `callstack/agent-device`. Use the `gh` CLI for issue operations.
3+
Issues and PRDs for this repo are GitHub issues in `callstack/agent-device`. Use the `gh` CLI for issue operations.
44

55
## Triage scope
66

7-
External PRs are not task requests in the issue-triage queue. Reading linked PRs to verify an issue's
8-
dependencies is allowed; it does not expand the task into PR maintenance.
7+
An external PR is not a task request in the issue-triage queue. To verify issue dependencies, you can read linked PRs.
8+
Do not maintain those PRs.
99

1010
## Conventions
1111

12-
Write issues as implementation contracts: purpose, required behavior, observable completion
13-
conditions, and dependencies. Include an API, data shape, or CLI example for boundary changes.
12+
Write each issue as an implementation contract: purpose, required behavior, observable completion
13+
conditions, and dependencies. For a boundary change, include an API, data shape, or CLI example.
1414

15-
Sandboxed `gh` may lack host login credentials. Retry the focused command with host authentication
16-
access when permitted before treating it as an authentication failure. Do not reconfigure
17-
credentials; report the command and remaining blocker if the retry fails.
15+
If sandboxed `gh` fails with an authentication error, run the same command with host access, if permitted.
16+
Do not reconfigure credentials. If it fails again, report the command and blocker.
1817

1918
For label meanings and state flow, see `docs/agents/triage-labels.md`.
2019

20+
## Current state
21+
22+
When you change a decision or the scope of your issue, post a comment that starts with `Decision:`.
23+
After a PR merges on your umbrella issue, post a `Current state:` comment: merged PRs, open PRs, and the next step.
24+
Before you continue work, read all `Decision:` comments (newest wins per topic) and the newest `Current state:` comment.
25+
2126
## Dependencies and sequencing
2227

23-
- Treat `Blocked by: ...` lines, linked prerequisite issues, and branch-base notes as part of the issue contract.
24-
- Before scheduling or reviewing work, check blockers and decide whether the work should wait, stack on a prerequisite branch, or explicitly rescope.
25-
- Do not mark an issue ready for implementation while prerequisite semantics are unresolved.
26-
A dependent PR can be published with its base and blockers explicit; merge-readiness follows
27-
`docs/agents/pull-requests.md`.
28-
- When closing an umbrella issue, verify child issue states and the key implementation PRs instead of relying only on checked boxes.
28+
- `Blocked by: ...` lines, linked prerequisite issues, and branch-base notes are part of the issue contract.
29+
- Before you schedule or review work, examine the blockers. If one is open, decide: wait, stack on its branch, or rescope explicitly.
30+
- If the prerequisite semantics are not resolved, do not mark the issue as ready for implementation.
31+
You can publish a dependent PR with its base and blockers explicit.
32+
- Before you close an umbrella issue, verify child issue states and key implementation PRs, not only checked boxes.
2933

30-
For authorized issue publication, use GitHub issues. A skill workflow alone is not authorization
31-
to publish.
34+
A skill workflow alone does not authorize you to publish an issue.

0 commit comments

Comments
 (0)