Synced from Hive. This page is pulled from hivecommons/hive@v5 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 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:

spektacular <spec|plan> status <name>

The JSON response maps to ArtifactStatus (src/pkg/spektacular/runner.go:127):

{
  "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:

spektacular plan export <name> --format json

The response maps to Plan/PlanTask (src/pkg/spektacular/runner.go:225):

{
  "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

Enable the runner:

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).

Ensure the binary prints JSON for spec status, plan status, and preferably plan export --format json; Hive passes no --json flag.
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).
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).
Let Hive import final plan tasks. ImportRunPlan admits exported tasks as a draft Hive plan; implement work is listed after approval (src/pkg/dashboard/stage_leases.go:485).

Example flow

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).
The runner polls spektacular spec status <name> until the spec is final (src/pkg/spektacular/runner.go:359).
Hive writes a stage receipt and advances the lease to plan (src/pkg/spektacular/adapter.go:97).
The runner polls plan status; on final it imports the structured plan (src/pkg/spektacular/runner.go:403).
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 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.