@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.
- package/README.md +235 -2
- package/bin/hivey.js +98 -0
- package/native/darwin-arm64/hivey +0 -0
- package/package.json +36 -4
- package/platforms.json +3 -0
- package/repo/LICENSE +201 -0
- package/repo/NOTICE +18 -0
- package/repo/README.md +148 -0
- package/repo/install.sh +365 -0
- package/repo/pets/README.md +25 -0
- package/repo/pets/hivey-dot/CLAUDE.md +55 -0
- package/repo/pets/hivey-dot/build.sh +34 -0
- package/repo/pets/hivey-dot/main.swift +750 -0
- package/repo/pets/hivey-h/CLAUDE.md +75 -0
- package/repo/pets/hivey-h/build.sh +34 -0
- package/repo/pets/hivey-h/main.swift +739 -0
- package/repo/pets/hivey-prompt/CLAUDE.md +59 -0
- package/repo/pets/hivey-prompt/build.sh +34 -0
- package/repo/pets/hivey-prompt/main.swift +691 -0
- package/repo/pets/pet.py +288 -0
- package/repo/pets/shared/HiveyWatch.swift +437 -0
- package/repo/pets/test_pet.py +122 -0
- package/repo/plugins/README.md +108 -0
- package/repo/plugins/agent-creator/herdr-plugin.toml +17 -0
- package/repo/plugins/dashboard/dashboard.py +507 -0
- package/repo/plugins/dashboard/herdr-plugin.toml +14 -0
- package/repo/plugins/dashboard/test_dashboard.py +134 -0
- package/repo/plugins/github/github.py +261 -0
- package/repo/plugins/github/herdr-plugin.toml +14 -0
- package/repo/plugins/github/test_github.py +49 -0
- package/repo/plugins/skills/herdr-plugin.toml +11 -0
- package/repo/plugins/skills/skills.md +41 -0
- package/repo/plugins/slack-relay/connect.py +198 -0
- package/repo/plugins/slack-relay/create_channel.py +134 -0
- package/repo/plugins/slack-relay/herdr-plugin.toml +15 -0
- package/repo/plugins/slack-relay/relay.py +401 -0
- package/repo/plugins/slack-relay/slack-app-manifest.json +30 -0
- package/repo/plugins/slack-relay/test_connect.py +66 -0
- package/repo/plugins/slack-relay/test_create_channel.py +61 -0
- package/repo/plugins/slack-relay/test_relay.py +254 -0
- package/repo/plugins/swarm-creator/herdr-plugin.toml +17 -0
- package/repo/plugins/swarm-watcher/dashboard.py +333 -0
- package/repo/plugins/swarm-watcher/herdr-plugin.toml +16 -0
- package/repo/plugins/swarm-watcher/usage.py +129 -0
- package/repo/plugins/swarm-watcher/watcher.py +191 -0
- package/repo/plugins/team-template/herdr-plugin.toml +15 -0
- package/repo/plugins/team-template/setup.py +211 -0
- package/repo/plugins/team-template/test_setup.py +73 -0
- package/repo/plugins/tts/herdr-plugin.toml +15 -0
- package/repo/skills/herdr/SKILL.md +214 -0
- package/repo/skills/hivey/SKILL.md +322 -0
- package/repo/skills/hivey/scripts/handoff.py +27 -0
- package/repo/skills/hivey/scripts/new_wiki.py +143 -0
- package/repo/skills/hivey-agent-creator/SKILL.md +303 -0
- package/repo/skills/hivey-agent-creator/references/agent-claude-md.md +256 -0
- package/repo/skills/hivey-agent-creator/references/global-guidelines.md +67 -0
- package/repo/skills/hivey-agent-creator/references/reviewer-agent.md +35 -0
- package/repo/skills/hivey-agent-creator/scripts/agent_context.py +76 -0
- package/repo/skills/hivey-agent-creator/scripts/agent_gate.py +78 -0
- package/repo/skills/hivey-agent-creator/scripts/setup_agent.py +288 -0
- package/repo/skills/hivey-agy/SKILL.md +123 -0
- package/repo/skills/hivey-agy/references/gemini-prompting.md +134 -0
- package/repo/skills/hivey-agy/scripts/agy_run.py +146 -0
- package/repo/skills/hivey-codex/SKILL.md +66 -0
- package/repo/skills/hivey-context7/SKILL.md +56 -0
- package/repo/skills/hivey-create-wiki/SKILL.md +329 -0
- package/repo/skills/hivey-grok/SKILL.md +101 -0
- package/repo/skills/hivey-grok/scripts/grok_run.py +139 -0
- package/repo/skills/hivey-swarm-creator/SKILL.md +384 -0
- package/repo/skills/hivey-swarm-creator/references/agent-claude-md.md +313 -0
- package/repo/skills/hivey-swarm-creator/references/archify-report.md +24 -0
- package/repo/skills/hivey-swarm-creator/references/dashboard.md +46 -0
- package/repo/skills/hivey-swarm-creator/references/retrospective.md +23 -0
- package/repo/skills/hivey-swarm-creator/references/shared-rules.md +39 -0
- package/repo/skills/hivey-swarm-creator/references/wiki-memory.md +30 -0
- package/repo/skills/hivey-swarm-creator/scripts/setup_agent.py +76 -0
- package/repo/skills/hivey-swarm-creator/scripts/shared_rules.py +50 -0
- package/repo/skills/hivey-swarm-creator/scripts/swarm_tasks.py +171 -0
- package/repo/skills/hivey-wiki-ingest/SKILL.md +45 -0
- package/repo/skills/hivey-wiki-lint/SKILL.md +38 -0
- package/repo/skills/hivey-wiki-list/SKILL.md +46 -0
- package/repo/skills/hivey-wiki-log/SKILL.md +45 -0
- package/repo/skills/hivey-wiki-query/SKILL.md +44 -0
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: hivey-grok
|
|
3
|
+
description: Run tasks with xAI's Grok Build CLI (`grok`, installed at ~/.grok/bin/grok) headless through a bundled uv Python runner — research questions (web search, "what's X/Twitter saying about…", trend scans with source links), quick answers, structured JSON extraction, or coding work in a folder — then check the result and report cost. Also manages grok itself: models, sessions, resuming, login, usage limits, updates, config and docs. Use whenever the user says "grok", "ask Grok", "with Grok", "grok -p", wants a Grok/xAI second opinion, or wants a Grok-powered scan of X/Twitter discussion, even if they don't say "CLI". Not for the grok.com web app in Chrome (use grok-research / deep-research-duo) and not for calling the xAI API from code.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
> Local additions: if `EXTRA_SKILL.md` exists in this skill's folder, read it too and follow it.
|
|
7
|
+
> It holds this machine's own additions; hivey updates never touch it, so put local changes
|
|
8
|
+
> there, never here.
|
|
9
|
+
|
|
10
|
+
# grok: run tasks with the Grok Build CLI
|
|
11
|
+
|
|
12
|
+
`grok` is xAI's agentic CLI (like Claude Code): it can search/fetch the web, read and edit files,
|
|
13
|
+
run shell commands and spawn subagents. Headless mode (`-p`) runs one prompt and exits.
|
|
14
|
+
|
|
15
|
+
Runner: `uv run -q --script ~/.claude/skills/hivey-grok/scripts/grok_run.py` (called `RUN` below).
|
|
16
|
+
Stdlib-only; wraps `~/.grok/bin/grok -p … --output-format json`, prints the answer to stdout
|
|
17
|
+
and a one-line `[grok] stop=… turns=… session=… cost=$…` summary to stderr.
|
|
18
|
+
|
|
19
|
+
## Why the runner and not bare `grok -p`
|
|
20
|
+
|
|
21
|
+
Two things bit us when we ran grok headless directly:
|
|
22
|
+
- **Tool calls that need approval are silently cancelled.** The JSON comes back with
|
|
23
|
+
`stopReason: "cancelled"` and a half-finished answer. The first `web_fetch` is enough to
|
|
24
|
+
trigger it. The runner turns this into exit code 3 and prints a hint.
|
|
25
|
+
- **Unrestricted, grok explores the machine.** For an "search X for…" prompt it read
|
|
26
|
+
`~/.claude/skills/*`, looked for local CLIs, and tried to drive Chrome through agent-browser.
|
|
27
|
+
That burned 17 turns (~$0.54) and hit the free-tier limit. `--research` stops this: it allows
|
|
28
|
+
WebSearch/WebFetch, denies Bash/Edit/Write/MCP, and adds a rule to cite URLs.
|
|
29
|
+
`--tools` would be the obvious fix, but it needs internal tool IDs and ignores names it doesn't know.
|
|
30
|
+
|
|
31
|
+
The runner also runs in a scratch `--cwd` (`/tmp/grok-runs`) by default, so grok doesn't index
|
|
32
|
+
whatever repo you happen to be in.
|
|
33
|
+
|
|
34
|
+
## 1. Pick the mode
|
|
35
|
+
|
|
36
|
+
| Task | Command |
|
|
37
|
+
|---|---|
|
|
38
|
+
| Research / news / "what's X saying" / trends with links | `RUN --research "<prompt>"` |
|
|
39
|
+
| Quick answer, explanation, rewrite | `RUN "<prompt>"` (add `--max-turns 3` to keep it cheap) |
|
|
40
|
+
| Structured extraction | `RUN --schema '<json schema or file.json>' "<prompt>"` → prints JSON |
|
|
41
|
+
| Code/file work in a project | `RUN --code --cwd <project> "<task>"` (auto-approves edits and shell; only in a folder the user named) |
|
|
42
|
+
| Follow-up in the same conversation | `RUN -c --cwd <same dir> "<follow-up>"` or `RUN -r <session-id> "<follow-up>"` |
|
|
43
|
+
| Long prompt | write it to a file and use `cat prompt.md \| RUN --research -` |
|
|
44
|
+
|
|
45
|
+
Useful extras: `--save out.md` (write the answer to a file), `--json` (full envelope with usage),
|
|
46
|
+
`-m <model>`, `-e low|medium|high|xhigh|max` (reasoning effort), `--max-turns N` (cost cap),
|
|
47
|
+
`--allow '<Rule>'` / `--deny '<Rule>'` (e.g. `--allow 'Bash(git *)'`), `--timeout 900`.
|
|
48
|
+
|
|
49
|
+
Research runs take 1–4 minutes. Run them with a long Bash timeout (600000 ms) or in the background.
|
|
50
|
+
|
|
51
|
+
## 2. Write the prompt
|
|
52
|
+
|
|
53
|
+
Grok does what the prompt literally says, so be specific about:
|
|
54
|
+
- **Scope and time window**: "last 7 days", "since 2026-10-08". Grok knows today's date.
|
|
55
|
+
- **Sources**: "posts on X (x.com)", "GitHub repos", "Hacker News threads".
|
|
56
|
+
- **Output shape**: sections, a table, or "top 10 with one line each".
|
|
57
|
+
- **Evidence**: "include the original post URL for every item; skip items you can't link".
|
|
58
|
+
|
|
59
|
+
Example (the user's own):
|
|
60
|
+
```bash
|
|
61
|
+
RUN --research --save ~/Desktop/agent-frameworks.md \
|
|
62
|
+
"Search X for the most discussed AI agent frameworks over the last 7 days. Identify emerging trends, recurring complaints, and promising new projects. Include links to the original posts."
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**About X/Twitter data**: on this account the CLI has no native X-search connector. It sees X
|
|
66
|
+
through web search and fetch, and x.com pages often need a login. Expect fewer and less fresh
|
|
67
|
+
X links than grok.com's in-app search gives. If the answer comes back thin on actual post URLs,
|
|
68
|
+
tell the user, and offer the Chrome-based `grok-research` / `deep-research-duo` skills, which use
|
|
69
|
+
grok.com directly.
|
|
70
|
+
|
|
71
|
+
## 3. Check and report
|
|
72
|
+
|
|
73
|
+
- Exit 0: show the answer, or summarise it if it's long and was saved with `--save`. Include
|
|
74
|
+
the cost/turns line, and mention the session id when a follow-up is likely.
|
|
75
|
+
- Spot-check that links are real `x.com/<user>/status/<id>` (or the asked-for source) URLs, not
|
|
76
|
+
invented or generic search URLs. Mention any that look made up.
|
|
77
|
+
- Exit codes: `1` error (message printed) · `2` **usage limit**: the free Grok Build quota is
|
|
78
|
+
exhausted, so tell the user to wait or upgrade to SuperGrok; don't retry in a loop · `3` cancelled
|
|
79
|
+
by a permission prompt, so rerun with the right mode or `--allow` · `4` empty answer ·
|
|
80
|
+
`124` timeout.
|
|
81
|
+
|
|
82
|
+
## 4. Managing grok itself
|
|
83
|
+
|
|
84
|
+
These don't need the runner. They're plain `grok` subcommands:
|
|
85
|
+
|
|
86
|
+
| Need | Command |
|
|
87
|
+
|---|---|
|
|
88
|
+
| Version / update | `grok --version` · `grok update` |
|
|
89
|
+
| Auth status / login | `grok models` (first line shows login) · `grok login` (browser) · `grok login --device-auth` · or `XAI_API_KEY` env |
|
|
90
|
+
| Models | `RUN --models` |
|
|
91
|
+
| Sessions | `RUN --sessions` (per cwd) · `grok sessions search <q>` · `grok export <id>` (transcript as Markdown, good for seeing which tools it used) |
|
|
92
|
+
| Token/cost of a session | `grok usage <session-id>` |
|
|
93
|
+
| Config in effect | `grok inspect` · file: `~/.grok/config.toml` |
|
|
94
|
+
| MCP servers / plugins / memory | `grok mcp …` · `grok plugin …` · `grok memory …` |
|
|
95
|
+
| Health check | `grok doctor` · `grok du` (disk use of ~/.grok) |
|
|
96
|
+
| Interactive TUI | `grok` or `grok "<initial prompt>"`. Can't run inside Claude Code's Bash; tell the user to run it with `! grok` or in their own terminal |
|
|
97
|
+
|
|
98
|
+
Full docs ship with the CLI in `~/.grok/docs/user-guide/`. Read only the file you need:
|
|
99
|
+
`14-headless-mode.md` (flags, JSON format, exit codes), `22-permissions-and-safety.md`
|
|
100
|
+
(allow/deny rule syntax), `17-sessions.md`, `07-mcp-servers.md`, `26-config-reference.md`,
|
|
101
|
+
`02-authentication.md`.
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
#!/usr/bin/env -S uv run --script
|
|
2
|
+
# /// script
|
|
3
|
+
# requires-python = ">=3.11"
|
|
4
|
+
# dependencies = []
|
|
5
|
+
# ///
|
|
6
|
+
"""Run the Grok Build CLI (`grok`) headless from Python.
|
|
7
|
+
|
|
8
|
+
Examples:
|
|
9
|
+
grok_run.py "What changed in Python 3.14?"
|
|
10
|
+
grok_run.py --research "Search X for the most discussed AI agent frameworks over the last 7 days ..."
|
|
11
|
+
grok_run.py --research --save ~/Desktop/agents.md "..." # also write the answer to a file
|
|
12
|
+
grok_run.py --code --cwd ~/projects/app "Fix the failing test in tests/test_api.py"
|
|
13
|
+
grok_run.py --schema '{"type":"object","properties":{"major":{"type":"integer"}}}' "Parse v2.14.3"
|
|
14
|
+
grok_run.py -c "Now go deeper on the second trend" # continue last session in --cwd
|
|
15
|
+
grok_run.py -r <session-id> "Follow-up question"
|
|
16
|
+
echo "long prompt" | grok_run.py -
|
|
17
|
+
grok_run.py --models | --sessions
|
|
18
|
+
"""
|
|
19
|
+
import argparse
|
|
20
|
+
import json
|
|
21
|
+
import os
|
|
22
|
+
import subprocess
|
|
23
|
+
import sys
|
|
24
|
+
from pathlib import Path
|
|
25
|
+
|
|
26
|
+
GROK = os.environ.get("GROK_BIN", str(Path.home() / ".grok/bin/grok"))
|
|
27
|
+
SCRATCH = Path("/tmp/grok-runs")
|
|
28
|
+
|
|
29
|
+
# Research mode: search and fetch the web, nothing else. Without these, headless grok
|
|
30
|
+
# cancels on the first web_fetch approval, or wanders into shell/browser automation.
|
|
31
|
+
RESEARCH_PERMS = ["--allow", "WebSearch", "--allow", "WebFetch",
|
|
32
|
+
"--deny", "Bash", "--deny", "Edit", "--deny", "Write", "--deny", "MCPTool"]
|
|
33
|
+
RESEARCH_RULES = ("Answer using only web_search and web_fetch. Do not run shell commands, "
|
|
34
|
+
"read local files, drive a browser or look for local tools. "
|
|
35
|
+
"Cite every claim with the original URL. If a source can't be reached, "
|
|
36
|
+
"say so and continue with what you have.")
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def build_cmd(a, prompt: str) -> list[str]:
|
|
40
|
+
cmd = [GROK, "-p", prompt, "--output-format", "json", "--no-auto-update"]
|
|
41
|
+
if a.model:
|
|
42
|
+
cmd += ["-m", a.model]
|
|
43
|
+
if a.effort:
|
|
44
|
+
cmd += ["--effort", a.effort]
|
|
45
|
+
if a.max_turns:
|
|
46
|
+
cmd += ["--max-turns", str(a.max_turns)]
|
|
47
|
+
if a.schema:
|
|
48
|
+
schema = Path(a.schema).expanduser()
|
|
49
|
+
cmd += ["--json-schema", schema.read_text() if schema.is_file() else a.schema]
|
|
50
|
+
if a.cont:
|
|
51
|
+
cmd += ["-c"]
|
|
52
|
+
if a.resume:
|
|
53
|
+
cmd += ["-r", a.resume]
|
|
54
|
+
if a.research:
|
|
55
|
+
cmd += RESEARCH_PERMS + ["--rules", RESEARCH_RULES]
|
|
56
|
+
if a.code:
|
|
57
|
+
cmd += ["--always-approve"]
|
|
58
|
+
for rule in a.allow:
|
|
59
|
+
cmd += ["--allow", rule]
|
|
60
|
+
for rule in a.deny:
|
|
61
|
+
cmd += ["--deny", rule]
|
|
62
|
+
return cmd
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def run(a, prompt: str) -> dict:
|
|
66
|
+
p = subprocess.run(build_cmd(a, prompt), capture_output=True, text=True, cwd=a.cwd,
|
|
67
|
+
env={**os.environ, "GROK_DISABLE_AUTOUPDATER": "1"}, timeout=a.timeout)
|
|
68
|
+
try:
|
|
69
|
+
return json.loads(p.stdout)
|
|
70
|
+
except json.JSONDecodeError:
|
|
71
|
+
return {"type": "error", "message": (p.stderr or p.stdout).strip() or f"exit {p.returncode}"}
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def main() -> int:
|
|
75
|
+
ap = argparse.ArgumentParser(description="Run grok (Grok Build CLI) headless")
|
|
76
|
+
ap.add_argument("prompt", nargs="?", help="prompt text, or '-' to read stdin")
|
|
77
|
+
mode = ap.add_mutually_exclusive_group()
|
|
78
|
+
mode.add_argument("--research", action="store_true", help="web search/fetch only, cite URLs")
|
|
79
|
+
mode.add_argument("--code", action="store_true", help="auto-approve all tools in --cwd (edits, shell)")
|
|
80
|
+
ap.add_argument("-m", "--model", help="model id (see --models)")
|
|
81
|
+
ap.add_argument("-e", "--effort", help="none|minimal|low|medium|high|xhigh|max")
|
|
82
|
+
ap.add_argument("--max-turns", type=int, help="cap agent turns (limits cost)")
|
|
83
|
+
ap.add_argument("--schema", help="JSON schema string or path to a .json file")
|
|
84
|
+
ap.add_argument("--cwd", type=lambda s: str(Path(s).expanduser()),
|
|
85
|
+
help="working dir (default: /tmp/grok-runs scratch dir)")
|
|
86
|
+
ap.add_argument("-c", "--continue", dest="cont", action="store_true", help="continue last session in --cwd")
|
|
87
|
+
ap.add_argument("-r", "--resume", help="resume a session id")
|
|
88
|
+
ap.add_argument("--allow", action="append", default=[], help="extra permission allow rule")
|
|
89
|
+
ap.add_argument("--deny", action="append", default=[], help="extra permission deny rule")
|
|
90
|
+
ap.add_argument("--timeout", type=int, default=900, help="seconds before killing grok (default 900)")
|
|
91
|
+
ap.add_argument("--save", help="also write the answer to this file")
|
|
92
|
+
ap.add_argument("--json", action="store_true", help="print the full JSON envelope")
|
|
93
|
+
ap.add_argument("--models", action="store_true", help="list models and exit")
|
|
94
|
+
ap.add_argument("--sessions", action="store_true", help="list recent sessions and exit")
|
|
95
|
+
a = ap.parse_args()
|
|
96
|
+
|
|
97
|
+
if a.models:
|
|
98
|
+
return subprocess.run([GROK, "models"]).returncode
|
|
99
|
+
if a.sessions:
|
|
100
|
+
return subprocess.run([GROK, "sessions", "list"], cwd=a.cwd).returncode
|
|
101
|
+
if not a.prompt:
|
|
102
|
+
ap.error("prompt required (or --models / --sessions)")
|
|
103
|
+
prompt = sys.stdin.read() if a.prompt == "-" else a.prompt
|
|
104
|
+
if not a.cwd:
|
|
105
|
+
SCRATCH.mkdir(parents=True, exist_ok=True)
|
|
106
|
+
a.cwd = str(SCRATCH)
|
|
107
|
+
|
|
108
|
+
try:
|
|
109
|
+
r = run(a, prompt)
|
|
110
|
+
except subprocess.TimeoutExpired:
|
|
111
|
+
print(f"[TIMEOUT] grok ran longer than {a.timeout}s", file=sys.stderr)
|
|
112
|
+
return 124
|
|
113
|
+
|
|
114
|
+
if a.json:
|
|
115
|
+
print(json.dumps(r, indent=2, ensure_ascii=False))
|
|
116
|
+
if r.get("type") == "error":
|
|
117
|
+
if not a.json:
|
|
118
|
+
print(f"[ERROR] {r.get('message')}", file=sys.stderr)
|
|
119
|
+
return 2 if "usage limit" in r.get("message", "") else 1
|
|
120
|
+
|
|
121
|
+
text = r.get("text", "")
|
|
122
|
+
if not a.json:
|
|
123
|
+
print(text)
|
|
124
|
+
if a.save:
|
|
125
|
+
Path(a.save).expanduser().write_text(text)
|
|
126
|
+
cost = r.get("total_cost_usd")
|
|
127
|
+
print(f"[grok] stop={r.get('stopReason')} turns={r.get('num_turns')} session={r.get('sessionId')}"
|
|
128
|
+
+ (f" cost=${cost:.3f}" if cost is not None else ""), file=sys.stderr)
|
|
129
|
+
if r.get("stopReason") == "cancelled":
|
|
130
|
+
print("[CANCELLED] a tool call needed approval. Use --research, --code, or --allow <Rule>.",
|
|
131
|
+
file=sys.stderr)
|
|
132
|
+
return 3
|
|
133
|
+
if not text.strip():
|
|
134
|
+
return 4
|
|
135
|
+
return 0
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
if __name__ == "__main__":
|
|
139
|
+
sys.exit(main())
|
|
@@ -0,0 +1,384 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: hivey-swarm-creator
|
|
3
|
+
description: Turn a task into a coordinated swarm of coding agents (Claude Code, Codex, Grok, Antigravity/Gemini) in hivey. This session becomes the coordinator (the swarm's master) - it designs the smallest team with the user, always adds a critic, writes a detailed CLAUDE.md brief per agent with deliverables and runnable checks, sets up the task board, git worktrees, the swarm's wiki, skills and Slack, launches it with `hivey swarm launch`, and then coordinates it. Use whenever the user says "swarm", "/swarm", "/hivey-swarm-creator", "spin up a team of agents", "launch multiple agents for this", "split this across agents", "create agents to build/research X in parallel", or otherwise wants several agents working together on one project, even if they don't say the word swarm. Also use to pause, resume, restart or continue an existing swarm ("pause the swarm", "stop the agents and save progress", "resume the swarm").
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
> Local additions: if `EXTRA_SKILL.md` exists in this skill's folder, read it too and follow it.
|
|
7
|
+
> It holds this machine's own additions; hivey updates never touch it, so put local changes
|
|
8
|
+
> there, never here.
|
|
9
|
+
|
|
10
|
+
# hivey swarm creator
|
|
11
|
+
|
|
12
|
+
You are the **coordinator**. You don't become one of the workers: you design the team with the
|
|
13
|
+
user, set it up, launch it, and then stay on as its master (pane 1 of the swarm's space). The
|
|
14
|
+
user wants a team that runs with little supervision, so most of the value is in the design and
|
|
15
|
+
the per-agent CLAUDE.md briefs.
|
|
16
|
+
|
|
17
|
+
You run either as the setup pane of `hivey swarm new "<task>"` (`HIVEY_SETUP_TASK` holds the
|
|
18
|
+
task, `HIVEY_SETUP_CWD` the folder it was started from) or because the user typed
|
|
19
|
+
`/hivey-swarm-creator` in a hivey pane. The `hivey` skill knows every hivey command;
|
|
20
|
+
`hivey swarm <command> --help` shows usage without running anything.
|
|
21
|
+
|
|
22
|
+
Scripts live in `~/.claude/skills/hivey-swarm-creator/scripts/` (or
|
|
23
|
+
`~/.agents/skills/hivey-swarm-creator/scripts/` for Codex), called `$S` below. Standard library only.
|
|
24
|
+
|
|
25
|
+
**House rules** (`references/shared-rules.md`) apply to you and every agent: end every final
|
|
26
|
+
response with `DONE: <3 words max>` on its own line (hivey's Stop hook speaks it for masters
|
|
27
|
+
and solo agents; workers stay silent), look up docs with `hivey-context7` first, respect the
|
|
28
|
+
safety hooks, keep secrets out of files, style Obsidian notes with callouts.
|
|
29
|
+
|
|
30
|
+
## Preconditions
|
|
31
|
+
|
|
32
|
+
- `test "$HIVEY_ENV" = 1`: you must be inside hivey. If not, say so and stop.
|
|
33
|
+
- **Folder** = `HIVEY_SETUP_CWD`, else the current directory, unless the user named another.
|
|
34
|
+
The **swarm root** is `<Folder>/<name>` (step 1). Agent homes go in `<root>/<agent>/`; the
|
|
35
|
+
shared work product goes in `<root>/` or a subfolder (e.g. `<root>/app/`). Every agent gets
|
|
36
|
+
access to the whole root.
|
|
37
|
+
- **Resuming?** If `<root>/.swarm/agents.json` already exists (or the current folder is a swarm
|
|
38
|
+
root), this swarm has run before. Follow **Resume a swarm** instead of designing a new one,
|
|
39
|
+
unless the user asks for a new or changed team.
|
|
40
|
+
|
|
41
|
+
## 1. Name (ask first)
|
|
42
|
+
|
|
43
|
+
Ask the user for the swarm's **name** (suggest one from the task; `[a-z][a-z0-9-]{0,18}`),
|
|
44
|
+
unless the task already says "Name: …". That one name is used everywhere: the slug
|
|
45
|
+
(`--slug`), the Slack channel `#<name>`, the root `<Folder>/<name>` and the wiki
|
|
46
|
+
`<root>/<name>-wiki`. No `swarm-` prefix anywhere. Below, `<name>` and `<slug>` are the same.
|
|
47
|
+
In the same question suggest an **emoji** for it (e.g. 📈 for trading, 📡 for a news radar)
|
|
48
|
+
unless the task already says "Icon: …"; the sidebar shows the space as `<emoji> <name>`
|
|
49
|
+
(`--icon`, step 7). The user can pick another or none.
|
|
50
|
+
|
|
51
|
+
## 2. Design the team
|
|
52
|
+
|
|
53
|
+
Work out the **smallest team** that covers the task, usually 2–5 workers. Each one costs
|
|
54
|
+
attention and coordination, so give each a **distinct deliverable**. If one agent needs
|
|
55
|
+
another's output, make that hand-off explicit instead of having two agents share a job.
|
|
56
|
+
|
|
57
|
+
**Every swarm includes a `critic`**, on top of the workers. It produces nothing itself: it
|
|
58
|
+
reviews each deliverable posted as DONE, sends concrete critique to the owner, and approves the
|
|
59
|
+
work once it's good, so the team improves its drafts instead of shipping them. Tailor its
|
|
60
|
+
criteria to the project (code: correctness, tests, security; research: sources, gaps, logic;
|
|
61
|
+
copy: clarity, audience fit) and put them in its CLAUDE.md.
|
|
62
|
+
|
|
63
|
+
For each agent decide:
|
|
64
|
+
- **key**: short kebab-case role matching `[a-z][a-z0-9_-]{0,31}` (`researcher`, `builder`,
|
|
65
|
+
`designer`). It's the folder name and the address for `hivey msg send <key>`.
|
|
66
|
+
- **mission and deliverables**: exact output paths and an objective **"done when"** for each.
|
|
67
|
+
- **dependencies**: who it needs input from and who consumes its output.
|
|
68
|
+
- **coding agent** (`--kinds`): which CLI runs it. Claude Code is the default. Suggest per
|
|
69
|
+
role: **Claude Code** for most work and the critic; **Codex** for code review or a second
|
|
70
|
+
opinion; **Grok** for X/Twitter and web research; **agy** (Antigravity, Gemini) for fast,
|
|
71
|
+
cheap tasks and image generation. All four read the CLAUDE.md you write: launch links
|
|
72
|
+
`AGENTS.md` (and `GEMINI.md` for agy) to it.
|
|
73
|
+
- **model** (`--models`): for Claude Code, `opus` for builders, the critic and deep reasoning;
|
|
74
|
+
`sonnet` for research, writing and data gathering, at a fraction of the cost. A swarm costs
|
|
75
|
+
many times what one agent does, so spend the strong model where it pays off. For Codex, Grok
|
|
76
|
+
and agy leave it to the CLI's default unless the user names one.
|
|
77
|
+
- **skills**: run `hivey skills guide` and follow it for every agent (skylls first, skills.sh
|
|
78
|
+
only with the user's OK). Skills go in the plan per agent and land in each agent's own
|
|
79
|
+
`.claude/skills/`, never globally. Capabilities no skill covers are **skill gaps**: list them
|
|
80
|
+
as suggestions (`/skill-creator`), don't build them now.
|
|
81
|
+
|
|
82
|
+
Then break the work into a **task list** for the task board. Each task has an ID, title, owner,
|
|
83
|
+
dependencies, deliverable path and, where possible, a **`check` command**: a shell command that
|
|
84
|
+
exits 0 only when the deliverable is really done (`npm test`, `pytest -q`,
|
|
85
|
+
`test -s report.md && grep -q '## Sources' report.md`, a link checker, a schema validator).
|
|
86
|
+
Runnable checks catch "claimed done but isn't", which prose criteria miss. Most failed
|
|
87
|
+
multi-agent runs come from vague specs, agents out of sync or missing verification; the board,
|
|
88
|
+
contracts and checks target exactly those.
|
|
89
|
+
|
|
90
|
+
**Contracts first** when agents build things that must fit together (code, data, APIs, file
|
|
91
|
+
formats): task T1 is "Write `<root>/shared/CONTRACTS.md`" (interfaces, data shapes, formats,
|
|
92
|
+
naming, layout), with a check, and every build task depends on it, so no builder starts before
|
|
93
|
+
the critic approves the contract.
|
|
94
|
+
|
|
95
|
+
**Code swarms: one git worktree per builder.** When two or more agents write code in the same
|
|
96
|
+
repo, each gets its own worktree and branch (step 6) so they never overwrite each other. Name an
|
|
97
|
+
**integrator** (the critic, or a dedicated agent for bigger builds) who merges the branches into
|
|
98
|
+
the main checkout and runs the full test suite on the combined result, as its own task with a
|
|
99
|
+
check.
|
|
100
|
+
|
|
101
|
+
**Mobile apps (iPhone, iOS, Android): build them with Expo**: Expo SDK (latest stable) + Expo
|
|
102
|
+
Router + TypeScript. Don't plan native Swift/Kotlin projects, even if a spec says "native". The
|
|
103
|
+
app runs through Expo tooling (`npx expo start`, `npx expo run:ios`, a dev-client build via
|
|
104
|
+
`expo prebuild`). Shared logic goes in plain TS packages; anything that must be native
|
|
105
|
+
(widgets, Live Activities, extensions) goes in as Expo modules or targets through config
|
|
106
|
+
plugins, not a hand-maintained Xcode project. Give the mobile builder Expo skills (the
|
|
107
|
+
`expo:*` plugin skills if installed, or via `hivey skills guide`) and make its check an Expo
|
|
108
|
+
command (`npx tsc --noEmit`, the tests, a prebuild + simulator build). Anything that needs the
|
|
109
|
+
user's EAS or App Store account stays with the user.
|
|
110
|
+
|
|
111
|
+
**Budget**: agree a time budget with the user (e.g. 120 min). The watcher warns you at 80% and
|
|
112
|
+
100%.
|
|
113
|
+
|
|
114
|
+
## 3. Confirm with the user
|
|
115
|
+
|
|
116
|
+
Show the plan and wait for approval before creating anything:
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
Swarm: <emoji> <name> root: <Folder>/<name> channel: #<name> budget: <N> min
|
|
120
|
+
| Agent | CLI | Model | Role / mission | Deliverables (path) | Skills | Depends on |
|
|
121
|
+
Tasks:
|
|
122
|
+
| ID | Task | Owner | Deps | Check |
|
|
123
|
+
Skill gaps: <gap> → suggestion …
|
|
124
|
+
Code: <repo path>, worktrees for <builders>, integrator: <agent> (code swarms only)
|
|
125
|
+
(critic always included)
|
|
126
|
+
Wiki: <root>/<name>-wiki (the swarm's memory; say no to skip it)
|
|
127
|
+
Slack: #<name> (connected) | not connected: run `hivey slack connect` first, or go without
|
|
128
|
+
Schedules: monitoring pass every <N> min · <timed task> … (or none)
|
|
129
|
+
Addons: hivey.dashboard, hivey.slack-relay, hivey.swarm-watcher
|
|
130
|
+
Publish: product repo <name>, swarm repo <name>-swarm, private (only if it builds something)
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
In the same message:
|
|
134
|
+
- **Confirm each agent's CLI and model.** Show them per agent with a one-line reason
|
|
135
|
+
("builder: Claude Code opus, writes the core code"; "researcher: Grok, X and web research";
|
|
136
|
+
"reviewer: Codex, second opinion on the code") and ask whether to keep or change them. The
|
|
137
|
+
user pays for every agent, so this is their call, not a default to apply silently.
|
|
138
|
+
- **Ask whether you should run scheduled checks**, and how:
|
|
139
|
+
- a **monitoring pass** every N minutes (who is idle, blocked or stuck; answer questions;
|
|
140
|
+
review finished work). Suggest 15 min, shorter for fast swarms, longer for long research.
|
|
141
|
+
- **timed tasks** with their own instructions ("every day at 09:00 summarize progress to the
|
|
142
|
+
user", "every 2 h run the test suite and file failures").
|
|
143
|
+
- or **none** (you only react to messages and alerts).
|
|
144
|
+
Each wake-up costs a turn of your model.
|
|
145
|
+
- **Slack**: run `hivey slack status` before showing the plan. Connected: `hivey swarm launch`
|
|
146
|
+
creates (or joins) `#<name>`, invites the user and starts the relay, nothing else to do. Not
|
|
147
|
+
connected: ask the user to run `hivey slack connect` in a terminal (never ask for the token in
|
|
148
|
+
chat), or go on without Slack if they prefer.
|
|
149
|
+
- **GitHub**: if the swarm builds something, ask whether to publish (product and swarm are
|
|
150
|
+
separate repos; see step 7).
|
|
151
|
+
|
|
152
|
+
The wiki always lives **inside the swarm folder**, at `<root>/<name>-wiki`, so the swarm, its
|
|
153
|
+
agents and its knowledge can be moved or shared as one folder. Never ask where the user's
|
|
154
|
+
Obsidian is. In anything an agent reads, write it relative to the agent's folder:
|
|
155
|
+
`../<name>-wiki`. Adjust the plan until the user says yes.
|
|
156
|
+
|
|
157
|
+
## 4. Scaffold the swarm
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
mkdir -p <root>/shared
|
|
161
|
+
python3 $S/shared_rules.py <root> # house rules into <root>/CLAUDE.md (marked block)
|
|
162
|
+
python3 $S/setup_agent.py <root> <agent> [--worktree <root>/app] # once per agent, critic too
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
`setup_agent.py` creates `<root>/<agent>/` and its `.claude/settings.json`, which grants access
|
|
166
|
+
to the swarm root (`permissions.additionalDirectories`, plus `--vault` if the vault lives
|
|
167
|
+
elsewhere) and sets `AGENTS_TTS=0` so workers stay silent. **Code swarms:** make sure the repo
|
|
168
|
+
(e.g. `<root>/app`) exists with at least one commit, then pass `--worktree <repo>` for each
|
|
169
|
+
builder: it gets `<root>/<agent>/repo` on branch `swarm/<agent>`. Builders commit on their
|
|
170
|
+
branch; the integrator merges into the main checkout and runs the checks there.
|
|
171
|
+
|
|
172
|
+
Then install each agent's skills as `hivey skills guide` says (step 4 of the guide), and check
|
|
173
|
+
`ls <root>/<agent>/.claude/skills`.
|
|
174
|
+
|
|
175
|
+
**Task board.** Load the approved task list. Always pass `--root <root>`, since your working
|
|
176
|
+
directory may not be under the root:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
T="python3 $S/swarm_tasks.py --root <root>"
|
|
180
|
+
$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"
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
This writes `.swarm/tasks.json` (the `hivey.dashboard` reads it), a readable `.swarm/TASKS.md`,
|
|
186
|
+
and `.swarm/events.jsonl`, the swarm's timeline. Rules the board enforces: agents **claim**
|
|
187
|
+
before starting, only their own (or unowned) tasks, and only once every dependency is
|
|
188
|
+
`approved`. Only `critic` or `coordinator` can set `approved`, and only when the task's check
|
|
189
|
+
passes (checks run outside the board lock, so a slow suite doesn't block anyone). Statuses:
|
|
190
|
+
`open → in-progress → review → approved` (`blocked` any time).
|
|
191
|
+
|
|
192
|
+
## 5. Write the briefs
|
|
193
|
+
|
|
194
|
+
Read `references/agent-claude-md.md` now: it has the template and role guidance. The briefs are
|
|
195
|
+
the heart of the swarm. Each agent works only from its own file, so it must understand the
|
|
196
|
+
whole team, not just its own job.
|
|
197
|
+
|
|
198
|
+
1. **Write "The swarm" section once**: setup (root, the swarm's space, you as master, Slack
|
|
199
|
+
mirror, wiki), the **full roster** (every agent including you and the critic: key, CLI, role,
|
|
200
|
+
what it owns, what to ask it for), a "who to talk to" list, the task board, the hand-off
|
|
201
|
+
chain, critique loop, messaging, contracts and code, safety, secrets and docs. Save it as
|
|
202
|
+
`<root>/.swarm/README.md`.
|
|
203
|
+
2. **Write `<root>/<agent>/CLAUDE.md` for each agent**: its own sections (mission, scope,
|
|
204
|
+
deliverables with paths and checks, skills, method, definition of done, Status) plus that
|
|
205
|
+
swarm section pasted in **verbatim**, so every agent sees the same roster and rules.
|
|
206
|
+
|
|
207
|
+
Make each brief detailed and specific: quote the user's original request, use exact paths, and
|
|
208
|
+
name the real agents in the commands. A vague brief leads to an agent that idles, duplicates a
|
|
209
|
+
teammate or asks the wrong agent.
|
|
210
|
+
|
|
211
|
+
## 6. Create the wiki (memory)
|
|
212
|
+
|
|
213
|
+
Unless the user said no, create the swarm's Obsidian wiki with the **`hivey-create-wiki`**
|
|
214
|
+
skill (Skill tool, args `<name> --in <root> --agent <root>/<agent> [--agent …]`, every agent
|
|
215
|
+
including the critic) now that the briefs exist. It reads the briefs, tailors the vault and
|
|
216
|
+
patches every agent's CLAUDE.md. Answer any question it has from the plan instead of asking the
|
|
217
|
+
user again. If the vault already exists (a resumed swarm), reuse it. Shape it for a swarm:
|
|
218
|
+
- `raw/reports/<agent>/` for each worker and the critic: agents write their reports there, and
|
|
219
|
+
only there.
|
|
220
|
+
- `wiki/` sub-folders: `agents/`, `findings/`, `decisions/`, `deliverables/`, `lessons/`.
|
|
221
|
+
- In the vault's CLAUDE.md add the swarm rule: *only the coordinator writes `wiki/`; it ingests
|
|
222
|
+
agent reports from `raw/reports/` without waiting to discuss them, because the swarm runs
|
|
223
|
+
unattended.* Agents writing `index.md`/`log.md` in parallel would clobber each other.
|
|
224
|
+
|
|
225
|
+
Then initialize the memory: `wiki/swarm-overview.md` (the user's request, goal, roster, Slack
|
|
226
|
+
channel, root, hand-off chain), `wiki/agents/<agent>.md` per agent (role, owns, deliverables,
|
|
227
|
+
report folder, status "not started"), `wiki/decisions/plan.md` (the approved plan and the
|
|
228
|
+
user's tweaks), linked from `index.md`, with a `bootstrap` entry in `log.md`.
|
|
229
|
+
|
|
230
|
+
## 7. Launch
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
hivey swarm launch <root> --slug <name> --icon <emoji> <agent>... critic \
|
|
234
|
+
--models builder=opus,critic=opus,writer=sonnet --kinds reviewer=codex,scout=grok \
|
|
235
|
+
--budget-min 120 --heartbeat 15m \
|
|
236
|
+
--heartbeat-task "Monitoring pass: follow the hivey-swarm-creator skill's monitoring pass" \
|
|
237
|
+
--addon hivey.dashboard --addon hivey.swarm-watcher \
|
|
238
|
+
--kickoff "Read your CLAUDE.md, then send START to coordinator as it says."
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
- This pane becomes the master `<name>-coordinator` and moves into a new space `<name>`; the
|
|
242
|
+
agents open beside it, each as `<name>-<agent>` in its own folder, run unattended.
|
|
243
|
+
- Slack: when connected, launch creates (or joins) `#<name>`, invites the user and starts
|
|
244
|
+
`hivey.slack-relay`. Post a short kickoff there (goal, roster); `hivey swarm info <name>`
|
|
245
|
+
shows the channel.
|
|
246
|
+
- Addons: `hivey.dashboard` (states, tokens per agent, active time vs budget, tasks, messages),
|
|
247
|
+
`hivey.slack-relay` (Slack ⇄ bus) and `hivey.swarm-watcher` (stalled, blocked, idle and budget
|
|
248
|
+
alerts to you, plus a live Gantt dashboard in Chrome; see `references/dashboard.md`). Missing
|
|
249
|
+
addons are reported and skipped; check `hivey plugin list`. Reopen one later with
|
|
250
|
+
`hivey swarm addon <name> <id>`.
|
|
251
|
+
- Leave out `--heartbeat` if the user chose no monitoring pass. Add timed tasks with
|
|
252
|
+
`hivey swarm schedule add <name> --at 09:00 [--id ID] "<instructions>"` or `--every 2h`
|
|
253
|
+
(`--to <agent>` wakes an agent instead of you); `hivey swarm schedule list|remove|run <name>
|
|
254
|
+
[<id>]`. Each wake-up arrives as a `[hivey]` message with the task and a status snapshot, only
|
|
255
|
+
when you're idle; one still waiting is never duplicated, and paused swarms are skipped.
|
|
256
|
+
- **Directory**: register what the swarm does so other swarms and agents can judge whether to ask
|
|
257
|
+
it for help: `hivey swarm profile <name> --description "<one line>" --skills a,b --tools "gh, …"`.
|
|
258
|
+
Only you (the master) may message another swarm (`hivey msg send <slug>/master "…"`), and only
|
|
259
|
+
after the user says yes; don't disturb one marked busy.
|
|
260
|
+
- **GitHub**: if the user wants the product published, keep it in its own folder (default
|
|
261
|
+
`<root>/app`, or `"product_dir"` in `.swarm/agents.json`) with its own git repo, and run
|
|
262
|
+
`hivey swarm addon <name> hivey.github`: it shows the plan, the user confirms in that pane,
|
|
263
|
+
and secrets are scanned before each first push. Never create or push repos without that.
|
|
264
|
+
|
|
265
|
+
Tell the user what's running: the space, agents, CLIs, Slack channel, wiki path, dashboards,
|
|
266
|
+
schedules and skill gaps.
|
|
267
|
+
|
|
268
|
+
### Save and share (skylls)
|
|
269
|
+
|
|
270
|
+
If `skylls --version` works, offer to save the swarm once it's running, so the user can reuse
|
|
271
|
+
and share it. Only with their yes: `skylls swarms push <root> -m "<what it does>"`, plus
|
|
272
|
+
`skylls push <skill folder>` for any new skill you wrote. Push scans for secrets and personal
|
|
273
|
+
data and refuses if it finds any: remove them, never pass `--skip-scan`. Share
|
|
274
|
+
(`skylls swarms share <name> @user`) only when the user asks. Before designing a new swarm,
|
|
275
|
+
`skylls --json swarms find <words> --limit 5` may show one that already fits.
|
|
276
|
+
|
|
277
|
+
## 8. Coordinate
|
|
278
|
+
|
|
279
|
+
**The wiki is your source of truth too.** Read `wiki/index.md`, `swarm-overview.md`, the agent
|
|
280
|
+
pages and recent `findings/`/`decisions/` whenever you start or resume coordinating, and before
|
|
281
|
+
any decision that depends on what the swarm knows. If an agent's claim or your memory conflicts
|
|
282
|
+
with the wiki, check the source, then correct the wiki or the agent, so there is one truth.
|
|
283
|
+
|
|
284
|
+
Watch the agents, not just their messages:
|
|
285
|
+
|
|
286
|
+
```bash
|
|
287
|
+
hivey swarm list # states (working/idle/blocked) + queued messages
|
|
288
|
+
hivey agent read <name>-<agent> --source recent-unwrapped --lines 120 # what it is doing/said
|
|
289
|
+
hivey msg inbox # messages for you
|
|
290
|
+
hivey msg log --swarm <name> --limit 40 # the team's traffic
|
|
291
|
+
hivey swarm info <name> # channel, vault, addons, budget, tasks
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
You reach agents with `hivey msg send <agent> "…"` (`@all`, `@role:worker`, `--fyi` never wakes,
|
|
295
|
+
`--urgent` interrupts). Delivery waits until the recipient is idle, and you're told when one is
|
|
296
|
+
blocked. Messages and alerts arrive in your pane as `[hivey]` prompts; handle them as
|
|
297
|
+
coordinator work.
|
|
298
|
+
|
|
299
|
+
**Handling an alert or message** (one agent):
|
|
300
|
+
- **It asked a question**: answer it if it's within the plan; if it's the user's call, ask the
|
|
301
|
+
user and relay the answer.
|
|
302
|
+
- **It says it's done**: check the deliverable exists, meets its "done when" and its check
|
|
303
|
+
passes, that it sent DONE to the critic and wrote its report to the wiki. If anything is
|
|
304
|
+
missing, tell it exactly what.
|
|
305
|
+
- **It's waiting on a teammate**: check that teammate's state and nudge whichever side holds
|
|
306
|
+
things up.
|
|
307
|
+
- **It stopped mid-task** with no question and no DONE: tell it to continue from its own Next
|
|
308
|
+
steps.
|
|
309
|
+
- **Blocked on a dialog**: read its pane first; answer only dialogs you understand, ask the user
|
|
310
|
+
about anything else.
|
|
311
|
+
- **A safety block** (`hivey safety` hooks): decide whether the operation is really needed. If it
|
|
312
|
+
is, ask the user. Never tell an agent to work around a block, and never turn safety off.
|
|
313
|
+
- **Gone** (pane closed or agent exited): `hivey swarm relaunch <name> <agent>`; it continues its
|
|
314
|
+
conversation and its Status section.
|
|
315
|
+
|
|
316
|
+
**Check every START message.** Each agent's first message restates its task and lists its
|
|
317
|
+
assumptions. Compare them with the plan as they arrive: a wrong assumption corrected in minute
|
|
318
|
+
two saves an hour.
|
|
319
|
+
|
|
320
|
+
**A monitoring pass** (each heartbeat, and whenever the user asks for status):
|
|
321
|
+
1. `hivey swarm list`, then `hivey agent read` for any agent whose state changed since the last
|
|
322
|
+
pass (all of them every third pass). Read `hivey msg log`, `.swarm/TASKS.md` and the tail of
|
|
323
|
+
`.swarm/events.jsonl`.
|
|
324
|
+
2. Glance at token use on the dashboard. An agent burning tokens while its tasks don't move is
|
|
325
|
+
probably looping: read its pane and redirect it. Compare each agent's work with its tasks;
|
|
326
|
+
flag anything missing, out of scope or duplicated, unclaimed tasks whose deps are approved
|
|
327
|
+
(assign them), and `review` tasks nobody is reviewing.
|
|
328
|
+
3. Answer open questions, nudge idle agents that still have work, resolve stalled critique.
|
|
329
|
+
4. Ingest new reports into the wiki (`references/wiki-memory.md`), and update **Swarm status**
|
|
330
|
+
at the bottom of `.swarm/README.md` and in `wiki/swarm-overview.md` (date, each agent's state
|
|
331
|
+
and deliverables, critique rounds, open decisions, what to do first on resume).
|
|
332
|
+
5. Tell the user only what changed or needs their decision; otherwise keep the pass quiet.
|
|
333
|
+
|
|
334
|
+
**Critique loop.** Every deliverable goes owner → DONE → critic → CRITIQUE r<N> → REVISED →
|
|
335
|
+
APPROVED. If owner and critic disagree, or a deliverable reaches round 3 without APPROVED, you
|
|
336
|
+
decide: accept, re-scope, or give a specific fix, and tell both.
|
|
337
|
+
|
|
338
|
+
**Roster changes** (agents added or re-scoped): update `.swarm/README.md` and the swarm section
|
|
339
|
+
in every agent's CLAUDE.md, then `hivey msg send @all` what changed. A new agent: scaffold it,
|
|
340
|
+
write its brief, and add it with `hivey swarm relaunch <name> <agent>` once it's in the manifest
|
|
341
|
+
(or ask the user to relaunch the swarm).
|
|
342
|
+
|
|
343
|
+
Every agent keeps its own Status section; if one looks stale against its pane output, tell the
|
|
344
|
+
agent to update it. Don't close the swarm's space or panes unless the user asks.
|
|
345
|
+
|
|
346
|
+
**Finishing.** A worker only counts as finished once every deliverable is APPROVED and its final
|
|
347
|
+
report is ingested into the wiki. When all workers and the critic have finished, run the
|
|
348
|
+
connection pass and write `wiki/swarm-final-report.md` (`references/wiki-memory.md`), check the
|
|
349
|
+
deliverables against the user's original request, and give the user the **final report**:
|
|
350
|
+
outcome, where each deliverable is, open risks, next steps and the wiki path. If the `archify`
|
|
351
|
+
skill is installed, add the visual report (`references/archify-report.md`). Then write the
|
|
352
|
+
retrospective (`references/retrospective.md`).
|
|
353
|
+
|
|
354
|
+
## Pause a swarm
|
|
355
|
+
|
|
356
|
+
When the user says "pause/stop the swarm (for now)" or "save progress for next run":
|
|
357
|
+
1. Tell every agent: `hivey msg send @all --urgent "Pause: stop at a safe point, save your
|
|
358
|
+
in-progress work to files, and rewrite the Status section of your CLAUDE.md (keep the STATUS
|
|
359
|
+
markers). Then reply PAUSED --fyi and wait."`
|
|
360
|
+
2. Wait until every agent is idle in `hivey swarm list` and its CLAUDE.md changed after the
|
|
361
|
+
pause began (`ls -l <root>/*/CLAUDE.md`). For any that didn't save, read its pane and ask
|
|
362
|
+
again, or write what you can see into `.swarm/README.md`. Never invent its status.
|
|
363
|
+
3. `hivey swarm pause <name>`: holds message delivery; schedules skip a paused swarm.
|
|
364
|
+
4. Record half-done work in **Swarm status** (`.swarm/README.md` and `wiki/swarm-overview.md`):
|
|
365
|
+
what's approved, what's open, who does what first on resume, and the resume command. Log it:
|
|
366
|
+
`python3 $S/swarm_tasks.py --root <root> log pause --as coordinator --note "<reason>"`.
|
|
367
|
+
5. Tell the user it's paused, what's saved where, and how to resume. Panes and sessions stay;
|
|
368
|
+
stopping the hivey session would stop the agents, so only do that if the user asks.
|
|
369
|
+
|
|
370
|
+
## Resume a swarm
|
|
371
|
+
|
|
372
|
+
When `<root>/.swarm/agents.json` exists, the team, briefs, skills and channel already exist, and
|
|
373
|
+
each agent's memory is its Status section.
|
|
374
|
+
1. Read the wiki first (`index.md`, `swarm-overview.md`, `swarm-final-report.md` if present,
|
|
375
|
+
agent pages, recent findings and decisions), then `.swarm/README.md` (Swarm status),
|
|
376
|
+
`.swarm/TASKS.md` and each agent's Status. Summarize for the user where each agent left off
|
|
377
|
+
and what's next, and ask how much time remains.
|
|
378
|
+
2. `hivey swarm resume <name>` releases message delivery. If agents exited or their panes are
|
|
379
|
+
gone (e.g. after a restart), `hivey swarm relaunch <name> [<agent>...]` starts them again,
|
|
380
|
+
continuing their conversations, and reopens dead addons (`--addons-only` for just those).
|
|
381
|
+
3. `hivey msg send @all "Resumed: read the wiki and your Status, then continue from Next steps
|
|
382
|
+
and send RESUMED to coordinator."` Check each RESUMED reply against the Swarm status notes.
|
|
383
|
+
4. Coordinate as in step 8. For roster changes, update every brief first. Use
|
|
384
|
+
`hivey swarm launch` again only for a brand-new team or when the manifest is missing.
|