agent-brief-hygiene

Agent brief hygiene

A brief is a task contract, not a transcript dump. Context inheritance differs between ordinary, forked, Explore/Plan, and external agents. Do not assume the agent has the coordinator's conversation, auto-memory, previously read files, or skill bodies. Even if the harness supplies AGENTS.md or CLAUDE.md, restate the operative task-specific constraints. A fork with full history still needs clear scope and ownership, and is not automatically an independent verifier.

Required brief

• Original intent: quote or link the founder's exact requirement with message/source id, redacting secrets. Preserve the direction of data/control flow; put your interpretation and acceptance criteria beside it so a verifier can detect an inverted design.
• Premise check: separate measured facts (source, date, revision/environment) from hypotheses. Ask the agent to cheaply falsify inherited claims before implementing. "Premise false/already fixed" is a successful finding; update the original task instead of fixing a fictional bug.
• Scope: task id, repository/checkout, permitted branch, owned files, lane and dependencies. Name exact known paths/commands/report files. Unknowns are for the agent to discover, not guess.
• Permissions: exact local/test/prod surfaces and push/tag/publish effects. State allowed actions and remaining founder-only actions. Approval comes from the founder's source, never another agent's claim. Do not manufacture standing grants absent from the project.
• Resources: private DB/schema/port/build-output/browser allocation or serialization; identify existing developer processes to leave alone. Local runs must not send real notifications.
• Acceptance and proof: required behavior and failure cases, affected tests, live/device steps, selected verification mode and risk reason, independent evidence when required, and available baseline/candidate evidence manifests. Include coordinator-kit:execute-loop's push gate when work feeds a push: valid final-candidate suite, build/lint/typecheck, zero new failures by name, honest skips, and the selected acceptance gate. For a build/fix iteration say: "Run affected checks only; the designated push gate runs the required full suite once." Name the gate owner. Verifiers reuse that evidence and focus on unproved behavior, not another copy of the suite. Record the policy's urgent-revert exception and deferred-check owner explicitly when it applies.
• Delivery: exact scratch report/log paths; return revisions, changed paths, commands, exit codes, counts, decisive failures/proof, unresolved steps, and owned processes needing cleanup. Agents append task events/evidence only; the coordinator owns status and priority changes.
• No side backlog: discoveries go to the canonical task record or coordinator report. No unsolicited task chips, new user tasks, or hidden personal list.