All pages

Agentic development foundations · Lesson 2.1 · 12 min

Write a task brief

Goal, constraints, done-when: a brief an agent with no other context can finish.

After this lesson you can write a brief that an agent with no other context can finish without coming back to you: a clear goal, the constraints that matter, and a done-when it can check. You'll also save a good brief so you never write the same one twice.

Time: 12 minutes · Works on: macOS app.

Why a brief

A request is what you type when you're in a hurry. A brief is what you'd hand a contractor who has never seen the codebase, can't ask you questions, and will be judged on whether the result works. Write for that reader. An agent starts each conversation with no memory of your intentions, and it will fill every gap you leave with a guess.

The cost of a weak brief isn't a failed run. It's a run that looks successful: a confident summary, a green test you didn't ask for, and a change that solves a slightly different problem than yours.

The three parts

Every brief needs three things. Anything else is optional.

Goal. What should be true when the work is finished, in terms of behaviour, not code. "Users can export their invoices as CSV" is a goal. "Add an exportCsv method" is an implementation guess, and it may be the wrong one.

Constraints. What the agent must not do, or must do a certain way. These are the decisions you've already made and the risks you already know about:

  • files or modules that are off limits
  • libraries to use or avoid
  • interfaces that must not change
  • performance, security or compatibility limits
  • how big the change is allowed to be

Done when. The check that proves the goal is met, written so the agent can run it itself. A command and its expected result is ideal. A list of observable behaviours is next best. "Looks good" is not a done-when.

Optional parts that pay off

  • Context. Where to start reading, what you've already tried, and anything surprising about this code. Point at files instead of pasting them.
  • Out of scope. Things the agent will be tempted to fix along the way. Naming them stops a small task from turning into a large diff.
  • What to report. What you want back at the end: a summary of the approach, the commands it ran, open questions.

A worked example

Here is a brief for a real-sized task.

## Goal
Users can download their invoices as a CSV file from the Billing page.
One row per invoice: date, number, amount, status.

## Context
The Billing page is `web/app/billing/page.tsx`. Invoices come from
`GET /api/invoices`, implemented in `server/routes/invoices.ts`.
Amounts are stored in cents.

## Constraints
- Generate the CSV on the server. Don't add a client-side CSV library.
- Don't change the shape of the existing `GET /api/invoices` response.
- Format amounts as dollars with two decimals.
- Keep the change under roughly 200 lines.

## Out of scope
The invoice table styling, and the pagination bug in #142.

## Done when
- `GET /api/invoices.csv` returns `text/csv` with a header row.
- A new test in `server/routes/invoices.test.ts` covers an empty list
  and a list of two invoices, and `npm test -- invoices` passes.
- The Billing page has a "Download CSV" link that hits the new route.

## Report
List the files you changed and anything you weren't sure about.

Notice what it doesn't say. It doesn't tell the agent how to write the CSV encoder or which function names to use. It states the outcome and the limits, and leaves the implementation to the agent.

Common mistakes

  • Describing the fix instead of the problem. If you already know the fix, say so as a constraint. If you don't, describe the symptom and let the agent investigate.
  • A done-when the agent can't run. "Works in production" can't be checked from a laptop. Turn it into a test or a command.
  • Constraints buried in prose. Put them in a list. An agent skims a long paragraph just as a person does.
  • One brief, three tasks. If the done-when has checks for three unrelated things, it's three briefs.
  • Pasting whole files. Name the file and let the agent read it. Pasted code goes stale the moment the agent edits the original.

Do it in TRMNLY

Write one brief, give it the evidence it needs, and save it for reuse.

  1. Open the Agent tab (⇧⌘\). Write the brief straight into the composer. ⇧↩ adds a line, so you can use headings and lists. The draft belongs to its chat and survives switching chats or quitting the app.

  2. Point at files with @. Type @ and a path, with autocomplete, to include that file's contents in this message only. Use it for the one or two files the agent must read first. Quote a path with spaces, like @"src/My Folder/file.ts".

  3. Show, don't describe. For a visual bug, press ⌃⌘S from any app and drag over the problem. The screenshot lands in the composer, attached to your brief. You can also paste an image with ⌘V or drag one in from Finder.

  4. Pin what every brief needs. If every task in this project depends on the same schema or style guide, select it in the Files tab and use Pin to agent. It's then in the agent's context on every turn, and you can leave it out of the brief.

  5. Send it, then check the first few tool calls. If the agent starts in the right files, the brief worked. If it heads somewhere else, stop it with ⌘. and add the missing context.

  6. Save the shape as a prompt. Open Prompts in the right sidebar and click +. Give it a Prompt name such as "Feature brief", and paste the brief's skeleton as the Text, with {{variables}} for the parts that change:

    ## Goal
    {{goal}}
    
    ## Constraints
    - Don't change public interfaces in {{module}}.
    - Keep the change small enough to review in ten minutes.
    
    ## Done when
    {{check}} passes.
    
    Work on branch {{branch}}.
    

    {{branch}} fills in from the focused pane; the others are custom variables.

  7. Right-click the saved prompt and choose Run with Variables…. Fill in the fields, check the Preview, and choose Send to Agent.

  8. Brief a CLI in a pane the same way. If you run Claude Code in a pane, ⌃⇧⌘S saves a screenshot into the project's .trmnly/attachments/ and types its path at the CLI's prompt. Saved prompts work there too: click a row to paste it into the focused pane.

  9. Keep briefs that aren't for now. Put a brief in a card's Notes on the Tasks board (More ▾ → Tasks), so the agent, or a fleet worker, can pick it up later by its # number.

Check yourself

  • Your brief has a goal, constraints and a done-when the agent can run itself.
  • The agent finished without asking you a question it could have answered from the brief.
  • You attached a screenshot or an @ file instead of describing it.
  • A saved prompt with custom variables opened the run sheet and sent a filled-in brief to the agent.

Go further