ghola

iii is the framework and the ecosystem doing the real work here: the turn loop, the tools, worktrees, the forge client, durable queues, the console. You can build on it a piece at a time, adding each worker when you need it, and for a distributed system that is often the right call. ghola is the other route: one clone that has already wired a harness and a factory together, plus the handful of things that make running it easier.

A harness constrains one turn. A factory runs many. You need both, and they are not the same job.

Assembling these yourself on iii is a real option, and nothing below is hidden from you. What a kit saves is the wiring and the order to do it in: which workers, on which ports, in what sequence. Which of them has to be up before the next one writes anything.

A harness with no factory gives you a well-behaved agent and no way to get work through it. A factory with no harness runs unattended and cannot tell you what it was allowed to do. That split is also how the improve lane sorts its proposals.

flowchart TB
    subgraph f["THE FACTORY: many turns, to a diff"]
        direction LR
        s(["a spec"]) --> g["the stage graph
durable between stages"]
        g --> gate["the delivery gate
over the finished diff"]
        gate --> pr(["a pull request"])
    end

    subgraph h["THE HARNESS: one turn, constrained"]
        direction LR
        brief["the brief
and the prompt"] --> grant["the grant
what this phase may call"]
        grant --> cb["four callbacks
around the turn"]
        cb --> lad["the ladder
refuses in the rule's own words"]
    end

    g -. "starts a turn" .-> brief
    lad -. "an outcome" .-> g

    classDef fac fill:#23150C,stroke:#6E2E13,color:#E7C982
    classDef har fill:#1A100A,stroke:#A4470F,color:#E8A33D
    classDef out fill:#3A2112,stroke:#E7C982,color:#E7C982
    class g,gate fac
    class brief,grant,cb,lad har
    class s,pr out
    

iii is the product. ghola is a starter kit for it.

iii ships the turn loop, the tools, git worktrees, the GitHub client, the approval gate, durable queues, and the console. That is where the engineering is, and it is worth reading on its own terms at iii.dev. The rule here is that if a worker does it, ghola does not, which is why there is so little of ghola to read.

Two workers are ghola's own, because nothing else carries these ideas: the constraint and capability ladder, and the append-only record. Both ship inside the repository, so one clone is the whole thing.

Neither registers a tool any phase is granted. They serve the factory, the callbacks and you, never a model mid-turn, so a phase's tools still all belong to a stock iii worker.

Each also lives on its own, at ladder and audit-log, which is where each becomes a worker other projects install. Point LADDER or AUDITLOG at a checkout and it serves instead of the copy, because the seam is the function id rather than an import. A starter kit whose best ideas are locked inside it is a worse starter kit.

It works before you configure anything. Step two is optional, and step three is the one that costs money.

ghola runs on built-in defaults with an empty settings/, so a fresh clone does the whole lifecycle without a decision from you. The shortest honest path points it at a scratch repository with no forge at all, and the first pull request then costs one turn and no GitHub account.

make config is what makes that safe rather than mysterious. It prints every effective value with the source that produced it, so a default is never a magic number you go hunting for in the code.

1. clone the repo          git clone https://github.com/tacoda/ghola.git && make setup
2. add config and scripts  edit settings/, drop files in actions/
3. tell it to do work      make submit SPEC=specs/x.md REPO=../repo

# repos.local.toml, and no account, no token, no slug
[repos."/Users/you/code/scratch"]
forge = "local"
base  = "main"

flowchart LR
    spec(["a spec"]) --> plan --> run --> prove --> review --> commit
    commit -- "your hook refused" --> run
    commit -- "your hook accepted" --> pr(["a pull request"])
    pr --> you(["you"])
    you -- "a comment" --> run
    you -- "a merge" --> landed(["landed"])

    classDef edge fill:#1A100A,stroke:#A4470F,color:#E8A33D
    classDef stage fill:#23150C,stroke:#6E2E13,color:#E7C982
    classDef gate fill:#3A2112,stroke:#E7C982,color:#E7C982
    class spec,pr,landed edge
    class plan,run,prove,review,commit stage
    class you gate
    

make doctor checks your tools, the harness pin, your key, and your gh login. Look there first when a job fails and nothing says why.

Config for a value, a script for a judgment. Take the cheapest one that can say the thing.

Every decision has a home, a built-in default, and a way to override it. Most of what you want is a key in a YAML file. The rest is a Python file dropped into a named directory, found by its filename, with no registration step and no import to add.

# settings/phases.yaml — one key, and the rest of the phase keeps its defaults
phases:
  review:
    thinking_level: high
    max_turns: 30

# predicates/no_secrets.py — no ghola imports, so you can run it directly
def check(path: str, content: str, context: dict) -> list[dict]:
    return [{"line": n, "why": "a credential in source"}
            for n, line in enumerate(content.splitlines(), 1)
            if PATTERN.search(line)]

A name that resolves to nothing is an error rather than a no-op. make pipeline reports it before a job has paid for a worktree and a plan. What does not belong here is your repository's own conventions: those go in its CLAUDE.md, versioned with the code they describe.

A constraint has a rung: the mechanism that carries it.

Writing a rule down is rung zero, and rung zero enforces nothing. Each rung above it puts the same rule further out of reach of what it constrains. The interesting question about a rule is not whether the agent agrees with it, but which mechanism still stops it on a bad day.

Capability climbs the other way

A constraint withholds, and gets stronger as it moves out of the agent's reach. A capability grants, and gets stronger as it reaches further. Both are primitives of the same shape, and both are served by the same worker.

The two ladders join at rung 1, the grant, which is the sum of the capabilities that reached a phase minus everything a constraint took back. ladder::list answers both sides at once, and the ladder worker serves the whole promote, demote, add and remove lifecycle, not ghola.

iii trigger ladder::list
iii trigger ladder::move --json '{"id":"no-secrets","move":"carry","at":"delivery"}'

A dial, not a switch.

"Dark factory" is a useful phrase and a bad setting. Nobody wants a system where no human sees anything, and nobody wants to approve every read either. The level is a dial, and a stage may override it, because run and review want different answers.

An ask never becomes an allow, at any level. An unattended factory reading "ask" as "yes" has answered a question nobody put. The default is supervised.

One terminal and one console. There is no third surface.

This is the part a kit is actually for. The workers underneath would run without any of it. What ghola adds is the management: one place to ask what is configured, what is up, what a job did, and what it cost.

make is that whole operator surface, and every target is four lines of shell you can read. The $ column marks the ones that send a paid turn, because a command that spends money should say so before you run it.

While a job is up, the picture worth having open is the iii console. Each phase is one traced session, named for the job and the phase. The span count beside it is every tool call that phase made.

What ghola does not do.

Every tool's documentation says what it does. I put the limitations page first in the reading order instead. Deciding against this cheaply and early costs you less than finding these out in week two. None of it is a promise to fix, and some of it is on purpose.

• Nothing merges itself. No configuration removes the pull request. The gate is not a setting, so there is nothing here to turn off.
• No upgrade path. Clone it and it is yours. Want a later change? Read the diff and take the parts you want.
• No CLI. make is the whole operator surface. Every target is four lines of shell, and you can read all of them.
• No HTTP surface of its own. The iii console is the interface. A dashboard of ours would be a second thing to maintain and a worse trace view.
• The harness pin is load-bearing. On 1.8.7 the engine honors a pre-trigger hook's deny. On 1.8.1 it ignored that deny and ran the call anyway, so a ladder mounted there looks wired and enforces nothing.