@cmgmyr/hive 1.7.0 → 1.9.0

package/claude-plugin/skills/profile/SKILL.md

@@ -47,7 +47,7 @@ The user may want more than one profile - a simple one and an orchestration one,
 
 ## Start small; editing is how a profile grows
 
-A first profile carries only what this interview actually surfaced. A new simple profile is `posture.md` plus a short `runbook.md` written from the confirmed answers - not a copy of anything thicker. A new orchestration profile fills in the shipped orchestration template's placeholders from those same answers; it does not add sections nobody asked for. Depth comes from running this skill again later to edit, not from a bigger first pass. Do not add a mandatory extra `.md` file, a review tool, or a tracking artifact that nobody's answer called for.
+A first profile carries only what this interview actually surfaced. A new simple profile is `posture.md` plus a short `runbook.md` written from the confirmed answers - not a copy of anything thicker. A new orchestration profile starts from the shipped orchestration files as they are. That base already says the lead assigns todo ids, supervises and accepts, and a worker never completes its own todo. The runbook spells out lanes, the brief, scope, worktrees, shared resources, checks, review, permissions, waiting, the context checkpoint, handback and record, closing a lane and cold boot, and the posture sets the model tiers, so do not interview for any of them. The interview only fills its optional vars from confirmed answers and edits a rule the user wants changed; it does not add sections nobody asked for. Depth comes from running this skill again later to edit, not from a bigger first pass. Do not add a mandatory extra `.md` file, a review tool, or a tracking artifact that nobody's answer called for.
 
 ## Converge, then confirm once
 
@@ -82,7 +82,11 @@ An edit changes only the rule that was discussed and any dependent instruction t
 
 ## Route project facts into `hive.yml` `vars`, not prose
 
-A command, a repository name, a ticket prefix: these belong in `hive.yml` `vars` and get referenced from the profile as `{{var}}`, not hard-coded into the generated `posture.md`/`runbook.md`/`worker.md` text. This is what lets one profile serve several projects. `references/interview.md` lists the `hive.yml` keys and var names this skill knows how to write, and which existing shipped vars (`check`, `repo`, `install`, `ticket_prefix`, `start_command`) to reuse before introducing a new one.
+A command, a repository name, a ticket prefix: these belong in `hive.yml` `vars` and get referenced from the profile as `{{var}}`, not hard-coded into the generated `posture.md`/`runbook.md`/`worker.md` text. This is what lets one profile serve several projects. `references/interview.md` lists the `hive.yml` keys and var names this skill knows how to write. The shipped orchestration profile renders these optional vars: `check`, `install`, `repo`, `ticket_prefix`, `start_command`, `test_command`, `suite_command`, `verify_command`, `review_command` and `worker_model`. Offer one only when the interview confirmed its value, and leave the rest unset: an unset var drops its section, and nothing makes the user fill every one.
+
+## Worked examples, only on request
+
+`references/examples/README.md` indexes two worked examples: one orchestration profile rendered for a personal repo and a work repo, and an annotated skeleton of the three files. Open one only when the user asks to see an example or wants to adapt one. They are not part of discovery and add no interview question.
 
 ## Offer a recipe only on its own signal
 
@@ -90,7 +94,7 @@ A command, a repository name, a ticket prefix: these belong in `hive.yml` `vars`
 
 ## Validate before you tell them it's done
 
-After writing, run `hive doctor` and read each file you touched with "Read a rendered file in bounded sections" above, from the project the profile is meant to serve. Read it to the last line: a change near the end of a large file is easy to miss. A profile with no readable `runbook.md` fails `hive doctor` outright; `posture.md` and `worker.md` do not, but check them anyway. Tell the user to restart any running hive session so it picks up the change, and invite one small follow-up edit once they've tried it - that is the expected way a profile keeps improving.
+After writing, run `hive doctor` and read each file you touched with "Read a rendered file in bounded sections" above, from the project the profile is meant to serve. Read it to the last line: a change near the end of a large file is easy to miss. Read worker text with `hive profile read worker.md`, never `hive posture`: `hive posture` prints the lead's file only. `worker.md` keeps its identity placeholders (`{{agent_name}}` and the like) in that read because they fill at spawn, so do not treat them as a defect. A profile with no readable `runbook.md` fails `hive doctor` outright; `posture.md` and `worker.md` do not, but check them anyway. Tell the user to restart any running hive session so it picks up the change, and invite one small follow-up edit once they've tried it - that is the expected way a profile keeps improving.
 
 ## After a profile edit lands, ask once about notifying leads
 
@@ -100,6 +104,10 @@ For each matching project, call `agent_list` with `{project_id: <project id>}`.
 
 On no, send nothing. On yes, call `wake_set` once per qualifying lead with `delay_seconds: 1`, `project_id: <that project's integer id>`, and `deliver_to: <lead's integer agent_id>`. Do not pass an actor id such as `lead:663` as `deliver_to`. Each wake body names the changed files and commit range, then tells the lead to re-read with `hive posture`, `hive runbook`, and `hive profile read <file>`, or restart through `hive lead` to reload the posture. Do not send a wake before the human says yes.
 
