@hivey/cli 0.9.40 → 0.9.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -9,8 +9,10 @@ Writes, inside the agent folder only (never the global Claude Code config):
9
9
  resume-context (SessionStart) hooks
10
10
  .mcp.json project-scoped MCP servers given with --mcp
11
11
  .codex/config.toml the same MCP servers for a Codex agent
12
- .agent/config.json the run check (--check-cmd) and optional progress log
13
- .claude/agents/reviewer.md with --reviewer (Claude Code only)
12
+ .agent/config.json the run check (--check-cmd), optional progress log and the fresh
13
+ review ("review": critics, default 2 × sonnet; --critics 0 = off),
14
+ run by the hivey skill's fresh_review.py: one-shot critics with an
15
+ empty context and no saved session, for every kind of agent
14
16
  .gitignore keeps files that may hold keys and runtime state out of git
15
17
 
16
18
  Idempotent: re-running only adds. Skills are not installed here: follow `hivey skills guide`.
@@ -159,7 +161,7 @@ def main():
159
161
  description="Scaffold or update a hivey solo agent's folder (see SKILL.md step 5).",
160
162
  formatter_class=argparse.RawDescriptionHelpFormatter,
161
163
  epilog="example:\n setup_agent.py ~/agents/seo-auditor --name seo-auditor --kind claude \\\n"
162
- " --check-cmd 'bash scripts/check.sh' --gate --reviewer --git")
164
+ " --check-cmd 'bash scripts/check.sh' --gate --critics 2 --git")
163
165
  p.add_argument("folder", help="the agent folder (created if missing)")
164
166
  p.add_argument("--name", required=True, help="agent name / slug, [a-z][a-z0-9-]{0,31}")
165
167
  p.add_argument("--kind", choices=KINDS, default="claude", help="coding agent (default claude)")
@@ -173,8 +175,11 @@ def main():
173
175
  p.add_argument("--progress-log", help="a newest-first log file the resume context summarizes")
174
176
  p.add_argument("--gate", action="store_true",
175
177
  help="register the done gate and resume-context hooks (Claude Code only)")
176
- p.add_argument("--reviewer", action="store_true",
177
- help="install the read-only reviewer subagent (Claude Code only)")
178
+ p.add_argument("--critics", type=int,
179
+ help="fresh critics per review (default 2; 0 = no fresh review)")
180
+ p.add_argument("--critic-model", help="the critics' model (default sonnet)")
181
+ p.add_argument("--review-rounds", type=int, help="max review rounds per run (default 3)")
182
+ p.add_argument("--reviewer", action="store_true", help=argparse.SUPPRESS) # old flag: no-op
178
183
  p.add_argument("--git", action="store_true", help="git init the folder if it isn't in a repo")
179
184
  args = p.parse_args()
180
185
 
@@ -185,6 +190,8 @@ def main():
185
190
  raise SystemExit("refusing to use your home folder as an agent folder")
186
191
  if args.gate and not (args.check_cmd or read_json(agent_dir / ".agent" / "config.json").get("check")):
187
192
  raise SystemExit("--gate needs a run check: pass --check-cmd")
193
+ if args.critics is not None and not 0 <= args.critics <= 8:
194
+ raise SystemExit("--critics must be 0..8")
188
195
  agent_dir.mkdir(parents=True, exist_ok=True)
189
196
  result = {"agent": args.name, "kind": args.kind, "dir": str(agent_dir), "notes": []}
190
197
 
@@ -239,14 +246,23 @@ def main():
239
246
  "with its own CLI, or prefer a CLI tool")
240
247
 
241
248
  cfg_path = agent_dir / ".agent" / "config.json"
242
- if args.check_cmd or args.progress_log:
243
- cfg = read_json(cfg_path)
244
- if args.check_cmd:
245
- cfg["check"] = args.check_cmd
246
- if args.progress_log:
247
- cfg["progress_log"] = str(Path(args.progress_log).expanduser())
248
- write_json(cfg_path, cfg)
249
- result["agent_config"] = cfg
249
+ cfg = read_json(cfg_path)
250
+ review = cfg.setdefault("review", {})
251
+ review.setdefault("critics", 2)
252
+ review.setdefault("model", "sonnet")
253
+ review.setdefault("rounds", 3)
254
+ if args.critics is not None:
255
+ review["critics"] = args.critics
256
+ if args.critic_model:
257
+ review["model"] = args.critic_model
258
+ if args.review_rounds:
259
+ review["rounds"] = args.review_rounds
260
+ if args.check_cmd:
261
+ cfg["check"] = args.check_cmd
262
+ if args.progress_log:
263
+ cfg["progress_log"] = str(Path(args.progress_log).expanduser())
264
+ write_json(cfg_path, cfg)
265
+ result["agent_config"] = cfg
250
266
  (agent_dir / ".agent" / "state").mkdir(parents=True, exist_ok=True)
