| 1 | # Agent briefs |
| 2 | |
| 3 | Two shapes: one for building, one for each review round. Keep the headings and |
| 4 | fill in the angle brackets. UI agents use `ui-review-loop`'s brief, with this |
| 5 | brief's Checkout and Claim sections. |
| 6 | |
| 7 | ## Build brief |
| 8 | |
| 9 | ``` |
| 10 | You own **<outcome>** in <project>. The user is Clover (she/her). |
| 11 | Read <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>. |
| 15 | Conservative 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>" |
| 19 | The 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 |
| 28 | 1. <item>: <concrete change, states, entry points> |
| 29 | N. Anything else in your area that clearly breaks: fix it, without adding features beyond this list. |
| 30 | |
| 31 | ## Claim |
| 32 | You own: <files, directories, patches>. |
| 33 | Others own: <owner: area>, one line each. Don't edit those; ask through the orchestrator. |
| 34 | History: 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 | |
| 56 | A new `delegate_task` per round, with its own `clientRequestId`. |
| 57 | |
| 58 | ``` |
| 59 | Review round <n> of <subject> in <project>. The user is Clover (she/her). |
| 60 | Diff: <from commit> → <to commit>, in <checkout>. Read-only: edit nothing, rewrite nothing. |
| 61 | Read <project>/AGENTS.md first. |
| 62 | |
| 63 | ## Threat model and stop rule (agreed with Clover, <date>) |
| 64 | Threat model: <who or what fails, and how; what is trusted> |
| 65 | Stop rule: <e.g. ship when no P1 or P2 remains inside the threat model; P3 and copy batch into the next release> |
| 66 | Out 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: <…> |
| 73 | Don'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 | ``` |