+## Without the Claude plugin
+
+The plugin only delivers this skill and the `/hive:profile` trigger. A stock Codex user, or anyone without the plugin, follows the same steps by hand: open this file and `references/interview.md` (they ship in the npm package: for a global install the directory is `$(npm root -g)/@cmgmyr/hive/claude-plugin/skills/profile/`, and in a checkout it is `claude-plugin/skills/profile/`), then run the interview in any session. Every command here is a plain `hive` CLI call (`hive profile list`, `path`, `read`, `fork`, `hive doctor`, `hive posture`, `hive runbook`), and the profiles are ordinary markdown. Three parts are Claude-only or harness-specific: the `/hive:profile` trigger, a subagent for reading transcripts (do it inline in a harness with none, in small batches), and Claude Code's transcript location (Codex's rollout path is named above). The notify-leads step uses hive's own MCP tools, so it works wherever hive is registered.
+
 ## What this skill does not do
 
-It does not dispatch project work, change which agent application or model a project uses beyond what was explicitly asked, install a third-party tool, or commit or publish anything. It edits `hive.yml`'s `profile`, `agents`, `vars`, `context_checkpoint_percent`, and `lead_turn_budget` keys only on an explicit ask, and only to values the user gave or confirmed.
+It does not dispatch project work, change which agent application or model a project uses beyond what was explicitly asked, install a third-party tool, or commit or publish anything. It does not choose a model name for the user: `worker_model` is written only to a value they gave. It edits `hive.yml`'s `profile`, `agents`, `vars`, `context_checkpoint_percent`, and `lead_turn_budget` keys only on an explicit ask, and only to values the user gave or confirmed.

package/claude-plugin/skills/profile/references/examples/README.md

@@ -0,0 +1,26 @@
+# Worked examples
+
+Open one of these only when the user asks to see an example or wants to adapt one. Do not open them during discovery, and do not add an interview question to reach them. The interview in `../interview.md` stays the way a profile gets built.
+
+| File | What it shows | Open it when |
+|---|---|---|
+| [two-projects.md](two-projects.md) | One orchestration profile and two `hive.yml` files, a personal repo and a work repo. Every "rendered" block is real output from the shipped profile. | The user asks how one profile differs per project, or what `vars` do. |
+| [skeleton.md](skeleton.md) | The three profile files cut down to their seams: who dispatches, where review lands, what a brief carries, which facts belong in `vars`. | The user wants a different method and needs the places where it would diverge. |
+
+## What they are not
+
+- They are illustrations to read and adapt. hive never forks, runs or injects them. `posture.md`, `runbook.md` and `worker.md` are the three files hive loads on its own. Any other `.md` in a profile directory renders its `{{vars}}` only when read with `hive profile read <file>.md`.
+- The projects in them are invented. Nothing is copied from a real setup.
+- A rendered block is checked by `test/profile-examples.test.mjs`, which renders the shipped orchestration profile with the example's `hive.yml` and fails when a block no longer matches. If the shipped profile changes, regenerate the block from the real output; do not edit it by hand.
+
+## Every example assumes
+
+- hive is installed and the project is a git repository registered with `hive init`.
+- One stock harness (Claude Code or Codex) and nothing else: no extra skills, plugins, CI, tracker tooling or scripts.
+- Commands such as `npm test` are placeholders for the user's own. A var left unset drops its section; nothing is required.
+
+If the user has none of this, use the simple profile instead.
+
+## Trust
+
+`hive.yml` `vars` land in the lead's posture and every worker's brief with no approval step. Read a cloned repo's `hive.yml` the way you would read its `CLAUDE.md`.

package/claude-plugin/skills/profile/references/examples/skeleton.md

