@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.
- package/native/darwin-arm64/hivey +0 -0
- package/package.json +1 -1
- package/repo/plugins/README.md +1 -0
- package/repo/plugins/slack-relay/relay.py +19 -5
- package/repo/plugins/slack-relay/test_relay.py +17 -0
- package/repo/skills/hivey/SKILL.md +22 -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 +62 -28
- package/repo/skills/hivey-swarm-creator/references/agent-claude-md.md +40 -50
- package/repo/skills/hivey-swarm-creator/references/shared-rules.md +9 -0
- 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
|
@@ -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. **
|
|
122
|
-
`
|
|
123
|
-
|
|
124
|
-
|
|
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
|
-
- [ ]
|
|
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
|
|
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).
|
|
217
|
-
|
|
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)
|
|
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,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
|
|
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`.
|
|
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
|
|
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
|
-
|
|
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
|
|
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>...
|
|
234
|
-
--models builder=opus,
|
|
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
|
|
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
|
-
**
|
|
335
|
-
|
|
336
|
-
|
|
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
|
|
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
|
|
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.
|
|
@@ -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,
|
|
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
|