docs(agents): write agent docs in ASD-STE100 and remove misleading docs
TH
3h ago+619+619+012345678901234567890123456789-1227-1227-0123456789012345678901234567890123456789
Summary
Agent docs now use ASD-STE100 Simplified Technical English. Material that misled agents with small context windows is removed.
AGENTS.mdand alldocs/agents/*.md: rewritten in STE, one commit per file. Eight rules that were stated in two places are deleted; each deletion has agit grepproof in its commit.AGENTS.mdnow requires STE for agent docs. It also routes new shared constraints to task docs, not private agent memory, and warns that all worktrees sharegit stash.issue-tracker.md: postDecision:comments when a decision or the scope changes. Post aCurrent 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.mdis merged intoCONTEXT.md.cli-flags.mdandcode-ownership.md: the owner paths are corrected.device-foldable.md: the Xcode 27.1 availability notes are removed.- 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.mdnow says to commit first and then runcheck: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,874 of 40,000. The ADR and help rewrites are in separate PRs: #3729, #3730, #3731, and one help PR to come.
Validation
- Tested SHA:
27473b1aee. pnpm check:affected --run --head 27473b1aeepassed withexactCommit=true: format, lint, typecheck, layering, fallow, build, vitest-related, and agent-guidance.- An independent Claude Opus review found 8 issues (2 medium, 6 low). All 8 are fixed in the last three commits.
- The code changes are comments only, in a test fixture and in
command-result.ts. No device run is required.