Ratchet — one-pager
What it is
Self-hosted AI build-and-verify control plane. Human types a goal → system queues missions → AI builder pushes code → deploy gate waits for live version signal → AI tester grades the live site → repeat until a streak of passes. Name = contract: only moves forward.
Happy path
Stack (roles)
| Piece | Place | Job |
|---|---|---|
| Composer | control plane UI | Goals, queue, product shells |
| Ratchet loop | harness | Build → gate → live test |
| Vault | credentials boundary | Secrets + brokered access |
| Products | product shells | Repo + live URL + version signal |
| Overnight helpers | optional | Observe only; no product features |
Non-negotiables
- Live is truth — tester hits the live URL, not the local tree
- Version signal — product must return the deployed git SHA for the deploy gate
- Proof of work — loop checks git; ignore agent claims
- Streak — usually several consecutive passes
- No secrets in builder env — credentials boundary only
- Team git author — unknown bot authors may be blocked by hosts
- Multi-step goals → several focused queue items; bind cloud project identities
- Credentials stay brokered — builder and tester never hold cloud tokens
Loop outcomes
| Outcome | Meaning |
|---|---|
| Success | Required streak |
| Max iterations | Attempts exhausted |
| Deploy timeout | Version never caught up |
| Tester contract | Bad structured result |
| Builder proof-of-work | No real git progress |
| Budget | Spend limit exceeded |
Mental model
Composer = factory office · Ratchet = factory floor · Vault = key cabinet · Product version signal = time clock.
Rebuild in one breath
Model CLIs → control plane + harness + product shells → credentials boundary → mock loop → product with version signal → tiny real mission → docs pack for friends/AIs.
Share / go deeper
| Need | Open |
|---|---|
| Full guide | README.md |
| All diagrams | diagrams.md |
| Agent prompts | ai-prompts.md |
| Footguns | footguns.md |
| Guide history | CHANGELOG.md |