@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,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()
|