@@ -0,0 +1,127 @@
+# Annotated skeleton
+
+This example assumes what `README.md` lists: hive, git and one stock harness. It is a skeleton, not the shipped text. Each section keeps its heading and one line saying what it holds; the real wording is in `profiles/orchestration/`. Use it to see where a different method would diverge. hive loads exactly three files on its own; any other `.md` in a profile directory renders its `{{vars}}` when read with `hive profile read <file>.md`.
+
+Template syntax: `{{var}}` fills from `hive.yml` `vars`. `<!--if:var-->` ... `<!--end-->` keeps a section only when the var is set. Edit the raw template (`hive profile path <name> <file>`), and read what an agent sees with `hive profile read <file>`.
+
+## posture.md
+
+Rendered into every lead's system prompt. Keep it the smallest file.
+
+```markdown
+You are the lead of a hive crew. <one sentence: you hold the plan, workers do the work, you accept.>
+
+- Name the lane before acting. <the lane kinds, one line on why each ends differently>
+- Ambiguity is a question, not a guess.
+- Dispatch by assigning todo ids. <why: nobody self-dispatches>
+- Give a worker a brief it can follow cold. <the brief's fields, see THE BRIEF below>
+- Keep every lane isolated. <worktree per writer, lease per shared runtime>
+- Read the real diff and run the change before you accept it.
+- Only you complete a todo, and only after you accept it.
+- Outward-facing actions need authority already given.
+- Run yourself on the strongest model tier, workers on a cheaper one.
+<!--if:worker_model-->
+- Default worker model: {{worker_model}}.
+<!--end-->
+- When asked how work runs here, run `hive runbook`.
+```
+
+SEAMS: who dispatches (the lead, by todo id) and who accepts (the lead) are fixed here. A method where a human steers each worker changes those two lines and the matching lines in `worker.md`.
+
+## runbook.md
+
+Read on demand, not loaded into every prompt. Order is the method.
+
+```markdown
+RUNBOOK: how work runs here. Live state belongs in todos, not in this file.
+
+THE ONE RULE
+<the single invariant, stated with the failure it prevents>
+
+LANES
+<one bullet per lane: what it ends with>
+<!--if:ticket_prefix-->
+- Ticket ({{ticket_prefix}}-NNN): <link, do not copy>
+<!--end-->
+
+HOW A LANE RUNS
+1. <read the request, name the lane and who accepts>
+2. <write the brief>
+3. <prepare the worktree and shared runtime>
+4. <spawn with agent_spawn: cwd, name, model>   <!--if:worker_model-->Worker model: {{worker_model}}.<!--end-->
+5. <read comments, diff, agent_output; run it yourself; triage findings>
+6. <reconcile with base, rerun affected checks>
+7. <accept, close out, record the next action>
+
+THE BRIEF
+<fields in order: goal, decisions made, files owned, input limits, base and worktree, checks and done-means, reviewer and acceptor, publish authority, open questions>
+
+SCOPE | WORKTREES | SHARED RESOURCES | CHECKS | REVIEW | PERMISSIONS | WAITING
+<each a short block: the rule, then the failure it prevents>
+<!--if:install-->
+- A fresh worktree has no dependencies installed: {{install}}
+<!--end-->
+
+CHECKS (inside it)
+<!--if:check-->
+- Gate command: {{check}}
+<!--end-->
+<!--if:test_command-->
+- Scoped checks: {{test_command}}
+<!--end-->
+<!--if:suite_command-->
+- Full suite: {{suite_command}}
+<!--end-->
+
+REVIEW (inside it)
+<when a fresh-context reviewer runs; keep findings raw; record fix, accept or defer>
+<!--if:review_command-->
+- This project's review command: {{review_command}}
+<!--end-->
+
+CONTEXT CHECKPOINT | HANDBACK AND RECORD | CLOSING A LANE | COLD BOOT
+<each a short block>
+```
+
+SEAMS: review lands in REVIEW and in step 5; a method that reviews before the worker commits moves it to step 4. The brief's fields are where a method says what a worker must be told. Any project-specific command goes in a `vars` entry and a gated line, never in prose, so one profile serves several repos.
+
+## worker.md
+
+Rendered into every worker's first prompt. Identity placeholders (`{{agent_name}}`, `{{actor_id}}`, `{{project_name}}`, `{{project_path}}`, `{{cwd}}`, `{{primary_root}}`) fill at spawn, not from `hive.yml`.
+
+```markdown
+[HIVE CONTEXT]
+You are agent "{{agent_name}}" (actor id: {{actor_id}}) in project "{{project_name}}" ({{project_path}}).
+Your working directory is {{cwd}}.
+<the hive tools the worker may use: whoami, pad_read, todo_get, todo_comment, lease_acquire>
+[END HIVE CONTEXT]
+
+SCOPE | YOUR FILES AND YOUR STORE | CHECKS
+<each a short block, as in the runbook>
+<!--if:install-->
+<install line>
+<!--end-->
+
+BEFORE YOU REPORT DONE, in this order.
+1. <status in the worktree>
+2. <rebuild>
+3. <rerun scoped checks>
+<!--if:check-->
+   Also run this project's gates: {{check}}
+<!--end-->
+4. <commit; do not push; publish only where the brief grants it>
+5. <post reader findings raw, report on the todo, wait for the lead>
+
+WAIT FOR EVERYTHING YOU START | IF YOU HIT YOUR CONTEXT CHECKPOINT
+<each a short block>
+```
+
+SEAMS: the worker never completes its own todo and never publishes unless the brief grants it. The gate is an unnumbered line under the scoped-checks step, so the numbering is the same with `check` set or unset.
+
+## Which facts go in vars
+
+| Put in `vars` | Leave in prose |
+|---|---|
+| a command (`install`, `test_command`, `suite_command`, `check`, `verify_command`, `review_command`) | how and why a rule exists |
+| a name (`repo`, `ticket_prefix`, `worker_model`) | the order of steps |
+| anything that differs between two repos | anything true for every repo |

package/claude-plugin/skills/profile/references/examples/two-projects.md

