@hivey/cli 0.0.0-stage → 0.9.36

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.
Files changed (83) hide show
  1. package/README.md +235 -2
  2. package/bin/hivey.js +98 -0
  3. package/native/darwin-arm64/hivey +0 -0
  4. package/package.json +36 -4
  5. package/platforms.json +3 -0
  6. package/repo/LICENSE +201 -0
  7. package/repo/NOTICE +18 -0
  8. package/repo/README.md +148 -0
  9. package/repo/install.sh +365 -0
  10. package/repo/pets/README.md +25 -0
  11. package/repo/pets/hivey-dot/CLAUDE.md +55 -0
  12. package/repo/pets/hivey-dot/build.sh +34 -0
  13. package/repo/pets/hivey-dot/main.swift +750 -0
  14. package/repo/pets/hivey-h/CLAUDE.md +75 -0
  15. package/repo/pets/hivey-h/build.sh +34 -0
  16. package/repo/pets/hivey-h/main.swift +739 -0
  17. package/repo/pets/hivey-prompt/CLAUDE.md +59 -0
  18. package/repo/pets/hivey-prompt/build.sh +34 -0
  19. package/repo/pets/hivey-prompt/main.swift +691 -0
  20. package/repo/pets/pet.py +288 -0
  21. package/repo/pets/shared/HiveyWatch.swift +437 -0
  22. package/repo/pets/test_pet.py +122 -0
  23. package/repo/plugins/README.md +108 -0
  24. package/repo/plugins/agent-creator/herdr-plugin.toml +17 -0
  25. package/repo/plugins/dashboard/dashboard.py +507 -0
  26. package/repo/plugins/dashboard/herdr-plugin.toml +14 -0
  27. package/repo/plugins/dashboard/test_dashboard.py +134 -0
  28. package/repo/plugins/github/github.py +261 -0
  29. package/repo/plugins/github/herdr-plugin.toml +14 -0
  30. package/repo/plugins/github/test_github.py +49 -0
  31. package/repo/plugins/skills/herdr-plugin.toml +11 -0
  32. package/repo/plugins/skills/skills.md +41 -0
  33. package/repo/plugins/slack-relay/connect.py +198 -0
  34. package/repo/plugins/slack-relay/create_channel.py +134 -0
  35. package/repo/plugins/slack-relay/herdr-plugin.toml +15 -0
  36. package/repo/plugins/slack-relay/relay.py +401 -0
  37. package/repo/plugins/slack-relay/slack-app-manifest.json +30 -0
  38. package/repo/plugins/slack-relay/test_connect.py +66 -0
  39. package/repo/plugins/slack-relay/test_create_channel.py +61 -0
  40. package/repo/plugins/slack-relay/test_relay.py +254 -0
  41. package/repo/plugins/swarm-creator/herdr-plugin.toml +17 -0
  42. package/repo/plugins/swarm-watcher/dashboard.py +333 -0
  43. package/repo/plugins/swarm-watcher/herdr-plugin.toml +16 -0
  44. package/repo/plugins/swarm-watcher/usage.py +129 -0
  45. package/repo/plugins/swarm-watcher/watcher.py +191 -0
  46. package/repo/plugins/team-template/herdr-plugin.toml +15 -0
  47. package/repo/plugins/team-template/setup.py +211 -0
  48. package/repo/plugins/team-template/test_setup.py +73 -0
  49. package/repo/plugins/tts/herdr-plugin.toml +15 -0
  50. package/repo/skills/herdr/SKILL.md +214 -0
  51. package/repo/skills/hivey/SKILL.md +322 -0
  52. package/repo/skills/hivey/scripts/handoff.py +27 -0
  53. package/repo/skills/hivey/scripts/new_wiki.py +143 -0
  54. package/repo/skills/hivey-agent-creator/SKILL.md +303 -0
  55. package/repo/skills/hivey-agent-creator/references/agent-claude-md.md +256 -0
  56. package/repo/skills/hivey-agent-creator/references/global-guidelines.md +67 -0
  57. package/repo/skills/hivey-agent-creator/references/reviewer-agent.md +35 -0
  58. package/repo/skills/hivey-agent-creator/scripts/agent_context.py +76 -0
  59. package/repo/skills/hivey-agent-creator/scripts/agent_gate.py +78 -0
  60. package/repo/skills/hivey-agent-creator/scripts/setup_agent.py +288 -0
  61. package/repo/skills/hivey-agy/SKILL.md +123 -0
  62. package/repo/skills/hivey-agy/references/gemini-prompting.md +134 -0
  63. package/repo/skills/hivey-agy/scripts/agy_run.py +146 -0
  64. package/repo/skills/hivey-codex/SKILL.md +66 -0
  65. package/repo/skills/hivey-context7/SKILL.md +56 -0
  66. package/repo/skills/hivey-create-wiki/SKILL.md +329 -0
  67. package/repo/skills/hivey-grok/SKILL.md +101 -0
  68. package/repo/skills/hivey-grok/scripts/grok_run.py +139 -0
  69. package/repo/skills/hivey-swarm-creator/SKILL.md +384 -0
  70. package/repo/skills/hivey-swarm-creator/references/agent-claude-md.md +313 -0
  71. package/repo/skills/hivey-swarm-creator/references/archify-report.md +24 -0
  72. package/repo/skills/hivey-swarm-creator/references/dashboard.md +46 -0
  73. package/repo/skills/hivey-swarm-creator/references/retrospective.md +23 -0
  74. package/repo/skills/hivey-swarm-creator/references/shared-rules.md +39 -0
  75. package/repo/skills/hivey-swarm-creator/references/wiki-memory.md +30 -0
  76. package/repo/skills/hivey-swarm-creator/scripts/setup_agent.py +76 -0
  77. package/repo/skills/hivey-swarm-creator/scripts/shared_rules.py +50 -0
  78. package/repo/skills/hivey-swarm-creator/scripts/swarm_tasks.py +171 -0
  79. package/repo/skills/hivey-wiki-ingest/SKILL.md +45 -0
  80. package/repo/skills/hivey-wiki-lint/SKILL.md +38 -0
  81. package/repo/skills/hivey-wiki-list/SKILL.md +46 -0
  82. package/repo/skills/hivey-wiki-log/SKILL.md +45 -0
  83. package/repo/skills/hivey-wiki-query/SKILL.md +44 -0
