hivecommons-hive · Oct 3, 2026 · Oct 3, 2026
@@ -0,0 +1 @@
+- Publish Hive's third-party Integration guide (work-source providers, Clanker/Flue-style interface, Spektacular project inception) under a new "Integrating with Hive" nav section, synced from `hivecommons/hive` `src/docs/`.
@@ -0,0 +1,37 @@
+> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/integration-guide.md) during the docs build. Edit the canonical source in the Hive repository.
+
+# Integration guide
+
+Audience: platform teams and tool authors who want Hive to read a non-GitHub backlog, lend external execution capacity, or connect planning/specification tools without over-claiming what v5 can do today.
+
+The canonical Hive documentation source for the published Hive docs is this repository's `src/docs/` tree. The separate `hivecommons/docs` site repository is the Next.js/Nextra shell for docs.hivecommons.dev; its README says the site syncs Hive content from `hivecommons/hive` `src/docs/` on branch `v5`. Put Hive guide changes here first, then let that mirror pick them up.
+
+```mermaid
+flowchart LR
+    WorkSource[Work source provider\nlist source-native work items] --> Governor[Governor queue]
+    Governor --> Agents[Hive agents and contributor relay]
+    Clanker[ClankeR contributor relay\n/api/contribute/ws] --> Agents
+    Flue[Flue external workflow\nextwork adapter] --> Clanker
+    Spek[Spektacular CLI\nspec/plan status + plan export] --> Runs[Long-running run leases]
+    Runs --> WorkSource
+    Runs --> Governor
+```
+
+## 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 Wavefront are additive sources. | [Work source providers](/docs/hive/integrations/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](/docs/hive/integrations/clanker-flue) |
+| 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](/docs/hive/integrations/spektacular) |
+
+Related surfaces that are not redefined here: [agent configuration](/docs/hive/agent-configuration), [CLI/backend setup](https://github.com/hivecommons/hive/blob/v5/docs/backend-setup.md), [MCP write policy](/docs/hive/security-model), [hub API](https://github.com/hivecommons/hive/blob/v5/src/docs/api-reference.md), [contributor relay](/docs/hive/contributor-relay), [work sources](/docs/hive/work-sources), [long-running runs](https://github.com/hivecommons/hive/blob/v5/src/docs/runs.md), and [Spektacular runner](/docs/hive/integrations/spektacular).
+
+## 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](https://github.com/hivecommons/hive/blob/v5/src/docs/work-source-terminology.md).
+
+## Gaps tracked from this guide
+
+- Work source adapters are compile-time Go integrations, not external plugins: [#10174](https://github.com/hivecommons/hive/issues/10174).
+- Project Inception only wires a Spektacular-compatible CLI boundary; there is no generic named planning-engine registry: [#10175](https://github.com/hivecommons/hive/issues/10175).
@@ -0,0 +1,80 @@
+> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/integrations/clanker-flue.md) during the docs build. Edit the canonical source in the Hive repository.
+
+# ClankeR and Flue-style external execution
+
+## Audience
+
+This page is for authors of external workflow engines that want Hive to hand them bounded work the way the Flue pilot does. It is also for operators deciding whether ClankeR is the right integration point.
+
+## Concepts
+
+In this codebase, **ClankeR** is the contributor relay: a contributor-owned process connects to a hive over `/api/contribute/ws`, advertises backend/model/capabilities, receives one task at a time, heartbeats, and reports completion metadata. The user-facing setup is documented in [ClankeR contributor relay](/docs/hive/contributor-relay).
+
+Flue is not a separate Hive Commons repository in the org listing; the v5 integration lives in this repo under `pkg/extwork/flue`. The adapter comment names the probed upstream Flue runtime commit `c5a2a725fe1d93209ed294cca90af97060f6f2e2` and maps Hive's external-work contract to Flue's keyed admission, runtime UID, status, abort, and artifacts (`src/pkg/extwork/flue/flue.go:1`).
+
+## Interface
+
+The engine-neutral contract is `pkg/extwork.Adapter`:
+
+- `Engine() string` returns the engine name (`src/pkg/extwork/adapter.go:111`).
+- `Start(ctx, StartRequest)` admits a keyed request idempotently; same key plus same payload should deduplicate, same key plus different payload should conflict (`src/pkg/extwork/adapter.go:47`, `src/pkg/extwork/adapter.go:114`).
+- `Observe(ctx, key, incarnation)` reports one of `accepted`, `running`, `waiting`, `terminal`, or `unknown`; transport errors become unknown, not fabricated failure (`src/pkg/extwork/adapter.go:11`, `src/pkg/extwork/adapter.go:71`).
+- `Cancel(ctx, key, incarnation)` reports requested, acknowledged, and stopped separately (`src/pkg/extwork/adapter.go:88`, `src/pkg/extwork/adapter.go:119`).
+- `OpenArtifact(ctx, key, incarnation, path)` streams an artifact by execution key and relative path; the binding verifies size, path, and digest before parsing (`src/pkg/extwork/adapter.go:121`).
+
+Adapters are constructed through `extwork.Factory` and registered in an `extwork.Registry` (`src/pkg/extwork/registry.go:16`, `src/pkg/extwork/registry.go:36`). The Flue build tag links the Flue adapter into the default registry (`src/cmd/hive/extwork_flue.go:17`). Dashboard code sees only the `ExternalExecution` seam, not the adapter package (`src/pkg/dashboard/extwork_binding.go:51`).
+
+## How Flue maps the contract
+
+Flue's `Config` contains only an endpoint, a pinned workflow version, and an optional test HTTP client (`src/pkg/extwork/flue/flue.go:52`). `New` validates that the endpoint is `http` or `https`, has a host, and has no userinfo/query/fragment, then uses an HTTP client with proxy disabled (`src/pkg/extwork/flue/flue.go:71`).
+
+The HTTP surface used by Hive is:
+
+| Hive call | Flue request | Real fields |
+| --- | --- | --- |
+| Pin incarnation | `GET /` | `engine`, `version`, `incarnation` (`src/pkg/extwork/flue/flue.go:93`) |
+| Start | `POST /dispatch` | request body `idempotency_key`, `payload`; response `submission_id`, `uid`, `deduplicated` (`src/pkg/extwork/flue/flue.go:186`) |
+| Observe | `GET /submissions?key=<execution-key>` | response `id`, `uid`, `state`, `stage`, `result_class`, `receipt` (`src/pkg/extwork/flue/flue.go:132`, `src/pkg/extwork/flue/flue.go:282`) |
+| Cancel | `POST /submissions/{id}/abort` | response `requested`, `acknowledged`, `stopped`, `detail` (`src/pkg/extwork/flue/flue.go:303`) |
+| Artifact | `GET /submissions/{id}/artifacts/{path}` | stream returned bytes after the binding verifies the declared receipt (`src/pkg/extwork/flue/flue.go:323`) |
+
+The adapter never receives a GitHub token, dashboard token, or publication credential. `runs.external.flue` has `enabled`, `mode`, `endpoint`, and `workflow_version`; enabled with no mode is shadow, and only `report-only` dispatches (`src/pkg/config/runs.go:38`).
+
+## Step-by-step: integrate a third-party engine
+
+1. Decide whether your engine should be a **relay peer** or an **HTTP runtime**. Flue is an HTTP runtime; OMP is a relay peer behind the same `extwork` contract.
+2. Implement `extwork.Adapter`, returning sentinel errors such as `ErrConflict`, `ErrRefused`, `ErrNotFound`, `ErrIncarnationMismatch`, and `ErrTransport` so the binding can classify outcomes (`src/pkg/extwork/adapter.go:95`).
+3. Add a factory and registry name. Flue's factory reads `endpoint` and `workflow_version` from plain string settings (`src/pkg/extwork/flue/flue.go:89`).
+4. Wire the engine in `cmd/hive` with a build tag, following `extwork_flue.go` and `newExternalFlueBinding` (`src/cmd/hive/extwork_flue.go:17`, `src/cmd/hive/extworkwire.go:226`).
+5. Add config under `runs.external.<engine>` if it needs operator settings. Keep the default off and use shadow before report-only, as `FlueBindingConfig` does (`src/pkg/config/runs.go:38`).
+6. Provide a deterministic fixture and conformance tests. Flue's fixture lives under `pkg/extwork/flue/fixture`, with adapter tests and smoke tests (`src/pkg/extwork/flue/conformance_test.go:1`, `src/test/extwork/flue_smoke_test.go:45`).
+
+## Example: minimal Flue-style calls
+
+```sh
+curl -s http://flue-runtime.example/ | jq .
+
+curl -s -X POST http://flue-runtime.example/dispatch \
+  -H 'content-type: application/json' \
+  -d '{"idempotency_key":"hive-example-key","payload":"base64-or-json-bundle"}' | jq .
+
+curl -s 'http://flue-runtime.example/submissions?key=hive-example-key' | jq .
+```
+
+Hive makes those calls through the adapter, not shell commands; the snippet is for implementers validating their runtime surface.
+
+## Testing
+
+Use the engine-neutral tests in `pkg/extwork` for admission and receipt behavior, plus adapter-specific conformance. Flue's test suite verifies factory validation, duplicate/different payload behavior, status mapping, cancellation facts, artifact fetch, and fixture smoke paths (`src/pkg/extwork/flue/flue_test.go:58`, `src/pkg/extwork/flue/conformance_test.go:1`).
+
+## Operational notes
+
+- Auth: v5 Flue carries no auth header in the adapter. Put the runtime behind network controls or add a reviewed adapter auth field before using it outside a trusted environment.
+- Rate limits and backpressure: use `waiting` for human, budget, or capacity waits instead of returning terminal failure.
+- Failure modes: transport failure is `unknown`; incarnation mismatch is a refusal to adopt a possibly unrelated recreated runtime; artifact digest mismatch rejects the candidate while preserving evidence.
+- Terminology: describe this as an external workflow engine or contributor relay capability, not a GitHub-only integration.
+
+## Gaps
+
+- ClankeR is not an independent plugin marketplace or MCP server. It is Hive's contributor relay protocol plus code in this repository.
+- The Flue binding is compile-time/build-tagged. A third-party engine still needs a Hive PR unless it mimics an already-wired protocol endpoint.
@@ -0,0 +1,114 @@
+> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/integrations/spektacular.md) during the docs build. Edit the canonical source in the Hive repository.
+
+# Spektacular and Project Inception
+
+## Audience
+
+This page is for tool authors who want to understand Hive's Project Inception and long-running-run seam. It distinguishes what is actually pluggable from what is simply a Spektacular-compatible CLI contract.
+
+## Concepts
+
+Project Inception can admit an approved issue into a long-running `spec` run when Spektacular support is enabled. The approval handler checks `runs.spektacular.enabled` before admission (`src/pkg/dashboard/inception_handlers.go:269`). The stage runner is installed at boot only when that same config flag is true (`src/cmd/hive/spektacularwire.go:19`).
+
+Spektacular owns artifact state; Hive owns the workflow lease. Hive polls Spektacular for `spec` and `plan` artifacts, advances leases on final documents, and imports final plan tasks into Hive's planner (`src/pkg/spektacular/adapter.go:97`). The dashboard side stays decoupled through the stage lease interface and `SetStageRunner` (`src/pkg/dashboard/stage_leases.go:87`).
+
+## Interface
+
+Hive talks to a CLI executable, configured by `runs.spektacular.binary` with default `spektacular` (`src/pkg/config/runs_config.go:137`). The runner executes commands through `BinaryExec`, which runs the configured binary with arguments and captures stdout (`src/pkg/spektacular/runner.go:249`).
+
+Required status command:
+
+```sh
+spektacular <spec|plan> status <name>
+```
+
+The JSON response maps to `ArtifactStatus` (`src/pkg/spektacular/runner.go:127`):
+
+```json
+{
+  "error": false,
+  "kind": "spec",
+  "name": "000057_git-commit",
+  "artifact_id": "artifact-uuid-or-stable-key",
+  "document_status": "draft",
+  "current_step": "outline",
+  "completed_steps": ["intake"],
+  "created_at": "2026-10-02T00:00:00Z",
+  "updated_at": "2026-10-02T12:00:00Z",
+  "closed_at": "",
+  "spec": "000057_git-commit",
+  "plan": "000057_git-commit"
+}
+```
+
+Hive decides progress from `document_status`, `current_step`, and `completed_steps`; `updated_at` is informational and never decides progress (`src/pkg/spektacular/runner.go:127`). `document_status: final` advances; `draft` waits; `stale` parks the run for human attention (`src/docs/spektacular.md:139`).
+
+Preferred final-plan export:
+
+```sh
+spektacular plan export <name> --format json
+```
+
+The response maps to `Plan`/`PlanTask` (`src/pkg/spektacular/runner.go:225`):
+
+```json
+{
+  "kind": "plan",
+  "name": "000057_git-commit",
+  "tasks": [
+    {
+      "id": "T1",
+      "ref": "T1",
+      "repo": "hivecommons/hive",
+      "title": "Add encoding helpers",
+      "depends_on": ["T0"],
+      "execution": "agent_suitable"
+    }
+  ]
+}
+```
+
+If export is unavailable, Hive falls back to `spektacular plan file read <name>/tasks.json` and then `<name>/plan.md` (`src/pkg/spektacular/runner.go:429`, `src/pkg/spektacular/runner.go:445`).
+
+## Step-by-step: use or emulate Spektacular
+
+1. Enable the runner:
+
+   ```yaml
+   runs:
+     max_stage_retries: 2
+     spektacular:
+       enabled: true
+       binary: spektacular
+       poll_interval_s: 30
+   ```
+
+   These fields are `SpektacularConfig` and default off (`src/pkg/config/runs_config.go:137`).
+2. Ensure the binary prints JSON for `spec status`, `plan status`, and preferably `plan export --format json`; Hive passes no `--json` flag.
+3. Use the bare artifact name as the CLI address. Hive normalizes `<name>.md` and `<name>/plan.md` to `<name>` with `ArtifactKey` (`src/pkg/spektacular/runner.go:65`).
+4. Let Hive own stage leases. `RunStageLeaseAccessor` lists pending stages as work items when `run_stages: true` is enabled (`src/pkg/worksource/run_stage.go:37`).
+5. Let Hive import final plan tasks. `ImportRunPlan` admits exported tasks as a draft Hive plan; implement work is listed only after approval (`src/pkg/dashboard/stage_leases.go:485`).
+
+## Example flow
+
+1. An operator approves an Inception run with an issue URL; when Spektacular is enabled, Hive admits the issue as a `spec` run (`src/pkg/dashboard/inception_handlers.go:269`).
+2. The runner polls `spektacular spec status <name>` until the spec is final (`src/pkg/spektacular/runner.go:359`).
+3. Hive writes a stage receipt and advances the lease to `plan` (`src/pkg/spektacular/adapter.go:97`).
+4. The runner polls `plan status`; on final it imports the structured plan (`src/pkg/spektacular/runner.go:403`).
+5. Hive exposes implement work as run-stage items after plan approval (`src/pkg/worksource/run_stage.go:62`).
+
+## Testing
+
+Use `pkg/spektacular/testdata/spektacular-fake/spektacular`, which implements the CLI scenarios documented by the runner page. Tests cover no direct file access, status parsing, stale/final transitions, retries/escalations, plan export fallback, and dashboard lease integration (`src/docs/spektacular.md:277`, `src/pkg/spektacular/adapter_test.go:142`, `src/pkg/dashboard/spektacular_runner_test.go:153`).
+
+## Operational notes
+
+- Auth and secrets: Hive invokes a local binary; any Spektacular backend credentials belong to that tool's own environment, not to Hive's dashboard token.
+- Rate limits: tune `poll_interval_s`; every active `spec` or `plan` stage is polled at that cadence (`src/pkg/config/runs_config.go:145`).
+- Failure modes: missing artifacts become typed not-found errors; stale/replaced documents are refused rather than silently rebound; expired leases retry until `max_stage_retries` then escalate (`src/pkg/spektacular/runner.go:300`, `src/pkg/spektacular/runner.go:520`).
+- What is exposable: status JSON, plan export JSON, run-stage work items, stage receipts, and campaign projections through `/api/campaigns`.
+- What is not exposable: Hive does not open Spektacular files directly, does not provide a generic planning-engine registry, and does not let a third-party engine mutate Hive's leases except through the configured runner boundary.
+
+## Gaps
+
+- A different inception/planning engine can work only by behaving like the Spektacular CLI or by adding new Hive code. There is no named `runs.<engine>` registry for Project Inception yet; tracked in [#10175](https://github.com/hivecommons/hive/issues/10175).
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		- Publish Hive's third-party Integration guide (work-source providers, Clanker/Flue-style interface, Spektacular project inception) under a new "Integrating with Hive" nav section, synced from `hivecommons/hive` `src/docs/`.