Writing Agent Briefs
Relevant source files
The following files were used as context for generating this wiki page:
An agent brief is a structured technical contract posted on a GitHub issue when that issue transitions to the ready-for-agent state. It serves as the authoritative specification for an Away From Keyboard (AFK) agent to execute tasks autonomously. While the original issue and discussion provide context, the brief defines the specific behavioral requirements and acceptance criteria for the agent. Sources: skills/triage/AGENT-BRIEF.md:1-5, skills/triage/SKILL.md:68-69
Core Principles
Durability Over Precision
Codebases evolve constantly. You must write briefs that remain valid even if files move, classes refactor, or lines shift.
- Describe interfaces, types, and behavioral contracts instead of specific file paths. Sources: skills/triage/AGENT-BRIEF.md:7-9
- Avoid referencing specific line numbers or assuming implementation structures remain static. Sources: skills/triage/AGENT-BRIEF.md:10-12
- Identify specific types, function signatures, or configuration shapes for the agent to locate. Sources: skills/triage/AGENT-BRIEF.md:9-10
Behavioral Specification
Define what the system must achieve rather than how to implement it. The agent performs its own codebase exploration and implementation decisions based on the required outcome. Sources: skills/triage/AGENT-BRIEF.md:14-16
- Focus on outcomes, such as field changes in a
SkillConfigor user-visible summaries. Sources: skills/triage/AGENT-BRIEF.md:17-20 - Avoid prescribing internal logic like "add a switch statement" or specific line edits. Sources: skills/triage/AGENT-BRIEF.md:18-22
Verifiable Acceptance Criteria
The brief must provide testable criteria so the agent knows when the work is complete. Each criterion requires independent verification. Sources: skills/triage/AGENT-BRIEF.md:24-26
- Use specific commands or observable results (e.g.,
gh issue listreturns specific labels). Sources: skills/triage/AGENT-BRIEF.md:27-28 - Avoid vague statements like "Triage should work correctly." Sources: skills/triage/AGENT-BRIEF.md:29
Scope Boundaries
Clearly define what is out of scope. This prevents the agent from making assumptions about adjacent features or over-engineering a solution. Sources: skills/triage/AGENT-BRIEF.md:31-32
Triage Workflow Integration
Agent Briefs are the final output of a successful triage process. The triage skill moves issues through a state machine, culminating in an agent-ready specification. Sources: skills/triage/SKILL.md:2-3
The diagram above shows the lifecycle of an issue from initial report to agent execution, highlighting the Brief as the entry point for automation. Sources: skills/triage/SKILL.md:20-29, skills/triage/AGENT-BRIEF.md:3-5
Triage Roles
Every triaged issue requires a category role and a state role. Sources: skills/triage/SKILL.md:20-22
| Role Type | Name | Purpose |
|---|---|---|
| Category | bug | Indicates broken behavior requiring a fix. |
| Category | enhancement | Indicates a new feature or improvement. |
| State | needs-triage | Initial evaluation required by maintainer. |
| State | needs-info | Waiting for reporter feedback. |
| State | ready-for-agent | Fully specified; requires an Agent Brief. |
| State | ready-for-human | Requires human judgment or external access. |
| State | wontfix | Issue will not be actioned. |
Sources: skills/triage/SKILL.md:10-18
Brief Structure and Template
The standard template ensures consistency across all tasks. Sources: skills/triage/AGENT-BRIEF.md:34-58
Key Components
- Category and Summary: High-level classification and a one-line goal.
- Current vs. Desired Behavior: Contrast the broken/status-quo state with the target state.
- Key Interfaces: Specify the types, signatures, or configurations that govern the change.
- Acceptance Criteria: A checklist of testable requirements.
- Out of Scope: Explicit list of excluded modifications.
Sources: skills/triage/AGENT-BRIEF.md:36-58
Relationship to Production Preflight
When an agent begins work from a brief, it initiates the production-preflight phase. This phase maps the behavioral obligations defined in the brief into a behaviorMap of JSON objects. Sources: skills/production-preflight/SKILL.md:12-14, skills/production-preflight/SKILL.md:205-215
This diagram illustrates how the brief acts as a bridge between high-level maintenance and low-level production execution. Sources: skills/triage/SKILL.md:68-69, skills/production-preflight/SKILL.md:9-11
Implementation Standards
Briefs must adhere to global project rules:
- Simplicity First: Briefs should not request "flexibility" or abstractions that are not explicitly needed. Sources: CLAUDE.md:17-20
- Mock Ban: All acceptance criteria must cross real production interfaces; mocks or stubs are not valid proof of completion. Sources: CLAUDE.md:32-37
- Root-Cause First: For bugs, the brief must address the source trigger rather than visible symptoms. Sources: CLAUDE.md:50-53
- Surgical Changes: Briefs should direct agents to touch only what is necessary, avoiding adjacent refactors. Sources: CLAUDE.md:57-61
Related Documents
Writing effective Agent Briefs enables the project to scale by allowing AI agents to handle routine bugs and enhancements with minimal human supervision. By focusing on durable, behavioral specifications and testable criteria, maintainers ensure that agents deliver high-quality code that aligns with architectural goals. Sources: skills/triage/AGENT-BRIEF.md:1-5, skills/triage/SKILL.md:2-3