---
name: build-brainstorm
description: Start a new Introspection agent (Recipe) by drafting its cases from the owner's own material, asking only about the gaps, and getting the cases approved. Use when someone wants a new agent built and there is no approved set of cases yet. The first step of build; build-draft follows.
---

# Build: brainstorm

Turn what the owner wants into **cases** they approve: concrete situations, each with the input the agent receives, a good result, a bad result, and how it will be checked. The cases are the agent's specification and its first eval. Nothing is built in this step.

Understand the job before drafting a single case. How you get there depends on what the owner brings. With real material (their rules or guidelines, templates, examples of good results), the documents answer most questions: write the brief from them, confirm it, and draft early, asking only about the gaps. With little or none (a role description, a sentence of intent), interview first: a short conversation until you can write the brief, and only then draft. Either way the owner confirms the brief before they see cases, so approving the cases means approving tests of something you both agreed, not your guesses.

## Before you start

- If the repository already has cases in `evals/cases/`, resume from them: this step is done for every approved case, and you continue with the drafts that aren't approved.
- **Starting fresh, ask how to start** when the owner hasn't described the agent yet (a new build opens with only "help me build a new agent" or similar): call the question tool (`ask_user_question` in Pi, `AskUserQuestion` in Claude Code) before anything else; never write the question and its options in your reply, header "Start", "How do you want to start the new agent?", options "From scratch" (they describe what it should do; you draft its tests, then build and test it with them) and "From a template" (a starter Recipe they edit themselves), with one sentence before it on what building from scratch involves. Only once they choose "From scratch", ask in your reply (not with the question tool): "What should the agent do? Describe the problem it solves, who uses it and what they get back. If you have examples or documents it should follow, share them too." Say how, from the workspace note: on the platform, "attach them here" (they reach the inputs folder through the Files API); locally, "put them in `<the inputs folder's real path>`"; either way, or paste a link, and ask nothing else until they answer. For a template, ask in your reply which template repository to start from: a name in the introspection-recipes catalog, `template-starter` if they have none in mind. `introspection init` takes only catalog names (a private one works if their git credentials reach it); for a repository outside the catalog, say so and offer `template-starter`. Then propose a short name, run `introspection init <name> --template <template>` from the build folder, and check the result before handing it over: `introspection check` in it, then, from the build folder, `introspection tasks create runs/smoke-1 --work-dir <name> --prompt "hello"` to see it start and answer. If either fails, say what failed (a template that doesn't validate, a model Pi has no credentials for) rather than handing over a Recipe that won't run. When both pass, tell them to run `cd <name> && introspection local`, and stop: there are no cases to draft. If the owner's first message already describes the agent, they've chosen to build: skip the question.

- <!-- rule: R-readiness-one-line --> You need the `introspection` CLI (`npm i -g @introspection-ai/cli`). This step needs no login. `introspection init` already checked the CLI, Pi and the folder, and the workspace note says where `files/` and `outputs/` are: don't check them again or tell the owner about them. Say something only when something is missing, in one line.
- **Without the Operator's launcher** (in Claude Code, Codex, or wherever no workspace note says where `files/` and `outputs/` are), the current folder is one of two things; set it up yourself, without asking the owner to. An empty folder is the build folder: create `files/` and `outputs/` in it, and the agent's repository inside it as below. A folder scaffolded from a template (a git repository with `package.json` and `.introspection/`) is the agent's repository: work in it instead of creating another, create `files/` and `outputs/` in it, and add both to its `.gitignore`.
- <!-- rule: R-template-starter-keep-license --> Create the agent's repository first, so the cases have a home: from the build folder, `introspection init <name> --template template-starter && cd <name> && git checkout -b pr/<name>`. Don't make the folder first: `init` makes it, and inside one it makes another. Choose a short name from what the owner described and propose it in your first message without waiting; if they prefer another, rename the folder, the `package.json` name and `.introspection/<name>.yaml`. Use another template only when the owner names one, and keep its licence. Commit as you go: a session that stops resumes from these files.

## Steps

1. **Start from what's already here, then the job.** Look in the workspace's inputs folder (`files/`) yourself and read anything there at once, saying in one line what you found. It's normally empty at the start: then say nothing about it, since it's only where the owner can drop documents if they want to. If the owner hasn't said what the agent should do, ask only that, in one short sentence in your reply, not with the question tool (it has no options to choose between) ("What should the agent do?"). Don't ask for material up front, and don't explain how to share files or ask for access to `files/`: you already have it. Ask for a document only later, when a question in step 2 is one a document they may have would answer (rules or guidelines, a scoring guide, a template, an example of a result they liked), as an optional part of that question ("If you have a scoring guide, drop it in the files folder; otherwise, how should answers be judged?"). **A link the owner gives is material they've shared:** open it yourself at once, with the host's web tool or `curl -L` in a shell, save the readable text into `files/` and read the part that describes the job, before saying anything else; never print a whole page into the conversation, and delete the raw HTML. For Python use `uv run python` or `python3`, never `python`. Never say you can't read a link you haven't tried, and never ask them to paste what it shows; only if fetching fails, say so in one line and ask for the text. Keep each message short enough to read aloud, under about 40 words, and never repeat a request the owner has already seen. When they share a file, read it at once (see the shared instructions for Word and PDF), and keep it in the repository for build-draft to turn into a skill the agent loads at run time (a file nothing points to is invisible to the agent). Never ask them to summarise or redact their own material.
2. **Understand the job, then draft.**
   - **Write the brief:** one short paragraph in plain language saying who the agent is for and how a task starts, what each request brings, what it returns, what a good and a bad result look like, and what it must never do or must leave to a person, with any defaults you chose listed after it. These are items 1 to 7 of [the readiness check](references/readiness.md). **Name who reads each output.** When it isn't the person talking to the agent (a hiring team reading about a candidate, staff reading about a customer), propose two agents in the brief: one for the person in the conversation, which produces nothing they shouldn't see, and one for the other audience, run by them in a task of their own (item 6).
   - **When the material answers them,** write the brief from it straight away.
   - **When it doesn't, interview first.** Ask open questions in your reply, not with the question tool: discovery isn't a choice between options. One or two per message, each building on the last answer, starting with what the material leaves most open (who it's for, how it should come across, what happens with its result, what would make it go well or badly). Use the readiness check to pick the next question, not as a questionnaire, and default what wouldn't change what the agent does. Stop when you can write the brief, or after about five exchanges, whichever comes first; when something stays vague, show something concrete instead of asking again.
   - **Confirm the brief** before drafting: write it into Part A of `docs/DESIGN.md` and ask for a review of that file with `review_artifacts` (one item, labelled "The brief", with `section: "Part A"` so only the brief shows), so the owner reads it beside the conversation and approves it or says what to change. Revise it and review it again until it's approved. Without `review_artifacts`, ask with the host's question tool and the brief in an option's preview when it can show one (Claude Code's `AskUserQuestion`); otherwise, or when the result says nothing was shown, show the brief in your reply and ask what they'd change or add ("Anything you'd change or add?").
   - **Ask what it runs on, once the brief is approved:** one question with the question tool, header "Model", in plain words: which model the agent runs on and how hard it thinks. Offer the model you're running on first, as the recommended option: the workspace note names it in Pi; in another host (Claude Code, Codex) it's the model you run as, written as Pi names it (`anthropic/<model>`, `openai/<model>`). The agent runs in Pi, which has its own credentials, so run `pi --list-models` first and offer only models it lists; when it lists none from a provider you'd recommend, say Pi needs signing in (`pi`, then `/login`, or the provider's API key in the environment) and offer what it does list. Then one or two others it has credentials for. Label every option by what it means and name the model in the label itself, since some question tools show only labels: "Balanced: gpt-6-luna, medium (recommended)", "Faster and cheaper: …", "Most careful: …", never a bare "Recommended". In its description say when it suits this agent (a live conversation wants quick replies; a reviewer of transcripts can think longer); the owner can name another. With several agents, ask once, and say if one of them (a reviewer, say) should think harder. Record the answer under Exact values and set it in the agent's YAML (`ai.model`, and `thinking_level` when the model has one); never keep the template's model.
   - **Then draft from the confirmed brief and the material:**
     - the cases: the three or four that matter most for this agent, chosen from its must-haves and boundaries (positions it insists on, structural rules, how results should read) and the readiness kinds (ordinary work, ambiguity, missing input, partial failure, a request it should decline, such as conceding something the material forbids). Always one ordinary case and its most important boundary;
     - one example result on a sample, if the owner has one. Say which kind of input the sample should be, the one the agent receives in an ordinary case, not just "a sample" ("share one you received, as the agent would get it; it won't be committed").
       Keep the set to **three or four cases per agent** for this first build, so the owner reviews them in a few minutes and the build reaches a deployed agent quickly; list the others you'd add in Part A under "Later cases", for improve to turn into cases from real conversations. Mark every property that can be checked mechanically `check: code` ([cases](references/cases.md)).
       Write the drafts to `evals/cases/` in [the case format](references/cases.md), with approval fields empty.
3. <!-- rule: R-request-brings-list --> **Ask only about the gaps,** one decision per question: what each request brings, the scope for now, choices the material leaves open, and contradictions you found between documents. Use [the readiness check](references/readiness.md) to find gaps, not as a questionnaire: an item the material answers is not a question.
4. **Show the draft for approval.** First, in your message, a table of every case: id, title, and how it's checked. If no case is `code`, say in one line what that leaves untested, and offer to make the mechanical ones code checks. Then ask for the review with `review_artifacts`: each case, labelled with its id and title, with `docs/DESIGN.md` first only if it changed since the owner approved the brief ("C2: the candidate gives a vague answer"). The owner steps through them with each file shown beside the list, approving or requesting changes, with an optional comment. Without `review_artifacts`, review with the host's question tool when it can preview content (Claude Code's `AskUserQuestion` with `preview`): one question per file, up to four per call, headed with the case id, options "Approve" and "Request changes", each option's `preview` holding the file's text, so the owner reads each file beside the choice and types what to change. Without either, or when the result says nothing was shown, put one short block per case in your message instead (id and title, the situation, a good result, a bad result, how it's checked) and ask what they'd change or add, in neutral words ("Anything you'd change or add before I build it?"), with "Approve all" as the option. Present the cases as tests of the one job, not as features: if the owner wants fewer, say what will go untested. Change what they asked for and review just those files again; when a change request doesn't say what to change ("too vague"), ask one question about that case before editing it.
5. <!-- rule: R-approval-never-inferred --> **Record the approval** in each approved case: who, when, and the message they approved it in (for a review, "review_artifacts" and its time, and "not opened" when the result says so). Record only what the result says was approved. An approval is an explicit message, never inferred. Change a case's approval fields only from a review that included that case: never re-stamp or rewrite the others, even when the brief changes. Ask about an approved case again only when its file has changed since it was approved; one that hasn't keeps its approval and isn't shown again. Commit to `pr/<name>` and hand over to **build-draft**. Never read build-draft before every case is approved in a review: brainstorm writes the brief and the cases, not the Recipe's instructions or agents.

If the owner has no material, the interview in step 2 does the work: once the brief is confirmed, draft from it and a realistic example, and let their corrections build the cases.

## Where the build is

If the host keeps a task list (Claude Code's tasks, Codex's plan), add the build's steps when you start, Brainstorm, Draft and Review, and mark each done as it finishes. Pi shows them in its footer without this.

## How to ask

- **Use the host's question tool** for every decision: `ask_user_question` in Introspection and Pi, `AskUserQuestion` in Claude Code, or the equivalent elsewhere. One question, two or three short option labels; the tool numbers them and lets the owner type a different answer. Without a question tool, or with one that returns before the owner answers (Codex's `request_user_input_async` does), ask in text with numbered options and "or tell me otherwise", and end your turn there. Don't list the options in the question text. A request for files or other free text isn't a decision: ask it in your reply (step 1), and so are step 2's interview questions.
- **Every question must work read aloud:** under about 75 words, with enough context that a bare option number makes sense.
- **Ask only what changes a case,** and never re-ask what's answered or restate the owner's answers.
- **Speak the owner's language:** no tool, model or file names in questions or cases, unless they're an engineer.
- **Find out what the agent must reach** for each case (email, a Drive folder, an internal API). A case that needs a source it can't reach isn't done.
- **Request material is not standing material.** A customer's contract or an inbox is a case input: referenced by content hash, never committed. When something could be either (a deal brief serves one deal or many), ask.