Hydra Orchestrator

What this is

Hydra Orchestrator is a local-first system for orchestrating tasks and managing workflows, currently in public alpha. At its core it is a file-based task queue (tasks/todo/ → tasks/doing/ → tasks/done//tasks/blocked/) that schedules, dispatches, and validates discrete units of work ("tasks") across local workers — AI agents and scripts — with no mandatory network dependency for local work. Tasks are schema-validated contracts, not free-form prompts: each one declares its own scope, dependencies, and permission range before a worker is allowed to act on it.

Why it exists

Hydra follows a classic, old-school local Unix-style architecture on purpose: a file-based queue, shell/Perl automation, standard CLI tools (git, bash, jq, curl, …), explicit process boundaries, plain-text logs, and Git as durable history — not a daemon/service architecture, not a database-backed queue, and not a framework layer. The problem it solves is running AI-driven and scripted work as auditable, boundary-respecting units instead of ambient agent trust: every task states exactly what it may touch before it runs, every change is committed, and the runtime that executes work is kept separate from the source checkout that defines it.

What works today

See Public Alpha Status for the full, sourced breakdown of what is stable, what may still change incompatibly, and which unusual alpha rules are intentional rather than defects. Substantiated by current code, not just prose:

• Local-first task orchestration — the file-based queue itself.
• Source/runtime separation — enforced by lib/Hydra/Layout.pm and bin/hydra-layout.
• Protected process-queue state — only tasks/doing/ is executable; workers do not silently move task files.
• Explicit task contracts — docs/TICKET_SCHEMA.md plus scripts/validate_task.sh enforce task shape.
• Explicit dependency scheduling — Depends-On: is parsed and enforced by scripts/lib/task_selection_precheck.sh.
• Worker/model routing — Required-Worker, Capability, and Delegation-Objective drive routing against live registry health. Worker adapters map observed quota, capacity, and health into one abstract vocabulary; the Worker Resource Telemetry Contract is the source of truth.
• Audit trails — Git history for both the source repo and the local process/ pipeline state.
• Head runner pull protocol — a working poll/filter/claim/copy implementation (scripts/head-pull.sh and related scripts); whether a specific remote Head is online is runtime state, checked live, not assumed from the docs.

Not everything is finished. Worker-registry economic/trust fields, full VZTEC provider-capsule enforcement, the project-owned process-repository lease/certificate model, and complete command-level permission sandboxing are all partial or may change incompatibly — see Public Alpha Status before relying on them.

What's unusual here — read before you touch anything

These are intentional engineering constraints of running Hydra today, not missing features. Understanding them is necessary to use Hydra safely:

• Capabilities and filesystem boundaries govern access. Hydra does not have developer, production, worker-only, or mobile installation editions. Repository registration, task permissions, resolved paths, credentials, and operating-system permissions determine what a concrete installation can do. The retired scripts/hydra-node-role.sh command only reports legacy configuration as ignored.
• HYDRA_HOME is runtime state, not a source workbench. It contains the live operational installation — active queues, reports, and dispatch state. Projects may be checked out anywhere and are registered explicitly. Hydra self-update is a separate runtime transaction sourced from the configured published Hydra repository; it does not depend on a project checkout. See Hydra Layout and Runtime vs. Version.
• The process queue is protected state, not a suggestion. process/ (tasks/todo/, tasks/doing/, tasks/done/, tasks/blocked/) is lifecycle state. The queue path is the sole current lifecycle truth. The central transition helper moves the file and appends an audit-only Lifecycle-Event: in the same operation. Legacy Status: lines are removed from lifecycle task manifests; Status: remains valid for inbox/report records whose own workflow defines it. Historical files are repaired through the registry, not interpreted by choosing between two current states.
• Tasks are explicit contracts. Every task file must conform to docs/TICKET_SCHEMA.md and pass scripts/validate_task.sh, including a stated permission range — the specific paths and commands a worker may use. Unscoped or ambient access is rejected, not assumed.
• Dependency scheduling is enforced, not advisory. A task's Depends-On: list is checked before selection; the scheduler will not pick a task whose dependency is missing, waiting, or blocked.
• Permission ranges are per-task. A worker's read/write/command grants come from the task it is currently executing, not from a standing role — this README was itself written under one such grant.
• Output-Repo: is an apply target, never a review target. A task names where its changes land; a separate Review-Target-Repo:, when present, is inspection-only. The two are not interchangeable.
• Worker/model routing is manifest- and registry-driven, not a fixed assignment — the same task can route to a different worker or model depending on live worker health and capability.
• Feature-state labels are load-bearing. Docs in this repository mark claims Current, Planned/partial, Historical, or Unsubstantiated (see Terminology). Treat an unlabeled or differently-labeled claim you run into as a documentation bug to report, not as license to assume more is implemented than is stated.

TDD Law for Hydra work

Hydra changes and Hydra-managed project tasks are TDD- or verification-gated by default. Before mutating anything, read the relevant documentation and contracts first. Code, scripts, configuration, schemas, and behavior changes require RED evidence, the smallest useful change, GREEN verification, and final verification; documentation and architecture work uses source-grounded claim checks and minimal diffs.

An exception is allowed only when the Hydra operator or the named project owner explicitly authorizes it. The task must record the attributable authority, reason, exact scope, and expiry before planned mutation; an exception removes only the named obligation and does not remove remaining verification. Project-ID: does not select a weaker standard: Parlay, base-relay, and other Hydra-managed project tasks inherit this law.

This general TDD Law is separate from the planned Autonomous TDD Worker mode. That mode is not yet implemented and remains blocked; its owner label or task fields must not be read as activating an available worker. See the TDD Law.

How Merlin fits

Merlin (lib/Hydra/Merlin.pm, bin/hydra-merlin) is a Hydra component, not a separate product or an independent agent. It depends on Hydra's own layout and process state, and it enforces the rule that the Hydra runtime is never a workbench: fixes happen in the registered project, are committed and published, and the runtime is updated only through its controlled path. Phase 1 is read-only diagnostics — it reads queue, incident, pause, lock, watchdog, and worker-history evidence and emits a local health snapshot. Phase 2 apply/healing (for example, requeuing an explicitly stale blocked task) is dry-run by default; even with --apply, it is gated behind operator.pause, the absence of an active doing task, no scheduler/runner lock, a clean process repo, and passing task validation. The narrow scheduler-owned exception is a matching TARGET_REPO_DIRTY_BEFORE_WORKER incident where the blocked task's latest report names a target checkout that is now clean; Merlin may then clear that one incident marker and requeue that exact task under the scheduler lease. It does not bypass or replace scheduler ownership of task selection.

How Parlay fits

Parlay is a separate, incomplete/experimental pilot and is not required to operate Hydra — see the Public Alpha Status Parlay section. It is the pilot/motivating example for project-owned process repositories (task dependency resolution across Heads): that architecture is decided, but the full resolver/lease/certificate model it exercises is not complete. Parlay's own strategy docs separately describe a longer-term human deliberation/interface role built on Hydra's Head Conversation Room Protocol; that protocol is an unimplemented design (no code backs it yet), not current Hydra behavior. For current operator interaction, use the Operator Guide and First Useful Run.

Where a new tester should start

1. Public Alpha Status — the sourced maturity statement referenced throughout this page.
2. Getting Started for External Alpha Testers — the primary step-by-step path for a technical tester with repository access: install checks, the source/runtime split, capabilities, turning an idea into a validated task, running one task, inspecting the result, and stopping safely.
3. Install — the Quick Install section below, or the full Install Guide / DIY Install Guide, for install-only detail beyond what step 2 covers.
4. First Useful Run — the first meaningful task loop for an operator initializing their own local instance, as opposed to a tester using an existing shared runtime.
5. Operator Guide — day-to-day operator interaction with the task queue.
6. Terminology — look up any term used above or in other docs.
7. docs/DOCS_INDEX.md — the full documentation map, including Concepts, Operations, Security, Examples, and advanced/internal Reference material once you are past first contact.

Quick Install

Bootstrap one-liner, for the fast private-alpha path. This requires git access to git.rpdo.net:

HYDRA_REPO_URL='ssh://git@git.rpdo.net/rpdo-net/hydra-orchestrator.git' sh -c 'tmp=$(mktemp -d) && git clone --depth 1 "$HYDRA_REPO_URL" "$tmp/hydra-bootstrap" && sh "$tmp/hydra-bootstrap/bootstrap/install.sh" --skip-pull --yes'

Preferred if you want to inspect before running:

HYDRA_REPO_URL='ssh://git@git.rpdo.net/rpdo-net/hydra-orchestrator.git'
tmp=$(mktemp -d)
git clone --depth 1 "$HYDRA_REPO_URL" "$tmp/hydra-bootstrap"
cat "$tmp/hydra-bootstrap/bootstrap/install.sh"
sh "$tmp/hydra-bootstrap/bootstrap/install.sh" --skip-pull --yes

The bootstrap installer clones a disposable published candidate under the system temporary directory, delegates to its install.sh, and removes that candidate afterward. It does not create a persistent Hydra source tree. Set HYDRA_HOME to choose another runtime state path.

For a new local alpha test installation:

git clone https://git.rpdo.net/rpdo-net/hydra-orchestrator.git
cd hydra-orchestrator
bash install.sh --skip-pull --yes
bin/hydra-ticket doctor
bash scripts/autopilot_status.sh --short

install.sh creates the protected local runtime skeleton (tasks/, process/, recovery/) if it is missing and then attempts local worker setup. If no local AI backend is available yet, the core install can still complete with warnings.

For the first meaningful task loop, follow First Useful Run. For the full installer walkthrough, see Install Guide and DIY Install Guide.

Documentation

• Install Guide
• Public Alpha Status
• First Useful Run
• Operator Guide
• Public Alpha Readiness
• Worker Onboarding
• Terminology
• docs/DOCS_INDEX.md — full documentation map
• CONTRIBUTING_ALPHA.md
• SYSTEM_AS_IS — historical/obsolete: this document describes Hydra as "a distributed computing platform designed for scalability and reliability," which contradicts the current local-first alpha positioning above and in Public Alpha Readiness. Do not use it as a current architecture reference; see the DOC-01 source-of-truth audit and the DOC-03 truthfulness audit.

Contributing

To contribute, please read the CONTRIBUTING_ALPHA.md guide.