@hivey/cli 0.9.41 → 0.9.45

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.
@@ -118,10 +118,17 @@ run; it has the full method.">
118
118
  and blocks you until it passes, up to 3 times. Answering a question isn't a run: don't set
119
119
  the flag for that.
120
120
  2. Do the work following **Method**.
121
- 3. **Review**: <with a reviewer:> hand the artifacts to the `reviewer` subagent (Agent tool,
122
- `subagent_type: reviewer`, with the paths). Fix every defect it reports, then ask again
123
- until it says PASS (at most 3 rounds; then record what's left in Status).
124
- <without one:> self-review (below), spot-checking 3 claims against their sources.
121
+ 3. **Fresh review**: <with fresh review, the default:> run
122
+ `python3 ~/.claude/skills/hivey/scripts/fresh_review.py run --folder . --label <run> --artifact <path> …`
123
+ (`~/.agents/skills/…` if that's missing; for code add `--repo . --range <first commit of
124
+ this run>~1..HEAD`; from round 2 add `--round <n> --previous <last review>`). It takes a few
125
+ minutes (allow up to 15: run it in the background or with a long timeout). <N> one-shot
126
+ critics read only your spec, the artifact and the check (not your notes or this
127
+ conversation), and it writes one merged review to `.agent/reviews/`. Exit 0 = APPROVED.
128
+ Otherwise fix **every** defect in its Defects list in one revision and run it again (at
129
+ most <R> rounds; then record what's left in Status and tell the user). Don't summarize or
130
+ defend your work to the critics: they judge the result.
131
+ <without (critics 0):> self-review (below), spot-checking 3 claims against their sources.
125
132
  4. **Check**: run `<check command>` yourself. It must exit 0.
126
133
  5. **Commit** this folder only, never push: `git add -A . && git commit -m "<name>: <what
127
134
  changed>"`. The git log is part of your memory.
@@ -167,7 +174,7 @@ does, its skills and tools, and whether it is busy or idle.
167
174
 
168
175
  ## Definition of done
169
176
  - [ ] Every deliverable's Check passes
170
- - [ ] Self-review done against The ask
177
+ - [ ] Fresh review APPROVED <or, with critics 0: self-review done against The ask>
171
178
  - [ ] <memory: wiki ingested>
172
179
  - [ ] <if Slack: run summary sent>
173
180
  - [ ] Committed, not pushed
@@ -210,11 +217,12 @@ The same CLAUDE.md works; adjust these parts:
210
217
  - **Skills**: these CLIs don't load `.claude/skills/` by themselves. In the Skills table, give
211
218
  each skill's path (`.claude/skills/<skill>/SKILL.md`) and write "read the skill's SKILL.md
212
219
  before the first time you use it".
213
- - **No hooks**: there is no done gate, resume context or reviewer subagent. Replace step 0 of
220
+ - **No hooks**: there is no done gate or resume context (the fresh review still works: it's a
221
+ script). Replace step 0 of
214
222
  "Start of every session" with: read `.agent/state/gate.log` (if any), `git log -5 --oneline
215
223
  -- .` and `tasks.json` (if any). In the Run protocol, run the check yourself and don't finish
216
- until it passes (at most 3 attempts; then write why into Status). Self-review instead of the
217
- reviewer.
224
+ until it passes (at most 3 attempts; then write why into Status). Use
225
+ `~/.agents/skills/hivey/scripts/fresh_review.py` for the review.
218
226
  - **Grok** can't work in extra folders: keep everything inside the agent folder.
219
227
  - **Codex** MCP servers live in `.codex/config.toml` (setup_agent.py copies them there).
220
228
  - Keep the `DONE:` rule: it's how hivey and the user see each run's summary.
@@ -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,16 @@ 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.
158
+ - **Ask how chatty the swarm may be** (comms preset): `normal` (suggest it: 10 messages/min,
159
+ 30 wake-ups/h per agent, 4 `@all`/h, repeats dropped, Slack mirrors only master and human
160
+ traffic), `quiet` for big or long-running swarms (5/min, 12/h, 2 broadcasts/h, Slack masters
161
+ only), or `chatty` for short, tightly coupled builds (Slack mirrors everything). Over a limit,
162
+ messages are saved as FYI (they don't wake anyone) or refused, so agents batch and stop
163
+ ping-ponging.
145
164
  - **Slack**: run `hivey slack status` before showing the plan. Connected: `hivey swarm launch`
146
165
  creates (or joins) `#<name>`, invites the user and starts the relay, nothing else to do. Not
147
166
  connected: ask the user to run `hivey slack connect` in a terminal (never ask for the token in
@@ -159,7 +178,9 @@ Obsidian is. In anything an agent reads, write it relative to the agent's folder
159
178
  ```bash
160
179
  mkdir -p <root>/shared
161
180
  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
181
+ python3 $S/setup_agent.py <root> <agent> [--worktree <root>/app] # once per agent
182
+ F=~/.claude/skills/hivey/scripts/fresh_review.py; [ -f "$F" ] || F=~/.agents/skills/hivey/scripts/fresh_review.py
183
+ python3 $F config <root> --critics 2 --model sonnet --rounds 3 # the user's choice (step 3)
163
184
  ```
164
185
 
165
186
  `setup_agent.py` creates `<root>/<agent>/` and its `.claude/settings.json`, which grants access
@@ -178,15 +199,19 @@ directory may not be under the root:
178
199
  ```bash
179
200
  T="python3 $S/swarm_tasks.py --root <root>"
180
201
  $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"
202
+ --check "test -s shared/CONTRACTS.md" --spec "every endpoint's request/response shape and errors"
203
+ $T add T2 "Build the API" --owner builder --deps T1 --path app/ --check "cd app && npm test" \
204
+ --spec "all CONTRACTS.md endpoints implemented, each with a test"
183
205
  ```
184
206
 
207
+ Also write the user's request, verbatim, to `<root>/.swarm/REQUEST.md`: every fresh critic
208
+ judges against it.
209
+
185
210
  This writes `.swarm/tasks.json` (the `hivey.dashboard` reads it), a readable `.swarm/TASKS.md`,
186
211
  and `.swarm/events.jsonl`, the swarm's timeline. Rules the board enforces: agents **claim**
187
212
  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:
213
+ `approved`. Owners `submit` a finished task, which starts its fresh review; only that review
214
+ (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
215
  `open → in-progress → review → approved` (`blocked` any time).
191
216
 
192
217
  ## 5. Write the briefs
@@ -196,7 +221,7 @@ the heart of the swarm. Each agent works only from its own file, so it must unde
196
221
  whole team, not just its own job.
197
222
 
198
223
  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,
224
+ mirror, wiki), the **full roster** (every agent including you: key, CLI, role,
200
225
  what it owns, what to ask it for), a "who to talk to" list, the task board, the hand-off
201
226
  chain, critique loop, messaging, contracts and code, safety, secrets and docs. Save it as
202
227
  `<root>/.swarm/README.md`.
@@ -212,10 +237,10 @@ teammate or asks the wrong agent.
212
237
 
213
238
  Unless the user said no, create the swarm's Obsidian wiki with the **`hivey-create-wiki`**
214
239
  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
240
+ now that the briefs exist. It reads the briefs, tailors the vault and
216
241
  patches every agent's CLAUDE.md. Answer any question it has from the plan instead of asking the
217
242
  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
243
+ - `raw/reports/<agent>/` for each worker: agents write their reports there, and
219
244
  only there.
220
245
  - `wiki/` sub-folders: `agents/`, `findings/`, `decisions/`, `deliverables/`, `lessons/`.
221
246
  - In the vault's CLAUDE.md add the swarm rule: *only the coordinator writes `wiki/`; it ingests
@@ -230,9 +255,9 @@ user's tweaks), linked from `index.md`, with a `bootstrap` entry in `log.md`.
230
255
  ## 7. Launch
231
256
 
232
257
  ```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 \
235
- --budget-min 120 --heartbeat 15m \
258
+ hivey swarm launch <root> --slug <name> --icon <emoji> <agent>... \
259
+ --models builder=opus,writer=sonnet --kinds reviewer=codex,scout=grok \
260
+ --budget-min 120 --heartbeat 15m --comms-preset normal \
236
261
  --heartbeat-task "Monitoring pass: follow the hivey-swarm-creator skill's monitoring pass" \
237
262
  --addon hivey.dashboard --addon hivey.swarm-watcher \
238
263
  --kickoff "Read your CLAUDE.md, then send START to coordinator as it says."
@@ -300,7 +325,8 @@ coordinator work.
300
325
  - **It asked a question**: answer it if it's within the plan; if it's the user's call, ask the
301
326
  user and relay the answer.
302
327
  - **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
328
+ passes, that its fresh review approved it (`.swarm/reviews/`) and it wrote its report to the
329
+ wiki. If anything is
304
330
  missing, tell it exactly what.
305
331
  - **It's waiting on a teammate**: check that teammate's state and nudge whichever side holds
306
332
  things up.
@@ -331,9 +357,17 @@ two saves an hour.
331
357
  and deliverables, critique rounds, open decisions, what to do first on resume).
332
358
  5. Tell the user only what changed or needs their decision; otherwise keep the pass quiet.
333
359
 
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.
360
+ **Review loop.** Every deliverable goes owner → `submit` → fresh review (N one-shot critics in
361
+ parallel, one merged review in `.swarm/reviews/<ID>-r<N>.md`) → APPROVED, or CRITIQUE back to
362
+ the owner → one revision → `submit` again. A task `blocked` after its last round, or a review
363
+ that ended in ERROR, is yours: read the review and accept it (`set <ID> approved --as
364
+ coordinator`), re-scope it, or give the owner a specific fix. If an owner disputes a defect, it
365
+ tells you with evidence; you decide. Don't review deliverables yourself instead of the critics.
366
+
367
+ **Too much talk.** If agents ping-pong, flood `@all` or Slack, tighten the swarm's limits
368
+ (`hivey swarm comms <name> --preset quiet`, or one flag such as `--hourly-wakes 12` or
369
+ `--slack masters`) and tell the agents involved to batch their messages. Ask the user before
370
+ loosening them.
337
371
 
338
372
  **Roster changes** (agents added or re-scoped): update `.swarm/README.md` and the swarm section
339
373
  in every agent's CLAUDE.md, then `hivey msg send @all` what changed. A new agent: scaffold it,
@@ -344,7 +378,7 @@ Every agent keeps its own Status section; if one looks stale against its pane ou
344
378
  agent to update it. Don't close the swarm's space or panes unless the user asks.
345
379
 
346
380
  **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
381
+ report is ingested into the wiki. When all workers have finished, run the
348
382
  connection pass and write `wiki/swarm-final-report.md` (`references/wiki-memory.md`), check the
349
383
  deliverables against the user's original request, and give the user the **final report**:
350
384
  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.
@@ -5,6 +5,15 @@ Always end your final response with `DONE: <3 words max>` on its own line (e.g.
5
5
  stop hooks`). hivey's Stop hook reads it as the run's summary and speaks it for masters and solo
6
6
  agents; swarm workers stay silent.
7
7
 
8
+ # Messages
9
+
10
+ Every message wakes someone and costs their turn. Send only what the other agent must act on:
11
+ no acks, thanks or "got it"; one message per hand-off; long content goes in a file and you
12
+ send the path. Don't reply to FYIs. Use `@all` only when everyone must act. When a notice says
13
+ you and a teammate hit the pair limit, or your hourly limit, stop and batch what's left into
14
+ one message (or let the task board and files speak). Your swarm's limits: `hivey swarm comms
15
+ <swarm>`.
16
+
8
17
  # Docs: Context7 first
9
18
 
10
19
  For any library, framework, SDK, API, CLI or cloud service, look the docs up with the
@@ -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