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

TH
3h ago
+619-1227

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: 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 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.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,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 27473b1aee passed with exactCommit=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.