@cmgmyr/hive 1.2.2 → 1.3.0

package/claude-plugin/README.md

@@ -22,6 +22,9 @@ in place rather than copied, so `git pull && npm run build` upgrades the hook
 along with the rest of hive. `rm ~/.claude/skills/hive` uninstalls it.
 
 The hook lives here, and so does a skill (`skills/cleanup`, `/hive:cleanup`).
+A second skill, `skills/profile` (`/hive:profile`), interviews you about how
+you work and creates or edits a hive profile from the answers - see
+[docs/profiles.md](../docs/profiles.md).
 hive's posture and worker briefs still travel as command-line flags from
 `hive lead` and `agent_spawn`, because a plugin has no way to ship always-on
 instructions: plugin `CLAUDE.md` is not loaded as context, and the one

package/claude-plugin/kickoff.mjs

@@ -8,7 +8,8 @@ async function reexecUnderPinnedInterpreter() {
   if (process.env.HIVE_KICKOFF_REEXEC) return;
 
   if (process.env.HIVE_AGENT_ID && process.env.HIVE_LEAD !== "1") return;
-  if (!existsSync(join(process.cwd(), "hive.yml"))) return;
+  const { storeDir } = await import("../dist/dataDir.js");
+  if (!existsSync(join(process.cwd(), "hive.yml")) && !existsSync(join(storeDir(), "hive.yml"))) return;
 
   const { checkAbi } = await import("../dist/abi.js");
   if (checkAbi().ok) return;

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

@@ -0,0 +1,78 @@
+---
+name: profile
+description: Interviews the user about how they work with agents, then creates a new hive profile or edits an existing one - the posture, runbook, and worker files a lead and its workers read. Use when the user says /hive:profile, "set up a hive profile", "create a profile for this project", "edit our hive profile", "make hive lead/orchestrate here", or wants a project to go from no standing process to one hive can run, globally or per project.
+---
+
+# hive profile
+
+You are interviewing someone to produce, or change, a hive profile: the standing instructions (`posture.md`, `runbook.md`, `worker.md`) that tell a lead and its workers how this person wants work to run. Read `references/interview.md` before you ask a follow-up question or write anything - it holds the discovery map, the target-selection rules, and the `hive.yml` routing this skill depends on.
+
+## Read before you ask anything
+
+Run `hive profile list` and `hive doctor` (or read this project's `hive.yml` directly) before the first question. If this is an edit, also read the named profile's current, rendered behavior with `hive profile read <file> --profile <name>` for each of `posture.md`, `runbook.md`, `worker.md`, and any other `.md` it carries, so you understand what this profile actually does today. Do not ask the user to repeat anything already answered by what you just read. This rendered read is for understanding only - `references/interview.md` covers the raw template (via `hive profile path`) you must read from, and write onto, when you actually apply an edit; a rendered copy drops any conditional section whose var is unset, so it is never a safe edit source.
+
+## Discovery first, not a checklist
+
+Start with the work, not with profile structure: ask about a recent task they did with an agent, from start to finish. Follow what they say into current agent use, handoffs, checking, review, and permissions - what already works and where they repeat themselves or correct the agent. This is adaptive: choose the next question from the last answer, not from a fixed list. `references/interview.md` has a scored map of optional follow-up questions - each tied to an answer signal that makes it worth asking - and a question budget so discovery converges instead of running forever. Most of that map goes unused in any one interview; it is there so you know what to ask *if* the signal for it shows up, not a form to complete.
+
+For an edit, ask "what should change, and what should stay?" first, and read the current profile before asking about anything it already states.
+
+## Both routes are equally valid
+
+Orchestration (a lead delegating to workers) and simple (one session doing its own work) are both first-class outcomes. Recommend one from what you heard, name the one reason tied to their answer, and offer the other without calling it an upgrade or a downgrade. No stated preference means recommend simple: it is the smaller thing to start from, and delegation is available later through an edit. `references/interview.md` lists the signals for each route.
+
+## Several profiles are fine
+
+The user may want more than one profile - a simple one and an orchestration one, or a different profile per kind of project. Handle building several in one session: preflight every name and destination before the first write, so a bad name is caught before anything is created, and keep each profile's own differences and confirmation separate even when the discovery was shared.
+
+## 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.
+
+## Converge, then confirm once
+
+Stop discovery when you can state: the current task flow, at least one pain or wanted change, one habit to keep, who owns which actions, how they'll know work is done, and who the profile is for (this project only, or every project on this machine). Summarise that back, offer at most three improvements each tied to something they said, and let them accept, decline, or edit each one. Before writing anything, show: profile name(s), the base each starts from, the target(s) you are about to write to (see below), and - for an edit - a concrete diff. Confirm once. Do not keep discovering after the user asks to proceed.
+
+## Offer a flows diagram before writing
+
+After the summary is confirmed and before any write, offer to draft a Mermaid flowchart of the proposed workflow - who does what, in what order, and where the human decides. Draw it only from the confirmed answers and the files you are about to write; never invent a step the profile itself does not contain. Iterate on it with the user until it matches what they actually agreed to. Once accepted, save it as `flows.md`, an ordinary optional extra `.md` in the profile - resolved and reported by `hive profile list`/`hive doctor` the same as any other fork-local file, never required. Tell the user plainly that Mermaid renders on GitHub or in an editor preview, not in a terminal, so they know where to look at it. On a later edit that changes the workflow, update `flows.md` in the same change, or say explicitly that it is now stale if you cannot update it in this pass - never leave it silently wrong.
+
+## Read past sessions as evidence, with permission
+
+For an established project - one that already has prior Claude Code or Codex sessions - ask permission before reading any of them: "Can I look at your recent sessions in this project to see how you actually work?" On a decline, or when nothing usable turns up, fall back to the ordinary discovery questions; this is a supplement to discovery, never a replacement for it.
+
+On acceptance, read a bounded, recent first batch (for example, the ten most recent) from each harness's standard transcript location, filtered to this project. Claude Code groups its transcripts by project directory already, under its config dir's `projects/` (`$CLAUDE_CONFIG_DIR`, default `~/.claude`); Codex's rollout files live under `$CODEX_HOME/sessions/` (default `~/.codex`) and are not grouped by project, so filter by the working directory recorded inside each session instead. Do this reading in a subagent when the harness offers one, so raw transcript content never enters this interview's own context - only the findings below do.
+
+That first batch is a starting sample, not a cap. If it leaves the evidence too thin to act on - no repeated pattern, or every session from just one kind of task - say plainly what is missing and ask the user whether to read another batch. Read more only on a yes, and you may ask again after each further batch; never extend the sample on your own judgment without asking first.
+
+Surface what you found as observations, each with one short quoted example, covering how the user briefs work, what they correct repeatedly, and where work stalls or gets redone. Use those observations to propose a workflow, then ask "what didn't work for you here?" so the user can correct a wrong reading before you act on it. Never write transcript content - a quote, a session id, a path - into the profile itself; only the resulting workflow decisions belong there. Naming a specific harness's transcript convention here is fine (it is a documented fact about how that tool stores its own history), but do not name a skill hive does not ship as part of how you read or process them.
+
+## Know which file you are about to write
+
+There are two possible write targets, and they behave differently:
+
+- **The user's own override** (their machine's copy-on-write fork, normally under their hive data directory). This always wins at read time over anything shipped.
+- **The shipped source**, only when you are running inside a hive checkout (this repository, or another clone of it) - the actual template files under this checkout's `profiles/<name>/`.
+
+`references/interview.md` has the exact detection and confirmation rules. Never guess: an unclear target is a question, not a default. If the user's own override already exists for a name whose shipped source you are about to edit, say so - the override will keep hiding your change until they deal with it - rather than silently editing both or picking one.
+
+## Preserve what you did not ask about
+
+An edit changes only the rule that was discussed and any dependent instruction the user explicitly approved. Everything else - unrelated sections, an optional `.md` file, `hive.yml` comments and keys, loader-owned metadata - is read fresh immediately before writing and carried through unchanged. If the file changed since you proposed the edit, re-read it, show the revised diff, and confirm again before writing.
+
+## 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.
+
+## Offer a recipe only on its own signal
+
+`references/recipes/index.md` links a small library of optional patterns - a verification step, a shared-resource rule, a review-decision habit, and so on - each written to solve one problem an interview signal points to. Read a recipe only after discovery actually surfaces its signal; propose its benefit and cost, and apply it only if the user accepts. A recipe with no signal in this interview does not get offered, and accepting one is never required to finish a profile.
+
+## Validate before you tell them it's done
+
+After writing, run `hive doctor` and `hive profile read <file> --profile <name>` for each file you touched, from the project the profile is meant to serve. 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.
+
+## 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.
+

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

@@ -0,0 +1,139 @@
+# Interview design
+
+Read this before asking a follow-up question, choosing a write target, or writing `hive.yml`. It is a reference for `SKILL.md`, not a second skill: everything here is optional detail behind the five rules in that file.
+
+## 1. Discovery topics and openers
+
+Start with the work, not with profile structure: "Tell me about a recent task you did with an agent - what happened from start to finish?" Follow the answer into current agent use, handoffs, checking, review, and permissions, and into what already works. Ask "Where do you spend effort repeating yourself or correcting the agent?" and "What would you want to keep exactly as it is?" only if the first answer did not already establish them.
+
+For an edit, open with "What should change, and what should stay?" and read the selected profile and this project's `hive.yml` first, so you never ask about a fact already on record. Do not reopen a rule the user did not mention.
+
+**Budget:** at most six discovery questions before summarising what you know; one focused question at a time, since a detailed initial answer may need none of the rest. After that summary, at most three targeted follow-ups toward one draft. Anything past that is optional, offered in a user-chosen batch of up to three questions, never an automatic loop. An unknown optional preference is left out of the draft, never filled with invented policy. A missing target, an unclear edit boundary, or an unknown required check is stated in the summary and resolved before any dependent write. A project with no automated checks gets an explicit manual verification step written into its profile instead of an assumed command.
+
+## 2. Signals for each route
+
+**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.
+
+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
+
+Every row below is optional. A row with no answer signal in what the user already said produces no question and no policy - it is not a form to complete. "Neutral default" is what to propose when the user has no preference of their own; never treat it as house style to recommend.
+
+| # | Dimension | Answer signal | Optional question | Neutral default | Destination |
+|---|---|---|---|---|---|
+| 01 | Responsibility | Several sessions, or repeated supervision. | Who should coordinate work, and who answers a blocked session? | Keep your current responsibility split. | posture.md, worker.md |
+| 02 | Coordinator edits | The user already delegates changes. | Should the coordinating session make any commits itself? | Keep your existing boundary. | posture.md |
+| 03 | Work categories | The user describes several kinds of task. | Which tasks need code, a document, or only a decision? | Use only the categories the user named. | runbook.md |
+| 04 | Plan approval | The user wants delegation. | When should you approve a plan before it is assigned? | Confirm scope before assigning work. | runbook.md |
+| 05 | Plan fidelity | Unexpected findings interrupt work in progress. | Can a session change its approach on its own, or should it bring the choice back to you? | Ask on a material approach change. | runbook.md, worker.md |
+| 06 | Assignment detail | Repeated instructions are painful to write. | What must every assignment contain, and what is already standing policy? | Goal, files, checks, and the evidence that counts as done. | runbook.md, worker.md |
+| 07 | Preparation order | Overlapping branches run at once. | When do you prepare a branch and its dependencies? | Prepare immediately before work starts. | runbook.md |
+| 08 | Checkout location | The user already has a convention. | Where do you keep temporary checkouts? | Keep the user's current location. | hive.yml vars, runbook.md |
+| 09 | Push ownership | A remote is in use. | Who may push a completed branch, and when? | Keep the user's existing permission policy. | posture.md, worker.md |
+| 10 | Request state | Pull requests are in use. | Do you want a draft while checks run, or a ready request after review? | Use the user's present practice. | runbook.md |
+| 11 | Merge authority | Merge friction comes up. | Who approves merging, and may that approval be reused across changes? | Require the user's own merge instruction each time. | posture.md, runbook.md |
+| 12 | Completion definition | The user describes what "done" means to them. | What evidence makes a change finished for you? | Checks, plus the outcome the user named. | runbook.md, worker.md |
+| 13 | External actions | Sessions touch issue trackers or review tools. | Which external actions are already authorised, and which need your say each time? | Retain current permissions; assume none beyond what was stated. | posture.md, worker.md |
+| 14 | Tracking systems | A tracker is already in use. | Where is work recorded, and who updates each system? | hive's own records plus whatever the user already uses. | hive.yml vars, runbook.md |
+| 15 | Check commands | The user names existing checks. | Which command proves this project is ready, and which covers just a small change? | Use the commands the user already runs and can name. | hive.yml vars |
+| 16 | Suite coordination | Parallel checks would contend for a resource. | Do simultaneous checks share a database, port, or other resource? | Serialise only the resource that is genuinely shared. | runbook.md, worker.md |
+| 17 | Automation cadence | Automated checks are already scheduled. | When do checks run, and what stands in for them when none exist? | Keep the project's current cadence. | hive.yml vars, runbook.md |
+| 18 | Review location | Review already happens somewhere useful. | Where does your useful review happen today? | Preserve the review that is already useful to the user. | runbook.md |
+| 19 | Review selection | Review cost or coverage is a stated problem. | What review do you want for routine work, and what for a consequential change? | Only tools the user actually has and chooses. | hive.yml vars, runbook.md |
+| 20 | Review decisions | Review feedback feels noisy. | What makes a finding worth acting on, and who decides? | A concrete failure or a broken requirement. | runbook.md |
+| 21 | Review budget | Review passes repeat without concluding. | When should another review pass stop, or come back to you instead? | Do not add a numeric budget unless asked. | runbook.md |
+| 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 |
+| 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 |
+| 29 | Capacity accounting | Usage limits already affect the user's day. | Does capacity change scheduling for you, and how do you check it today? | Use measured capacity only; assume nothing about any specific provider. | runbook.md; top-level hive.yml `lead_turn_budget` only if asked |
+| 30 | Checkpoint recipient | Long delegated work has lost context before. | Who should receive a checkpoint, and decide whether to continue? | The person or session the user already designated. | worker.md; top-level hive.yml `context_checkpoint_percent` |
+| 31 | Child-session authority | Nested sessions have already caused a surprise. | May a nested helper edit, or should it only report back? | Read-only helpers unless the user explicitly assigns writes. | worker.md |
+| 32 | Commit conventions | The repository has commit conventions. | What commit format and signing does this repository require? | Keep the repository's own conventions. | runbook.md, worker.md |
+| 33 | Handoff ownership | State is lost between sessions. | What should survive a session, and who records it? | The outcome and the next action, in whatever record the user already keeps. | runbook.md, worker.md |
+| 34 | Information boundaries | Generated text gets published or shared. | What belongs in private notes but must never reach external text? | Respect the audience and policy the user already stated. | runbook.md, worker.md |
+| 35 | Outcome measurements | The user wants evidence for future model or process choices. | Which outcomes would help you improve this process later? | No new tracking system for a first profile. | runbook.md |
+| 36 | Reviewer feedback | The user maintains or tunes a reviewer. | Do review outcomes need to be recorded anywhere for future tuning? | Keep feedback in whatever record already exists. | runbook.md |
+| 37 | Supporting artifacts | Repeated long instructions are becoming hard to use. | Would one optional reference file help, and when should it be read? | No extra artifact without a concrete, stated need. | runbook.md, an optional profile `.md` |
+| 38 | Fork provenance | The user edits an existing fork, or shares one across projects. | Should this change affect every project on this profile, or only this one? | Preserve provenance; offer a separately named copy for isolation. | profile selection, minimal file edits |
+| 39 | Status messages | The user says updates are noisy or unhelpful. | What do you need to see in a status update? | A short outcome, the active work, and any open decision. | posture.md |
+| 40 | Startup routine | Setup gets repeated every time a session reopens. | What must a new session read before it starts work? | Existing project context plus live hive state. | runbook.md |
+| 41 | Waiting and deadlines | Time is lost to silent waits. | Which waits need a finish notice, or a deadline? | Completion wakes for real delegated work; no timer machinery by default. | runbook.md |
+
+**For simple**, skip the coordination-only dimensions unless the user asks to add delegation: 01-02, 04, 06-08, 16, 24, 28, 30-31. Every other dimension still needs its own answer signal before it becomes a question - simple does not mean asking less carefully about checking, review, or permissions, it means there is no second session to coordinate.
+
+**Common candidate defaults**, useful across both routes but never mandatory: keep the user's existing habits that already work, keep project-specific facts out of shared prose (route them to `vars` instead), use hive's own state for durable work records, ask on unclear scope, isolate concurrent file writes, and verify completion with something real rather than trusting a clean status line. Do not import a default just because it is common; every row above still needs its own answer signal from this user.
+
+## 4. Convergence and confirmation
+
+Stop discovery once you can describe: the current task flow, at least one pain or wanted change, one habit to preserve, who owns which actions, how completion will be verified, and who the profile is for (this project, or every project on this machine). Summarise earlier if the question budget is reached or the user asks to proceed. Keep observations, proposed improvements, and unresolved required inputs visibly distinct in that summary. Offer no more than three improvements, each linked to something the user said; the first draft includes only the ones they accepted.
+
+Before writing anything, show: profile name(s), the base each starts from, the intended scope (this project, or global), any permission change, the target files, any `hive.yml` change, and - for an edit - a concrete diff. Confirm this proposal once. For several profiles, confirm the whole batch but identify each profile separately.
+
+After writing and validating, explain how to restart the affected session(s) so the change takes effect, and invite one small edit after they try it. Do not dispatch actual project work, change which agent application is in use, install a third-party tool, or publish anything as part of this interview.
+
+## Scope: "this project" versus "every project"
+
+There is no way today to make a profile live as files inside a project's own repository; hive's profile loader only resolves named directories under a store's profiles directory or under hive's own shipped `profiles/`, and a profile name cannot contain a path separator. So:
+
+- **"This project only"** means: pick (or create) a distinct, named profile and set it with `profile: <name>` in *this project's* `hive.yml`. Other projects are unaffected.
+- **"Every project on this machine"** means: set `profile: <name>` in the user's own `~/.hive/hive.yml` (the global defaults file), which every project without its own `profile:` then inherits. Offer this only when the user explicitly asks for it, and say plainly that it changes the default for every project that does not already set its own `profile:`.
+
+Never suggest that a profile can live inside the project's own repository; that is a different, larger change this skill does not make.
+
+## Target selection: whose file are you about to write?
+
+Two possible write targets exist for any profile name, and they are not interchangeable:
+
+- **The user's own override**: a directory under the configured hive data directory's `profiles/<name>/` (normally `~/.hive/profiles/<name>/`, respecting `HIVE_DATA_DIR` if the user has set it - never assume the default location). This always wins at read time over anything shipped.
+- **The shipped source**: the actual template files under `profiles/<name>/` in a hive source checkout - available only when the current project *is* a hive checkout (this repository, or another clone of it), never the files an installed hive package ships.
+
+Recognise a hive source checkout by its own profiles directory together with its package identity and where its loader code lives, not by directory name alone. If you are not sure, ask; do not infer it from a folder simply being called `hive`.
+
+**Creating a new name** always writes to the user's own override, using the shipped template as the starting content for a chosen base (or a minimal new `posture.md` when starting from nothing). It never creates a new name under the shipped source.
+
+**Editing an existing name** offers both targets when both are available and lets the user choose, showing the absolute writable path for each and what it affects before confirmation:
+
+- Editing the **user's override** changes only what this user's machine resolves; it never touches the shipped checkout.
+- Editing the **shipped source** changes tracked product text everyone who updates that checkout will get. It must stay generic - no project-specific fact, no personal name or path, values still routed through `vars` - and it does not authorise a commit or a publish; that is a separate, explicit step the user takes themselves. If the user's own override for that same name already exists, say so explicitly: the override will keep hiding the edit at read time until the user deals with it, so never silently edit both, or edit one and call it done.
+
+**Validating a source-target edit** must not read through the ordinary store, because that would resolve the user's override instead of the change you just made. Read that checkout's own template file directly for authoring, and validate the *rendered* result using a scratch store that has no override in it - never the user's usual `hive doctor` or `hive profile read`, which resolve overrides first.
+
+**Reading for authoring never means reading a rendered file.** A rendered read drops any conditional block whose var is unset, so it is never a safe source for an edit - it can only look like the whole file when it is not. Read the raw template (`hive profile path <name> <file>` shows where it is) for authoring, and use `hive profile read`, `hive runbook`, and `hive posture` only to verify the rendered result afterward.
+
+**Splitting a shared profile.** If the user wants a change for one project only, but the profile is currently shared, propose a separately named copy that carries every one of that profile's existing valid `.md` files, not just the three known ones, rather than editing the shared original.
+
+**Preflight, then write.** For several new names or edits in one session, check every proposed name and destination for conflicts (an existing directory, an invalid name, a rejected reuse of a shipped name) before the first write. A profile name must start with a letter or digit, and every remaining character must be a letter, digit, dot, dash, or underscore, with no `..` anywhere in it; reject `none` as a name outright, since it means "no profile" to hive's own loader. If one item in a batch fails, leave the successful ones written and reported, and resume only the unfinished ones - never redo work that already succeeded.
+
+## Preserving what the interview did not touch
+
+Before writing an edit, re-read the actual target file (not a cached copy from earlier in the conversation): unrelated sections, comments, any extra `.md` file the profile carries, and `hive.yml`'s own keys and comments all carry through unchanged. Patch only the discussed rule and any dependent instruction the user explicitly approved; never regenerate a whole file from its base just to make one change. If the file changed since the proposal was shown, re-read it, present the revised diff, and confirm again before writing - never write over a change you have not seen.
+
+When selecting one project's `profile:` key in `hive.yml`, treat each project's selection as independent: writing one project's key must never overwrite, or be reported as though it overwrote, another project's selection.
+
+## `hive.yml` routing
+
+- `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.
+- `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.
+
+## Known traps
+
+- Reading a *rendered* profile file drops unset-var sections; never use it as the source for an edit (see above).
+- Conditional markers (`<!--if:var-->` / `<!--end-->`) each need their own line and must nest symmetrically; there is no inverse or else-branch, so never introduce a derived var meant to flip a section the opposite way.
+- A new `hive.yml` var only starts working once the code that renders it ships and the server restarts; a var referenced in a profile before that is simply absent from every render in the meantime, silently, since a presence-conditional has no error state.
+- Copying "the known three files" when isolating a shared profile drops any extra `.md` file that profile carries; enumerate what actually exists instead of assuming the three.
+- `hive doctor`'s global exit code mixes in unrelated environment checks; judge a profile by its own reported lines, never by that exit code alone.
+- Never fill an identity var (a worker's own name, actor id, working directory) with a project value just to quiet a var-usage report; those are supplied per spawn, not from `hive.yml`.
+

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

@@ -0,0 +1,12 @@
+# Recipe index
+
+A recipe is an optional pattern a profile can adopt: a short, named block of text (and sometimes a `hive.yml` var) that solves one recurring problem. Read the matching recipe only after discovery reveals its signal - this index exists so you know which one to open, not as five more required interview questions. Propose a recipe's benefit and cost, then apply it only if the user accepts it. Declining leaves the draft unchanged.
+
+| Recipe | Signal | Benefit | Route |
+|---|---|---|---|
+| [verification.md](verification.md) | Sessions finish without proving the outcome, or a known check gets repeated by hand. | A completion step that actually runs the user's own check and reports a real result. | Both |
+| [shared-test-resource.md](shared-test-resource.md) | Simultaneous test runs collide on a shared database, port, or device. | One agreed coordinator for the shared resource, so runs stop colliding. | Both |
+| [review-decision.md](review-decision.md) | Review already happens, but feedback causes churn or has no clear owner. | A named decision owner and evidence bar for acting on a finding. | Both |
+| [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 |
+

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

@@ -0,0 +1,41 @@
+# Review decision
+
+## Problem
+
+Review already happens, but feedback keeps churning because nobody agreed what makes a finding worth acting on, or who gets to decide.
+
+## Offer when
+
+The user already has some form of review, and says feedback is noisy, repeats, or has no clear owner. Interview dimensions 18-21. Both routes.
+
+## Requirements
+
+Where useful review already happens today, and who should decide whether a finding gets acted on. A review command is optional - only include one if the user names a real, installed tool they already run; human review needs none.
+
+## Add
+
+A runbook block naming the reviewer, the timing, and the decision owner:
+
+```markdown
+REVIEW
+Review happens at <existing point in the process>.
+<!--if:review_command-->
+Run: {{review_command}}
+<!--end-->
+A finding is worth acting on when it points to a concrete failure or a
+broken requirement, not a style preference. <decision owner> decides;
+record the decision where this project already keeps its work record.
+```
+
+## Verify
+
+Walk a sample real finding through the block and confirm it reaches the named decision owner, and that the decision gets recorded somewhere the project already tracks work - not a new location this recipe invents.
+
+## Remove
+
+Delete the added block. Leave `review_command` in `vars` if another part of the profile still references it.
+
+## Boundaries
+
+This does not install a new review tool, define a severity scale, or set a numeric limit on review passes. It only names who decides and what counts, using review the user already has.
+

package/claude-plugin/skills/profile/references/recipes/session-continuity.md

@@ -0,0 +1,37 @@
+# Session continuity
+
+## Problem
+
+A session reopens after a break and re-derives decisions it already made, or loses track of what it was about to do next, because nothing carried that forward.
+
+## Offer when
+
+The user says a reopened session repeats itself or has lost the next action. Interview dimensions 33, 40, 35. Both routes.
+
+## Requirements
+
+Whatever record the user already keeps work in (a tracker, a hive todo, a plain note); this recipe writes a habit around that record; it does not invent a new one. If the user has no such record yet, offer a hive todo comment as the smallest starting point, and only add it once they agree.
+
+## Add
+
+A short finish/start habit in `runbook.md`:
+
+```markdown
+SESSION CONTINUITY
+Before ending a session, record the outcome, any unresolved choice, and
+the next action in <the user's existing record>. The next session reads
+that record before starting new work.
+```
+
+## Verify
+
+Confirm a fresh session, reading only that record, can name the next action a prior session left behind.
+
+## Remove
+
+Delete the added habit from `runbook.md`. Historical entries already recorded stay; removing the habit only stops new ones.
+
+## Boundaries
+
+This does not create a new pad, a session directory, or any tool beyond what the user already uses to record work. It is a habit, not a mechanism.
+

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

@@ -0,0 +1,45 @@
+# Shared test resource
+
+## Problem
+
+Two sessions run a full check at the same time and collide on a database, a port, or a device the checks both need, producing a failure that looks like a broken change but is really two runs fighting over one resource.
+
+## Offer when
+
+The user describes simultaneous test runs colliding on something shared. Interview dimensions 16, 15. Both routes, including several solo sessions sharing one machine.
+
+## Requirements
+
+The name of the actual shared resource (a database, a port, a device) and who or what should coordinate access to it - a named person, or "whoever holds it first."
+
+## Add
+
+A runbook rule naming the resource and the coordination habit:
+
+```markdown
+SHARED TEST RESOURCE
+<name of the shared resource> is shared across sessions on this machine.
+Run one full check against it at a time; ask <coordinator> for the slot
+before starting one. Scoped checks that do not touch it can still run
+independently.
+```
+
+For orchestration, give workers the same obligation - asking the lead for the slot rather than assuming it is free - in `worker.md`.
+
+```yaml
+vars:
+  suite_command: <existing full-suite command, if templating helps>
+```
+
+## Verify
+
+Walk through two proposed runs and confirm both name the same coordinator and the same resource, and that the second is described as waiting for the first rather than running alongside it. This is a stated process, not an enforced lock; nothing in hive itself serializes it.
+
+## Remove
+
+Delete the added runbook rule (and the worker.md line on orchestration). Leave any existing runner-level lock the project already has untouched; this recipe only adds the human process on top of it.
+
+## Boundaries
+
+This does not implement a real lock, a queue, or a CI concurrency guard. It only gives the people and sessions involved one agreed rule to follow.
+

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

@@ -0,0 +1,50 @@
+# Verification
+
+## Problem
+
+A session reports a change "done" on a clean status line, but nothing actually ran the project's own check, or a known checking command gets retyped by hand every time because the runbook never wrote it down.
+
+## Offer when
+
+The user says work has finished without proving the outcome, or repeats a checking command they already have. Interview dimensions 15, 17, 22. Both simple and orchestration.
+
+## Requirements
+
+The user's confirmed scoped-check command (`vars.test_command` or the shipped `check`) and, if they have one, a real verification command (`vars.verify_command`) - a way to exercise the actual outcome, not just run a linter. Neither is invented; both come from the user or from a command you have watched them run.
+
+## Add
+
+A short completion block in `runbook.md`:
+
+```markdown
+BEFORE CALLING THIS DONE
+<!--if:check-->
+Run: {{check}}
+<!--end-->
+<!--if:verify_command-->
+Then verify the actual outcome: {{verify_command}}
+<!--end-->
+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.
+
+```yaml
+vars:
+  check: <existing scoped-check command>
+  verify_command: <existing real-outcome check, if any>
+```
+
+## 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.
+
+## Remove
+
+Delete the added block from `runbook.md` (and `worker.md` on orchestration). Leave `check` and `verify_command` in `vars` if anything else still references them; only drop a var once nothing does.
+
+## Boundaries
+
+This recipe does not install a review tool, a CI pipeline, or a numeric pass budget. It only makes an existing check part of what "done" means.
+

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

@@ -0,0 +1,51 @@
+# Worker context checkpoint
+
+## Problem
+
+A worker's context keeps growing across a long delegated task and never resets on its own; run long enough with no checkpoint and it loses useful earlier context, or gets stuck and needs a successor that has to relearn everything.
+
+## Offer when
+
+The user describes delegated work running long enough to lose context, or a session repeatedly needing a fresh replacement. Interview dimensions 30, 28. Orchestration only - there is no worker to checkpoint in simple.
+
+## Requirements
+
+A context-fill threshold (a percentage), and who should receive a checkpoint and decide whether the worker continues, splits, or hands off to a fresh session - usually the lead, keep an existing threshold if the user already has one instead of asking again.
+
+## Add
+
+`context_checkpoint_percent` at the top level of `hive.yml`:
+
+```yaml
+context_checkpoint_percent: <the user's chosen or existing threshold, 1-100>
+```
+
+A block in `worker.md`:
+
+```markdown
+AT THE CONTEXT CHECKPOINT
+Commit what works. Write what is done, what is left, and anything you now
+know that the assignment did not say, onto the todo. Report to
+<decision owner>, then wait: do no further work until they answer with one
+of continue, split, or hand over to a fresh session.
+```
+
+And the recipient's obligation in `runbook.md`:
+
+```markdown
+When a worker reports its context checkpoint, read what it wrote and
+answer with continue, split, or hand over - do not leave it waiting.
+```
+
+## Verify
+
+`hive doctor` reports the configured threshold, and the generated `worker.md` names the confirmed recipient. Exercise a synthetic checkpoint handoff - a worker reporting the checkpoint and the recipient answering - without spawning real project work, to confirm the instruction is legible end to end.
+
+## Remove
+
+Restore the previous `context_checkpoint_percent` value, or delete the key entirely if this recipe introduced it. Remove the inserted `worker.md` and `runbook.md` blocks. This does not stop a worker already running; restart or newly start workers to pick up the change.
+
+## Boundaries
+
+The threshold only informs; hive does not stop a worker at it. The behavior at the checkpoint comes entirely from the instruction this recipe adds, not from any enforcement hive performs on its own.
+

package/dist/build-info.json

@@ -1 +1 @@
-{"version":"1.2.2","sha":"df20075","dirty":false,"build_id":"2f8ecccc-4d22-424a-8c24-c48551ed2441"}
+{"version":"1.3.0","sha":"196e28e","dirty":false,"build_id":"f75b8010-85e7-400f-8036-0c0484e509f9"}