orchestrator

Autonomous engineering orchestrator for local LLMs — build agentic workflows on consumer hardware.

Orchestrator is a Go-based agentic loop that reads planning documents, generates atomic tasks, executes them against a local LLM, validates and applies the resulting patches, and commits clean, reviewable git history — all without human supervision.

It is purpose-built for Qwen2.5 / Qwen3 Coder and other open-weight models running on consumer CPUs via Ollama or any OpenAI-compatible endpoint.

• Document-driven task generation — reads GAPS.md, GOALS.md, PLAN.md, and ROADMAP.md to bootstrap a task queue automatically
• DAG-based execution — respects depends_on ordering; tasks run only when their dependencies are satisfied
• Patch safety — validates every diff before application: line-count limits, file-touch limits, and deletion-ratio guards
• Automatic task splitting — oversized or failing tasks are split into smaller atomic subtasks and re-queued
• Build-and-fix loop — runs go build ./... && go test ./... after each patch; retries with compiler output as context until the build passes or retries are exhausted
• Structured JSON logging — every event is appended to orchestrator.log in machine-readable format
• Git branch isolation — each run creates a fresh autonomous/<timestamp> branch; commits are small and traceable
• Adaptive memory — cross-run metrics (retry rates, patch sizes, branch history) are persisted and injected into the planner on the next run
• Static audit mode — standalone code-quality analysis: architecture, API surface, and concurrency passes against any Go package graph
• Self-evolution mode — elevated patch limits for the orchestrator to improve itself (--self-evolve)
• Dry-run mode — simulate a full run without writing files or committing

Recommended models: Qwen2.5-Coder-32B-Instruct or Qwen3-Coder (quantized GGUF via Ollama).

# 1. Pull a local model (example using Ollama)
ollama pull qwen2.5-coder:32b

# 2. Build the orchestrator
go build -o orchestrator .

# 3. Write a planning document in your target repo
echo "# GOALS\n\n- Add error handling to the HTTP client\n- Add unit tests for parser" > GOALS.md

# 4. Run
./orchestrator \
  --endpoint http://localhost:11434/v1/chat/completions \
  --model qwen2.5-coder:32b \
  --max-patch-lines 50 \
  --max-files 3 \
  --max-retries 5

The orchestrator will:

1. Parse GOALS.md (and any other planning docs it finds) into atomic tasks
2. Create a new git branch autonomous/<timestamp>
3. Execute each task in dependency order, applying and committing patches as they pass build validation

The orchestrator scans the working directory for any of the following files at startup and generates tasks from them if tasks.json does not already exist:

Tasks are deduplicated by content hash across documents. Existing tasks.json files are never overwritten — delete or rename the file to re-bootstrap from documents.

Run a standalone static analysis pass on any Go codebase:

./orchestrator --audit --audit-pattern ./... --audit-pass all --audit-output findings.json

Audit passes:

• architecture — dependency cycles, package layering violations, file and function size
• api — exported symbol surface, interface drift, undocumented exports
• concurrency — shared-state access, goroutine safety, mutex usage

Findings are written as structured JSON to --audit-output.

Planning docs
     │
     ▼
ensureTasksFile()   ← generate + deduplicate tasks via LLM
     │
     ▼
nextExecutableTask() ← DAG ordering, deps satisfied check
     │
     ▼
resolveContextFiles() + gatherFileContext()
     │
     ▼
executeTask()       ← LLM returns unified diff
     │
     ▼
validatePatch()     ← line count, file count, deletion ratio
     │
     ▼
applyPatch()        ← `patch -p1`
     │
     ▼
build()             ← `go build ./... && go test ./...`
     │
   pass? ──yes──► gitCommit() → task complete
     │
    no
     │
     ▼
fixTask() loop      ← retry with compiler errors as context
     │
  exhausted? ──► splitTask() → re-queue smaller subtasks

Cross-run state is stored under the memory/ package and persisted to disk. On each run start, a compressed summary of prior metrics is injected into the planner prompt, allowing the orchestrator to:

• Prefer smaller patches in areas with high historical retry rates
• Recognise recently unstable files
• Track cumulative task throughput over many sessions

• Deterministic by default — intelligence lives in the Go scaffolding, not in prompts
• Micro-edits over large refactors — patch caps are enforced at every level
• Strict validation before mutation — no patch reaches disk without passing structural checks
• Retry convergence over reasoning depth — the loop retries with structured error context rather than relying on model chain-of-thought
• Bounded complexity — all advanced behaviour is behind explicit flags and must remain reversible

See LICENSE.