1# Agent briefs
2
3Two shapes: one for building, one for each review round. Keep the headings and
4fill in the angle brackets. UI agents use `ui-review-loop`'s brief, with this
5brief's Checkout and Claim sections.
6
7## Build brief
8
9```
10You own **<outcome>** in <project>. The user is Clover (she/her).
11Read <project>/AGENTS.md and <the files you'll touch> first; its rules apply in full.
12
13## Checkout
14<path> (jj workspace <name>), on <change> <commit id>.
15Conservative mode instead: <path>, shared with Clover and the orchestrator; you are its only editor until you report.
16
17## Clover's words (verbatim)
18"<quote>"
19The job, as I read it: <one or two lines>.
20
21## What it looks like now
22- <defect or state, where it shows, file:line leads>
23
24## Decisions already made
25- <decision> (<source: Clover, date | review round>)
26
27## Deliverable
281. <item>: <concrete change, states, entry points>
29N. Anything else in your area that clearly breaks: fix it, without adding features beyond this list.
30
31## Claim
32You own: <files, directories, patches>.
33Others own: <owner: area>, one line each. Don't edit those; ask through the orchestrator.
34History: commit on top in your own workspace. <Only if you are the rewriter: you may fold and rebase, per the orchestrate skill's references/jj.md; fold into <change ids>.>
35
36## Rules for this task
37- <only what AGENTS.md doesn't already say, e.g. "don't fold while the end-to-end run on <commit> is going">
38- Foreground only: background notifications never reach you. Poll cheaply with a timeout.
39
40## Verify
41- Test on <commit id>, and report the commit ids you tested.
42- Probes that count effects: <"one click sends exactly one request", "the end-to-end row passes 3/3">.
43- Visual changes: screenshots or a video, at <paths>.
44- Before reporting: a cleanup pass on your diff, every wait you started stopped, your scratch deleted.
45
46## Report (≤<N> lines)
47- Per item: done / skipped (why).
48- Change and commit ids, and the exact tree you tested.
49- Evidence paths: logs, screenshots, videos.
50- Anything you touched outside your claim and scratch.
51- Questions, each with a lean.
52```
53
54## Review round brief
55
56A new `delegate_task` per round, with its own `clientRequestId`.
57
58```
59Review round <n> of <subject> in <project>. The user is Clover (she/her).
60Diff: <from commit> → <to commit>, in <checkout>. Read-only: edit nothing, rewrite nothing.
61Read <project>/AGENTS.md first.
62
63## Threat model and stop rule (agreed with Clover, <date>)
64Threat model: <who or what fails, and how; what is trusted>
65Stop rule: <e.g. ship when no P1 or P2 remains inside the threat model; P3 and copy batch into the next release>
66Out of scope: <…>
67
68## History
69- Original brief: <pasted or path>
70- Round <k> findings: <F1 … Fn, one line each, severity>
71- Responses: <F1 resolved in <change> | accepted as temporary: why | disputed: why>
72- Unresolved objections: <…>
73Don't reopen findings marked resolved or accepted unless the diff changed them.
74
75## Report (≤<N> lines, also written to <path>)
76- Verdict: SHIP | BLOCK, against the stop rule.
77- Per prior finding: RESOLVED (how you checked) | OPEN.
78- New findings: id, severity, file:line, failure scenario. P3 and copy as one batched list.
79```