Whilly Orchestrator

Control plane for safe, observable AI-assisted engineering workflows.

Getting Started View on GitHub

What Whilly Does

Whilly turns structured engineering work into a deterministic, auditable task execution pipeline. It accepts tasks from JSON plans, GitHub Issues, GitHub Projects, Jira, and PRD/Forge intake, normalizes them into one task model, and stores execution state in Postgres.

The orchestrator owns task selection and state transitions. Agents receive a prepared prompt through a runner or handoff backend; they do not pick arbitrary tasks or take over the whole project plan.

Whilly tracks dependencies, priorities, budgets, decision gates, worker claims, events, errors, health, metrics, and human review points. It is built for issue-driven coding work: bug fixes, features, refactoring, test generation, and documentation updates.

Boundaries

Whilly orchestrates agents; it does not guarantee that every agent output is correct. The value is controlled acceleration: limiting the work scope, validating inputs, managing the queue, recording state, making execution observable, and keeping humans in control at critical points.

The current core should not be described as full autonomous multi-repo execution, automatic PR-review feedback handling, mandatory CI/lint verification unless verification commands are configured, full sandbox or VM isolation, autonomous rollback/recovery, automatic merge, or autonomous production release.

Current scope wording: operator-triggered rollback; explicit configured CI polling; bounded repair attempts; deterministic governance risk policy.

Semantic memory is explicitly deferred from current scope; deterministic events, task history, PR evidence, and verification logs remain authoritative.

No continuous polling, auto-merge, production recovery, or unbounded repair is claimed.

One-liner demo 

pipx install whilly-orchestrator
whilly --config path            # where to drop your config
whilly --from-issue you/repo/42 --go

That fetches issue 42, generates a one-task plan, imports it into the orchestration flow, runs a worker, and exits 0 only when the runner reports a successful completion.

Page When to read
Getting Started First time here — eight practical walkthroughs
Agent Local Setup Hand this runbook to an agent for quick-setup and local Docker startup
OpenCode Developer Guide Run workers with OpenCode and set WHILLY_MODEL
Full Usage Reference Every CLI flag, env var, and config field
GitHub Integration Guide Setting up Projects v2 + board sync
Current vs Target Alignment status against the target documentation pack
Interfaces & Tasks Module contracts + the JSON plan schema
Architecture Decisions Why things are the way they are (if published)

Under the hood 

Sources ──▶ Plan/task model ──▶ Postgres queue ──▶ Worker claim ──▶ Runner/backend
                         │              │                 │
                         ▼              ▼                 ▼
                 Decision gates    Audit events      Human review
                         │              │                 │
                         └──── Dashboard / SSE / metrics / health

Full module map lives in Whilly-Interfaces-and-Tasks.

Current status

  • Focused pytest suites, Ruff formatting/linting, and import-boundary checks.
  • Layered config — whilly.toml + OS keyring, migrates from legacy .env with one command.
  • Profile-native verification commands feed runtime verification, with operator-triggered rollback, explicit configured CI polling, bounded repair attempts, and deterministic governance risk policy represented as scoped current capabilities.
  • Target documentation imported under docs/target/ with current-vs-target status tracked separately.
  • Latest release · Open issues · Changelog