Overview

Elevator pitch

Ratchet is a control plane for AI software work that refuses to declare victory until the live site agrees.

flowchart TD
  H["Human: change homepage CTA…"] --> B[Composer · goal capture]
  B --> Q[Mission queue<br/>multi-step if needed]
  Q --> R[Build-and-verify loop]
  R --> BL[Build: coding agent · commit + push]
  BL --> DG[Deploy gate · wait for live version]
  DG --> T[Test: live app only]
  T -->|FAIL · feedback to next build| BL
  T -->|PASS| ST{Streak ≥ N?}
  ST -->|no| BL
  ST -->|yes| OK[Done]

ASCII (terminals without Mermaid):

Human goal → Composer → Queue → Build → Deploy gate → Test
                              ↑              │
                              └──── FAIL ────┘
                                    PASS streak → done

The name is the contract: like a mechanical ratchet, the loop only moves forward. Open issues stay visible until fixed. The run ends only after N consecutive clean passes against the deployed app.

More diagrams: diagrams.md · Printable: one-pager-print

Component cheat sheet

Component	Role
Composer	Human-facing surface: capture goals, manage product shells, queue missions
Ratchet loop	Orchestration: builder → deploy gate → live tester → streak
Credentials boundary	Secrets stay brokered; agents never hold cloud tokens
Product shells	One product = one repo + one live URL + one version signal
Optional helpers	Observe and report only — never implement product features

What “done” means

Layer	Done when
Single mission	A streak of consecutive live passes
Deploy gate	Live version signal matches what the builder just pushed
Builder step	Real git work is proven — not agent claims alone
Product campaign	Each focused step succeeded (or was intentionally dropped)

What this system is not

Not a general chat UI for product end users
Not a drop-in replacement for CI (it pairs with whatever deploys from git)
Not “overnight helpers ship features” — builders change product code
Not a place to put secrets in agent prompts
Not a host operations runbook (see operations.md for pack scope)

Suggested first hour (reading)

Skim principles.md
Read loop-and-missions.md until the live-version contract is clear
Skim footguns.md for the common design mistakes
Only then decide how your install would realize the same product ideas

Continue → Architecture