@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.
- package/native/darwin-arm64/hivey +0 -0
- package/package.json +1 -1
- package/repo/skills/hivey/SKILL.md +10 -0
- package/repo/skills/hivey/scripts/critic-brief.md +46 -0
- package/repo/skills/hivey/scripts/fresh_review.py +381 -0
- package/repo/skills/hivey-agent-creator/SKILL.md +18 -12
- package/repo/skills/hivey-agent-creator/references/agent-claude-md.md +16 -8
- package/repo/skills/hivey-agent-creator/scripts/setup_agent.py +29 -22
- package/repo/skills/hivey-swarm-creator/SKILL.md +50 -27
- package/repo/skills/hivey-swarm-creator/references/agent-claude-md.md +40 -50
- package/repo/skills/hivey-swarm-creator/references/wiki-memory.md +3 -3
- package/repo/skills/hivey-swarm-creator/scripts/swarm_tasks.py +141 -8
- package/repo/skills/hivey-agent-creator/references/reviewer-agent.md +0 -35
|
@@ -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)
|
|
13
|
-
|
|
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 --
|
|
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("--
|
|
177
|
-
help="
|
|
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
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
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,
|
|
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
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
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
|
|
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
|
|
74
|
-
|
|
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
|
|
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
|
|
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
|
-
(
|
|
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
|
|
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`.
|
|
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
|
|
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
|
-
|
|
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
|
|
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>...
|
|
234
|
-
--models builder=opus,
|
|
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
|
|
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
|
-
**
|
|
335
|
-
|
|
336
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
119
|
-
- Only
|
|
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/ →
|
|
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
|
-
###
|
|
143
|
-
Every deliverable
|
|
144
|
-
1.
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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:
|
|
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
|
|
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
|
|
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 /
|
|
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:** -
|
|
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
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
`swarm/<agent>` branch into the main checkout and runs the full suite on the combined result
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
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,
|
|
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
|
|
24
|
-
|
|
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
|