> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twill.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How Twill works

> The architecture: real CLI agents, specialized sub-agents, and self-verification against a running app.

## Built on the agents you already use

Twill orchestrates existing CLI coding agents — Claude Code, Codex, OpenCode — rather than shipping its own harness. That's deliberate: model providers train and tune their models against their own toolchains, so delegating to those CLIs inherits that optimization, and the code they produce follows the same patterns your team writes locally.

## Sub-agents keep context focused

A long task rots when one context window has to hold everything. Twill splits work across specialized sub-agents, each starting fresh with only what its phase needs:

<Steps>
  <Step title="Research & planning (optional)">
    The planning agent explores the repo, asks clarifying questions, and
    produces a plan for approval. See [Plans & questions](/planning).
  </Step>

  <Step title="Implementation">
    The main coding agent implements the change, adapting when the codebase
    doesn't match assumptions.
  </Step>

  <Step title="Environment setup (when needed)">
    If the dev environment is missing or unhealthy, a dedicated agent repairs
    the bootstrap on the long-lived workspace VM — so the fix persists for every
    future task. See [Your dev environment](/environment).
  </Step>

  <Step title="Verification & review">
    Mechanical checks (tests, lint, types, build) plus a focused pass by a
    code-reviewer agent for logic issues and missed requirements. See
    [Verification](/verification).
  </Step>

  <Step title="Commit">
    A commit agent produces clean, reviewable commits and the PR.
  </Step>
</Steps>

## Self-verification against a real environment

What makes the loop work is that tasks run inside a fork of your workspace's dev environment — the whole stack, live. The agent doesn't stop at writing code; it starts your dev server, runs your tests, drives the UI in a browser, calls your API endpoints, and reads service logs until it has observed the change working. The artifacts of that observation are what land on the PR as [proof](/verification#proof-on-the-pr).