@@ -0,0 +1,105 @@
+# One profile, two projects
+
+This example assumes what `README.md` lists: hive, git and one stock harness. The projects are invented.
+
+Both projects use the shipped orchestration profile unchanged. Only `hive.yml` `vars` differ, so the same three template files read differently in each repo. An unset var drops its section; a set one fills a placeholder or opens a section.
+
+## Project A: a personal repo
+
+Install and a scoped test command. No tracker, no suite, no review command.
+
+```yaml hive.yml personal
+profile: orchestration
+vars:
+  install: npm install
+  test_command: npm test -- test/<file>.test.js
+```
+
+What the lead's runbook says (`hive runbook`):
+
+```text rendered personal runbook
+- Use absolute paths in edits and `git -C <worktree>`. A relative path after a `cd` resolves against the wrong tree.
+- A fresh worktree has no dependencies installed: npm install
+```
+
+```text rendered personal runbook
+CHECKS
+Run the named checks. A green summary or a stale build is not a working result.
+- Scoped checks: npm test -- test/<file>.test.js
+```
+
+What a worker sees (`hive profile read worker.md`). With no `check` var set, the scoped-checks step has no gate line under it:
+
+```text rendered personal worker
+2. Rebuild before any screenshot, browser check, or measurement.
+3. Run the scoped checks again after your last edit, and the full suite once if the brief asks for it.
+4. Commit; do not push. Research lanes record findings on the todo and need no commit. Publish only where the brief grants it; otherwise ask the lead.
+```
+
+## Project B: a work repo
+
+A ticket prefix, a gate, a full suite, a review command and a worker model.
+
+```yaml hive.yml work
+profile: orchestration
+vars:
+  ticket_prefix: PAY
+  check: make lint test
+  suite_command: make ci
+  review_command: /review
+  worker_model: the gateway's mid-size tier
+```
+
+The lead's posture gains one line:
+
+```text rendered work posture
+- Default worker model: the gateway's mid-size tier.
+```
+
+The runbook gains a ticket lane, a worker model, a gate, a suite and a review command:
+
+```text rendered work runbook
+- Ticket (PAY-NNN): link the ticket from the todo. Do not copy its body, or the two drift apart. Name who updates the ticket and which states they set.
+```
+
+```text rendered work runbook
+   Worker model: the gateway's mid-size tier.
+```
+
+```text rendered work runbook
+- Gate command for this project: make lint test
+- Full suite: make ci. Run it once before handback and again after a rebase.
+```
+
+```text rendered work runbook
+- This project's review command: /review
+```
+
+The worker's report-done list gets a gate line under the scoped-checks step, and the numbering does not change:
+
+```text rendered work worker
+3. Run the scoped checks again after your last edit, and the full suite once if the brief asks for it.
+   Also run this project's gates and fix what they find: make lint test
+4. Commit; do not push. Research lanes record findings on the todo and need no commit. Publish only where the brief grants it; otherwise ask the lead.
+```
+
+## What to change for your project
+
+1. List what your project actually has: an install step, a scoped test command, a full suite, a gate, a review command, a ticket prefix, a remote.
+2. Write only those into `hive.yml` `vars`. Use the names in the examples; the shipped profile renders `check`, `install`, `repo`, `ticket_prefix`, `start_command`, `test_command`, `suite_command`, `verify_command`, `review_command` and `worker_model`.
+3. Do not set a var you cannot fill. Leave it out.
+4. Set `worker_model` only to a model the user named.
+5. Read the result: `hive runbook`, `hive posture`, and `hive profile read worker.md`.
+6. Run `hive doctor` and restart any running lead so it reloads.
+
+To change a rule itself, fork first: `hive profile fork orchestration`, then edit the files under `hive profile path orchestration`.
+
+## Paste-ready prompt
+
+```text
+I use hive with the shipped orchestration profile. Here is my project: <one line on what it is>.
+Commands I actually run: install = <cmd or none>, scoped tests = <cmd or none>, full suite = <cmd or none>, lint/gate = <cmd or none>, review = <cmd or none>.
+Ticket prefix: <PREFIX or none>. Remote: <owner/name or none>.
+Write a hive.yml for this repo with `profile: orchestration` and a `vars:` block holding only the commands above that are not "none". Do not invent commands.
+Then run `hive runbook`, `hive posture` and `hive profile read worker.md` and tell me which sections appeared and which dropped. Do not edit the profile files.
+```

package/claude-plugin/skills/profile/references/interview.md

@@ -14,6 +14,13 @@ For an edit, open with "What should change, and what should stay?" and read the
 
 **Simple** fits one active agent, sequential tasks, the user directly controlling the work, or a case where coordinating several sessions would cost more than it saves. **Orchestration** fits someone who already delegates, needs independent work to run in parallel, or names a concrete coordination problem they are trying to solve. Treat both as signals to weigh, never as a rule to apply mechanically.
 
