# Subagent Briefs

Course: [Intent Engineering](https://www.devtutorials.ai/learn/intent-engineering) · Section: Real Codebases
Source: https://www.devtutorials.ai/learn/intent-engineering/real-codebases/subagent-briefs

> Write a brief a subagent can follow and an orchestrator can merge: goal, inputs, allowed tools, output shape and done-when.

## A Brief That Says Please

Some agents hand work to other agents.

Two words to know:

- **Orchestrator** = the main agent. It splits a big task into small ones.
- **Subagent** = a helper agent. It does one small task and sends back the result.

The orchestrator gives each subagent a short instruction.

- **Brief** = the instruction an orchestrator gives a subagent.

In this example, the brief is very friendly:

```text
Please fix the dates in the export. Thanks!
```

The subagent tries hard. But it has to guess:

- It edits two files.
- It changes a helper nobody asked about.
- It sends back a long sentence about what it did.

None of this helps the orchestrator.

**Simple lesson:** a friendly brief is not a clear brief. The subagent only knows what the brief says.

### A Real-World Example

An editor tells a reporter, "Write something about the match."

The reporter writes about the weather, the food and the parking.

The story is long, but the editor cannot use it.

An orchestrator and a subagent work the same way. A vague brief gets a useless answer.

Click the button and open the **Agent** tab.

- **Agent tab:** five **GUESS** lines. Each one is a part the brief left out.
- **Preview & Checks:** the orchestrator says **REJECTED**.

The subagent worked hard. The problem is the shape of the brief.

**Simple lesson:** the orchestrator is a program. It can only use an answer in the shape it expects.

## TL;DR

1. **Brief** = the instruction an orchestrator gives a subagent.
2. A brief is a tiny spec for one task.
3. A good brief has five parts:
   - **Goal** = the one task to do
   - **Inputs** = what to read
   - **Tools** = what it may use
   - **Output** = the exact shape of the answer
   - **Done when** = the check that says the task is finished
4. Give only the tools the task needs.
5. Ask for the answer as data with exact fields, like JSON.
6. A sentence back is rejected. Data with every field is merged.

## What You Will Learn

In this lesson, you will learn:

1. What an orchestrator and a subagent are.
2. The five parts of a good brief.
3. Why a subagent should get only a few tools.
4. Why the answer must have a fixed shape.
5. How "Done when" stops work at the right time.

**About the agents in this lesson**

- The orchestrator and the subagent are **simulated**. They are not real AI.
- A missing part of the brief always causes the same guess.
- The orchestrator merges an answer only when every field it needs is there.

## The Five Parts of a Brief

Watch a brief grow, one part at a time:

Each new part turns one guess into a clear answer.

With all five parts, the subagent has nothing left to guess.

### Goal

**Goal** = the one task the subagent must do.

Example:

```text
Goal: Format every date in the export as YYYY-MM-DD.
```

A clear goal keeps the subagent on one task.

A vague goal invites extra changes nobody asked for.

### Inputs

**Inputs** = the exact things the subagent should read.

These can be:

- files
- requirements
- acceptance criteria
- design notes

Example:

```text
Inputs: src/features/export/exportOrders.ts, AC-2 in spec.md
```

Without inputs, the subagent searches everywhere. It may change the wrong file.

### Tools

**Tools** = what the subagent is allowed to use.

A small fix usually needs only three:

- read files
- edit files
- run tests

Also say what is not allowed:

```text
Tools: read, edit, test. No push, no install.
```

A subagent with too many tools can do things nobody wanted.

### Output

**Output** = the exact shape of the answer.

Example:

```text
Output: JSON {"file": string, "changed": number, "testsPassed": boolean}
```

The orchestrator does not read stories. It reads fields.

Every field it needs must be there.

### Done When

**Done when** = the check that says the task is finished.

Example:

```text
Done when: AC-2 (the date check) passes.
```

Without it, the subagent may:

- stop too early
- stop too late
- skip the tests

**Simple lesson:** five parts, five fewer guesses.

## Structured Output

### Why a Sentence Is Rejected

The orchestrator is a program.

A program cannot reliably read a sentence like this:

```text
I updated the dates and everything should be fine now.
```

But it can read this:

```json
{
  "file": "exportOrders.ts",
  "changed": 3,
  "testsPassed": true
}
```

So the brief must say the exact shape of the answer.

Watch the orchestrator check three answers:

- A sentence is rejected.
- Data with a missing field is rejected.
- Data with every field is merged.

**Important:** "Return a summary" is not an output shape.

- It invites a long sentence.
- Name a format, like JSON.
- List every field the orchestrator needs.

## Limit the Tools

### Only What the Job Needs

A date fix needs to read, edit and test.

It does not need to:

- push code
- install packages
- deploy the app

**Least privilege** = give only the tools a task needs, nothing more.

Watch three different Tools lines:

Fewer tools means less can go wrong.

**Simple lesson:** if the task does not need a tool, do not give it.

### Lab Exercise: Write a Brief the Orchestrator Can Merge

The orchestrator sends you a note. It tells you:

- the fields it needs in the answer
- the tools a subagent may use
- the file to change
- the check that means done

Use the note to write all five parts of the brief.

Press **Check my spec**.

If every part is clear, the orchestrator says **MERGED**.

**Copy field names exactly.**

- `testsPassed` and `tests_passed` look alike to you.
- To a program, they are two different fields.

## Done When

### Stop at the Right Time

A good "Done when" stops two problems:

- stopping before the tests run
- working forever

It should name a check that clearly passes or fails.

Example:

```text
Done when: AC-2 passes.
```

**Simple lesson:** a subagent needs a finish line it can test.

## What Changes per Tool

| Tool | Where subagents are defined |
|---|---|
| Claude Code | `.claude/agents/<name>.md` |
| Codex | `.codex/agents/<name>.toml` |
| Cursor | `.cursor/agents/<name>.md` |
| Spec Kit | Through the agent it runs on |
| Kiro | Through the agent it runs on |

The file format is different in each tool.

The five parts of a good brief stay the same.

## Common Mistakes

| Mistake | Wrong idea | Correct idea | What goes wrong |
|---|---|---|---|
| A one-line brief | "It is smart. It will understand." | Write all five parts. | Extra edits, the wrong file, and a sentence back. |
| "Return a summary" | "A summary is an output." | Ask for JSON with exact fields. | The orchestrator rejects the answer. |
| A missing field | "Close enough is fine." | List every field the orchestrator reads. | The merge fails. |
| Every tool allowed | "More tools, more help." | Allow only read, edit and test. | It may push half-done work. |
| No "Done when" | "It knows when to stop." | Write "Done when AC-2 passes." | It stops before testing. |
| Two tasks in one brief | "Fewer briefs, less work." | One task per brief. | You cannot tell which part failed. |

## Exercises

These exercises help you practise writing briefs.

Press **Check** when you are ready. Use **Show Hint** if you get stuck.

## What to Remember

- An orchestrator hands out work with briefs.
- A subagent knows only what the brief says.
- Every brief needs five parts: Goal, Inputs, Tools, Output and Done when.
- The answer must be data with exact fields, not a sentence.
- Field names must match exactly.
- Give only the tools the task needs.
- "Done when" should name a check that passes or fails.
- One brief, one task.

## Further Reading

- [Effective harnesses for long-running agents, by Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents): handing work between agents and sessions.
- [Harness engineering, by OpenAI](https://openai.com/index/harness-engineering/): structure that makes agent output usable.
- [GitHub Spec Kit](https://github.com/github/spec-kit): tasks that can be handed out one by one.

Next: **Spec Review**. You will learn to review the agent's work against the spec, not against your own taste.