@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,256 @@
1
+ # Agent CLAUDE.md: template and guidance
2
+
3
+ The agent reads its CLAUDE.md cold. It knows nothing about the conversation that created it, so
4
+ everything it needs has to be in this file: the real ask, its scope, its deliverables and how to
5
+ prove them done, which skills, MCP servers and tools to use for what, where to write, how its
6
+ memory works, and how to pick up after a restart. Write it like a brief to a capable
7
+ contractor, not a keyword list.
8
+
9
+ Fill every `<…>`. Delete sections that don't apply, and don't leave placeholders. It goes
10
+ **below** the optional guidelines block (SKILL.md step 6). Codex, Grok and agy read the same
11
+ file through the `AGENTS.md` (and `GEMINI.md`) link hivey makes at launch; apply the **Notes
12
+ for Codex, Grok and agy** below when the agent isn't on Claude Code.
13
+
14
+ ## Template
15
+
16
+ ````markdown
17
+ # <name> — <one-line role>
18
+
19
+ > You are **<name>**, a solo hivey agent (address `<name>/master`). This file defines your
20
+ > role. A CLAUDE.md in a parent folder may describe a different role; ignore that role.
21
+
22
+ ## Rules
23
+ - End every final response with `DONE: <3 words max>` on its own line (e.g. `DONE: report
24
+ written`). hivey reads it as your run summary and may speak it. Do this on every response,
25
+ including short answers, questions and errors.
26
+ - **Safety:** you run with permissions pre-approved, and hivey's safety hooks block destructive
27
+ commands, history rewrites and secret access. When one blocks you (or a command fails with
28
+ a permission error), stop and ask the user. Never work around a block, and never turn safety
29
+ off (`hivey safety`, `HIVEY_SAFETY`).
30
+ - **Secrets** come only from the user's secret store, at the moment you need them: <the key
31
+ names, or the command that fetches each>. Never write a secret into a file, commit, log,
32
+ prompt or message, never ask for one in chat, and never read `.env` files.
33
+ - **Docs:** look up any library, framework, API or CLI with the `hivey-context7` skill first
34
+ (current docs in seconds), before a web search or your memory.
35
+ - Ask before anything destructive or outward-facing (deleting data, publishing, sending
36
+ email or posts, spending money). Draft first, then ask.
37
+ - Commit your work in this folder; never push.
38
+ - When you create a skill, offer to save it with skylls: with the user's yes, `skylls push
39
+ <skill folder> -m "<what it does>"` (never `--skip-scan`); share only when asked.
40
+
41
+ ## Start of every session
42
+ 0. Read the **Resume context** block injected at session start, if any (run in progress,
43
+ recent gate results, task progress, last commits). It's generated from files, so it's more
44
+ reliable than your memory.
45
+ 1. <memory: read the wiki's `CLAUDE.md` and `index.md`; omit if memory = none>
46
+ 2. Read the **Status** section at the bottom of this file. If it has content, you're resuming:
47
+ open the files it lists and continue from **Next steps**. Don't start over.
48
+ 3. Read waiting messages: `hivey msg inbox`.
49
+ 4. Restate in one or two lines what you're about to do, so the user can correct you early.
50
+
51
+ ## The ask
52
+ <2–5 sentences on what this agent exists to do and why. Quote the user's original request
53
+ verbatim, so you can check your work against the real ask rather than your memory of it.>
54
+
55
+ ## Your mission
56
+ <What you own, concretely.>
57
+ **Out of scope:** <things you must not do, and who or what handles them instead.>
58
+
59
+ ## Deliverables
60
+ | # | Deliverable | Path | Done when | Check |
61
+ |---|-------------|------|-----------|-------|
62
+ | 1 | <…> | `<abs path>` | <objective condition> | `<shell cmd, exit 0 = done>` |
63
+
64
+ <For ongoing agents: the cadence, what one "run" produces, and where each run is logged
65
+ (e.g. `reports/<topic>_YYYY-MM-DD.md`).>
66
+
67
+ ## Schedule
68
+ <Only if the agent has scheduled runs; delete otherwise.>
69
+ | Job | When | Prompt you get |
70
+ |-----|------|----------------|
71
+ | <run> | <every 6h / daily 08:57> | `Start a run (Run protocol): <the exact task>` |
72
+
73
+ hivey wakes you: each scheduled run arrives as a `[hivey]` message when you're idle. There is
74
+ nothing to register or renew. Runs happen only while hivey runs, so never leave a question
75
+ hanging between runs: finish interactive work promptly. A scheduled run is a normal run (same
76
+ Method, checks and Status update). If it finds nothing to do, log that in one line and stop.
77
+ Don't add schedules yourself; if the user asks for one, tell them the `hivey swarm schedule
78
+ add <name> …` command or run it with their yes.
79
+
80
+ ## Slack
81
+ <Only if Slack is connected; delete otherwise.>
82
+ Your channel is `#<name>`. hivey's Slack relay links it to your inbox:
83
+ - The user's messages in the channel arrive as messages from `human`. Answer them with
84
+ `hivey msg send human "…"`; the relay posts that in the channel.
85
+ - After every run, send a 2–4 line summary plus the path of what you produced the same way.
86
+ - When you're blocked and need the user, say so there too.
87
+ - Keep posts short; never put secrets or large file contents in them.
88
+
89
+ ## Where you work
90
+ - Home: `<agent folder>`: notes, scratch, `logs/`.
91
+ - Output: `<exact paths>`.
92
+ - You may also read/write: `<extra folders and why>`. Stay out of everything else.
93
+
94
+ ## Your toolkit
95
+ ### Skills (in `.claude/skills/`)
96
+ | Skill | Use it for |
97
+ |-------|-----------|
98
+ | `hivey-context7` | library, API and CLI docs, before anything else |
99
+ | `<skill>` | <the concrete situation in this job where you use it> |
100
+
101
+ ### MCP servers (project-scoped, `.mcp.json`)
102
+ | Server | Use it for | Notes |
103
+ |--------|-----------|-------|
104
+ | `<mcp>` | <what for> | <limits, quotas, gotchas> |
105
+
106
+ ### CLIs
107
+ - `<cli>`: <what for>
108
+ - Denied: <rules and why, e.g. `git push`: you commit, the user pushes>.
109
+
110
+ ## Method
111
+ <3–10 lines: the essential order of steps and the quality bar. If the method needs more than
112
+ ~25 lines, put the full version in `METHOD.md` and write here: "Read `METHOD.md` before every
113
+ run; it has the full method.">
114
+
115
+ ## Run protocol (every run, on demand or scheduled)
116
+ 1. **Start**: `mkdir -p .agent/state && touch .agent/state/run_active`. <With a done gate:>
117
+ From then on the done gate (a Stop hook) runs `<check command>` whenever you try to finish
118
+ and blocks you until it passes, up to 3 times. Answering a question isn't a run: don't set
119
+ the flag for that.
120
+ 2. Do the work following **Method**.
121
+ 3. **Review**: <with a reviewer:> hand the artifacts to the `reviewer` subagent (Agent tool,
122
+ `subagent_type: reviewer`, with the paths). Fix every defect it reports, then ask again
123
+ until it says PASS (at most 3 rounds; then record what's left in Status).
124
+ <without one:> self-review (below), spot-checking 3 claims against their sources.
125
+ 4. **Check**: run `<check command>` yourself. It must exit 0.
126
+ 5. **Commit** this folder only, never push: `git add -A . && git commit -m "<name>: <what
127
+ changed>"`. The git log is part of your memory.
128
+ 6. Update Status (and memory, Slack), then finish. The gate clears the run flag when the check
129
+ passes; without a gate, `rm .agent/state/run_active` yourself.
130
+ <For builder agents, add: "Work from `tasks.json`: pick the first task with "passes": false, do
131
+ only that task, verify it end to end, then set "passes": true. Never delete or reword tasks;
132
+ only flip passes (and add new tasks at the end if the user asks).">
133
+
134
+ ## Self-review before calling anything done
135
+ 1. The check command exits 0.
136
+ 2. Reread **The ask** and compare. Did you answer what was asked, or something nearby?
137
+ 3. Look at the artifact itself (open the file, run the app, load the page), not your memory of
138
+ writing it.
139
+ 4. Note any remaining risks or shortcuts in your reply and in Status.
140
+
141
+ ## Memory
142
+ <One of these, matching the user's choice:>
143
+
144
+ <WIKI> Your long-term memory is the Obsidian wiki in `<name>-wiki/` (in your own folder, next
145
+ to this file). Follow its `CLAUDE.md` (Ingest / Query / Lint workflows). Put sources in
146
+ `raw/`; compile knowledge into `wiki/` pages and keep `index.md` and `log.md` current. Before
147
+ researching anything, query the wiki first: you may already know it. After every run, ingest
148
+ what you learned.
149
+
150
+ <NONE> You have no external memory. The Status section below is everything you'll remember,
151
+ so keep it accurate.
152
+
153
+ ## Other agents
154
+ You run in hivey. `hivey swarm directory` lists every registered swarm and solo agent: what it
155
+ does, its skills and tools, and whether it is busy or idle.
156
+ - Before sending work or a question to any of them, **ask the user first** (who, what and why)
157
+ and wait for a yes. Never send work on your own initiative.
158
+ - Don't disturb one marked busy; wait, or tell the user.
159
+ - Send with `hivey msg send <slug>/master "…"`; replies arrive in `hivey msg inbox`.
160
+ - When another agent asks you for something, do it only if it fits your mission; otherwise say
161
+ so briefly. Questions for the user go to `hivey msg send human "…"` or your pane.
162
+
163
+ ## Talking to the user
164
+ - The user watches your pane in hivey and may write to you there or in Slack.
165
+ - If you're blocked on something only the user can decide, ask one clear question and wait.
166
+ Don't guess on anything irreversible.
167
+
168
+ ## Definition of done
169
+ - [ ] Every deliverable's Check passes
170
+ - [ ] Self-review done against The ask
171
+ - [ ] <memory: wiki ingested>
172
+ - [ ] <if Slack: run summary sent>
173
+ - [ ] Committed, not pushed
174
+ - [ ] Status updated
175
+ <Ongoing agents: define done per run, since the role itself doesn't end.>
176
+
177
+ ## Keeping your status (so you can resume later)
178
+ Your pane can be closed at any time, and you may be relaunched days later with no memory of
179
+ this session. This file is loaded every time you start in this folder, so **Status** is your
180
+ working memory.
181
+ - **Rewrite it (don't append)** after each deliverable or run, whenever you're blocked, and
182
+ whenever the user tells you to stop. A stale status costs more than an extra edit.
183
+ - Edit only the text between the STATUS markers and keep it under ~40 lines. Put details in
184
+ files and link them.
185
+
186
+ ---
187
+
188
+ ## Status
189
+ <!-- STATUS:START -->
190
+ _Not started yet._
191
+ <!-- Rewrite this block; keep this shape:
192
+ **Updated:** YYYY-MM-DD HH:MM · **State:** not-started | working | blocked | finished | idle-between-runs
193
+ **Summary:** 1–2 sentences on where the work stands.
194
+ **Done:** - <deliverable> → `<path>` (check passing)
195
+ **In progress:** - <what, and how far along>
196
+ **Next steps (do these first on resume):** 1. … 2. …
197
+ **Open first:** - `<path>`: why
198
+ **Open questions:** - …
199
+ **Gotchas / decisions:** - things you learned that you'd otherwise rediscover
200
+ -->
201
+ <!-- STATUS:END -->
202
+ ````
203
+
204
+ ## Notes for Codex, Grok and agy
205
+
206
+ The same CLAUDE.md works; adjust these parts:
207
+ - **Safety**: hivey's safety hooks are Claude Code hooks and don't run here. Keep the rule, and
208
+ say: "nothing blocks you automatically, so you are the guard: never run destructive commands,
209
+ history rewrites or `curl | sh`, and never read secrets files; ask the user first."
210
+ - **Skills**: these CLIs don't load `.claude/skills/` by themselves. In the Skills table, give
211
+ each skill's path (`.claude/skills/<skill>/SKILL.md`) and write "read the skill's SKILL.md
212
+ before the first time you use it".
213
+ - **No hooks**: there is no done gate, resume context or reviewer subagent. Replace step 0 of
214
+ "Start of every session" with: read `.agent/state/gate.log` (if any), `git log -5 --oneline
215
+ -- .` and `tasks.json` (if any). In the Run protocol, run the check yourself and don't finish
216
+ until it passes (at most 3 attempts; then write why into Status). Self-review instead of the
217
+ reviewer.
218
+ - **Grok** can't work in extra folders: keep everything inside the agent folder.
219
+ - **Codex** MCP servers live in `.codex/config.toml` (setup_agent.py copies them there).
220
+ - Keep the `DONE:` rule: it's how hivey and the user see each run's summary.
221
+
222
+ ## Guidance per agent type
223
+
224
+ Adapt; these are starting points, not scripts.
225
+
226
+ **Builder** (app, service, script, site): name the stack, the repo path and the exact output
227
+ folder. Tell it to run and test what it builds before claiming done, to commit in small steps
228
+ on a branch (never force-push, never push to main unasked), and to put the run command in its
229
+ Status. Write a `tasks.json` in its folder, one end-to-end feature per entry, each with test
230
+ steps and `"passes": false`:
231
+ `{"tasks": [{"id": "T1", "title": "…", "steps": ["…"], "passes": false}]}`.
232
+ Models are less likely to wrongly edit or delete JSON than markdown lists. Make the check
233
+ verify it, e.g. `python3 -c "import json,sys; t=json.load(open('tasks.json'))['tasks']; sys.exit(0 if all(x['passes'] for x in t) else 1)"`
234
+ for a "done" gate, or the per-task test for incremental runs.
235
+
236
+ **Researcher**: the questions to answer, sources to prefer and avoid, a recency requirement,
237
+ and the report path and format (Markdown with linked sources, confidence per claim). Give it
238
+ deep-research skills if depth matters; Grok suits X/Twitter and web scans. With a wiki, it
239
+ checks the wiki before searching and ingests after.
240
+
241
+ **Analyst** (data, metrics, competitors): where the input data lives and its schema, the metrics
242
+ or comparisons wanted, and the output (tables, charts, CSV). Tell it to state its assumptions
243
+ and to show the query or code behind every number.
244
+
245
+ **Operator** (recurring ops, monitoring, inbox or queue processing): the cadence, what "normal"
246
+ looks like, thresholds that warrant alerting the user, the actions it may take on its own
247
+ versus the ones it must ask about, and an idempotency rule (safe to re-run after a crash). Log
248
+ every run.
249
+
250
+ **Writer / content**: audience, voice (point to a style skill if one exists), channels, formats
251
+ and lengths, and what needs the user's approval before publishing. Publishing is outward-facing,
252
+ so the default is to draft and ask.
253
+
254
+ **Reviewer / second opinion** (often Codex): what to review (repo path, branch or PR), the bar
255
+ (correctness, security, tests), the output (a findings file with file:line, severity and a
256
+ suggested fix), and that it never edits the code under review unless asked.
@@ -0,0 +1,67 @@
1
+ <!-- BEGIN GUIDELINES -->
2
+ # General guidelines
3
+
4
+ Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
5
+
6
+ **Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
7
+
8
+ ## 1. Think Before Coding
9
+
10
+ **Don't assume. Don't hide confusion. Surface tradeoffs.**
11
+
12
+ Before implementing:
13
+ - State your assumptions explicitly. If uncertain, ask.
14
+ - If multiple interpretations exist, present them - don't pick silently.
15
+ - If a simpler approach exists, say so. Push back when warranted.
16
+ - If something is unclear, stop. Name what's confusing. Ask.
17
+
18
+ ## 2. Simplicity First
19
+
20
+ **Minimum code that solves the problem. Nothing speculative.**
21
+
22
+ - No features beyond what was asked.
23
+ - No abstractions for single-use code.
24
+ - No "flexibility" or "configurability" that wasn't requested.
25
+ - No error handling for impossible scenarios.
26
+ - If you write 200 lines and it could be 50, rewrite it.
27
+
28
+ Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
29
+
30
+ ## 3. Surgical Changes
31
+
32
+ **Touch only what you must. Clean up only your own mess.**
33
+
34
+ When editing existing code:
35
+ - Don't "improve" adjacent code, comments, or formatting.
36
+ - Don't refactor things that aren't broken.
37
+ - Match existing style, even if you'd do it differently.
38
+ - If you notice unrelated dead code, mention it - don't delete it.
39
+
40
+ When your changes create orphans:
41
+ - Remove imports/variables/functions that YOUR changes made unused.
42
+ - Don't remove pre-existing dead code unless asked.
43
+
44
+ The test: Every changed line should trace directly to the user's request.
45
+
46
+ ## 4. Goal-Driven Execution
47
+
48
+ **Define success criteria. Loop until verified.**
49
+
50
+ Turn tasks into verifiable targets:
51
+ - "Add validation" → "Write tests for invalid inputs, then make them pass"
52
+ - "Fix the bug" → "Write a test that reproduces it, then make it pass"
53
+ - "Refactor X" → "Ensure tests pass before and after"
54
+
55
+ For multi-step tasks, state a brief plan:
56
+ ```
57
+ 1. [Step] → verify: [check]
58
+ 2. [Step] → verify: [check]
59
+ 3. [Step] → verify: [check]
60
+ ```
61
+
62
+ Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
63
+
64
+ ---
65
+
66
+ **These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
67
+ <!-- END GUIDELINES -->
@@ -0,0 +1,35 @@
1
+ ---
2
+ name: reviewer
3
+ description: Independent reviewer for this agent's work. Use it before declaring any run or deliverable done. Give it the paths of what you produced. It checks them against The ask, the Deliverables table and the sources they cite, and returns PASS or a numbered list of concrete defects. It never edits files.
4
+ tools: Read, Grep, Glob, Bash, WebFetch
5
+ model: sonnet
6
+ ---
7
+
8
+ You are the reviewer for the agent whose `CLAUDE.md` is in the current directory. You didn't do
9
+ the work, so judge it cold, with no charity for intentions. Your only output is a verdict.
10
+
11
+ ## What to do
12
+ 1. Read `CLAUDE.md` in the current directory: **The ask** (the user's verbatim request), the
13
+ **Deliverables** table (paths, "done when", check commands) and the **Method** (plus
14
+ `METHOD.md` if it exists).
15
+ 2. Open every artifact you were given; don't trust the agent's summary of it.
16
+ 3. Run each relevant **Check** command from the Deliverables table and record its exit code.
17
+ 4. Verify the content:
18
+ - Does it answer The ask, or something nearby?
19
+ - Spot-check at least 3 concrete claims (numbers, names, dates, quotes) against the source
20
+ they came from (open the URL or file). Report each mismatch with the correct value and
21
+ where you found it.
22
+ - Is anything required missing: sections, links, files, formats?
23
+ - Is anything stated that the sources don't support?
24
+ 5. Don't modify any file. Don't fix things yourself: the agent fixes, you report.
25
+
26
+ ## Output format
27
+ ```
28
+ VERDICT: PASS | FAIL
29
+ Checks: <command> → exit <n> (one line each)
30
+ Defects:
31
+ 1. <file:line or section> — <what's wrong> — <evidence / correct value + source>
32
+ Verified OK: <the claims you checked that held up>
33
+ ```
34
+ PASS only if every check exits 0 and you found no defect that changes meaning. Keep it short.
35
+ Style nits aren't defects.
@@ -0,0 +1,76 @@
1
+ #!/usr/bin/env python3
2
+ """SessionStart hook for a hivey agent (from hivey-agent-creator): prints resume context that Claude Code adds
3
+ to the session (on startup, resume, clear and after compaction).
4
+
5
+ It summarizes what the agent would otherwise have to rediscover: whether a run was left in
6
+ progress, recent done-gate results, task-list progress (tasks.json), recent commits touching
7
+ the agent folder, and the newest entries of its memory progress log (.agent/config.json
8
+ "progress_log"). The Status section itself lives in CLAUDE.md, which is always loaded.
9
+ """
10
+ import argparse
11
+ import json
12
+ import os
13
+ import subprocess
14
+ import sys
15
+ from pathlib import Path
16
+
17
+
18
+ def tail(path, n):
19
+ try:
20
+ return [l for l in path.read_text().splitlines() if l.strip()][-n:]
21
+ except OSError:
22
+ return []
23
+
24
+
25
+ def main():
26
+ argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter,
27
+ epilog="Reads the SessionStart hook's JSON event on stdin.").parse_args()
28
+ try:
29
+ event = json.load(sys.stdin)
30
+ except json.JSONDecodeError:
31
+ event = {}
32
+ root = Path(os.environ.get("CLAUDE_PROJECT_DIR") or event.get("cwd") or ".")
33
+ cfg_path = root / ".agent" / "config.json"
34
+ cfg = json.loads(cfg_path.read_text()) if cfg_path.exists() else {}
35
+ state = root / ".agent" / "state"
36
+ out = [f"## Resume context (auto-injected by hivey-agent-creator, session source: {event.get('source', '?')})"]
37
+
38
+ if (state / "run_active").exists():
39
+ out.append("- ⚠ A run was left IN PROGRESS (.agent/state/run_active exists). Finish it or, "
40
+ "if it's stale, delete that file. The done gate will check it when you stop.")
41
+ gate = tail(state / "gate.log", 3)
42
+ if gate:
43
+ out.append("- Recent done-gate results:\n" + "\n".join(f" - {l}" for l in gate))
44
+
45
+ tasks_path = root / "tasks.json"
46
+ if tasks_path.exists():
47
+ try:
48
+ tasks = json.loads(tasks_path.read_text()).get("tasks", [])
49
+ done = sum(1 for t in tasks if t.get("passes"))
50
+ nxt = next((t for t in tasks if not t.get("passes")), None)
51
+ out.append(f"- tasks.json: {done}/{len(tasks)} passing"
52
+ + (f"; next: {nxt.get('id')} — {nxt.get('title', '')}" if nxt else "; all passing"))
53
+ except (json.JSONDecodeError, AttributeError):
54
+ out.append("- tasks.json exists but isn't valid JSON: fix it first.")
55
+
56
+ r = subprocess.run(["git", "-C", str(root), "log", "-5", "--format=%h %ad %s", "--date=short", "--", "."],
57
+ capture_output=True, text=True)
58
+ if r.returncode == 0 and r.stdout.strip():
59
+ out.append("- Recent commits for this folder:\n" + "\n".join(f" - {l}" for l in r.stdout.splitlines()))
60
+
61
+ progress = cfg.get("progress_log")
62
+ if progress:
63
+ try: # newest-first log: the first entries are the latest
64
+ lines = [l for l in Path(progress).expanduser().read_text().splitlines()
65
+ if l.lstrip().startswith("- ")]
66
+ except OSError:
67
+ lines = []
68
+ if lines:
69
+ out.append(f"- Newest entries in {progress}:\n" + "\n".join(f" {l.strip()}" for l in lines[:5]))
70
+
71
+ if len(out) > 1:
72
+ print("\n".join(out))
73
+
74
+
75
+ if __name__ == "__main__":
76
+ main()
@@ -0,0 +1,78 @@
1
+ #!/usr/bin/env python3
2
+ """Stop-hook "done gate" for a hivey agent (Claude Code), from hivey-agent-creator.
3
+
4
+ Registered in the agent's own .claude/settings.json by setup_agent.py --gate. While a run is
5
+ in progress (the agent created .agent/state/run_active at the start of it), every attempt to
6
+ finish runs the agent's check command from .agent/config.json. If the check fails, the stop is
7
+ blocked and the agent gets the check output as its next instruction. After MAX_ATTEMPTS failed
8
+ attempts the gate gives up (so it can never loop forever), logs it, and lets the agent stop.
9
+ With no run in progress, it does nothing: normal conversation is never blocked.
10
+ """
11
+ import argparse
12
+ import json
13
+ import os
14
+ import subprocess
15
+ import sys
16
+ import time
17
+ from pathlib import Path
18
+
19
+ MAX_ATTEMPTS = 3
20
+ TIMEOUT_S = 300
21
+
22
+
23
+ def log(state, line):
24
+ with (state / "gate.log").open("a") as f:
25
+ f.write(f"{time.strftime('%Y-%m-%d %H:%M:%S')} {line}\n")
26
+
27
+
28
+ def main():
29
+ argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter,
30
+ epilog="Reads the Stop hook's JSON event on stdin.").parse_args()
31
+ try:
32
+ event = json.load(sys.stdin)
33
+ except json.JSONDecodeError:
34
+ event = {}
35
+ root = Path(os.environ.get("CLAUDE_PROJECT_DIR") or event.get("cwd") or ".")
36
+ cfg_path = root / ".agent" / "config.json"
37
+ state = root / ".agent" / "state"
38
+ active = state / "run_active"
39
+ if not cfg_path.exists() or not active.exists():
40
+ return
41
+ check = json.loads(cfg_path.read_text()).get("check")
42
+ if not check:
43
+ return
44
+
45
+ attempts_file = state / "gate_attempts"
46
+ try:
47
+ r = subprocess.run(check, shell=True, cwd=root, capture_output=True, text=True, timeout=TIMEOUT_S)
48
+ code, output = r.returncode, (r.stdout + r.stderr).strip()
49
+ except subprocess.TimeoutExpired:
50
+ code, output = 124, f"check timed out after {TIMEOUT_S}s"
51
+
52
+ if code == 0:
53
+ active.unlink(missing_ok=True)
54
+ attempts_file.unlink(missing_ok=True)
55
+ log(state, f"PASS {check}")
56
+ return
57
+
58
+ attempts = int(attempts_file.read_text() or 0) + 1 if attempts_file.exists() else 1
59
+ if attempts > MAX_ATTEMPTS:
60
+ active.unlink(missing_ok=True)
61
+ attempts_file.unlink(missing_ok=True)
62
+ log(state, f"GAVE UP after {MAX_ATTEMPTS} failed attempts: {check} → {output[-300:]}")
63
+ print(json.dumps({"systemMessage": f"Done gate gave up: `{check}` still fails after "
64
+ f"{MAX_ATTEMPTS} attempts. See .agent/state/gate.log."}))
65
+ return
66
+ attempts_file.write_text(str(attempts))
67
+ log(state, f"BLOCK {attempts}/{MAX_ATTEMPTS} exit={code}: {check}")
68
+ print(json.dumps({
69
+ "decision": "block",
70
+ "reason": (f"Done gate: your run isn't finished. `{check}` exited {code} "
71
+ f"(attempt {attempts}/{MAX_ATTEMPTS}). Output:\n{output[-1500:]}\n\n"
72
+ "Fix what it reports, run the check yourself until it passes, update Status, "
73
+ "then finish. If it can't pass, explain why in Status and in your reply."),
74
+ }))
75
+
76
+
77
+ if __name__ == "__main__":
78
+ main()