+**What the orchestration base already settles.** The shipped orchestration files are written outright, with no mode var to switch on. The lead assigns todo ids, supervises and accepts; workers never self-dispatch and never complete their own todo; a brief names goal, decisions, files, base, checks and done-means; scope stops go to the lead; each lane has its own worktree and a lease on any shared runtime; the lead reads the real diff and runs the change; a fresh-context review runs by risk or on request, never on every change; pushes, PRs and posts need standing authority; a handback and a record live on the todo; the lead runs on the strongest model tier and workers on a cheaper one. A follow-up question on any of these is wasted unless the user's answer pushes against it, and then it is an edit to that rule, not a new section.
+
+**Three synthetic walk-throughs, each inside the budget** (illustrations, not real interviews). Each converges in at most six discovery questions plus three follow-ups, and none needs a question beyond the map below.
+- A solo user with personal repos, one stock harness and no tracker, CI or suite: no preference for delegation, so recommend simple. Dimensions asked: 12 (what done means), 15 (which command, or a stated manual check). No var beyond `check`, if they name one.
+- A user in work repos with a hosted tracker, CI and required human PR review: recommend orchestration only if they say they delegate. Dimensions asked: 14 (tracker), 13 and 09 (who pushes and posts; human PR review stays required), 15. Vars: `ticket_prefix`, `start_command` if they run one, `repo`, `check`. Do not mirror the ticket body into todos, and do not add a model var for a gateway-routed setup.
+- Two harnesses on a shared project with one suite and one dev database: recommend orchestration, since they name a coordination problem. Dimensions asked: 16, 15, 24. Vars: `suite_command`, `test_command`; `install` only if they name a setup step. The shipped SHARED RESOURCES rule covers the resource; the shared-test-resource recipe is offered only if they want a named coordinator.
+
 Summarise your recommendation with one reason tied to what the user said, and offer the other route without framing it as an upgrade or a downgrade. No stated preference means recommend simple, as the smaller thing to start from, while noting delegation is available later through an edit. If different kinds of project the user described need conflicting policies, offer separate profiles for them; do not offer several profiles just because both bases exist. Share discovery once, then confirm each profile's own differences and its selection separately.
 
 ## 3. Optional follow-up map
@@ -46,7 +53,7 @@ Every row below is optional. A row with no answer signal in what the user alread
 | 22 | Runtime verification | Green checks have missed a real failure before. | What real action demonstrates the change actually works? | The outcome the user described, exercised with a realistic input. | hive.yml vars, runbook.md |
 | 23 | Visual evidence | The project has a visible interface. | Which visible states do you need to see before accepting a change? | Only the states relevant to this project. | hive.yml vars, runbook.md |
 | 24 | Agent applications | More than one agent application is already in use. | Which applications are available, and which can use your tools? | Keep whatever is already working for the user. | top-level hive.yml `agents` |
-| 25 | Model selection | The user has a model preference. | Do you want a default model, or to choose one per task? | Keep current settings; propose no model ranking of your own. | posture.md, runbook.md |
+| 25 | Model selection | The user has a model preference. | Do you want a default model, or to choose one per task? | Keep current settings; propose no model ranking of your own. | hive.yml vars (`worker_model`), posture.md, runbook.md |
 | 26 | Model identifiers | The user's setup routes models by a custom name. | Does your installed application expect an alias, or an exact identifier? | Use an identifier the user has verified works. | top-level hive.yml `lead`, runbook.md |
 | 27 | Reasoning effort | The user has an effort preference. | Should tasks inherit the default effort, or use a level you choose? | Inherit current settings. | top-level hive.yml `lead`, runbook.md |
 | 28 | Escalation | A session repeatedly gets stuck. | When do you want a fresh session, or a different model? | Return a blocked choice to the user. | runbook.md, worker.md |
@@ -119,14 +126,29 @@ When selecting one project's `profile:` key in `hive.yml`, treat each project's
 
 - `profile: <name>` selects the profile; write it to the project's own `hive.yml` for "this project", or to `~/.hive/hive.yml` only on an explicit ask for "every project" (see Scope, above).
 - `agents: [<harness>, ...]` selects which agent applications this project allows; write it only when the user names more than the default.
-- `vars:` holds project facts referenced as `{{var}}` from the profile's own text - reuse shipped names before inventing one: `check` (the before-you-report-done gate), `repo`, `install`, `ticket_prefix`, `start_command`. This lane's own additions, each a plain string substituted into prose and never executed by hive itself, are: `test_command` (scoped tests), `suite_command` (the full suite), `verify_command` (a real, observable outcome check), and `review_command` (an existing review the user already runs). Write one only when a generated template actually references it - an unreferenced var is dead weight, not a feature.
+- `vars:` holds project facts referenced as `{{var}}` from the profile's own text - reuse the shipped names before inventing one. Each is a plain string substituted into prose and never executed by hive itself, and each is optional: an unset var drops its section from the render. The shipped orchestration profile renders exactly these ten, and this skill offers each only on a confirmed signal:
+
+  | Var | Holds | Signal (dimension) |
+  |---|---|---|
+  | `check` | the before-you-report-done gate | the user names one command that proves readiness (15) |
+  | `test_command` | scoped checks for one change | they name a smaller command (15) |
+  | `suite_command` | the full suite | they name one, often alongside a shared resource (15, 16) |
+  | `verify_command` | a real, observable outcome check | green checks have missed a failure before (22) |
+  | `review_command` | a review the user already runs | they run an installed review tool (18, 19) |
+  | `worker_model` | the cheaper model tier workers spawn on | they name a model they want workers on (25) |
+  | `install` | dependency setup for a fresh worktree | the user names a setup step a fresh checkout needs |
+  | `repo` | the project's remote | a remote is in use (09) |
+  | `ticket_prefix` | a ticket id prefix, linked from the todo | a tracker is in use (14) |
+  | `start_command` | how ticket work starts; rendered only under `ticket_prefix` | they have a start routine for tickets (14, 40) |
+
+  `worker_model` is a value the user gave or confirmed, never a name you pick. Write a var only when a template actually references it; an unreferenced var is dead weight, not a feature. On a simple profile, only `check` is meaningful unless the user's own runbook references another.
 - `context_checkpoint_percent` (an integer from 1 to 100) and `lead_turn_budget` (a `{warn, stop}` pair, `stop` greater than `warn`) are optional and written only when the user asks for them.
 
 Never write a `hive.yml` key this skill does not know, and never invent a model name, an effort flag, a reserved identity var, or an `agents_*` / `harness_*` var - those are hive's own, computed at spawn time, and a project-defined one is stripped before it ever reaches a template.
 
 ## 5. Recipes
 
