Skip to content
Sign in

ghola

A starter kit for agentic systems on iii: a spec goes in, a pull request comes out, nothing merges itself. The stage-graph factory, the constraint ladder and the append-only audit log, wired as registry workers, with the operator profile and skills to run them.

Install0.1.0

# With the iii engine running

iii trigger directory::download-kit kit=tacoda/ghola@0.1.0
0Installs
0Last 7 days
0Today
30 days

Exact versions are immutable. Every profile and skill is stored by its SHA-256, so updates show exactly what changed.

README.md

ghola

You clone it. You teach it. It remembers.

A starter kit for agentic systems on iii. Clone it, point it at a repository. A spec goes in, a pull request comes out, nothing merges itself.

iii is the framework and the ecosystem doing the real work here: the turn loop, the tools, worktrees, the forge client, the approval gate, durable queues, the console. Read it on its own terms first, because everything below is that, wired up.

There are two ways to build on it. You can add each worker when you need it, which keeps you holding only the parts you understand, and for a distributed system that is often the right call. Or you clone a kit that has already made those choices. This is the second one, and what it gets you is a harness and a factory already wired together:

  • The harness constrains one turn. Six phases, each with its own model, thinking level, turn cap and tool grant. Four callbacks around the turn. The prompts it is actually asked. The ladder deciding what a rule refuses, in the rule's own words.
  • The factory runs many turns to a diff. A stage graph where every transition is a durable queue message, so a crash resumes rather than restarts. A worktree per job with a claim that stops two racing. A delivery gate over the finished diff, then a pull request nothing can merge for you.

A harness with no factory is a well-behaved agent you cannot get work through. 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.

It works before you configure anything. A fresh clone runs the whole lifecycle on built-in defaults with an empty settings/. Changing it is a key in a YAML file, or a Python file dropped into a named directory and found by its filename, with no registration step and no import to add. make config 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.

The rest of what a kit is for is management. The workers would run without any of it. make is one operator surface over all of them: doctor for what is missing, config for what is set and where it came from, pipeline for the stage graph before you pay for one, status for what is up, audit for whether the record still verifies, improve for what went wrong and what would have helped.

ghola composes twenty-six iii workers, five engine-owned ones and its own four, declared in a single worker-compose.yaml, and adds the conventions that wire them together. If a worker does it, ghola does not, which is why there is so little of ghola to read.

Two of those workers are ghola's own and ship inside this repository: the constraint and capability ladder at workers/ghola-ladder, and the append-only record at workers/ghola-audit. One clone is the whole thing.

Both are also general enough to be worth having on their own, so each has an upstream that is where it becomes a worker other projects install: ladder and audit-log. 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.

Status: M8. The whole lifecycle runs. A spec becomes a plan, a diff, a proof, a review, a commit through your repository's own hook, and a pull request. Comment on it and the job reworks. 675 tests, and the phased plan is in PLAN.md.

Start here: docs/ADOPTING.md gets a pull request out of a repository today. docs/LIMITATIONS.md says what this does badly and what it refuses to do. Read that one first. It costs less.

Usage

1. clone the repo          git clone … && cd ghola && 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

Step 2 is optional. ghola runs on built-in defaults with an empty settings/, which is what make config is for: it prints every effective setting tagged with where it came from, so a default is never a magic number. examples/ holds two worked configurations at opposite ends of the range.

Step 3 needs a repository named in repos.local.toml. The shortest version needs no GitHub account at all:

[repos."/Users/you/code/scratch"]
forge = "local"     # no account, no token. The request is a file in the repo
base  = "main"

Once you have cloned this, it is yours. No upgrade path, and a starter kit works that way on purpose rather than because I ran out of time.

Running it

make setup      # checks your tools, makes the venv, writes .env. Run this first
make up         # engine, its workers, the ladder and ghola's callbacks
make status     # what is up
make down       # all of it, and wait for the ports to free

make submit SPEC=specs/x.md REPO=../some-repo SLUG=owner/name
make idea IDEA="a rough sentence" REPO=../some-repo   # refined into a spec first
make jobs       # every job, newest first
make turn PHASE=plan PROMPT="why is the queue slow?" WORKSPACE=../some-repo
make config     # the effective settings, and where each value came from
make models     # what the router can actually reach
make test       # 675 tests, seconds, no engine, no money
make help       # everything else

make help: the targets grouped as getting started, running it, doing work,
improving it and checking it, with a dollar sign marking every target that sends
a paid turn

make is the whole operator surface, and the $ column is there because a target that spends money should say so before you run it. While a job is up, the picture worth having open is the console:

The iii console, chat on the left and a live trace panel on the right, listing
one traced session per phase for each job

make setup writes .env for you; put your ANTHROPIC_API_KEY in it before make up. The provider workers read their credentials from the engine's environment, so an engine started without them serves a router with no models and every turn fails at router::provider::resolve with nothing saying why.

