giro

Control never crosses an LLM. Content always does.

Most agent tooling tells a coding agent what to do and hopes it complies. giro inverts that. A deterministic loop owns every decision: it hands your coding agent one slice of a spec, runs your tests and blind reviewers on the result, feeds their findings back, and ends one of two ways: proof on a branch for you to merge, or a question for you. Never a silent "done". A budget enforced by a while loop cannot be talked out of; an instruction can.

Install

You do not type giro's commands. Paste this into your coding agent, in the git repository giro should work on:

Install giro here: run `uv tool install giro`, then `giro install`, then read .claude/skills/giro-setup/SKILL.md and follow it.

giro install places five skills in .claude/skills/ (.agents/skills/ links there for Codex and Cursor). giro-setup finds the commands your tests really run and the agent CLIs you have, asks only what it cannot look up, and writes giro.toml once you confirm. You need Python 3.11+, uv, git, and one supported coding agent logged in. Read running safely first: the worker gets its CLI's permission-bypass flag.

What you ask, in plain words

Grill, spec and plan

These three skills are the documentation phase, and they need no giro at all: copy them into any coding agent's skills folder. They start from Matt Pocock's grill-with-docs, to-spec and to-tickets and keep his judgment: the frontier-round interview, the spec template, tracer-bullet slicing. What changes is where the result lives. Everything is a file in your repository, beside the code it describes, and the loop treats those files as rules a worker cannot rewrite.

They are plain markdown, so adjust them to how you work: giro install keeps an edited copy as yours and replaces it only with --force. The side-by-side, section by section, is in skills/README.

The idea

The agent does the work. Structure it can't argue with decides what counts. A human holds the exits.

A Spec is markdown describing one feature. The engine splits it into Issues (small slices) and for each starts a fresh agent, the worker, to edit files. giro commits the change and runs your gates: command gates (the exit code decides) and judge gates, where a blind LLM, given the Spec, the Issue (with its log from earlier Runs), the diff and a criterion, gives a verdict. A while loop counts budgets; no prompt talks it round.

A Run that completes ends one of two ways. Proof: all gates green, the work waits on branch giro/<spec> for your merge. Or needs-human: budget spent or a worker question. The reason is written into the Issue in .giro/worktrees/<spec>/, where the giro skill reads it to you. After an error, ask again; the Run resumes from the markdown. Runs see only committed code (the Spec is copied as-is): commit what gates need.

What is enforced by code, and what only by instruction

Supported coding agents

giro starts a coding agent through a driver: prompt in, edits in the working tree, one JSON reply out. It ships drivers for Claude Code (claude, the default), Codex (codex), Gemini CLI (gemini) and Antigravity (agy). giro.toml picks one per role, so the worker, the reviewers and the planner can each use a different agent.

Any other agent that runs headless from the command line can be added. A driver is a short class in src/giro/drivers.py: it builds the command line and, if needed, unwraps the reply; register it in DRIVER_REGISTRY and name it in giro.toml. Drivers defined in giro.toml alone, with no code, are specified in open-drivers and not built yet. Cursor and other chat hosts need no driver: they read the same skills.

Reference

In CI, call the command the skills call: giro implement <spec> exits 0 on proof, 2 on needs-human, 1 on error; giro init writes a starter giro.toml with no interview. Every command, the loops, gates, state and drivers: the guide. The contract: design.

Where it is used

giro is built with giro. Four of the Specs under docs/specs/ (detached-runs, github-projection, setup-skill, strip-skill-frontmatter) were run to done by the engine, and each Issue file keeps its attempts and verdicts; the others were not. Two live runs elsewhere (first light, parallel waves) are on toy repos. This repository's public history begins at 0.1.0.

Status and limits

• Pre-alpha 0.1.0, POSIX, MIT. The GitHub projection is experimental.
• The engine bounds iteration, not blast radius: use a container, VM or throwaway clone.
• Judge gates are opinions; put real tests in command gates.

Credits

The grill, spec and plan skills, and the review gate's prompt, adapt Matt Pocock's Skills for Real Engineers (MIT): the interviewing, spec-writing, slicing and review judgment is his; the loop around them is giro's. The notice is in LICENSE.

Part of a set: folio · lab-kit · giro