# Hive: Hub & Spoke

AI Agent Orchestration for Open Source

From brainstorming to full autonomy and everything in-between.

A fully customizable fleet of AI agents covering every level of project maintenance.

hive.kubestellar.io

# Hub & Spoke Architecture

Hub (hive.kubestellar.io) - central registry, cross-hive leaderboard, contributor directory

Spoke - independent hive instance with its own agents, repos, and GitHub App

| Hub | Spoke
--- | --- | ---
Role | Registry, federation, leaderboard | Runs agents, manages repos
Auth | Contributor directory | Own GitHub App + scoped tokens
Data | Aggregated metrics | Local beads, wiki, snapshots

- Spokes register with hub, send heartbeats, share contributor metrics
- Each spoke is fully independent - hub coordinates, never controls
- Contributors can register with multiple spokes across the network

# Agents & the Governor

10 built-in agents, each with a lane, a policy, and boundaries. Custom agents can be added easily.

Agent | Role
--- | ---
Supervisor | Prioritizes, dispatches work
Scanner | Inbound triage, bug fixes
Quality | Test coverage, code quality
CI-Maintainer | Build health, workflows
Sec-Check | Security screening

Agent | Role
--- | ---
Architect | RFCs, refactors
Strategist | Cross-agent coordination
Outreach | Community, ADOPTERS
Guide | Repo setup advice (L1)
Brainstorm | Ideas to knowledge (L1)

Governor adapts cadence based on queue depth (thresholds fully customizable):

SURGE (> 20) | BUSY (10-20) | QUIET (2-10) | IDLE (<= 2)
--- | --- | --- | ---
Scanner only, all-hands triage | Scanner + Reviewer, reduced | All agents active | Architect + Outreach, deep work

# ACMM Levels & the Proxy

The AI-native Codebase Maturity Model - 6 levels from brainstorming to fully autonomous.

The ACMM Proxy sits between agents and GitHub, enforcing level constraints and preventing rogue behavior.

Level | Name | Agents | Allowed Actions
--- | --- | --- | ---
L1 | Inception | 2 | Advisory only. Guide + Brainstorm.
L2 | Advisory | 5 | Advisory beads on dashboard. No GitHub writes.
L3 | Quality-Gated | 6 | Quality opens hold-gated PRs. CI gates begin.
L4 | Security-Aware | 7 | Agents open issues. Sec-check joins.
L5 | Semi-Autonomous | 9 | PRs with `hold` label. Human batch-review.
L6 | Autonomous | 10 | Auto-merge on green CI. Full fleet.

Agents cannot bypass their level - the proxy blocks unauthorized PRs, issues, and merges.

> Paper: The AI Codebase Maturity Model

# Level 1: Inception (Brainstorming) & Spec-Kit

### Inception - onboarding a project into Hive

Phase | What Happens
--- | ---
Capture | Provide the raw idea or existing repo URL
Clarify | Brainstorm generates 5-7 questions; you answer
Structure | Creates knowledge base facts (vision, requirements, constraints)
Scaffold | Generates bootstrap files (README, CLAUDE.md, CI, tests)
Complete | Inception done, agents ready

Two modes: greenfield (new idea, no repo) or brownfield (existing repo, extract facts).

### Spec-Kit - structured artifacts generated at L1

`specs/CONSTITUTION.md` - immutable principles | `specs/SPEC.md` - requirements

`specs/PLAN.md` - implementation steps | `specs/TASKS.md` - task breakdown

These artifacts bootstrap the LLM-Wiki knowledge layer.

# LLM-Wiki: The Knowledge Layer

A 4-layer wiki (powered by `llm-wiki`) giving agents shared memory.

Injected as markdown into every agent's work order from L2 onward.

Layer | Scope | Source
--- | --- | ---
Personal | Private | User edits
Project | Repo | Auto-extracted from merged PRs
Org | Team | Auto-promoted (confidence >= 0.9)
Community | Public | PR-based contributions

Precedence: personal > project > org > community

### Fact types evolve as the project matures

Ideation (L1) | Operational (L2+) | Evolution
--- | --- | ---
idea, vision, constitution | pattern, gotcha, decision | acceptance -> test_scaffold
requirement, constraint | regression, integration | constraint -> gotcha
stakeholder, acceptance | test_scaffold, coverage_rule | constitution -> decision

# Beads & Advisory Mode

### Beads - the coordination ledger

A git-backed work tracker that keeps agents from stepping on each other.

Field | Values
--- | ---
type | bug, feature, task, advisory
status | open, in_progress, blocked, done, closed
priority | 0 (critical) to 4 (minor)
actor | scanner, quality, architect, ...
metadata | pr_ref, test_status, contributor_engaged

Agents claim beads before work. Skip what peers claimed. Dashboard shows real-time progress.

## Advisory Mode (L1-L3)

- All findings go to beads, not GitHub - proxy blocks writes
- Governor posts a single Advisory Digest Issue consolidating all agent findings
- Operators review and decide what to act on - system proposes, humans dispose

# Relay, Snapshots & Leaderboard

### Relay - contributors donate compute to hives they care about

1. Browse hives
2. Authenticate with GitHub
3. WebSocket relay connects CLI to hive
4. Hive assigns tasks
5. Report back, get next

Credentials never leave your machine. Relay is scoped to the contributor's GitHub permissions for each repo.

Trust tiers (auto-promote): Newcomer -> Contributor (5 tasks) -> Trusted (20 + vouched)

### Dashboard Snapshots

- 15-min intervals, 30-day retention (2,880 data points)
- Governor mode, agent states, token usage, CI health
- Published as self-contained HTML pages

### Cross-Hive Leaderboard

- Hub aggregates contributor metrics across all registered hives
- Tracks tasks completed, trust tier, last active - sorted by contribution
- Contributors build reputation across the entire Hive network

# Hive: Enterprise Scale

Hive supports self-hosted LLM inference on Kubernetes GPU clusters.

- vLLM - high-throughput serving on GPU (or llama.cpp on CPU)
- llm-d - Kubernetes-native inference routing via InferencePool + EPP
- API Proxy - translates Anthropic Messages API to OpenAI Chat Completions
- ACP - agent-to-agent communication protocol

| Docker/Kubernetes | Kubernetes + vLLM + llm-d
--- | --- | ---
Inference | Cloud API | Self-hosted GPU clusters
Scale | 1 hive, ~10 repos | Hundreds of hives, thousands of repos
Cost | Per-token billing | Fixed GPU fleet, amortized
Privacy | Code sent to provider | Code stays on-prem

# Demo Time

hive.kubestellar.io

Andy Anderson - andy@clubanderson.com

arxiv.org/abs/2604.09388 | github.com/kubestellar/hive

1