251
267
  (agent_dir / "logs").mkdir(exist_ok=True)
252
268
 
@@ -256,15 +272,6 @@ def main():
256
272
  else:
257
273
  result["notes"].append("the done gate is a Claude Code hook: the brief tells this "
258
274
  "agent to run the check itself")
259
- if args.reviewer:
260
- if args.kind != "claude":
261
- result["reviewer"] = "skipped: the reviewer subagent is Claude Code only"
262
- else:
263
- dest = agent_dir / ".claude" / "agents" / "reviewer.md"
264
- dest.parent.mkdir(parents=True, exist_ok=True)
265
- shutil.copy(HERE.parent / "references" / "reviewer-agent.md", dest)
266
- result["reviewer"] = str(dest)
267
-
268
275
  write_json(settings_path, settings)
269
276
  result["settings"] = str(settings_path)
270
277
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: hivey-swarm-creator
3
- description: Turn a task into a coordinated swarm of coding agents (Claude Code, Codex, Grok, Antigravity/Gemini) in hivey. This session becomes the coordinator (the swarm's master) - it designs the smallest team with the user, always adds a critic, writes a detailed CLAUDE.md brief per agent with deliverables and runnable checks, sets up the task board, git worktrees, the swarm's wiki, skills and Slack, launches it with `hivey swarm launch`, and then coordinates it. Use whenever the user says "swarm", "/swarm", "/hivey-swarm-creator", "spin up a team of agents", "launch multiple agents for this", "split this across agents", "create agents to build/research X in parallel", or otherwise wants several agents working together on one project, even if they don't say the word swarm. Also use to pause, resume, restart or continue an existing swarm ("pause the swarm", "stop the agents and save progress", "resume the swarm").
3
+ description: Turn a task into a coordinated swarm of coding agents (Claude Code, Codex, Grok, Antigravity/Gemini) in hivey. This session becomes the coordinator (the swarm's master) - it designs the smallest team with the user, writes a detailed CLAUDE.md brief per agent with deliverables and runnable checks, sets up the task board with fresh one-shot critics reviewing every deliverable, git worktrees, the swarm's wiki, skills and Slack, launches it with `hivey swarm launch`, and then coordinates it. Use whenever the user says "swarm", "/swarm", "/hivey-swarm-creator", "spin up a team of agents", "launch multiple agents for this", "split this across agents", "create agents to build/research X in parallel", or otherwise wants several agents working together on one project, even if they don't say the word swarm. Also use to pause, resume, restart or continue an existing swarm ("pause the swarm", "stop the agents and save progress", "resume the swarm").
4
4
  ---
5
5
 
6
6
  > Local additions: if `EXTRA_SKILL.md` exists in this skill's folder, read it too and follow it.
@@ -54,11 +54,20 @@ Work out the **smallest team** that covers the task, usually 2–5 workers. Each
54
54
  attention and coordination, so give each a **distinct deliverable**. If one agent needs
55
55
  another's output, make that hand-off explicit instead of having two agents share a job.
56
56
 
57
- **Every swarm includes a `critic`**, on top of the workers. It produces nothing itself: it
58
- reviews each deliverable posted as DONE, sends concrete critique to the owner, and approves the
59
- work once it's good, so the team improves its drafts instead of shipping them. Tailor its
60
- criteria to the project (code: correctness, tests, security; research: sources, gaps, logic;
61
- copy: clarity, audience fit) and put them in its CLAUDE.md.
57
+ **Every deliverable gets a fresh review; there is no critic agent.** When an owner submits a
58
+ task (`swarm_tasks.py submit`), the hivey skill's `fresh_review.py` starts N one-shot critics
59
+ in parallel (default 2 × Sonnet). Each is a `claude -p` process with no saved session, started
60
+ in an empty folder, given only the task spec, the user's request (`.swarm/REQUEST.md`), the
61
+ artifact (for code: the worktree and git range) and the check. It runs the check itself,
62
+ returns PASS or defects with file:line and evidence, and exits. The script merges the
63
+ verdicts (a defect counts if any critic reports it) and updates the board: every critic PASS
64
+ and the check exits 0 → `approved`; otherwise the task goes back to its owner with one merged
65
+ review for a single revision, and after the last round it's `blocked` for you to decide.
66
+ Nothing in the review lives on or remembers earlier rounds except the defect list it's asked
67
+ to re-check. Fresh critics catch more than a reviewer that has watched the work, and parallel
68
+ ones cost less than extra rounds. Ask the user how many critics, the model and the rounds
69
+ (step 3); it's set per swarm in `.swarm/review.json` (`fresh_review.py config`). Write each
70
+ task's "done when" into the board (`--spec`): it is what the critics judge against.
62
71
 
63
72
  For each agent decide:
64
73
  - **key**: short kebab-case role matching `[a-z][a-z0-9_-]{0,31}` (`researcher`, `builder`,
@@ -66,12 +75,12 @@ For each agent decide:
66
75
  - **mission and deliverables**: exact output paths and an objective **"done when"** for each.
67
76
  - **dependencies**: who it needs input from and who consumes its output.
68
77
  - **coding agent** (`--kinds`): which CLI runs it. Claude Code is the default. Suggest per
69
- role: **Claude Code** for most work and the critic; **Codex** for code review or a second
78
+ role: **Claude Code** for most work; **Codex** for code review or a second
70
79
  opinion; **Grok** for X/Twitter and web research; **agy** (Antigravity, Gemini) for fast,
71
80
  cheap tasks and image generation. All four read the CLAUDE.md you write: launch links
72
81
  `AGENTS.md` (and `GEMINI.md` for agy) to it.
73
- - **model** (`--models`): for Claude Code, `opus` for builders, the critic and deep reasoning;
74
- `sonnet` for research, writing and data gathering, at a fraction of the cost. A swarm costs
82
+ - **model** (`--models`): for Claude Code, `opus` for builders and deep reasoning; `sonnet`
83
+ for research, writing and data gathering, at a fraction of the cost. A swarm costs
75
84
  many times what one agent does, so spend the strong model where it pays off. For Codex, Grok
76
85
  and agy leave it to the CLI's default unless the user names one.
77
86
  - **skills**: run `hivey skills guide` and follow it for every agent (skylls first, skills.sh
@@ -90,11 +99,11 @@ contracts and checks target exactly those.
90
99
  **Contracts first** when agents build things that must fit together (code, data, APIs, file
91
100
  formats): task T1 is "Write `<root>/shared/CONTRACTS.md`" (interfaces, data shapes, formats,
92
101
  naming, layout), with a check, and every build task depends on it, so no builder starts before
93
- the critic approves the contract.
102
+ the contract's fresh review approves it.
94
103
 
95
104
  **Code swarms: one git worktree per builder.** When two or more agents write code in the same
96
105
  repo, each gets its own worktree and branch (step 6) so they never overwrite each other. Name an
97
- **integrator** (the critic, or a dedicated agent for bigger builds) who merges the branches into
106
+ **integrator** (one of the builders, or a dedicated agent for bigger builds) who merges the branches into
98
107
  the main checkout and runs the full test suite on the combined result, as its own task with a
99
108
  check.
100
109
 
@@ -122,7 +131,7 @@ Tasks:
122
131
  | ID | Task | Owner | Deps | Check |
123
132
  Skill gaps: <gap> → suggestion …
124
133
  Code: <repo path>, worktrees for <builders>, integrator: <agent> (code swarms only)
125
- (critic always included)
134
+ Review: <N> fresh critics × <model> per deliverable, <R> rounds max (default 2 × sonnet, 3)
126
135
  Wiki: <root>/<name>-wiki (the swarm's memory; say no to skip it)
127
136
  Slack: #<name> (connected) | not connected: run `hivey slack connect` first, or go without
128
137
  Schedules: monitoring pass every <N> min · <timed task> … (or none)
@@ -142,6 +151,10 @@ In the same message:
142
151
  user", "every 2 h run the test suite and file failures").
143
152
  - or **none** (you only react to messages and alerts).
144
153
  Each wake-up costs a turn of your model.
154
+ - **Ask how many fresh critics review each deliverable** (suggest 2; 3 for code or claims
155
+ where a miss is costly; 0 turns fresh review off and you approve by hand), their model
156
+ (suggest `sonnet`) and the maximum rounds (suggest 3). Each critic is one short `claude -p`
157
+ run per review, so N critics cost about N extra reads of the deliverable.
145
158
  - **Slack**: run `hivey slack status` before showing the plan. Connected: `hivey swarm launch`
146
159
  creates (or joins) `#<name>`, invites the user and starts the relay, nothing else to do. Not
147
160
  connected: ask the user to run `hivey slack connect` in a terminal (never ask for the token in
@@ -159,7 +172,9 @@ Obsidian is. In anything an agent reads, write it relative to the agent's folder
159
172
  ```bash
160
173
  mkdir -p <root>/shared
161
174
  python3 $S/shared_rules.py <root> # house rules into <root>/CLAUDE.md (marked block)
162
- python3 $S/setup_agent.py <root> <agent> [--worktree <root>/app] # once per agent, critic too
175
+ python3 $S/setup_agent.py <root> <agent> [--worktree <root>/app] # once per agent
176
+ F=~/.claude/skills/hivey/scripts/fresh_review.py; [ -f "$F" ] || F=~/.agents/skills/hivey/scripts/fresh_review.py
177
+ python3 $F config <root> --critics 2 --model sonnet --rounds 3 # the user's choice (step 3)
163
178
  ```
164
179
 
165
180
  `setup_agent.py` creates `<root>/<agent>/` and its `.claude/settings.json`, which grants access
@@ -178,15 +193,19 @@ directory may not be under the root:
178
193
  ```bash
179
194
  T="python3 $S/swarm_tasks.py --root <root>"
180
195
  $T add T1 "Write shared/CONTRACTS.md" --owner builder --path shared/CONTRACTS.md \
181
- --check "test -s shared/CONTRACTS.md"
182
- $T add T2 "Build the API" --owner builder --deps T1 --path app/ --check "cd app && npm test"
196
+ --check "test -s shared/CONTRACTS.md" --spec "every endpoint's request/response shape and errors"
197
+ $T add T2 "Build the API" --owner builder --deps T1 --path app/ --check "cd app && npm test" \
198
+ --spec "all CONTRACTS.md endpoints implemented, each with a test"
183
199
  ```
184
200
 
201
+ Also write the user's request, verbatim, to `<root>/.swarm/REQUEST.md`: every fresh critic
202
+ judges against it.
203
+
185
204
  This writes `.swarm/tasks.json` (the `hivey.dashboard` reads it), a readable `.swarm/TASKS.md`,
186
205
  and `.swarm/events.jsonl`, the swarm's timeline. Rules the board enforces: agents **claim**
187
206
  before starting, only their own (or unowned) tasks, and only once every dependency is
188
- `approved`. Only `critic` or `coordinator` can set `approved`, and only when the task's check
189
- passes (checks run outside the board lock, so a slow suite doesn't block anyone). Statuses:
207
+ `approved`. Owners `submit` a finished task, which starts its fresh review; only that review
208
+ (every critic PASS) or you can set `approved`, and only when the task's check passes (checks run outside the board lock, so a slow suite doesn't block anyone). Statuses:
190
209
  `open → in-progress → review → approved` (`blocked` any time).
191
210
 
192
211
  ## 5. Write the briefs
@@ -196,7 +215,7 @@ the heart of the swarm. Each agent works only from its own file, so it must unde
196
215
  whole team, not just its own job.
197
216
 
198
217
  1. **Write "The swarm" section once**: setup (root, the swarm's space, you as master, Slack
199
- mirror, wiki), the **full roster** (every agent including you and the critic: key, CLI, role,
218
+ mirror, wiki), the **full roster** (every agent including you: key, CLI, role,
200
219
  what it owns, what to ask it for), a "who to talk to" list, the task board, the hand-off
201
220
  chain, critique loop, messaging, contracts and code, safety, secrets and docs. Save it as
202
221
  `<root>/.swarm/README.md`.
@@ -212,10 +231,10 @@ teammate or asks the wrong agent.
212
231
 
213
232
  Unless the user said no, create the swarm's Obsidian wiki with the **`hivey-create-wiki`**
214
233
  skill (Skill tool, args `<name> --in <root> --agent <root>/<agent> [--agent …]`, every agent
215
- including the critic) now that the briefs exist. It reads the briefs, tailors the vault and
234
+ now that the briefs exist. It reads the briefs, tailors the vault and
216
235
  patches every agent's CLAUDE.md. Answer any question it has from the plan instead of asking the
217
236
  user again. If the vault already exists (a resumed swarm), reuse it. Shape it for a swarm:
218
- - `raw/reports/<agent>/` for each worker and the critic: agents write their reports there, and
237
+ - `raw/reports/<agent>/` for each worker: agents write their reports there, and
219
238
  only there.
220
239
  - `wiki/` sub-folders: `agents/`, `findings/`, `decisions/`, `deliverables/`, `lessons/`.
221
240
  - In the vault's CLAUDE.md add the swarm rule: *only the coordinator writes `wiki/`; it ingests
@@ -230,8 +249,8 @@ user's tweaks), linked from `index.md`, with a `bootstrap` entry in `log.md`.
230
249
  ## 7. Launch
231
250
 
232
251
  ```bash
233
- hivey swarm launch <root> --slug <name> --icon <emoji> <agent>... critic \
234
- --models builder=opus,critic=opus,writer=sonnet --kinds reviewer=codex,scout=grok \
252
+ hivey swarm launch <root> --slug <name> --icon <emoji> <agent>... \
253
+ --models builder=opus,writer=sonnet --kinds reviewer=codex,scout=grok \
235
254
  --budget-min 120 --heartbeat 15m \
236
255
  --heartbeat-task "Monitoring pass: follow the hivey-swarm-creator skill's monitoring pass" \
237
256
  --addon hivey.dashboard --addon hivey.swarm-watcher \
@@ -300,7 +319,8 @@ coordinator work.
300
319
  - **It asked a question**: answer it if it's within the plan; if it's the user's call, ask the
301
320
  user and relay the answer.
302
321
  - **It says it's done**: check the deliverable exists, meets its "done when" and its check
303
- passes, that it sent DONE to the critic and wrote its report to the wiki. If anything is
322
+ passes, that its fresh review approved it (`.swarm/reviews/`) and it wrote its report to the
323
+ wiki. If anything is
304
324
  missing, tell it exactly what.
305
325
  - **It's waiting on a teammate**: check that teammate's state and nudge whichever side holds
306
326
  things up.
@@ -331,9 +351,12 @@ two saves an hour.
331
351
  and deliverables, critique rounds, open decisions, what to do first on resume).
332
352
  5. Tell the user only what changed or needs their decision; otherwise keep the pass quiet.
333
353
 
334
- **Critique loop.** Every deliverable goes owner → DONE → critic → CRITIQUE r<N> → REVISED →
335
- APPROVED. If owner and critic disagree, or a deliverable reaches round 3 without APPROVED, you
336
- decide: accept, re-scope, or give a specific fix, and tell both.
354
+ **Review loop.** Every deliverable goes owner → `submit` → fresh review (N one-shot critics in
355
+ parallel, one merged review in `.swarm/reviews/<ID>-r<N>.md`) → APPROVED, or CRITIQUE back to
356
+ the owner → one revision → `submit` again. A task `blocked` after its last round, or a review
357
+ that ended in ERROR, is yours: read the review and accept it (`set <ID> approved --as
358
+ coordinator`), re-scope it, or give the owner a specific fix. If an owner disputes a defect, it
359
+ tells you with evidence; you decide. Don't review deliverables yourself instead of the critics.
337
360
 
338
361
  **Roster changes** (agents added or re-scoped): update `.swarm/README.md` and the swarm section
339
362
  in every agent's CLAUDE.md, then `hivey msg send @all` what changed. A new agent: scaffold it,
@@ -344,7 +367,7 @@ Every agent keeps its own Status section; if one looks stale against its pane ou
344
367
  agent to update it. Don't close the swarm's space or panes unless the user asks.
345
368
 
346
369
  **Finishing.** A worker only counts as finished once every deliverable is APPROVED and its final
347
- report is ingested into the wiki. When all workers and the critic have finished, run the
370
+ report is ingested into the wiki. When all workers have finished, run the
348
371
  connection pass and write `wiki/swarm-final-report.md` (`references/wiki-memory.md`), check the
349
372
  deliverables against the user's original request, and give the user the **final report**:
350
373
  outcome, where each deliverable is, open risks, next steps and the wiki path. If the `archify`
@@ -69,7 +69,9 @@ owns it (name that agent).>
69
69
  - **Sharing files:** write under `<root>/shared/` for hand-offs, then send the path to the
70
70
  consumer with `hivey msg send <consumer> "…"`.
71
71
  - Your home: `<root>/<agent>/`, for notes, scratch and logs.
72
- - Don't edit other agents' homes or outputs. Read them freely.
72
+ - Don't open other agents' homes: their notes and plans would pull your work toward theirs
73
+ (hivey blocks it for Claude agents). What you need comes as a path in a message (a
74
+ hand-off, which you may then open) or from the wiki; ask its owner with `hivey msg send`.
73
75
 
74
76
  ---
75
77
 
@@ -91,7 +93,6 @@ owns it (name that agent).>
91
93
  | Agent | CLI | Role | Owns / produces | Ask them for |
92
94
  |-------|-----|------|-----------------|--------------|
93
95
  | coordinator | Claude Code | Master: planned the swarm, monitors everyone | the plan, priorities, scope | decisions outside your scope, conflicts, unblocking, anything the user must decide |
94
- | critic | <CLI> | Reviews every deliverable, sends critique, approves | reviews in `<root>/critic/reviews/` | a review of your work, including early drafts |
95
96
  | <agent-a> | <CLI> | <role> | <deliverables + paths> | <what others should ask them> |
96
97
 
97
98
  ### Who to talk to
@@ -110,17 +111,17 @@ S=~/.claude/skills/hivey-swarm-creator/scripts; [ -d "$S" ] || S=~/.agents/skill
110
111
  python3 $S/swarm_tasks.py list --owner <agent> # your tasks
111
112
  python3 $S/swarm_tasks.py claim <ID> --as <agent> # fails if deps aren't approved
112
113
  python3 $S/swarm_tasks.py verify <ID> --as <agent> # run the task's check yourself
113
- python3 $S/swarm_tasks.py set <ID> review --as <agent> --note "<path>" # DONE → critic
114
+ python3 $S/swarm_tasks.py submit <ID> --as <agent> [--artifact <path>] [--repo <worktree> --range main...swarm/<agent>] # → fresh review
114
115
  python3 $S/swarm_tasks.py set <ID> blocked --as <agent> --note "waiting on …"
115
116
  ```
116
117
  - If a claim fails because a dependency isn't approved, work on something unblocked.
117
118
  - If a task you need isn't on the board, ask the coordinator; don't invent parallel work.
118
- - Run `verify` before you send DONE. A task with a check can't be approved until it passes.
119
- - Only the critic (or the coordinator) sets `approved`.
119
+ - Run `verify` before you submit. A task with a check can't be approved until it passes.
120
+ - Only a fresh review (or the coordinator) sets `approved`; you can't approve your own task.
120
121
 
121
122
  ### Hand-offs
122
123
  <The dependency chain in order, e.g. `researcher → findings.md → product → spec.md → builder →
123
- app/ → critic`. Say who waits for whom and what each one can do while waiting.>
124
+ app/ → integrator`. Say who waits for whom and what each one can do while waiting.>
124
125
 
125
126
  ### Reports (wiki)
126
127
  Write reports as Markdown in `<vault>/raw/reports/<agent>/`, named `<agent>-<topic>_YYYY-MM-DD.md`:
@@ -139,18 +140,23 @@ reports into the wiki:
139
140
  Don't edit `wiki/` or other agents' report folders. Mention the report path in your DONE and
140
141
  FINISHED messages. You're not finished until your final report is in the wiki.
141
142
 
142
- ### Critique loop
143
- Every deliverable goes through the critic before it counts as done:
144
- 1. Owner sends `DONE <deliverable> → <path>` to `critic` (and to the consumer if someone waits).
145
- 2. Critic writes `<root>/critic/reviews/<agent>-<deliverable>-r<N>.md` and sends the owner
146
- `CRITIQUE r<N> <deliverable> → <review path>` with the top issues, ranked by severity.
147
- 3. Owner fixes what's valid and sends `REVISED r<N> <deliverable> → <path>` to `critic`. For a
148
- point it disagrees with, it sends `DISAGREE <point>: <reason>` instead of ignoring it.
149
- 4. Critic re-reviews and sends `APPROVED <deliverable>`, or runs another round. No approval
150
- after 3 rounds, or an unresolved disagreement, goes to the coordinator, who decides.
151
-
152
- Critique is about the work, not the agent. Ask the critic early ("can you sanity-check my
153
- approach …") when a wrong direction would be costly.
143
+ ### Review (fresh critics)
144
+ Every deliverable is reviewed before it counts as done, by fresh critics, not by a teammate:
145
+ 1. When your task is done and `verify` passes, run `swarm_tasks.py submit <ID> --as <agent>`
146
+ (code: add `--repo <root>/<agent>/repo --range main...swarm/<agent>`; other outputs: add
147
+ `--artifact <path>` for anything beyond the task's path). It returns at once.
148
+ 2. In the background, <N> one-shot critics read the task spec, the user's request and your
149
+ artifact (never your notes or messages), run the check themselves and exit. You get a
150
+ message: `APPROVED <ID>` or `CRITIQUE r<N> <ID> → <review path>`. Work on something else
151
+ meanwhile; don't submit again while it's in review.
152
+ 3. On CRITIQUE, open the review and fix **every** defect in its Defects list in one revision
153
+ (each has file:line and evidence), then `submit` again. The next critics re-check that list
154
+ and review the rest fresh. If a defect is wrong, tell the coordinator with your evidence
155
+ instead of ignoring it.
156
+ 4. After the last round (<R>) the task is `blocked` and the coordinator decides.
157
+
158
+ Critique is about the work, not the agent. Before building something costly, sanity-check the
159
+ approach with the coordinator.
154
160
 
155
161
  ### How to communicate
156
162
  Every message goes through hivey's message bus. It's delivered when the recipient is idle
@@ -160,7 +166,7 @@ Every message goes through hivey's message bus. It's delivered when the recipien
160
166
  |----|-----|
161
167
  | another agent | `hivey msg send <agent> "<msg>"` |
162
168
  | everyone | `hivey msg send @all "<msg>"` |
163
- | a role | `hivey msg send @role:critic "<msg>"` (`worker`, `critic`, `master`) |
169
+ | a role | `hivey msg send @role:worker "<msg>"` (`worker`, `master`) |
164
170
  | the coordinator (master) | `hivey msg send coordinator "<msg>"` |
165
171
  | the user | through the coordinator, or `hivey msg send human "<msg>"` |
166
172
 
@@ -192,7 +198,7 @@ something the roster says someone else owns.
192
198
 
193
199
  ### Contracts and code
194
200
  - If `<root>/shared/CONTRACTS.md` exists, it's binding: interfaces, data shapes, formats,
195
- naming. Build to it. To change it, send the proposal to the coordinator and the critic and
201
+ naming. Build to it. To change it, send the proposal to the coordinator and
196
202
  wait for approval, because teammates build against it too.
197
203
  - **If you have your own git worktree**: work only in `<root>/<agent>/repo` on branch
198
204
  `swarm/<agent>`. Commit small and often. Never commit on another agent's branch or push to
@@ -224,7 +230,7 @@ For any library, framework, SDK, API, CLI or cloud service, look the docs up wit
224
230
  <Role-specific method; see the guidance below.>
225
231
 
226
232
  ## Definition of done
227
- <Checklist. Always includes "every deliverable APPROVED by the critic (or accepted by the
233
+ <Checklist. Always includes "every deliverable APPROVED by its fresh review (or accepted by the
228
234
  coordinator)", "every check passes" and "final report written to the wiki". Send FINISHED only
229
235
  when every item is true.>
230
236
 
@@ -249,11 +255,11 @@ _Not started yet._
249
255
  <!-- Rewrite this block; keep this shape:
250
256
  **Updated:** YYYY-MM-DD HH:MM · **State:** not-started | working | blocked | waiting-review | paused | finished
251
257
  **Summary:** 1–2 sentences on where the work stands.
252
- **Done:** - <deliverable> → `<path>` (APPROVED r2 / DONE, awaiting critic)
258
+ **Done:** - <deliverable> → `<path>` (APPROVED r2 / in review r1)
253
259
  **In progress:** - <what, and how far along>
254
260
  **Next steps (do these first on resume):** 1. … 2. …
255
261
  **Open first:** - `<path>`: why
256
- **Open threads:** - critique r<N> on <deliverable> (`<review path>`) · waiting on <agent> for …
262
+ **Open threads:** - review r<N> on <deliverable> (`<review path>`) · waiting on <agent> for …
257
263
  **Gotchas / decisions:** - things you learned that you'd otherwise rediscover
258
264
  -->
259
265
  <!-- STATUS:END -->
@@ -284,30 +290,14 @@ generate images.
284
290
  `hivey skills guide` when a particular voice is wanted.
285
291
 
286
292
  **Reviewer / second opinion** (often Codex): what to review, against which criteria, where to
287
- write findings, and that it reports to the critic, not straight to the builder, unless told.
288
-
289
- **Critic** (always present): the swarm's quality loop. It sets tasks to `approved`
290
- (`swarm_tasks.py set <ID> approved --as critic`), which runs the task's check; a failing check
291
- means it can't approve. In code swarms it's usually also the **integrator**: it merges each
292
- `swarm/<agent>` branch into the main checkout and runs the full suite on the combined result.
293
- Its CLAUDE.md should give:
294
- - **What to review**: every deliverable in the roster and its check, plus the user's original
295
- request, which is the bar everything is judged against.
296
- - **Criteria** per deliverable type. Code: run it and the tests; correctness, edge cases,
297
- security. Research: sources, recency, gaps, logic. Design and copy: clarity, consistency,
298
- audience fit.
299
- - **How to critique**: read or run the actual artifact (open sites and apps in a browser). Give
300
- specific, actionable issues ranked blocker / major / minor, each with a suggested fix. Don't
301
- restyle work to its own taste or rewrite others' work itself.
302
- - **The loop**: `CRITIQUE r<N>` → `REVISED` → `APPROVED`, at most 3 rounds before escalating to
303
- the coordinator. Reviews go in `<root>/critic/reviews/`.
304
- - **Cross-cutting checks**: whether deliverables fit together (did the builder implement what
305
- the researcher found and the spec says?). Raise mismatches with `@all`.
306
- - **Final report**: when all workers are FINISHED, write
307
- `<vault>/raw/reports/critic/critic-final-review_YYYY-MM-DD.md` (verdict per deliverable,
308
- remaining risks) and send `FINISHED` to the coordinator.
309
- - **Its Status** tracks review state per deliverable (round, verdict, review path), so it can
310
- resume the loop after a restart.
311
-
312
- Give it skills that support verification: browser or testing skills for builds, research skills
313
- for fact-checking.
293
+ write findings, and that it reports to the coordinator, not straight to the builder, unless
294
+ told. It's an extra opinion from another model family; tasks are still approved by their fresh
295
+ review.
296
+
297
+ **Integrator** (code swarms; one of the builders or a dedicated agent): merges each approved
298
+ `swarm/<agent>` branch into the main checkout and runs the full suite on the combined result,
299
+ as its own task with a check, which gets its own fresh review like any other.
300
+
301
+ **No critic agent.** Reviews are fresh one-shot critics started by `submit` (see the Review
302
+ section of every brief). Put each task's "done when" on the board (`--spec`) and the user's
303
+ request in `.swarm/REQUEST.md`: that's all the critics see besides the artifact.
@@ -12,7 +12,7 @@ Only the coordinator writes `wiki/`; agents write reports to `raw/reports/<agent
12
12
  `findings/`, `decisions/` or `lessons/` (concept pages as needed). **Merge into an existing
13
13
  page** when another agent already covered the topic, instead of making a near-duplicate.
14
14
  - **Connect across agents.** When two agents' findings relate (the researcher's data behind
15
- the builder's feature choice, the critic's issue with a design decision), link them both ways
15
+ the builder's feature choice, a fresh review's issue with a design decision), link them both ways
16
16
  with `[[wiki-links]]`. Where they contradict, record it in a `> [!warning]` callout on both
17
17
  pages and in `lessons/`.
18
18
  - Every page cites its source report(s). Update `wiki/agents/<agent>.md` (status,
@@ -20,8 +20,8 @@ Only the coordinator writes `wiki/`; agents write reports to `raw/reports/<agent
20
20
  - **When an agent sends FINISHED, ingest its final report before anything else.** A worker only
21
21
  counts as finished once its final report is in the wiki, fully linked, and its agent page says
22
22
  `finished`. A watcher "stopped" alert is often the moment to check this.
23
- - **Connection pass.** When every worker has sent FINISHED (which needs critic approval), the
24
- critic has written its final review, and all final reports are ingested, run the Lint workflow
23
+ - **Connection pass.** When every worker has sent FINISHED (which needs every deliverable approved
24
+ by its fresh review), and all final reports are ingested, run the Lint workflow
25
25
  in `<vault>/CLAUDE.md` (`/hivey-wiki-lint`) to find orphan pages, missing cross-links,
26
26
  contradictions and concepts that deserve their own page. Fix what it finds. Then write
27
27
  `wiki/swarm-final-report.md` (outcome vs. the original request, per-agent results linking