Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.
Integration guide
Use this guide to choose a connection to Hive v5. Configuring an existing integration is different from implementing a new one.
| Your task | Start here | Current boundary |
|---|---|---|
| Read tasks from a planning service | Work source providers, then its configuration examples | GitHub Issues, GitHub Projects, Linear, and Jira are primary providers. Implementing another primary provider requires Go changes in Hive. |
| Lend your machine’s AI coding tool | Contributor relay: basic setup | The relay receives work from Hive and reports its result. |
| Have an external workflow engine run work | ClankeR and Flue-style execution | Hive still decides what may run and verifies reported evidence; Flue dispatch is report-only. |
| Turn a specification into staged work | Spektacular integration | The planning tool must implement the documented Spektacular CLI contract; there is no general planning-engine registry. |
In the diagram, the work source supplies tasks, the governor schedules agents, and a run lease records who owns a stage and when it expires. An additive source appends tasks alongside the selected primary source rather than replacing it.
Two external projects shaped these surfaces and remain the reference integrations: Flue, the report-only external-execution pilot behind the pkg/extwork contract, and Crustify, the C/C++-to-Rust migration harness whose Wavefront migration graph is consumed as an additive work source (see work sources and the wavefront-smoke.yml canary).
Extension surfaces in v5
| Surface | What you can do today | Start here |
|---|---|---|
| Work sources | Add or configure an adapter that turns source-native items into worksource.Issue values. The only primary adapters linked today are GitHub Issues, GitHub Projects, Linear, and Jira; run stages and the Crustify Wavefront migration graph are additive sources. | Work source providers |
| ClankeR + Flue-style external execution | Use the contributor relay as the transport and the pkg/extwork contract as the engine-neutral admission/observation seam. Flue is the reference HTTP adapter. | ClankeR and Flue-style external execution |
| Spektacular | Let Hive poll a Spektacular-compatible CLI for spec/plan status and import final plan tasks into Hive’s run flow. | Spektacular and Project Inception |
| vibe-kanban | Mirror one repository’s admitted hive queue onto a local vibe-kanban board through its MCP server, optionally record board pick-ups as shadow executions, or opt in to the pkg/extwork/vibekanban host adapter for report-only workspace dispatch. Default off. | vibe-kanban mirror and dispatch |
Related surfaces that are not redefined here: agent configuration, CLI/backend setup, MCP write policy, hub API, contributor relay, work sources, long-running runs, and Spektacular runner.
Terminology
Use source-neutral words in generic integration docs: work source, project, item, and change request. Keep product names only when talking about a specific adapter, such as GitHub Projects or Jira. The glossary and guard-test intent live in Work-source terminology.
For implementers, source-native means retaining a service’s own item identifier; an admission/observation seam is the code boundary for allowing work and checking its progress. A canary is a small verification workflow, not another installation requirement.
Gaps tracked from this guide
- Work source adapters are compile-time Go integrations, not external plugins: #10174.
- Project Inception only wires a Spektacular-compatible CLI boundary; there is no generic named planning-engine registry: #10175.
Documentation maintenance: edit canonical Hive guides in this repository’s src/docs/ on v5. The hivecommons/docs Next.js/Nextra site mirrors that tree; its README describes syncing. This source relationship is not an integration prerequisite.