-`recipes/index.md` links a small library of optional patterns, each tied to one or more dimensions above: verification (15, 17, 22), a shared test resource (16, 15), a review decision (18-21), session continuity (33, 40, 35), and a worker context checkpoint (30, 28, orchestration only). Read the matching recipe when its dimension's signal shows up in discovery; it is never a required stop on the way to a first profile.
+`recipes/index.md` links a small library of optional patterns, each tied to one or more dimensions above: verification (15, 17, 22), a shared test resource (16, 15), a review decision (18-21), session continuity (33, 40, 35), and a worker context checkpoint (30, 28, orchestration only). Read the matching recipe when its dimension's signal shows up in discovery; it is never a required stop on the way to a first profile. On the shipped orchestration base, several recipes are mostly a var away because the base already renders the section (checks, review, shared resources, checkpoint); each recipe says what to set and when a block is still worth adding. Recipes keep their five-recipe count; the orchestration changes add no recipe.
 
 ## Known traps
 

package/claude-plugin/skills/profile/references/recipes/index.md

@@ -10,3 +10,4 @@ A recipe is an optional pattern a profile can adopt: a short, named block of tex
 | [session-continuity.md](session-continuity.md) | A reopened session repeats decisions or loses the next action. | A small finish/start habit that carries the next action across sessions. | Both |
 | [worker-context-checkpoint.md](worker-context-checkpoint.md) | Delegated work runs long enough that a worker loses useful context. | A checkpoint threshold and a designated recipient who decides whether to continue. | Orchestration only |
 
+Worked examples, not recipes: [../examples/README.md](../examples/README.md). Open one only when the user asks to see or adapt one.

package/claude-plugin/skills/profile/references/recipes/review-decision.md

@@ -14,6 +14,8 @@ Where useful review already happens today, and who should decide whether a findi
 
 ## Add
 
+The shipped orchestration runbook already has a REVIEW section: the lead reads the real diff, runs a fresh-context reviewer by risk or on request, keeps findings as written, and renders `review_command` when it is set. On that base, set `review_command` if the user runs a real tool, and add the block below only to name a decision owner other than the lead.
+
 A runbook block naming the reviewer, the timing, and the decision owner:
 
 ```markdown

package/claude-plugin/skills/profile/references/recipes/shared-test-resource.md

@@ -14,6 +14,8 @@ The name of the actual shared resource (a database, a port, a device) and who or
 
 ## Add
 
+The shipped orchestration runbook already has a SHARED RESOURCES section (name the runtime, take a lease, one full check at a time, the lead gives out the slot). That section is unconditional prose and renders no var; `suite_command` renders under CHECKS. On that base, set `suite_command` and add the block below only to name a coordinator other than the lead.
+
 A runbook rule naming the resource and the coordination habit:
 
 ```markdown

package/claude-plugin/skills/profile/references/recipes/verification.md

@@ -28,7 +28,7 @@ Report a failing result as failing. A clean status line is not evidence by
 itself.
 ```
 
-For orchestration, add the same obligation to `worker.md`'s completion section rather than only the lead's runbook, since it is the worker who reports done.
+On the shipped orchestration base, the runbook's CHECKS section already renders `check`, `test_command` and `verify_command` when they are set, and `worker.md` already asks for the named checks before a handback. So there, set the vars and add this block only if the user's own runbook lacks a completion step. For a forked or hand-written orchestration profile, add the same obligation to `worker.md`'s completion section rather than only the lead's runbook, since it is the worker who reports done.
 
 ```yaml
 vars:
@@ -38,7 +38,7 @@ vars:
 
 ## Verify
 
-Run `hive runbook` (and `hive posture` for the worker copy, on orchestration) and confirm both commands render. Then exercise it for real: pick a harmless, already-working change and confirm the block actually gets run and its result gets reported, not just written down.
+Run `hive runbook` and confirm both commands render. On orchestration, also run `hive profile read worker.md` and confirm the worker text carries the check obligation. Never use `hive posture` for the worker copy: it prints the lead's file only. Then exercise it for real: pick a harmless, already-working change and confirm the block actually gets run and its result gets reported, not just written down.
 
 ## Remove
 

package/claude-plugin/skills/profile/references/recipes/worker-context-checkpoint.md

@@ -14,6 +14,8 @@ A context-fill threshold (a percentage), and who should receive a checkpoint and
 
 ## Add
 
