Hive

---
name: hive
description: Operate Hive task pipelines and pre-release QA through its native CLI. Use when an agent needs to read durable daily activity or history, answer current Hive or Hive-bench status, identify the exact active task and blocker owner, discover or answer waiting brainstorm questions in Guided or explicit YOLO mode, follow work through bounded transitions, create a new project-local workflow from an ordinary-language request, inspect candidate QA evidence, advance a fresh routine recommendation, diagnose recovery state, initialize or configure Hive, or explain what requires operator action across registered projects.
---

# Hive Operations

Use Hive as the control plane. Do not replace its status, watch, scheduler, or recovery machinery with shell polling, process discovery, or an agent-authored sidecar.

## Request routing

For daily-history questions such as what happened today, yesterday, on a
persisted date, or in one project's daily activity, read
[daily-digest.md](references/daily-digest.md) and use its pure JSON route
immediately. Do not run the current operational-status loop first.

For present operational state, task progress, blockers, or actions, use this
loop:

1. Request a fresh machine snapshot with `hive status --operational --json`.
2. The normal `hive` command is the active installation. Inspect `runtime.channel`; when it is `dogfood`, report `runtime.display_version`, the full `runtime.build_sha`, and `runtime.deployment_id`. Do not bypass dogfood by locating another Hive binary, registry, daemon, or web service unless the operator explicitly asks: dogfood replaces the installed runtime rather than running beside it.
3. Check `ok`, `completeness`, task-graph freshness, and scheduler freshness before making a confident claim.
4. Report counts, the exact `project:slug`, state, blocker owner, reason, stage/marker, and provider or scheduler evidence when present.
5. For one exact task's result, usage, applicable evidence, or diagnostic locator, use `hive task TARGET --project NAME --json`. Follow its receipt-correlated log reference with `hive task TARGET --project NAME --log` only when the diagnostic is current; do not treat either task view as provider health or a bill.
6. Use `hive watch ... --json-lines` when the user wants ongoing status. Declare a target and terminal bound; do not write a polling loop.
7. Execute only a fresh action descriptor whose risk is routine, confirmation is not required, and opaque observation token came from that same task row. Use `hive act`; never execute status text or arbitrary argv.
8. Request another operational snapshot after any action. Never assume that a successful command proves the later pipeline state.

For project-local installable modules, prefer the shared read-only surfaces:
`hive module list --json`, `status`, `inspect`, `doctor`, and `dry-run`.
Treat their redacted status object as authority for generation, configuration,
grant, hook, trigger, decision, attempt, retry, and artifact state; do not infer
completion from worker logs.

## Operational vocabulary

- `running`: a verified live worker owns the task.
- `waiting_on_you`: a genuine operator decision or answer is required.
- `needs_repair`: Hive or an operator must repair a failed or stale condition.
- `waiting_on_provider_or_scheduler`: current evidence attributes the wait to quota, capacity, cooldown, dependency, or another scheduler gate.
- `completion_ready`: work reached a completion boundary but is not necessarily archived.
- `idle`: the task is ready for dispatch and has no current worker.
- `unknown`: evidence is incomplete or contradictory; say what is missing.

Do not reinterpret `idle` as “nothing is happening” without checking ownership and scheduler evidence. Do not attribute a provider wait unless the current snapshot names the provider or a current scheduler disposition proves it.

## Authority boundary

Proceed with read-only inspection and bounded watching. Proceed with an emitted routine action only when all freshness and action-policy checks above pass. Follow direct user requests for normal non-destructive workflow work through Hive’s documented verbs.

Ask before destructive or administrative changes, marker clearing, force/bypass options, stopping automation, replacing installed configuration, changing destinations, publishing externally, deploying, tagging, releasing, or changing release-version metadata. Preserve task folders, worktrees, attempts, queues, locks, and recovery evidence while diagnosing.

Daily-digest reads serve a single authenticated Hive operator and add no team
or per-project reader ACL. Agents do not configure recap schedules,
destinations, or delivery-status policy, and no MCP-specific digest wrapper
exists in V1. Digest work does not authorize a release, version choice,
publication, or deployment.

Module lifecycle and patrol-ownership changes are human-gated. Agents may
prepare read-only previews and diagnostics, but must not approve grants, apply a
module receipt, sign a migration report, cut over mutator ownership, or request
rollback without the operator's explicit direction.

## Load the relevant reference

- Read [workflow-installation.md](references/workflow-installation.md) when installing from a private or direct Git repository; check installed CLI support, repository access, and runtime prerequisites before reporting readiness.

- Read [daily-digest.md](references/daily-digest.md) when asked for recent merged changes; use `hive digest --json`, inspect its `local_date`, and read the saved `document`. Use an explicit date for today or yesterday.
- Read [workflow-creator.md](references/workflow-creator.md) when ordinary language asks to create a new project-local workflow. This focused route is the `hive-workflow-creator` capability inside the single canonical `/hive` skill; it is not a second skill or package.
- Read [workflow-creator-example.md](references/workflow-creator-example.md) for the accepted research → draft → approval editorial example.
- Read [workflow-schema.md](references/workflow-schema.md), [workflow-stage-design.md](references/workflow-stage-design.md), [workflow-checkpoints.md](references/workflow-checkpoints.md), [workflow-permissions.md](references/workflow-permissions.md), [workflow-testing.md](references/workflow-testing.md), and [workflow-common-mistakes.md](references/workflow-common-mistakes.md) only as needed while authoring or diagnosing a newly scaffolded descriptor.
- Read [status-and-watch.md](references/status-and-watch.md) for status interpretation, reporting, compatibility, and native watch semantics.
- Read [brainstorm-answering.md](references/brainstorm-answering.md) for waiting brainstorm input, read-only discovery, Guided/default answering, explicit YOLO answering, binding-safe persistence, and completion reporting.
- Read [workflow-actions.md](references/workflow-actions.md) for task creation, direct workflow verbs, daemon ownership, closed actions, and completion checks.
- Read [recovery.md](references/recovery.md) for diagnosis, coordinator ownership, provider holds, stale workers, migration, and guarded recovery.
- Read [patrol-health.md](references/patrol-health.md) when inspecting ordinary
  Patrol findings or Architecture Patrol jobs, blockers, and routed theses.
- Read [setup-and-platforms.md](references/setup-and-platforms.md) for installation, initialization, agent-skill setup, and platform invocation conventions.
- Read [release-candidate-qa.md](references/release-candidate-qa.md) for semantic E2E discovery, local candidate evidence, bounded hosted collection, retry semantics, and the explicit hosted-dispatch boundary.
- Read [safety.md](references/safety.md) before any admin, force, credential, external-publication, deployment, or release-sensitive operation.