Agents and prompts

Every agent is one headless claude -p call made by scripts/run-agent/Invoke-Agent.ps1. The factory uses your own Claude login. It never asks for or stores a token.

Roles

Role	Used for	Tools	Output
plan	Reading the issue and the code and writing the plan.	Read, Grep, Glob	Structured output from plan.schema.json.
build	Implementing the plan, and fixing a failed try.	Read, Grep, Glob, and Edit or Write only on the planned files.	A reply that ends in BUILT or CANNOT_BUILD.
diagnose	Working out why a try failed.	Read, Grep, Glob	Structured output from diagnose.schema.json.
accept	Using the change in real Flare.	Read screenshots, write step files, run one command line.	Structured output from accept.schema.json.
review	Defined in the wrapper with an optional extra directory. The current loop does not call it.	Read, Grep, Glob	Optional structured output.

The orchestrator runs plan, build and diagnose with Sonnet. The wrapper accepts only haiku and sonnet and checks that the model that answered is the one asked for.

The wrapper’s guard rails

• It runs the CLI with --restricted, dontAsk permissions, no MCP servers, only user settings and no saved session.
• No role gets a general command tool. The accept role gets a single Bash rule that allows scripts/vm-do.ps1 -File on a file in the command folder, because a permission rule cannot allow a command line that carries PowerShell’s own ;, $ and | characters.
• A build agent’s edit rights are one Edit(./path) rule per planned file. A path that is absolute, has .. or has characters outside a safe set is rejected.
• Reading .env files and anything under .git is denied for every role.
• The plugin’s CLAUDE.md is not loaded by --restricted, so the wrapper copies only its “Hard constraints”, “Security invariants” and “Writing copy” sections into an appended system prompt.
• The environment passed to the child is a short allow list, with telemetry and auto-update turned off.
• The prompt goes to the child’s standard input as raw UTF-8 bytes, written asynchronously so a child that never reads cannot outlast a timeout.

Outcomes and exit codes

The wrapper classifies each result and exits with a code the orchestrator reads.

Code	Outcome
0	Ok.
1	The agent failed. Covers an error, a turn cap, no output, a missing structured output, an expired login or a bad model name.
2	Timed out.
3	The CLI could not be invoked.
4	A model other than the one asked for answered.
5	Bad arguments.
6	A rate or usage limit. Try again later.

An error is classified before the result’s subtype, because an expired login reports a subtype of success. The orchestrator turns a 6, a 3 and an expired login into stops and records everything else.

Timeouts and turns

The plan, build and diagnose agents run with no timeout and no turn cap. Only the acceptance agent has bounds, 25 minutes and 60 turns.

The prompts

All prompts are in factory2/prompts/. They use {{NAME}} tokens, which Format-Prompt fills in a single pass so text inside a value, such as an issue body, is never read as a token again. A token with no value is an error.

Prompt	What it asks the agent to do
plan.md	Read the code the issue touches and trace each caller and write path. Return numbered steps with file and symbol, the files that may be edited, whether a writer could notice the change, whether it involves AI, and a release note in second person with no colons, semicolons or arrows.
implement.md	Follow the steps in order, read the code around each line, write or update the named tests so they fail without the change, never weaken an existing assertion, edit only the listed files, and stop with CANNOT_BUILD instead of guessing.
retry.md	The same, given what went wrong and the diff so far. Fix the cause and keep what is right in the first try.
diagnose.md	Find the first thing that went wrong, follow it into the source, give evidence, name one of four kinds of problem and give a direction in one to four sentences.
accept.md	List what must be true for a writer, check each in the running Flare, report pass, fail or could not verify with evidence, always judge whether a writer can use the result, and put unrelated problems in findings.

The four schema files next to the prompts make the structured outputs exact. A plan without structured output is an error. A plan whose status is cannot_plan stops the run with the planner’s reason.