+The shipped orchestration runbook and `worker.md` already carry a context-checkpoint section, active wherever `context_checkpoint_percent` is set. On that base, writing the key is the whole recipe; add the blocks below only to name a recipient other than the lead. A forked profile without that section needs them.
+
 `context_checkpoint_percent` at the top level of `hive.yml`:
 
 ```yaml

package/dist/build-info.json

@@ -1 +1 @@
-{"version":"1.7.0","sha":"2000149","dirty":false,"build_id":"c539d81be530294a451590d781bd6922cd7155087a70b8fc64dedc35cf94f3e2"}
+{"version":"1.9.0","sha":"b0be61b","dirty":false,"build_id":"b0c86484d75006efe978e316cdbccb3c9b4e09604634cfff5f7a61c8b8d825b0"}

package/dist/claudeWake.js

@@ -0,0 +1,44 @@
+import { createConnection } from "node:net";
+export const CROSS_SESSION_CLOSE = "</cross-session-message>";
+export const SOCKET_WAKE_FOOTER = "Automated hive wake. Do not reply to this sender.";
+const SOCKET_WRITE_BOUND_MS = 1000;
+export function senderAddress(socketPath) {
+    const encoded = socketPath.replace(/[^A-Za-z0-9/._-]/gu, (c) => [...Buffer.from(c)].map((b) => `%${b.toString(16).toUpperCase().padStart(2, "0")}`).join(""));
+    return `uds:${encoded}`;
+}
+function claudeWakeFrame(senderAddress, text) {
+    const content = `<cross-session-message from="${senderAddress}" from-name="hive">\n${text}\n${CROSS_SESSION_CLOSE}`;
+    return JSON.stringify({ type: "user", from: senderAddress, message: { role: "user", content } }) + "\n";
+}
+// True only for a completed local write. The socket sends no ack, so true never means the lead read it.
+export function postClaudeWake(options) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (ok)
+                socket.end();
+            else
+                socket.destroy();
+            resolve(ok);
+        };
+        const socket = createConnection(options.socketPath);
+        const timer = setTimeout(() => finish(false), SOCKET_WRITE_BOUND_MS);
+        socket.on("error", () => finish(false));
+        socket.on("connect", () => {
+            let allowed = false;
+            try {
+                allowed = options.beforeWrite();
+            }
+            catch {
+                allowed = false;
+            }
+            if (!allowed)
+                return finish(false);
+            socket.write(claudeWakeFrame(options.senderAddress, options.text), (err) => finish(!err));
+        });
+    });
+}

package/dist/cli.js

@@ -20,16 +20,16 @@ import { isLowHeadroom, orphanLoginShellDetails, ptyHeadroom } from "./ptys.js";
 import { addProject, agentProjectPin, assertQueenCrossProjectWrite, captureQueenWriteIdentity, currentActor, effectiveProjectId, findProjectForCwd, findProjectForDir, getProjectByPath, gitPrimaryRoot, getProject, listProjects, QUEEN_PROFILE, queenHomeDir, registeredAncestor, takeRegistrationNotice, } from "./context.js";
 import { confirmQueenWrite, listQueenAudit } from "./queenAudit.js";
 import { formatRowCounts, projectRowCounts, removeProject } from "./projectRemove.js";
-import { ensureHooksFile } from "./hooks.js";
+import { ensureHooksFile, ensureLeadHooksFile } from "./hooks.js";
 import { errorMessage, registrationNoticeText, withTrailingNewline } from "./result.js";
-import { ACTIVE_TIMER_WHERE, dashboardFileContained, describeStall, HELD_REASON_CONVERSATION, HELD_REASON_LEAD_PANE_DEAD, HELD_REASON_UNCLASSIFIABLE_PANE_PREFIX, isLeadRowClosedHold, isUnclassifiablePaneHold, HELD_REASON_UNSUBMITTED_INPUT_PREFIX, isUnsubmittedInputHold, janitor, resolveDashboardFile, generateQueenDashboardNow, transcriptStaleness, wasHeldForPaneIdentity, } from "./scheduler.js";
+import { ACTIVE_TIMER_WHERE, socketAwaitingWhere, dashboardFileContained, describeStall, HELD_REASON_CONVERSATION, HELD_REASON_LEAD_PANE_DEAD, HELD_REASON_UNCLASSIFIABLE_PANE_PREFIX, isLeadRowClosedHold, isUnclassifiablePaneHold, HELD_REASON_UNSUBMITTED_INPUT_PREFIX, isUnsubmittedInputHold, janitor, resolveDashboardFile, generateQueenDashboardNow, transcriptStaleness, wasHeldForPaneIdentity, } from "./scheduler.js";
 import { readTurnCount } from "./turnCount.js";
 import { collectPortfolio, leadText } from "./portfolio.js";
 import { STALL_BOUND_SECONDS } from "./backgroundTasks.js";
 import { probeSessionInterpreter, reexecTarget, sessionStartVerdict, } from "./sessionProbe.js";
 import { backupHealth, backupNow, backupsDir, formatBytes, listSnapshots, previewRestore, restoreSnapshot, totalSizeBytes, } from "./backup.js";
 import { describeTeardownWindow, readTeardowns, teardownLogPath, } from "./teardown.js";
-import { asNameClash, buildEnvFlags, closeAgentRow, isReservedAgentName, launchAgent, LEAD_KIND, LEAD_NAME, mintLeadActorId, upsertActor, withWindowClaim, } from "./spawn.js";
+import { asNameClash, buildEnvFlags, closeAgentRow, isReservedAgentName, launchAgent, LEAD_KIND, LEAD_NAME, mintLeadActorId, relayoutAfterPaneLeft, upsertActor, withWindowClaim, } from "./spawn.js";
 import { adoptableWindow, applyLayout, claimInitialWindow, configureHiveWindow, controlModeFor, createWindow, DEFAULT_LAYOUT, describePaneChoice, ensureSession, findProjectWindow, foreignSocket, isViewSessionName, listOwnedWindows, liveTargets, observationFailed, observeRowOwnership, ORPHAN_MIN_AGE_MS, orphanScratchServers, orphansWorthWarningAbout, paneIsAloneInWindow, paneVisibility, panePidForRecord, PROCESSES_LAYOUT, processesPaneTitle, processesWindowName, projectWindows, RAW_ATTACH_TMUX_CONFIG, renderAttachCommand, resolveAttachTarget, resolveInTmuxTarget, rowLive, rowOwnership, SESSION_PREFIX, appendGlobalHook, globalHooks, replaceGlobalHooks, sessionName, setPaneTitle, shellQuote, shownPaneTitle, makeProcessesWindow, tmux, TMUX_DOC, tmuxSaysNothingThere, tmuxTimeoutOverride, tmuxSocketPath, untrustedTmuxServer, waitForPaneEstablished, windowLayout, } from "./tmux.js";
 import { describeVisibility, processCounts } from "./dashboard.js";
 import { runningCommandRow, runningCommandRows, snapshotProcesses, stopAllProcesses, stopLine, stopProcess, STOP_REASONS, } from "./processes.js";
@@ -400,7 +400,7 @@ async function cmdLead(argv) {
         for (const w of warnings)
             console.log(`! ${w}`);
         const session = sessionName();
-        const hooksPath = ensureHooksFile();
+        const hooksPath = ensureLeadHooksFile(project.id, config?.quiet_messaging === true);
         let leadCommand = "claude";
         if (!config) {
             console.log("No hive.yml here; starting a plain claude lead. Add a hive.yml to define project commands and a custom lead (run hive --help for the format).");
@@ -546,7 +546,9 @@ async function cmdLead(argv) {
                     createdPane = true;
                 }
                 else {
-                    leadPane = tmux("split-window", ...(detach ? ["-d"] : []), "-P", "-F", "#{pane_id}", "-t", foundWindow, "-c", project.path, ...envFlags, launchCommand);
+                    const firstPane = tmux("list-panes", "-t", foundWindow, "-F", "#{pane_id}").split("\n")[0];
+                    leadPane = tmux("split-window", "-b", ...(detach ? ["-d"] : []), "-P", "-F", "#{pane_id}", "-t", firstPane || foundWindow, "-c", project.path, ...envFlags, launchCommand);
+                    relayoutAfterPaneLeft(foundWindow);
                     leadWindow = foundWindow;
                     createdPane = true;
                 }
@@ -601,7 +603,7 @@ async function cmdLead(argv) {
                 if (updated === 0)
                     return false;
                 db.prepare(`UPDATE wakes SET deliver_pane = ?, held_at = NULL, held_reason = NULL
