docs(agents): write agent docs in ASD-STE100 and remove misleading docs

[thymikee]

Summary

Agent docs now use ASD-STE100 Simplified Technical English. Material that misled agents with small context windows is removed.

• AGENTS.md and all docs/agents/*.md: rewritten in STE, one commit per file. Eight rules that were stated in two places are deleted; each deletion has a git grep proof in its commit. AGENTS.md now requires STE for agent docs. It also routes new shared constraints to task docs, not private agent memory, and warns that all worktrees share git stash.
• issue-tracker.md: post Decision: <topic>: comments when a decision or the scope changes. Post a Current state: comment on an umbrella issue after each merge.
• review.md: read an ADR's Status and "Rules at a glance" first. A bulk rewrite of prose needs a review by another model provider that compares each changed sentence with the base.
• docs/agents/domain.md is merged into CONTEXT.md.
• cli-flags.md and code-ownership.md: the owner paths are corrected.
• device-foldable.md: the DEVELOPER_DIR pin is removed (devicectl is the system CoreDevice tool). On devicectl 651.13.5, fold reports fold-pose-dispatched-unverified.
• The three tracked files in the ignored .device-evidence/ folder are untracked. They held task-scoped coordinator instructions.
• Three old notes in docs/ are deleted. The code now contradicts each one.
• CONTRIBUTING.md now says to commit first and then run check:affected --run --head <commit>.

Byte budgets stay inside their limits: AGENTS.md is 3,961 of 4,000, CONTEXT.md is 10,997 of 11,000, and docs/agents is 39,983 of 40,000. The ADR and help rewrites are in separate PRs: #3729, #3730, #3731, and one help PR to come.

Validation

• Rebased on origin/main (resolved conflicts with docs(agents): simplify review scope and follow-up rounds #3741 in review.md and pull-requests.md; main's meaning kept). Tested SHA: 82882bb44c.
• pnpm check:affected --run --head 82882bb44c passed with exactCommit=true: format, lint, typecheck, layering, fallow, build, vitest-related, and agent-guidance.
• A cross-provider (GPT) sentence review of the rebased head found 11 items. 2 are fixed in 82882bb44c. The others repeat an owner rule elsewhere, or are intentional, sourced changes.
• The code changes are comments only, in a test fixture and in command-result.ts. No device run is required.

[cubic-dev-ai]

All reported issues were addressed across 4 files

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

The docs change in 8cec04a reads well and CI is green (9 checks, none failing), but it drops two rules that still need to apply. I did not check every hunk of the four files, and I did not search for other readers of the Decision: prefix.

The disjoint-files rule is gone from Worktree setup in AGENTS.md. Parallel workers can again get overlapping files. The merge-readiness pointer to docs/agents/pull-requests.md is gone from issue-tracker.md. Please restore both rules, and make Decision: carry a topic key so "newest wins per topic" has something to match on. The next step before merge is those three changes.

Not blocking: you can take or leave these. In AGENTS.md the old note that check:affected and check serialize also vanished, so the replacement could also name the rule of distinct devices. In issue-tracker.md, Current state: could be read only on umbrella issues, when present. In device-verification.md, "also failed attempts" could read "Close each session you opened manually, including failed attempts."

The open inline threads on the topic key (#3723 (comment)), the disjoint-files rule (#3723 (comment)), the unconditional Current state read (#3723 (comment)), and the dropped pull-requests.md pointer (#3723 (comment)) still stand. The lower-priority thread on the failed-attempts clause also still applies (#3723 (comment)).

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.32 MB	5.32 MB	+192 B
Package (unpacked)	5.32 MB	5.32 MB	+192 B
Package (download)	1.60 MB	1.60 MB	+64 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	29.8 ms	29.6 ms	-0.2 ms
CLI --help	82.1 ms	82.6 ms	+0.5 ms

[cubic-dev-ai]

1 issue found across 11 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/agents/device-foldable.md">

<violation number="1" location="docs/agents/device-foldable.md:4">
P1: Removing the `DEVELOPER_DIR` pin leaves agents on hosts whose `xcode-select` points to an older Xcode without a working command. The repo's own Duo harness and README still require that pin and fail without it. Restore the toolchain instruction for these commands, or keep the note that `xcode-select` may select an older Xcode.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Removing the DEVELOPER_DIR pin leaves agents on hosts whose xcode-select points to an older Xcode without a working command. The repo's own Duo harness and README still require that pin and fail without it. Restore the toolchain instruction for these commands, or keep the note that xcode-select may select an older Xcode.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/agents/device-foldable.md, line 4:

<comment>Removing the `DEVELOPER_DIR` pin leaves agents on hosts whose `xcode-select` points to an older Xcode without a working command. The repo's own Duo harness and README still require that pin and fail without it. Restore the toolchain instruction for these commands, or keep the note that `xcode-select` may select an older Xcode.</comment>

<file context>
@@ -1,9 +1,7 @@
-The iOS 27.1 runtime comes only with its Xcode. `xcode-select` can select an older Xcode.
-For each command, set the toolchain explicitly:
-`DEVELOPER_DIR=<Xcode-27.1>/Contents/Developer xcrun devicectl device info displays --device <udid>`.
+To list the panels, run `xcrun devicectl device info displays --device <udid>`.
 
 - Panels: the command lists each integrated panel with `backlightState`. Only the lit panel permits capture.
</file context>

Suggested change

	To list the panels, run `xcrun devicectl device info displays --device <udid>`.
	To list the panels, run `DEVELOPER_DIR=<Xcode-27.1>/Contents/Developer xcrun devicectl device info displays --device <udid>`. The `xcode-select` default may point to an older Xcode, so set the toolchain explicitly.

[thymikee]

Not restored, because the pin does not select devicectl. I checked on this host: each Xcode's usr/bin/devicectl is a shim that runs /Library/Developer/PrivateFrameworks/CoreDevice.framework/.../devicectl. Both Xcode 26.2 and 27.1 expect 651.13.5 and report 651.13.5, and Xcode 26.2 simctl also lists the iOS 27.1 runtime and the Duo. The harness README keeps its own DEVELOPER_DIR requirement. I left this thread open for the maintainer.

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

The two earlier findings are still open at 01e5eb2, and the code change itself is fine. I fixed nothing myself. The AGENTS.md ownership wording now keeps the rule, so that part is done. No conflicts. Only Smoke Tests are still queued or running, and this docs-only change does not touch the device smoke routes, so I read that as unrelated.

The new text at docs/agents/issue-tracker.md:31 says a dependent PR can be published, but it gives no merge condition. The old text sent merge-readiness to docs/agents/pull-requests.md. Without it, a reader can treat a dependent PR as ready while its prerequisite is open. Please restore "merge-readiness follows docs/agents/pull-requests.md".

docs/agents/device-foldable.md:3 drops the DEVELOPER_DIR=<Xcode-27.1> pin from the devicectl commands. It also drops the bullet that the beta accepts only the iPhone Duo device type. If xcode-select points at an older Xcode, foldable verification fails or picks the wrong device type. Please restore both, or show that 27.1 is no longer beta. Does the repo still treat 27.1 as beta?

Not blocking: the "newest wins per topic" rule at docs/agents/issue-tracker.md:22 has no topic key, so a newer decision on one topic overrides unrelated ones, and requiring "Decision: : ..." and matching on the topic would fix it. You can take or leave it.

On the open inline threads, four of them still apply: no topic key for Decision, merge-readiness pointer missing, DEVELOPER_DIR pin missing, and Duo-only bullet dropped. Three more P2 threads still apply: Current state read unconditionally, the unnamed check in "Examine each result", and one P3 on ambiguous "also failed attempts". The AGENTS.md:50 thread no longer applies, because each worker now gets different files and a different device, which keeps the ownership rule, so you can resolve it. I did not check the CONTRIBUTING.md and review.md threads.

I read only the diffs of AGENTS.md, device-verification, device-foldable and issue-tracker. I did not check the other rewritten docs for dropped conditions, and I did not search for links to the deleted docs. Before merge, restore the merge-readiness pointer and the Xcode pin or Duo-only note, add a topic key to Decision:, and answer the open threads above.

This review covers 01e5eb2. The newer head 27473b1 only edits one row in docs/agents/code-ownership.md, which does not touch these findings.

[thymikee]

The earlier docs fixes look good, but one change still needs a fix before merge. At 27473b1 the rule in docs/agents/issue-tracker.md#L31 says only "You can publish a dependent PR with its base and blockers explicit." The old text also said that merge-readiness follows docs/agents/pull-requests.md, and that pointer is gone. An agent can now read this line as permission to merge while the prerequisites are still open. Please restore the pointer, for example by appending "Merge-readiness follows docs/agents/pull-requests.md." https://github.com/callstack/agent-device/blob/27473b1/docs/agents/issue-tracker.md#L31

I read only issue-tracker.md and AGENTS.md at this commit. I did not compare the other rewritten docs rule by rule, and I did not check every inline thread. The open thread on the same missing pointer still applies: #3723 (comment). Two more still apply: the "Decision:" topic rule at #3723 (comment) and the "Current state:" read rule at #3723 (comment). The thread on AGENTS.md:50 no longer applies, because that line now says different files and a different device per worker, so please resolve it: #3723 (comment). Seven lower-priority threads are still open and I did not verify them.

Only the Smoke Tests check is still queued or running. This change touches docs and type comments, not the device smoke routes, so that check is likely unrelated. There are no conflicts. Before merge, the pointer to docs/agents/pull-requests.md must be back at issue-tracker.md line 31.

[cubic-dev-ai]

All reported issues were addressed across 1 file (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

The earlier finding on docs/agents/issue-tracker.md is still open at 0be63cd. The line at https://github.com/callstack/agent-device/blob/0be63cd/docs/agents/issue-tracker.md#L31 reads only "You can publish a dependent PR with its base and blockers explicit." The old pointer to docs/agents/pull-requests.md is gone, and this update did not touch the file. An agent can read that line as permission to merge while prerequisites are open. Please append "Merge-readiness follows docs/agents/pull-requests.md." to it.

Not blocking, and you can take or leave it: the Declarations table in docs/agents/code-ownership.md and AGENTS.md no longer name packages/daemon/src/core/daemon-command-registry.ts, which AGENTS.md used to route daemon route ownership and request-policy traits to, so a row for it would restore that.

The open inline threads on the code-ownership row, the merge-readiness line, "Decision:" (#3723 (comment)), the weakened ownership rule in AGENTS.md (#3723 (comment)) and the unconditional "Current state:" read (#3723 (comment)) still apply, as do the ones on the DEVELOPER_DIR pin removal (#3723 (comment)), the device-verification line with no check (#3723 (comment)), the 27.1 beta bullet (#3723 (comment)), the dropped narration review target (#3723 (comment)) and the half-open panel list (#3723 (comment)). Three lower-priority threads still apply. The thread at device-foldable.md:22 (#3723 (comment)) no longer applies, because 0be63cd rewrote that hinge-angle instruction, so please resolve it.

The failing Repo Guards and Lint/Typecheck checks match main (the linux.gap error) and #3740 is pending for them. This PR changes only docs, so I see no link to the Smoke and Integration failures either. I did not read every rewritten file for changed meaning, and I did not check the Duo Xcode, DEVELOPER_DIR or devicectl claims on a host. Before merge, please restore the pointer and resolve or dismiss the open threads.

[thymikee]

Follow-up at 82882bb44c. I rebased the branch on origin/main. The conflicts with #3741 were in review.md and pull-requests.md. I kept main's meaning and wrote it in STE.

Commits: 6c5eee4558 adds "Merge-readiness follows docs/agents/pull-requests.md." to issue-tracker.md:31. 72321c11db adds the Decision: <topic>: key and limits the Current state: read to umbrella issues. 315486e9e5 fixes device-verification, 2a5167a0be restores the Duo-only bullet and the lit-panel caveat, 052bdb4939 restores the daemon predicate owner row, and de031a9a50 and 82882bb44c fix CONTRIBUTING and the self-review findings. 25eac88333 and ce05389b0e delete duplicate lines to make byte room (docs/agents is 39,983 of 40,000).

CI: everything passes at 82882bb44c. The Lint, Repo Guards, and Integration failures from before went away after the rebase (#3740 merged on main). iOS Smoke failed once with APP_NOT_RUNNING at the deep-link wait. It passed on rerun (attempt 2), and main's last two runs pass, so I read it as a flake.

Threads: 10 fixed, 2 already fixed, 1 rejected and left open: DEVELOPER_DIR pin. On this host, both Xcode 26.2 and 27.1 shims run the system CoreDevice devicectl, version 651.13.5.

Validation: pnpm check:affected --run --head 82882bb44c passed with exactCommit=true.

[thymikee]

At 82882bb the docs changes look good, and the fixes from the earlier review at 0be63cd are in. I found nothing new that needs a change. All 18 checks pass; the diff is docs plus one comment-only TypeScript change and one fixture comment, so the checks cover format, lint, typecheck and doc prose only. No conflicts. I read the pull-requests, review, issue-tracker, code-ownership, device-foldable, device-verification and testing docs and the AGENTS.md rules in full. For the other rewritten files I relied on the earlier reviews and your sentence review, which I could not inspect. I ran no host command. The claims about the system devicectl shim and the Xcode 26.2 simctl listing come from your thread reply.

On the open threads: please resolve the Cubic P1 thread on device-foldable.md, because that doc uses system CoreDevice and does not route to the Duo harness that needs DEVELOPER_DIR (#3723 (comment)). The other twelve Cubic threads are fixed at this commit and can be resolved too: issue-tracker.md lines 25, 27 and 33 (discussion_r4295719207, discussion_r4295719244, discussion_r4295719249), AGENTS.md line 46 (discussion_r4295719232), device-verification.md (discussion_r4295719265, discussion_r4296400303), device-foldable.md lines 27, 23-24 and 13,22 (discussion_r4296400312, discussion_r4297867509, discussion_r4297867531), CONTRIBUTING.md (discussion_r4296400323), review.md line 28 (discussion_r4296563604) and code-ownership.md line 13 (discussion_r4296959746).

After you resolve that thread, the PR is ready for human review.

[thymikee]

The code review at 82882bb is still clean, but the branch now conflicts with main after the latest merges. Please rebase onto main and resolve the conflicts. I removed the ready-for-human label until the branch merges cleanly again.