Skip to main content

The director–builder loop

The core RAPID engineering playbook — how a human directs an agent through Build. "From typing to directing" made concrete.

The loop​

  1. Decompose the design into agent-sized tasks — each small enough to review honestly and to fit a short-lived branch.
  2. Write the task brief — intent, constraints, the acceptance criteria in scope, the files in scope, and the Definition of Done embedded. A good brief is the difference between direction and hope.
  3. Direct → build → review → correct or accept:
    • The agent builds.
    • You review at checkpoints — intent-match, domain correctness, test honesty (see Code review).
    • You correct with a sharper prompt, or accept.
  4. Merge through the merge gate — a human always merges.

Intervention rules​

  • Re-prompt when the agent misunderstood — sharpen the brief, don't hand-fix.
  • Take over when the task turns out to need human judgement the brief can't carry.
  • Stop and rethink the task after three failed corrections — three strikes means the task is wrong (too big, ambiguous, or ill-posed), not that you should prompt harder.

Patterns​

  • Parallel agents on independent tasks — but isolate them (separate worktrees) so they don't collide.
  • Session hygiene — agents read gotchas and the runbook at session start (Repo context & memory); a new session starts clean rather than dragging stale context.
  • Prepare-then-authorise — an agent may fully prepare an irreversible action; only the irreversible step waits for you.

What stays with the human​

Direction, taste, trade-offs, and authorising the irreversible. Everything reversible is the agent's to execute. Judgement moves up; typing moves to the agent.