-           WHERE ${ACTIVE_TIMER_WHERE} AND deliver_actor = ?
+           WHERE ((${ACTIVE_TIMER_WHERE}) OR (${socketAwaitingWhere()})) AND deliver_actor = ?
              AND (? = 1 OR held_reason IS NULL OR held_reason NOT LIKE ?)`).run(leadPane, leadActorId, createdPane ? 1 : 0, `${HELD_REASON_UNCLASSIFIABLE_PANE_PREFIX}%`);
                 confirmQueenWrite("hive lead", project.id, { detach }, {
                     agent_id: leadAgentId,
@@ -743,6 +745,8 @@ const HIVE_YML_TEMPLATE = `# hive project config. Read by \`hive lead\` from the
 
 # dashboard: true               # write .hive/dashboard.html (default: false)
 
+# quiet_messaging: true        # wakes reach a claude lead as one row (default: false; restart the lead)
+
 # vars:                         # substituted into the profile runbook
 #   repo: owner/name            # {{repo}}
 #   ticket_prefix: DEVX         # sections needing it drop when it is unset
@@ -750,8 +754,13 @@ const HIVE_YML_TEMPLATE = `# hive project config. Read by \`hive lead\` from the
 #   start_command: /jira-start
 #   check: npm run lint && npx tsc --noEmit   # what a worker runs before
                                               # reporting done; gates only,
-                                              # no suite (test_all is that)
+                                              # no suite (suite_command is that)
 #   check: ./vendor/bin/pint --test && ./vendor/bin/phpstan   # a PHP stack's
+#   test_command: npm test -- test/foo.test.mjs   # scoped check for one change
+#   suite_command: npm test     # full suite; one run at a time, lead's slot
+#   verify_command: npm run build && node dist/cli.js --version   # exercises the real outcome
+#   review_command: /review     # a fresh-context reviewer, if your harness has one
+#   worker_model: sonnet        # the cheaper tier workers spawn on
 #   ci: weekly                  # absent: CI runs on push/PR. weekly: CI runs
                                 # on schedule + dispatch only, and the local
                                 # full suite gates the merge