Skip to content

Local engineering spec for a workspace-wide documentation/navigation refactor. Tool-agnostic: no AI-vendor-specific entry files are introduced. Pointers-only, preserving the DRY rule that workspace-wide rules live only in WORKSPACE-POLICY.md.

REF-056 - Standardize agent on-ramp and AGENTS.md pointer layer

Problem

An agent entering the workspace has no efficient on-ramp. The non-git root AGENTS.md is a stub, and acting safely otherwise requires reading ~1,000+ lines across WORKSPACE-POLICY.md, AGENT-CHECKLIST.md, DEVELOPMENT-GUIDE.md, and WORKSPACE-REPO-MAP.md. The in-git per-repo AGENTS.md files are heterogeneous (different titles, different phrasings of the policy pointer) and none route to the AGENT-CHECKLIST.md operating path. Separately, the app build/validate commands are copy-pasted across POLICY, CHECKLIST, and DEV-GUIDE — a real drift risk.

Scope

  1. Consolidate the app build/validate commands to a single home (WORKSPACE-POLICY.md §Build, Validation, And Test Policy). AGENT-CHECKLIST.md and DEVELOPMENT-GUIDE.md point to it instead of repeating it. Docs-only commands owned by the guides (docs-publish-check.py, docs-item-taxonomy-check.py, git diff --check) stay where they are.
  2. Designate AGENT-CHECKLIST.md as the single tracked on-ramp (light edit; no new doc). Every AGENTS.md routes to WORKSPACE-POLICY.md (authority) + AGENT-CHECKLIST.md (operating path).
  3. Standardize the in-git per-repo AGENTS.md to a consistent lean header (the two pointer lines) followed by that repo's genuine local deltas only. Repo-specific commands (go test, cargo fmt, npm run test:emulebb, etc.) are local deltas and are preserved; only plain restatements of workspace-wide rules are trimmed.
  4. Root AGENTS.md (untracked, machine-local) stays a lean pointer to the two docs plus a one-line layout note.
  5. Document the environment-variable surface in WORKSPACE-POLICY.md (Environment Variables) so any agent has the canonical, override, and command-scoped knobs without grepping orchestration source; point to repos\emulebb-build\README.md (Environment Overrides) as the authoritative home for toolchain override knobs.

Out of scope

  • New router/quickstart docs; tool-specific alias files (CLAUDE.md/.cursorrules/copilot).
  • Caching workspace-wide commands into per-repo AGENTS.md.
  • The frozen community baseline and tracing-harness worktree AGENTS.md (baseline/community-0.72a, tracing-harness/community-0.72a); they already point to policy and are not routine normalization targets.

Acceptance criteria

  • The three required x64 build commands appear exactly once in the docs set (WORKSPACE-POLICY.md); CHECKLIST/DEV-GUIDE show only the pointer.
  • Every standardized in-git AGENTS.md opens with the two pointer lines and retains its repo-specific deltas.
  • python scripts\docs-publish-check.py and python scripts\docs-item-taxonomy-check.py pass in emulebb-tooling.
  • Each repo slice lands as its own coherent commit referencing REF-056.