Design Principles

Agent as a Feature

OpenHive treats every AI agent as a first-class product feature, not a backend implementation detail. Every user message flows directly to an AI agent. The agent decides the response -- whether that's an immediate answer, a clarification question, an acknowledgment before starting work, or a delegation to a specialized team. Tools provide capabilities the agent CAN use, but the agent drives all decisions.

This principle shapes every design choice:

Principle	Implication
Messages go to AI first	No hardcoded routing, static responses, or middleware logic between user and agent
Agent decides the response shape	Acks, clarifications, and errors are all AI-generated
Tools are capabilities, not controllers	Organization tools (org, triggers, browser, credentials) extend what agents can do, they don't dictate behavior
Progressive interaction	Agents stream their thinking -- first text as ack, tool progress as updates, final text as result

Rules-First, Code-Second

Behavior lives in markdown rule files, not TypeScript. Code handles only what rules cannot: channel I/O, invariant enforcement, session lifecycle, and hook execution.

Uniform Recursive Design

Every child team node has the same structural skeleton: config.yaml, skills/, subagents/, org-rules/, team-rules/. Memory is stored in SQLite. A team can spawn children that are structurally identical to itself.

Within each team, the orchestrator delegates all tasks to subagents (ADR-40). Subagents follow skills, which orchestrate plugin tools. This hierarchy — orchestrator → subagents → skills → plugins — repeats at every level.

Main agent exception: The main agent is structurally a team node but functionally a router. It has no subagents, no skills, no learning or reflection triggers. It routes user requests to child teams and delegates. See Subagents#Main Agent Exception.

Cooperative Isolation

Teams operate within workspace boundaries enforced by hooks. Cross-team communication traverses the org tree through parent-child channels. No shortcuts unless explicitly defined in rules. The cooperative isolation model extends to inbound message validation — the TrustGate component evaluates sender trust at the perimeter before any LLM processing begins (see Architecture-Decisions#ADR-30).

Disposable Sessions, Durable State

Sessions are ephemeral -- each message spawns a fresh AI SDK streamText() call. State persists through SQLite (org tree, task queue, triggers, memory) and files (skills, rules). A container restart loses nothing.

Self-Evolution with Governance

Agents can modify their own skills, rules, and memory -- but only within governance boundaries. assertInsideBoundary() and assertGovernanceAllowed() (tool-guards.ts) validate every write against allowed paths and patterns.