@@ -0,0 +1,313 @@
1
+ # Agent CLAUDE.md: template and role guidance
2
+
3
+ The agent reads its CLAUDE.md cold. It knows nothing about the conversation that produced the
4
+ swarm, so everything it needs has to be here: the project goal, its own slice of the work, how
5
+ the whole swarm is set up, every teammate and what they own, how to reach each of them, where to
6
+ write, and when it is done. Write it like a brief to a capable contractor joining a team, not a
7
+ list of keywords. Codex, Grok and agy agents read the same file (launch links `AGENTS.md`, and
8
+ `GEMINI.md` for agy, to it), so don't write anything that only makes sense to Claude Code.
9
+
10
+ Two parts:
11
+ 1. **Agent-specific sections**: mission, deliverables, where you work, skills, method,
12
+ definition of done, Status. These differ per agent.
13
+ 2. **"The swarm" section**: setup, roster, routing, task board, hand-offs, reports, critique,
14
+ messaging, contracts, safety, secrets, docs. Write it once and paste it **identically** into
15
+ every agent's CLAUDE.md. Save the same text to `<root>/.swarm/README.md`.
16
+
17
+ ## Template
18
+
19
+ Fill every `<…>`. `<vault>` is the swarm's wiki, `<root>/<name>-wiki`, written relative to the
20
+ agent's folder as `../<name>-wiki` so the swarm folder can be moved or shared. Delete sections
21
+ that genuinely don't apply (e.g. the wiki when the user said no); don't leave placeholders.
22
+
23
+ ````markdown
24
+ # <agent>: <one-line role>
25
+
26
+ > You are the **<agent>** agent (hivey address `<agent>`, pane `<name>-<agent>`) in the
27
+ > **<name>** swarm. A CLAUDE.md in a parent directory may describe another role: ignore that
28
+ > role, this file defines yours. Do follow its house rules, which are repeated below.
29
+
30
+ ## House rules
31
+ - End every final response with `DONE: <3 words max>` on its own line (e.g. `DONE: wrote
32
+ market report`).
33
+ - Look up library, API, CLI and cloud docs with the `hivey-context7` skill first, before a web
34
+ search or your memory.
35
+ - Style Obsidian notes with callouts: `> [!tip] Title` then `> content`. Types: note, tip,
36
+ warning, danger, info, example, quote.
37
+ - When you create a new skill, offer to publish it with skylls (`skylls push <skill folder>
38
+ -m "<what it does>"`, only with the user's yes, never `--skip-scan`).
39
+
40
+ ## Start of every session: read the swarm wiki first
41
+ The swarm's wiki at `<vault>/` is the **shared source of truth**: what the swarm has done,
42
+ found, decided and learned. Every time you start or resume, before anything else:
43
+ 1. Read `wiki/index.md`, `wiki/swarm-overview.md` and `wiki/swarm-final-report.md` (if it exists).
44
+ 2. Read your page `wiki/agents/<agent>.md` and the pages of teammates you hand off with.
45
+ 3. Read the `findings/`, `decisions/` and `lessons/` pages relevant to your mission.
46
+
47
+ If the wiki conflicts with your memory, a message or an old file, **the wiki wins** for shared
48
+ knowledge. Raise the conflict with the coordinator rather than silently diverging. Your Status
49
+ section is your own operational state; the wiki is what the team knows. Re-check it before big
50
+ decisions and before researching something a teammate may already have covered.
51
+
52
+ ## The project
53
+ <2–5 sentences: what the swarm as a whole is building or investigating and why. Quote the
54
+ user's original request so the agent can check its work against the real ask.>
55
+
56
+ ## Your mission
57
+ <What this agent owns, concretely. Scope boundaries: what it must NOT do because another agent
58
+ owns it (name that agent).>
59
+
60
+ ## Deliverables
61
+ | # | Deliverable | Path | Done when | Check | Consumed by |
62
+ |---|-------------|------|-----------|-------|-------------|
63
+ | 1 | <…> | `<root>/<path>` | <objective criterion> | `<shell command>` | <agent(s)> |
64
+
65
+ ## Where you work
66
+ - **Project root: `<root>/`.** You have full read/write access. This is where the swarm builds
67
+ and where you share files: put your output there, not only in your home folder. Your output
68
+ goes to `<exact path>`.
69
+ - **Sharing files:** write under `<root>/shared/` for hand-offs, then send the path to the
70
+ consumer with `hivey msg send <consumer> "…"`.
71
+ - Your home: `<root>/<agent>/`, for notes, scratch and logs.
72
+ - Don't edit other agents' homes or outputs. Read them freely.
73
+
74
+ ---
75
+
76
+ ## The swarm (identical in every agent's CLAUDE.md)
77
+
78
+ ### Setup
79
+ - **Root:** `<root>`. Each agent has a home at `<root>/<agent>/`. Shared output lives in `<paths>`.
80
+ - **hivey:** the swarm has its own space `<name>`. The coordinator is pane 1 (the master); every
81
+ agent has its own pane, with a dashboard, a watcher and a Slack relay beside them. The
82
+ coordinator can read your pane and may message you directly.
83
+ - **Slack:** `#<name>` mirrors the swarm for the user, who may also send instructions from there.
84
+ You don't post to Slack yourself.
85
+ - **Shared README:** `<root>/.swarm/README.md` holds this same overview.
86
+ - **Wiki (swarm memory):** `<vault>/`. Each agent writes its reports to
87
+ `raw/reports/<agent>/`. Only the coordinator writes `wiki/`, filing your reports into
88
+ long-term memory.
89
+
90
+ ### Roster
91
+ | Agent | CLI | Role | Owns / produces | Ask them for |
92
+ |-------|-----|------|-----------------|--------------|
93
+ | 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
+ | <agent-a> | <CLI> | <role> | <deliverables + paths> | <what others should ask them> |
96
+
97
+ ### Who to talk to
98
+ <Concrete routing for this project, one line per common need, e.g.:
99
+ - Market data or competitor facts → `researcher`
100
+ - A design decision or screen spec → `designer`
101
+ - An interface change that affects others → `@all`
102
+ - Scope, priority or conflicting instructions → `coordinator`>
103
+
104
+ ### Task board (claim before you start)
105
+ All work is tracked in `<root>/.swarm/TASKS.md` (a read-only view managed by a script). Check
106
+ the board before starting anything, and **claim** a task before working on it, so two agents
107
+ never do the same work:
108
+ ```bash
109
+ S=~/.claude/skills/hivey-swarm-creator/scripts; [ -d "$S" ] || S=~/.agents/skills/hivey-swarm-creator/scripts
110
+ python3 $S/swarm_tasks.py list --owner <agent> # your tasks
111
+ python3 $S/swarm_tasks.py claim <ID> --as <agent> # fails if deps aren't approved
112
+ 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 set <ID> blocked --as <agent> --note "waiting on …"
115
+ ```
116
+ - If a claim fails because a dependency isn't approved, work on something unblocked.
117
+ - 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`.
120
+
121
+ ### Hand-offs
122
+ <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
+
125
+ ### Reports (wiki)
126
+ Write reports as Markdown in `<vault>/raw/reports/<agent>/`, named `<agent>-<topic>_YYYY-MM-DD.md`:
127
+ - a **milestone report** each time a deliverable is DONE (what you did, key findings, paths);
128
+ - a **final report** `<agent>-final-report_YYYY-MM-DD.md` before you send FINISHED (objective,
129
+ what was delivered where, key findings with sources, decisions and why, critique outcome,
130
+ open issues, what someone continuing should do next).
131
+
132
+ Start each report with a callout summary (`> [!tip] Summary`) and use callouts for key findings
133
+ (`[!info]`), risks (`[!warning]`) and blockers (`[!danger]`). Help the coordinator connect your
134
+ reports into the wiki:
135
+ - Wrap key entities and concepts in `[[wiki-links]]`, reusing page names from `wiki/index.md`.
136
+ - Link the teammates' reports and pages your work builds on or affects.
137
+ - Keep findings as separate, clearly headed items with sources, so each can become its own page.
138
+
139
+ Don't edit `wiki/` or other agents' report folders. Mention the report path in your DONE and
140
+ FINISHED messages. You're not finished until your final report is in the wiki.
141
+
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.
154
+
155
+ ### How to communicate
156
+ Every message goes through hivey's message bus. It's delivered when the recipient is idle
157
+ (never mid-task), several waiting messages arrive together, and everything is logged.
158
+
159
+ | To | How |
160
+ |----|-----|
161
+ | another agent | `hivey msg send <agent> "<msg>"` |
162
+ | everyone | `hivey msg send @all "<msg>"` |
163
+ | a role | `hivey msg send @role:critic "<msg>"` (`worker`, `critic`, `master`) |
164
+ | the coordinator (master) | `hivey msg send coordinator "<msg>"` |
165
+ | the user | through the coordinator, or `hivey msg send human "<msg>"` |
166
+
167
+ ```bash
168
+ hivey msg send <agent> "<msg>" # wakes them when they're idle
169
+ hivey msg send <agent> --fyi "<msg>" # informational: never wakes anyone
170
+ hivey msg send <agent> --urgent "<msg>" # only if they must stop what they're doing
171
+ hivey msg inbox # messages for you
172
+ hivey msg log --limit 40 # the team's recent traffic
173
+ ```
174
+
175
+ Incoming messages arrive as prompts starting `[hivey]` or `[hivey · N messages]`; `from human`
176
+ is the user. **Acknowledgements and status updates go as `--fyi`**; reply without `--fyi` only
177
+ when the other side must act. Two agents can wake each other at most 6 times in 5 minutes; after
178
+ that hivey turns the messages into FYIs. Only the coordinator messages other swarms.
179
+
180
+ Conventions:
181
+ - `START` to coordinator, once: **restate your task in your own words, list your assumptions,
182
+ and give your plan in ≤3 bullets**, so a misunderstanding is caught before you build on it.
183
+ - `DONE <deliverable> → <path>` when a deliverable lands; send it to whoever needs it.
184
+ - `BLOCKED <what you need>` to the agent who can unblock you; keep working on anything unblocked.
185
+ - `QUESTION …`: **when something is ambiguous, ask; don't guess.** Keep working on anything
186
+ unaffected while you wait.
187
+ - `FINISHED` to coordinator, with a summary and your final report path, when all your
188
+ deliverables are APPROVED.
189
+
190
+ Keep messages short; put long content in files and send the path. Don't ask a teammate for
191
+ something the roster says someone else owns.
192
+
193
+ ### Contracts and code
194
+ - 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
196
+ wait for approval, because teammates build against it too.
197
+ - **If you have your own git worktree**: work only in `<root>/<agent>/repo` on branch
198
+ `swarm/<agent>`. Commit small and often. Never commit on another agent's branch or push to
199
+ main. The integrator merges branches and runs the full checks on the combined result.
200
+
201
+ ### Safety
202
+ You run with permissions pre-approved. hivey's safety hooks (`hivey safety`, on by default)
203
+ block destructive commands (`rm -rf` on folders, history rewrites, `curl | sh`), secret access
204
+ (`.env`, `~/.ssh`, keys) and hand-edited lockfiles. When something is blocked, **don't try
205
+ another route to the same effect**: decide whether you really need it, and if so ask the
206
+ coordinator, who asks the user. Never turn safety off.
207
+
208
+ ### Secrets
209
+ Keys and tokens come only from the user's secret store, fetched at the moment you use them.
210
+ Never print a secret, and never write one into a file (`.env`, code, config), your CLAUDE.md,
211
+ the wiki, a message, Slack or a commit. If you need a key you don't have, ask the coordinator;
212
+ don't go looking for it in files.
213
+
214
+ ### Docs
215
+ For any library, framework, SDK, API, CLI or cloud service, look the docs up with the
216
+ `hivey-context7` skill first (current docs in seconds), before a web search or your memory.
217
+
218
+ ---
219
+
220
+ ## Skills available
221
+ <Each skill in `.claude/skills/` and when to use it for THIS mission.>
222
+
223
+ ## Working method
224
+ <Role-specific method; see the guidance below.>
225
+
226
+ ## Definition of done
227
+ <Checklist. Always includes "every deliverable APPROVED by the critic (or accepted by the
228
+ coordinator)", "every check passes" and "final report written to the wiki". Send FINISHED only
229
+ when every item is true.>
230
+
231
+ ## Keeping your status (so you can resume later)
232
+ Your pane can be closed at any time, and you may be relaunched days later with no memory of this
233
+ session. The **Status** section at the bottom of this file is your memory.
234
+
235
+ - **When you start**: after reading the wiki, check Status. If it has content you are resuming:
236
+ don't start over. Open the files it lists, check `hivey msg inbox`, send `RESUMED` to the
237
+ coordinator with where you're picking up, and continue from **Next steps**.
238
+ - **Rewrite it (don't append)** after each deliverable is DONE, REVISED or APPROVED, whenever
239
+ you're BLOCKED, before sending FINISHED, and whenever the user or coordinator tells you to
240
+ stop or pause. A stale status costs more than an extra edit.
241
+ - Edit only the text between the `STATUS` markers, and keep it under ~40 lines. Put details in
242
+ files and link them.
243
+
244
+ ---
245
+
246
+ ## Status
247
+ <!-- STATUS:START -->
248
+ _Not started yet._
249
+ <!-- Rewrite this block; keep this shape:
250
+ **Updated:** YYYY-MM-DD HH:MM · **State:** not-started | working | blocked | waiting-review | paused | finished
251
+ **Summary:** 1–2 sentences on where the work stands.
252
+ **Done:** - <deliverable> → `<path>` (APPROVED r2 / DONE, awaiting critic)
253
+ **In progress:** - <what, and how far along>
254
+ **Next steps (do these first on resume):** 1. … 2. …
255
+ **Open first:** - `<path>`: why
256
+ **Open threads:** - critique r<N> on <deliverable> (`<review path>`) · waiting on <agent> for …
257
+ **Gotchas / decisions:** - things you learned that you'd otherwise rediscover
258
+ -->
259
+ <!-- STATUS:END -->
260
+ ````
261
+
262
+ ## Role guidance
263
+
264
+ Adapt; these are starting points, not scripts.
265
+
266
+ **Builder** (app, service, script, site): name the stack and exact output directory. Ask it to
267
+ run and test what it builds before claiming DONE, to commit in small steps, and to send the run
268
+ command with its DONE. If it depends on a researcher or designer, say what to stub while
269
+ waiting. **Mobile builders use Expo** (Expo SDK + Expo Router + TypeScript, `npx expo start` /
270
+ `npx expo run:ios`, native pieces via config plugins); tell them to read their Expo skills
271
+ before scaffolding.
272
+
273
+ **Researcher**: the questions to answer, the sources to prefer, the report path and format
274
+ (Markdown with linked sources). Ask for findings that feed other agents' decisions, flagged with
275
+ confidence. Grok suits X/Twitter and live web research.
276
+
277
+ **Analyst** (data, competitors, metrics): the input data and where it is, the metrics or
278
+ comparisons wanted, and the output (tables, charts, CSV). Ask it to state its assumptions.
279
+
280
+ **Designer / UX**: design docs or screens in the hand-off format the builder needs. agy can
281
+ generate images.
282
+
283
+ **Writer / marketer**: audience, tone, channels and deliverable files; style skills from
284
+ `hivey skills guide` when a particular voice is wanted.
285
+
286
+ **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.
@@ -0,0 +1,24 @@
1
+ # Archify visual report (only if the archify skill is installed)
2
+
3
+ Use this only if the `archify` skill is installed; otherwise skip it, the prose final report is
4
+ enough.
5
+
6
+ A final report in prose is hard to scan. Alongside it, draw the project with `archify`, so the
7
+ user sees at a glance how the swarm and what it built fit together, and where each piece stands.
8
+ Follow archify's own authoring and finalize steps, saving to
9
+ `<root>/diagrams/<type>-<name>-<YYYYMMDD-HHMMSS>/` (one folder per diagram).
10
+
11
+ Draw at least:
12
+ 1. **How the swarm works** (`architecture`): coordinator, every agent with its role and CLI, the
13
+ message bus and Slack mirror, the wiki, and the deliverables each agent produced, with each
14
+ agent's state in its label (finished / blocked / approved r2 …).
15
+ 2. **Where the work stands** (`workflow`): the hand-off chain and critique loop, with each
16
+ deliverable's status (approved, in review, in progress, not started) and open blockers.
17
+
18
+ Add a third when it helps: an `architecture` of the system the swarm built (from the real code),
19
+ or a `dataflow` for a research or data pipeline.
20
+
21
+ Then make it reachable from the wiki: export one light PNG per diagram into the vault as
22
+ `assets/<diagram>_YYYY-MM-DD.png`, embed it in `wiki/swarm-final-report.md` (`![[…png]]`), and
23
+ give the user the path of the interactive HTML. Earlier folders stay, so progress can be
24
+ compared over time.
@@ -0,0 +1,46 @@
1
+ # Dashboards and the watcher
2
+
3
+ Read this when the user asks what the dashboards show, or how to read them.
4
+
5
+ ## hivey.dashboard (pane in the swarm's space)
6
+
7
+ A terminal pane beside the agents: each agent's state (working, idle, blocked), tokens per
8
+ agent, active time against the budget, task counts per status from `.swarm/tasks.json`, and the
9
+ latest messages. Reopen it with `hivey swarm addon <name> hivey.dashboard` (e.g. after `q`).
10
+
11
+ ## hivey.swarm-watcher (alerts + Chrome Gantt)
12
+
13
+ Started with `--addon hivey.swarm-watcher`. It watches every worker and messages you (the
14
+ master) when one:
15
+ - is **blocked** (an approval or question dialog), at once;
16
+ - has **stopped** (idle for a while): it probably finished, is waiting on someone, or asked
17
+ something in its output and is waiting;
18
+ - is **stalled**: working a long time with no activity (no message, no task-board change),
19
+ possibly looping or lost;
20
+ - and when the **time budget** (`--budget-min`) is 80% and 100% used.
21
+
22
+ Handle each alert as in step 8 of the skill. If alerts are too noisy, see the plugin's options
23
+ (`hivey plugin config-dir hivey.swarm-watcher`).
24
+
25
+ It also keeps a live **Gantt dashboard**, opened once in the browser and rebuilt every minute
26
+ from `.swarm/agents.json`, the task board, the event log and the agents' states, at
27
+ `<launch dir>/diagrams/dashboard-swarm-<slug>.html` (the page reloads itself):
28
+ - **Gantt**: one lane per agent, with its state over time and one bar per task colored by status
29
+ (in-progress, review, blocked, approved). Tasks not yet started show what they wait on. Lines
30
+ mark "now" and the budget.
31
+ - **Header**: time used vs budget, task counts, one card per agent (state, CLI/model, current
32
+ task).
33
+ - **Recent events**: claims, status changes, critiques, alerts.
34
+ - **Tokens**: the swarm total, the master's share, and each agent's total (tokens only, no
35
+ prices, since price tables go stale).
36
+ - **Freshness**: an "updated N s ago" stamp turns amber, then red, when the watcher stops
37
+ updating it; check that the watcher pane is running (`hivey swarm info <name>`).
38
+
39
+ It's pure script and costs no tokens. Rebuild or reopen it by hand with
40
+ `python3 <plugin folder>/dashboard.py <root> --open` (the folder is in `hivey plugin list`).
41
+ Give the user its path when you report the launch.
42
+
43
+ If the `archify` skill is installed, refresh its "where the work stands" diagram
44
+ (`references/archify-report.md`) at milestones (a task approved, an agent FINISHED, a blocker
45
+ resolved) and when the user asks, not on every monitoring pass: each diagram costs real model
46
+ work, while the dashboards update for free.
@@ -0,0 +1,23 @@
1
+ # Retrospective: improving this skill
2
+
3
+ Every swarm teaches something about running swarms. Capture it so the skill gets better, but
4
+ **don't edit the skill yourself**: write proposals for the user to review.
5
+
6
+ When the swarm finishes (after the final report), or the user stops it for good:
7
+ 1. Review the run from evidence, not impressions: `.swarm/events.jsonl` (timeline, alerts,
8
+ check failures, how long tasks sat in `review`), the task board, `hivey msg log --swarm
9
+ <name>`, and your own interventions. Useful questions:
10
+ - Where did agents stall, duplicate work or misunderstand?
11
+ - Which watcher alerts were noise?
12
+ - What did you do by hand that a script or rule could do?
13
+ - Were the team shape, CLIs and models right? (The dashboard's tokens per agent: which agents
14
+ used the most for what they delivered?)
15
+ - Which skills were missing or unused?
16
+ 2. Write `<vault>/wiki/lessons/swarm-retrospective_YYYY-MM-DD.md`: what worked, what didn't (with
17
+ evidence from events and messages), and a **"Proposed improvements to the swarm creator"**
18
+ section. Each proposal names the file to change (`SKILL.md`,
19
+ `references/agent-claude-md.md`, a script), the change, and the problem it fixes. Link it from
20
+ `index.md`.
21
+ 3. Tell the user where the proposals are. They decide which to apply. Changes for this machine
22
+ only go in this skill's `EXTRA_SKILL.md` (hivey updates never touch it); improvements for
23
+ everyone belong in hivey itself.
@@ -0,0 +1,39 @@
1
+ <!-- hivey-swarm:shared-rules:start -->
2
+ # Work summary
3
+
4
+ Always end your final response with `DONE: <3 words max>` on its own line (e.g. `DONE: updated
5
+ stop hooks`). hivey's Stop hook reads it as the run's summary and speaks it for masters and solo
6
+ agents; swarm workers stay silent.
7
+
8
+ # Docs: Context7 first
9
+
10
+ For any library, framework, SDK, API, CLI or cloud service, look the docs up with the
11
+ `hivey-context7` skill before a web search or your memory.
12
+
13
+ # Safety and secrets
14
+
15
+ Agents run with permissions pre-approved; hivey's safety hooks (`hivey safety`, on by default)
16
+ block destructive commands and secret access. When one blocks you, ask the user (workers ask the
17
+ coordinator); never work around it, and never turn safety off. Secrets come only from the user's
18
+ secret store at the moment they're used, never in files, prompts, messages or commits.
19
+
20
+ # Save skills
21
+
22
+ When you create a new skill with /skill-creator, offer to publish it with skylls so it can be
23
+ reused and shared: with the user's yes, `skylls push <skill folder> -m "<what it does>"` (it
24
+ scans for secrets and refuses if it finds any: remove them, never `--skip-scan`). Share
25
+ (`skylls share <name> @user`) only when asked. Before creating one, check
26
+ `skylls --json find <words> --limit 5`: the user or a friend may already have it.
27
+
28
+ # Write to Obsidian
29
+
30
+ Style Obsidian notes with callouts:
31
+
32
+ ```
33
+ > [!tip] Title
34
+ > Content here
35
+ ```
36
+
37
+ Types: note (blue), tip (green), warning (orange), danger (red), info (blue), example (purple),
38
+ quote (gray).
39
+ <!-- hivey-swarm:shared-rules:end -->
@@ -0,0 +1,30 @@
1
+ # Building the swarm's wiki memory
2
+
3
+ Read this when step 8 points here. The vault is `<root>/<name>-wiki`, inside the swarm folder.
4
+ Only the coordinator writes `wiki/`; agents write reports to `raw/reports/<agent>/`.
5
+
6
+ - **Build the memory as reports arrive.** When an agent writes a report to
7
+ `raw/reports/<agent>/` (at DONE milestones and always at FINISHED), ingest it with the Ingest
8
+ workflow in `<vault>/CLAUDE.md` (`/hivey-wiki-ingest <report>` finds the vault from inside the
9
+ swarm folder). The wiki is the swarm's **connected** memory, so don't just file each report as
10
+ its own page:
11
+ - Break the report into findings, decisions, entities/concepts and lessons, and file each in
12
+ `findings/`, `decisions/` or `lessons/` (concept pages as needed). **Merge into an existing
13
+ page** when another agent already covered the topic, instead of making a near-duplicate.
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
16
+ with `[[wiki-links]]`. Where they contradict, record it in a `> [!warning]` callout on both
17
+ pages and in `lessons/`.
18
+ - Every page cites its source report(s). Update `wiki/agents/<agent>.md` (status,
19
+ deliverables, report links, the pages its work fed), then `index.md` and `log.md`.
20
+ - **When an agent sends FINISHED, ingest its final report before anything else.** A worker only
21
+ counts as finished once its final report is in the wiki, fully linked, and its agent page says
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
25
+ in `<vault>/CLAUDE.md` (`/hivey-wiki-lint`) to find orphan pages, missing cross-links,
26
+ contradictions and concepts that deserve their own page. Fix what it finds. Then write
27
+ `wiki/swarm-final-report.md` (outcome vs. the original request, per-agent results linking
28
+ their agent pages and reports, key findings linking their pages, open risks, next steps) and
29
+ link it from `swarm-overview.md` and `index.md`, so it's the hub everything connects to. If the
30
+ `archify` skill is installed, add the visual report (`references/archify-report.md`).
@@ -0,0 +1,76 @@
1
+ #!/usr/bin/env python3
2
+ """Scaffold one hivey swarm agent's folder.
3
+
4
+ Creates <root>/<agent>/ (and <root>/<agent>/.claude/skills/) and writes
5
+ <root>/<agent>/.claude/settings.json with:
6
+ - permissions.additionalDirectories: the swarm root (and --vault, if given), so the agent
7
+ can read and write the whole swarm folder;
8
+ - env.AGENTS_TTS = "0": workers stay silent; only the master speaks its summaries.
9
+ Existing settings are kept and merged. The coordinator writes the agent's CLAUDE.md; skills
10
+ are installed separately, as `hivey skills guide` says.
11
+
12
+ --worktree REPO gives a coding agent its own git worktree of REPO at <root>/<agent>/repo on
13
+ branch swarm/<agent>, so parallel builders never overwrite each other. REPO needs at least one
14
+ commit. The integrator (the critic or a dedicated agent) merges the branches.
15
+
16
+ Usage: setup_agent.py <swarm_root> <agent> [--vault PATH] [--worktree REPO]
17
+ """
18
+ import argparse
19
+ import json
20
+ import re
21
+ import subprocess
22
+ from pathlib import Path
23
+
24
+ NAME_RE = re.compile(r"^[a-z][a-z0-9_-]{0,31}$") # hivey agent-name rule
25
+
26
+
27
+ def add_worktree(repo, worktree, agent):
28
+ if worktree.exists():
29
+ return
30
+ branch = f"swarm/{agent}"
31
+ exists = subprocess.run(["git", "-C", str(repo), "rev-parse", "--verify", "--quiet", branch],
32
+ capture_output=True).returncode == 0
33
+ cmd = ["git", "-C", str(repo), "worktree", "add", str(worktree)] + ([branch] if exists else ["-b", branch])
34
+ r = subprocess.run(cmd, capture_output=True, text=True)
35
+ if r.returncode != 0:
36
+ raise SystemExit(f"git worktree failed (does {repo} have a commit?): {r.stderr.strip()}")
37
+
38
+
39
+ def main():
40
+ p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
41
+ p.add_argument("root", help="the swarm root folder")
42
+ p.add_argument("agent", help="agent key, e.g. builder (matches [a-z][a-z0-9_-]{0,31})")
43
+ p.add_argument("--vault", help="the swarm's wiki, if it lives outside the root; the agent gets access")
44
+ p.add_argument("--worktree", metavar="REPO", help="git repo to give this agent its own worktree of")
45
+ args = p.parse_args()
46
+
47
+ if not NAME_RE.match(args.agent):
48
+ raise SystemExit(f"invalid agent name {args.agent!r}: must match {NAME_RE.pattern}")
49
+
50
+ root = Path(args.root).expanduser().resolve()
51
+ agent_dir = root / args.agent
52
+ (agent_dir / ".claude" / "skills").mkdir(parents=True, exist_ok=True)
53
+
54
+ worktree = None
55
+ if args.worktree:
56
+ worktree = agent_dir / "repo"
57
+ add_worktree(Path(args.worktree).expanduser().resolve(), worktree, args.agent)
58
+
59
+ settings_path = agent_dir / ".claude" / "settings.json"
60
+ try:
61
+ settings = json.loads(settings_path.read_text()) if settings_path.exists() else {}
62
+ except json.JSONDecodeError as e:
63
+ raise SystemExit(f"{settings_path} is not valid JSON ({e}); fix it and run again")
64
+ dirs = settings.setdefault("permissions", {}).setdefault("additionalDirectories", [])
65
+ for d in [root] + ([Path(args.vault).expanduser().resolve()] if args.vault else []):
66
+ if str(d) not in dirs:
67
+ dirs.append(str(d))
68
+ settings.setdefault("env", {})["AGENTS_TTS"] = "0" # workers stay silent; only the master speaks
69
+ settings_path.write_text(json.dumps(settings, indent=2) + "\n")
70
+
71
+ print(json.dumps({"agent": args.agent, "dir": str(agent_dir), "settings": str(settings_path),
72
+ "worktree": str(worktree) if worktree else None}, indent=2))
73
+
74
+
75
+ if __name__ == "__main__":
76
+ main()
@@ -0,0 +1,50 @@
1
+ #!/usr/bin/env python3
2
+ """Merge the swarm's house rules into a CLAUDE.md (default: <root>/CLAUDE.md, the master's).
3
+
4
+ The rules live in ../references/shared-rules.md between hivey-swarm:shared-rules markers.
5
+ Every agent loads <root>/CLAUDE.md through its parent folder, so they apply to the whole swarm.
6
+ - File missing → created with the rules.
7
+ - Marker block present → replaced with the current rules (keeps them up to date).
8
+ - No markers but every rule heading already present (e.g. a hand-written CLAUDE.md) → left alone.
9
+ - Otherwise → appended at the end. Existing content is never removed.
10
+
11
+ Usage: shared_rules.py <swarm_root | path/to/CLAUDE.md>
12
+ """
13
+ import argparse
14
+ import json
15
+ import re
16
+ from pathlib import Path
17
+
18
+ RULES_FILE = Path(__file__).resolve().parent.parent / "references" / "shared-rules.md"
19
+ BLOCK = re.compile(r"<!-- hivey-swarm:shared-rules:start -->.*?<!-- hivey-swarm:shared-rules:end -->", re.S)
20
+
21
+
22
+ def main():
23
+ p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
24
+ p.add_argument("target", help="swarm root folder, or a CLAUDE.md path")
25
+ args = p.parse_args()
26
+
27
+ rules = RULES_FILE.read_text().strip()
28
+ headings = [line for line in rules.splitlines() if line.startswith("# ")]
29
+ target = Path(args.target).expanduser().resolve()
30
+ if target.is_dir():
31
+ target = target / "CLAUDE.md"
32
+ text = target.read_text() if target.exists() else ""
33
+
34
+ if BLOCK.search(text):
35
+ new, action = BLOCK.sub(lambda _: rules, text), "updated"
36
+ elif text and headings and all(h in text for h in headings):
37
+ new, action = text, "already present (hand-written), left alone"
38
+ else:
39
+ new = (text.rstrip() + "\n\n" if text else "") + rules + "\n"
40
+ action = "appended" if text else "created"
41
+ if new != text:
42
+ target.parent.mkdir(parents=True, exist_ok=True)
43
+ target.write_text(new)
44
+ elif action == "updated":
45
+ action = "unchanged"
46
+ print(json.dumps({"file": str(target), "result": action}))
47
+
48
+
49
+ if __name__ == "__main__":
50
+ main()