make doctor checks your tools, the harness pin, your key and your gh login, which is where the answer to "why did that fail" usually is.

Ports are 3131 (http), 3133 (console), 3132 (stream) and 49154 (worker manager), off iii's stock numbers so a ghola engine runs beside another project's.

What ghola does not write

The rule is that if a worker does it, ghola does not.

Worker What ghola therefore does not write
harness the turn loop, transcript, retry, sub-agents, token budget
shell every tool. It owns coder::* too: read, search, tree, edit, exec
worktree worktree lifecycle, the claim that stops two jobs racing, land
github the forge: typed pr, issue, run, with read-vs-mutate gating
approval-gate the human-in-the-loop hold, and its pending inbox
eval A/B evaluation, its durable reports, and its console page
directory the charter surfaces: skills, prompts, system prompts
state, queue, cron, http, console the store, durable topics, scheduling, the surfaces

ghola registers no tools a turn can call. What is left is the stage graph and the briefs: which base ref, what happens in what order, when to land, and what the pull request says.

The two workers it does write are the exception that proves the rule. The ladder registers seven functions and the record registers six, and not one of them is in any phase's grant: they serve the factory, the policy callbacks and you, never a model mid-turn. So a phase's tools still all belong to a stock iii worker.

ghola's own worker Serves Upstream
workers/ghola-ladder ladder::list, evaluate, explain, move, add, gate, refused tacoda/ladder
workers/ghola-audit audit::append, read, verify, summary, tally, recorded tacoda/audit-log

Each ships here so one clone is the whole thing, and each stays swappable for its upstream because the seam is the function id: make up LADDER=../ladder changes the provider and no call site.

A forge is whoever hosts your code and receives the pull request. Which one you use is a setting rather than a fork. github and local ship, and a third is a file in forges/. local is no forge at all, and the shortest path to seeing this work.

The idea

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

0  prose        stated in the rules, and nothing enforces it
1  tool grant   the phase was never handed the tool
2  hook         the repository's own hook refuses
3  in-turn      a callback refuses the call before the target runs
4  stage gate   the delivery gate, over the finished diff
5  CI           out of reach of both the agent and the factory

Each rung puts the rule further out of reach of what it constrains. It is served by the ladder worker in workers/ghola-ladder, which also carries capabilities on a second ladder joined to this one at the grant, and the whole promote/demote/add/remove lifecycle.

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

Everything a team would want to change is configuration:

What differs between teams Where
the flow of work in the factory settings/pipeline.yaml
the development process in the harness settings/phases.yaml, prompts/
how much a person watches settings/oversight.yaml
project specifics the target repo's own AGENTS.md and .agents/

Oversight is 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.

level a person answers refuses without asking
manual every call nothing
attended every write reads run
supervised only what a rule marks ask the ladder, deterministically
dark nothing the ladder, and ask degrades to refuse

ask never becomes allow at any level. An unattended factory reading "ask" as "yes" has answered a question nobody put. Default is supervised, and a stage may override it because run and review want different answers.

Extension is two mechanisms: drop a Python file in actions/, guards/ or predicates/ and it is found by filename, or name any function id on the bus and write it in whatever language you like.

It reads its own record

make improve REPO=../some-repo   # what went wrong, and what would have helped
make proposals                   # what it staged
make accept RUN=abc123 N=0       # one proposal becomes a spec in specs/

The evidence is the audit log and the job records, not anyone's memory of the week: a refusal, a revision, a question the spec did not answer, a check that objected. Every proposal names the jobs it came from, and one that cannot be traced to evidence is dropped rather than repaired. A clean record produces no proposals, because a lane that always finds three things is a lane nobody believes by the third time.

Nothing is applied. Accepting writes a spec into specs/, and that spec goes through the same pipeline and the same pull request as any other work. The one exception is a move on the ladder — a promotion, a demotion or a carry — which is a rung in a file, handed to ladder::move. The ladder commits nothing either. Nothing that takes enforcement away is applied this way. Otherwise the lane that proposes changes to the charter would be the single thing here escaping the gate everything else goes through.

Documentation

Page Read it when
docs/ADOPTING.md you want a pull request out of a repository today
docs/GUIDE.md you want the walkthrough, part by part
docs/LADDER.md you are deciding where a rule belongs
docs/CUSTOMIZING.md you want to change something and need to know where it lives
docs/EVALS.md you are about to edit a prompt
docs/LIMITATIONS.md before any of it
ROADMAP.md you want to know which of those gaps is being worked on

Requirements

iii 0.23.0, Python 3.11+, git, and an authenticated gh. worker-compose.yaml pins harness at 1.8.7, and that pin is load-bearing: on 1.8.7 a pre-trigger hook's deny is honored, and on 1.8.1 it was ignored and the call ran anyway. A ladder mounted on 1.8.1 looks wired and enforces nothing.

License

MIT. See LICENSE.

Search the registry

Find workers, kits and executables, or jump to a page.