peer-agent-review
Skill4 starsChanged 20 days agoMITView on GitHub
Ask another AI agent to review or discuss your work and act on its answer: by default a permanent live omp session running GPT-6-Astra in the same worktree, launched automatically in a new adash terminal (`adash term`, adash's private tmux server) when none exists and reused for every later brief (\"Astra 확인\", \"Astra와 논의해봐\", \"Astra에게 검토\"), or any other live omp/Claude Code/Codex session, or a headless one-shot CLI (codex exec, claude -p, omp -p). Writes a durable brief, sends a one-line pointer, verifies delivery in the agent's session store, waits for the turn to finish, and reads the answer from the store. Encodes the accept loop (first line 수락/수정 필요 with replacement sentences, re-send until accepted) and the discussion mode (judgments, reasons, counterarguments, no verdict). Use adversarial-review for a parallel persona swarm inside your own session; use workshop-paper-review for OpenReview reports.
In this repository38 other files it gives its agents.
- academic-cvSkill
- academic-jobsSkill
- academic-proseSkill
- adversarial-reviewSkill
- bibtex-genSkill
- chrome-sessionSkill
- clickup-cliSkill
- clickup-todaySkill
- commit-triageSkill
- concept-explainerSkill
- contact-emailSkill
- cover-letterSkill
- dropboxSkill
- handdrawn-schematicSkill
- hep-rumor-millSkill
- journal-club-reviewSkill
- magi-researchSkill
- md2pdf-typoraSkill
- morgenSkill
- overleaf-section-workflowSkill
- overleapSkill
- proton-mailSkill
- reference-searchSkill
- remarkable-syncSkill
- research-backupSkill
- research-boardSkill
- research-logSkill
- research-portalSkill
- research-proposalSkill
- research-reportSkill
- research-statementSkill
- scienceplot-pySkill
- vastaiSkill
- wide-slide-illustratorSkill
- workshop-paper-reviewSkill
- xkcd-pySkill
- zai-web-searchSkill
- zoom-summarySkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 30
Every later brief goes to the same session, so the reviewer keeps its own earlier answers and the loop below can run to agreement.
- Very specific: line 70
Put it in the project (_guide/<topic>_brief_<date>.md) or ~/.cache/<topic>/, never /tmp (age-based cleaners delete it between sends).
- Distinctive: line 78
Use a new unique marker per request.
- Distinctive: line 79
If you and the reviewer read the same source, agreement is shared sourcing, not corroboration.
- Very specific: line 89
When you disagree, do not ask for acceptance again.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
peer-agent-review: get a second agent's verdict or discussion, then act on it
One helper, scripts/peer_review.py. A reviewer is a target. The default target
astra is the live omp session in the current worktree whose session model matches
/astra/. Other built-in targets: sol, luna, opus (live omp sessions by model),
codex and claude (live Codex / Claude Code TUIs), and argon (Antigravity CLI agy,
Gemini 4 Argon; "Agy Argon Medium" = -t argon --thinking medium). Any unknown target name is
treated as a model regex for a live omp session. Your own terminal ($ADASH_HANDLE) is never chosen.
Terminals are adash terminals: windows of adash's private tmux server (tmux -L adash), reached
only through adash term new|list|send|read|wait|close. adash must be on PATH. Handles look
like t_1a2b3c4d and stay the same across a tmux restart (adash restores its terminals).
Reviews are hostile by default (every mode except propose). Every pointer line tells the reviewer to read as the most
critical judge looking for reasons to reject: unsupported claims, overstatement, logical gaps,
source and number errors and missing counterexamples, each with a quotation, and no praise that
does not change the decision. Put any extra stance (e.g. "act as a selection committee member")
in the brief.
The reviewer is permanent. send/ask reuse a live reviewer of the target in the worktree
(the remembered one, else one found running there); only if none exists do they launch one in a
new adash terminal opened in the worktree directory (omp --model gpt-6-astra --thinking medium
for astra; override the level with --thinking). Its handle is remembered in
~/.cache/peer-agent-review/reviewers.json.
Every later brief goes to the same session, so the reviewer keeps its own earlier answers and
the loop below can run to agreement. Do not use a headless one-shot unless the user asks for
it (--oneshot): it forgets everything after one answer and cannot be argued with.
P=<skill dir>/scripts/peer_review.py
python3 $P targets # what each target resolves to here (never launches)
python3 $P spawn [-t sol] [--thinking high] # launch or reuse the permanent reviewer
python3 $P close [-t sol] # close the reviewer terminal when the work is done
python3 $P ask --brief _guide/x.md --marker 'sec3 KO check' # Astra, accept mode
python3 $P ask -t argon --thinking medium --brief _guide/x.md --marker 'sec3 argon' # agy Argon
python3 $P ask -t sol --mode discuss --brief _guide/x.md --marker '구조 논의'
python3 $P ask -t codex --brief notes/brief.md --marker 'second opinion' --out ans.md
python3 $P send / wait / read ... # split steps (e.g. send, keep working, wait later)ask blocks until the answer is complete (default timeout 1 h; the session record is checked
every 2 s). Run it in the background when the platform allows and keep working; a substantive
review takes 1 to 10 min.
Exit codes: 2 resolution failure, 3 not delivered, 4 timeout, 5 the reviewer's composer
holds an unsubmitted user draft (never send over it without asking).
argon (agy) answers through a file. agy has no session store this helper can read, so the
pointer asks it to write its whole answer to
~/.cache/peer-agent-review/answers/argon/<marker>.md and to touch no other file; it runs in
--mode accept-edits so it can write that file. Delivery is the marker on the terminal screen;
completion is the answer file non-empty and unchanged for --settle seconds (default 20) while
the agent is not working (adash's state for the handle, else no busy token on the screen).
A reused marker is refused (the answer file exists).
The {level} in the launch command becomes the model suffix (gemini-4-argon-medium).
Modes (the pointer line ends with the matching instruction)
| Mode | Use when | Reviewer is told |
accept (default) | you changed a file and need sign-off | first line 수락 or 수정 필요; required fixes as replacement sentences; do not edit files |
discuss | structure, framing, or a decision the user wants debated ("단순히 수락을 묻지 말고 논의") | judgments, reasons, counterarguments and its own best proposal per issue; no verdict |
free | anything else | do not edit files |
propose | you want options rather than a verdict (the proposer role in magi-research, usually Argon) | not hostile: 2 to 3 distinct alternatives with specs, required reader knowledge, trade-offs, risks and one recommendation; mockups only in the folder the brief names; facts only from files |
The brief (write it before sending)
- Put it in the project (
_guide/<topic>_brief_<date>.md) or~/.cache/<topic>/, never/tmp(age-based cleaners delete it between sends). The tool sends only a one-line pointer[marker] @<brief> …; multi-line terminal text would submit at every newline. - Contents: the user's instruction quoted verbatim (with the date), what you changed with file paths and a backup path of the previous version, exact new sentences or numbers, what you are unsure about as numbered questions, and the output contract.
- Apply your edits BEFORE sending and assert that each replacement happened; a failed script once sent the reviewer an unchanged file.
- Use a new unique marker per request; the marker is how delivery and the answer are found.
- If you and the reviewer read the same source, agreement is shared sourcing, not corroboration; say so in the brief and ask for falsifiable defects.
The loop
accept: read the answer. For each required fix, verify the claim against the files (numbers, file:line, quotations) before applying. Apply replacement sentences as given unless you can show they are wrong; then say why in the next brief.- Re-send a short
vN 확인brief listing exactly what changed. Repeat until 수락. - Optional suggestions: apply them or state why not.
- When you disagree, do not ask for acceptance again. Switch to
discuss, state the objection with evidence and let the reviewer answer it point by point. The user values real discussion over rubber-stamping. - Report to the user: verdict, what the reviewer corrected (including where it corrected itself), what changed, and anything unverified. Never forward a reviewer's numbers without re-deriving them.
Choosing another reviewer
- Same live agent, different model:
-t sol,-t luna,-t <regex>; or--handle t_…. Named targets are launched when missing;--no-launchmakes a missing reviewer an error. - Another worktree's agent (e.g. the experiment repo's session for recipe facts):
--cwd <that worktree>with-t <model regex>or--handle. Give it full context in the brief; it has not seen your conversation. - Claude Code or Codex TUI sessions:
-t codex/-t claudefind a live one in the worktree throughadash ls, else launch them read-only (codex -s read-only,claude --permission-mode plan);--handleor a"title"regex in the targets file picks a specific one. - Headless one-shot only when the user asks:
--oneshotruns the target'soneshotCLI with the brief on stdin (no memory between briefs).
Targets file (optional): $PEER_REVIEW_TARGETS, default
~/.config/peer-agent-review/targets.json, merged over the built-ins, e.g.
{"astra": {"thinking": "high"},
"mylab": {"transport": "session", "agent": "omp", "model": "glm", "launch": ["omp", "--model", "glm-5"]},
"gemini": {"transport": "oneshot", "agent": "gemini", "oneshot": ["gemini", "-p"]}}PEER_REVIEW_DEFAULT changes the default target.
How it works and why (traps it handles)
- Resolution order:
--handle; the remembered permanent reviewer (its terminal must still run the target's agent kind peradash ls, otherwise the pointer would land in a bare shell); a"title"regex (matched against the program's terminal title and the window name); a live terminal in the worktree whose agent, peradash ls --all --json(handle,agentType,model,identity= session file), is the target's kind and whose model matches the target regex; for omp targets the session store (below); otherwise launch. A reviewer found live is adopted as the permanent one bysend/ask/spawn(not bytargets/resolve). Several matches: the most recently active one wins, with a note on stderr. A handle that no longer exists is forgotten and the reviewer re-resolved or relaunched. - Launch:
adash term new --cwd <worktree> --title '<target> reviewer' --command <launch>, thenadash term wait --quiet-ms 2000until the screen is quiet and (omp, agy) the input area's rule lines are drawn, up to 6 min, before the first send; a prompt typed into a TUI that is still starting is lost. - Session-store resolution: for omp targets it scans the worktree's session store
(
~/.omp/agent/sessions/-<cwd relative to $HOME, / → ->), picks the newest session whose dominant"model"matches the regex, reads its title (first record), and finds the omp terminal in that worktree whose title contains it. - Delivery: a successful
adash term sendis not delivery. The tool waits until a user record containing the marker appears in the agent's session store (agy: the marker on the screen), and retries once after re-resolving. - Completion (omp, Claude Code, Codex): read from the reviewer's own session record, the file
holding the
[marker]user record. The turn is done when the last message after it ends the turn (ompstopReasonstop/length; Claudestop_reasonend_turnor aturn_durationrecord; Codextask_complete), not a message with a pending tool call, and the file is unchanged 3 s later (a finished background job can resume the turn).waitchecks every 2 s and re-parses only when the file changed, so the answer arrives about 5 s after the turn ends. A turn that ended in error or abort must stay unchanged for--settleseconds (omp retries provider errors). A finished turn with no answer exits 4 at once instead of waiting for--timeout. While the turn is working nothing is returned: an omp reviewer writes preamble text before its tool calls and may wait on subagents with nothing on the screen. Screen quiet (adash term wait) is not used for completion: it fires mid-turn. - The answer is read from the session store, never scraped from the TUI (hard-wrapped,
redraw noise).
adash termJSON is parsed after replacing invalid UTF-8. - Composer hazard: if the reviewer's input box holds text, sending would submit the
user's draft together with yours. The tool refuses (exit 5) unless
--force. - Slash-command prompts (
/skill:…) create no user record; send plain text only. - adash threads: with
$ADASH_HANDLEset,sendrunsadash thread registerandwaitrunsadash thread answered(ADASH_HOOK=0turns this off); they never affect the review.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

