recipes and roles

A recipe decides how a round goes. A role decides what each participant may do in it. cupof enforces the roles on the tools. It never decides who speaks or when.

Panel review is for a pull request someone else wrote. Every reviewer reviews on their own.

1. The lead opens a round.
2. Each reviewer reads the pull request and submits one review.
3. If the pull request changes and another round is needed, the lead starts it with next_round. The findings that are not settled are carried into it. Each reviewer marks their own carried findings fixed or withdrawn with resolve_finding, and references the rest in their review instead of filing them again.
4. After the last round, the lead closes it, with every review in or without the missing ones.
5. The lead drafts one combined review. Each finding says who raised it, who agreed and who disputed it.
6. You edit the draft and post it.

While the round is open, a reviewer cannot see the other reviews until they submit their own. Once they read another review, their own is frozen. So the panel does not drift toward the first opinion.

Build + duel is for your own pull request. An author agent writes the code, and a reviewer argues with it.

1. The author works on the pull request’s branch, with its own git credentials, and says so in the room.
2. The lead opens a round.
3. The reviewer submits a review.
4. The author answers each finding: accept it, or reject it with a reason.
5. The reviewer answers each rejection: withdraw the finding, or uphold it. A finding the new code fixes, the reviewer marks fixed.
6. Once the fixes are pushed, the lead starts the next round with next_round. The findings that are not fixed or withdrawn are carried into it, with the same ids, and the loop runs again from step 3.
7. After the last round, the lead closes it and drafts the review, and you post it as in panel review.

The author and the reviewer answer findings while the round is open. After it closes, they can still answer until the next round opens. Then a carried finding is answered in the new round.

cupof never pushes code. The author agent pushes with whatever git access its own machine has.

There are three roles. A participant can hold more than one.

• Lead. Opens the round, starts the next one, closes the last one and writes the draft.
• Reviewer. Reads the pull request, submits a review, and marks their own findings fixed, withdrawn or upheld.
• Author. In build + duel, answers the reviewer’s findings.

A lead who is also a reviewer must submit their own review before closing the round, or starting the next one.

An agent with no role gets one when it joins. What it gets depends on the recipe and on how many agents already hold a role.

Agent	Panel review	Build + duel
first	lead + reviewer	author
second	reviewer	lead + reviewer
third	reviewer	lead, and the second agent keeps only reviewer
any later one	reviewer	reviewer

People in the room get no default role. The room posts a note each time roles change, so every agent sees it.

Only you, the room owner, can change them. In the room’s header, press roles. On a phone, it is in the … menu. Pick the recipe and tick the roles for each member, agents and people alike. A person can lead a review.

Changing the recipe does not change anyone’s roles. Set both in the same dialog.

You can give an agent roles before it connects: add it from connect an agent → add to room. It gets the recipe’s default role right away, and it shows up in this dialog.

Over REST, the recipe is PATCH /api/v1/rooms/{slug}/review/recipe and the roles are PUT /api/v1/rooms/{slug}/review/roles. Both take your user key or your browser session. An agent key cannot change them.

Tool	Who may call it	Used in
get_pr_context	any member	both
get_file	any member	both
get_review_round	any member	both
open_review_round	lead	both
submit_review	reviewer	both
rebut_finding	author	build + duel
resolve_finding	the reviewer who raised the finding: fixed, withdrawn, or upheld after a rejection	both
next_round	lead	both
close_review_round	lead	both
draft_review	lead	both

The calls in order are on the round.