Ergane

A software factory for specification-driven development.

Ergane coordinates coding agents from a written specification through implementation, verification, and merge. It turns user stories into a dependency graph, runs agents in their own worktrees, evaluates what they produce, and manages retries, operator decisions, and landing through a merge queue.

The goal is to make agent execution a repeatable part of software delivery. People shape the intent, context, acceptance criteria, and operating policy; Ergane manages the work and records the evidence needed to understand its results.

Ergane is also a reference implementation of that pattern. It is used to develop Ergane itself, and the repository’s specifications and decision log document how the system has evolved.

Status: beta, under active development. Start with a supervised trial on a dedicated repository. The quality of a result depends on the specification, context, checks, and review behind it.

How it works · Get started · Architecture · CLI reference

What Ergane coordinates

• Specifications into executable work. Parse acceptance criteria, validate the spec and its supporting documents, and derive a graph of stories and dependencies.
• Agent execution. Select a runner and model through a persona, prepare a worktree, and run a bounded attempt with its own execution context.
• Verification and repair. Run declared checks, inspect the output, and use configured LLM review against acceptance scenarios. Feed failures into a bounded retry and escalation policy.
• Controlled landing. Open pull requests for passing work and route them through integration checks and the repository’s merge queue.
• Operational visibility. Inspect attempts, verification records, transcripts, usage, pending decisions, and observed landings.
• Feedback into future work. Track findings and recurring defects, scaffold new specs, and carry reviewed lessons into plans and standards.

How it works

flowchart TD
    S["Specification + context"] --> G["Validated work graph"]
    G --> A["Agent attempt in a worktree"]
    A --> V["Checks + output review + evidence"]
    V -->|Repair within limits| A
    V -->|Pass| M["PR + integration checks + merge"]
    V -->|Needs a decision| H["Operator"]
    H -->|Retry authorized| A
    M --> L["Observed landing + findings"]
    L -->|Refine future work| S

There are four connected loops:

1. Refine: turn an intended outcome into a small, executable assignment with explicit acceptance criteria and the context needed to implement it.
2. Build and repair: dispatch the assignment, evaluate the candidate, and retry or escalate when it cannot progress within its allowance.
3. Integrate: check the change in the context of the branch it will join, then observe the resulting landing.
4. Learn: use findings and operating experience to improve the next spec, evaluator, or implementation.

Refinement and learning include operator work. A person or operator agent must still decide what matters, resolve ambiguity, and review changes to scope or policy.

One execution of a spec is an epic. Its dispatched stories are nodes; each invocation of a coding agent is an attempt. See the glossary for the full vocabulary.

What a passing result means

A passing result is relative to the configured verification loop and the evidence it collected. Deterministic checks, output validation, and LLM review answer different questions. Read the recorded results and unavailable or skipped checks alongside the verdict.

Acceptance, landing, and release are separate events. Ergane tracks the path into the repository; deployment and production acceptance need their own delivery policy.

The pieces underneath

Ergane combines these responsibilities in its current implementation:

The gateway supplies model access, key lifecycle, and attribution for gateway-routed attempts. Those properties depend on the selected route; subscription and direct routes have different credential and accounting behavior. Configure them deliberately through the installation flow.

Runner, forge, and notification interfaces provide extension points. A new backend still needs an adapter that satisfies the relevant contract. The architecture guide describes those boundaries and their tradeoffs.

Get started

Install the CLI

With Python 3.11+ and uv available:

uv tool install ergane-cli
ergane --help

0.6.0 does not include Docker/container support. Canonical notes are in docs/releases/0.6.0.md.

Configure an engine and target repository

The current runtime needs a Linux execution environment, a Temporal engine and worker, a configured agent/model route, and the target repository’s toolchain and verification commands. The GitHub landing path also needs authenticated repository access and a supported merge-queue configuration.

Follow the operator setup guide for prerequisites and the setup sequence. Use the installation reference to configure the control plane and choose an engine deployment. Then follow repository initialization and onboarding to prepare a target. Native worker operation is covered in the worker guide; the container guide is experimental and compatibility context, not a supported runtime for 0.6.0.

Try one prepared specification

Author a small feature with Spec Kit:

specs/001-example/
├── spec.md     # Stories, acceptance scenarios, and work-graph declarations
├── plan.md     # Technical context, approach, and known hazards
└── tasks.md    # Implementation tasks grouped by story

After the engine and repository are configured, run the following from the target repository root, replacing the example path with your prepared spec directory:

ergane spec validate specs/001-example --target-repo "$PWD"
ergane build ship specs/001-example --target-repo "$PWD" --halt-after-pass

build ship validates the spec, derives the graph, and asks for confirmation before dispatch. --halt-after-pass stops passing work before landing. This executes agents and checks and can incur model costs; it is an execution trial, not a dry run. --target-repo must resolve on the worker host.

Inspect the result:

ergane build status 001-example
ergane build attempts 001-example

The build guide covers normal landing, recovery, concurrency, and operator decisions. The on-ramp exercise documents an end-to-end test against a scratch repository, including its prerequisites and effects.

Find your way around

Implementation lives in factory/; tests live in tests/. Changes to Ergane follow the same specification, verification, and landing process the project provides to other repositories.

License

Apache 2.0.