Skip to content

One agent. One repo. Five steps

The agent does the work. Excellent starts it, observes it, checks it, and tests changes to the setup before anything is promoted.

  1. Step 1

    Run the agent through Excellent

    Excellent starts the agent in an isolated worktree and records the exact agent version, model, instructions, tools, repo state, and task.

    Command: excellent run --agent "your-agent" --task ISSUE-438

  2. Step 2

    Check what happened

    Excellent treats done as a claim, not a result. It freezes the resulting tree and gathers evidence from the repo and tools connected to the task.

    Evidence it gathers

    • Git tree and commit
    • Test runner
    • Type checker
    • Browser test
    • Build
    • CI
    • API
    • Database
    • Deployment

  3. Step 3

    Return what is still wrong

    A returned attempt includes the unmet check, the observed result, the expected result, the supporting evidence, and the next action.

    Result states

    • Verified
    • Returned
    • Needs a decision
    • Not checked

  4. Step 4

    Compare better ways of running the agent

    Once Excellent has enough representative work, it establishes a baseline and tests candidate setups against work the candidate system did not see.

    What a candidate can change

    • Instructions
    • Model selection
    • Tool descriptions
    • Context selection
    • Planning
    • Check timing
    • Retry behavior
    • Stopping rules

  5. Step 5

    Promote only what holds up

    A candidate moves through historical comparison, held-out tasks, shadow, canary, promotion, and ongoing observation. A higher average score is not enough.

    The promotion path, in order

    • Historical comparison
    • Held-out tasks
    • Shadow
    • Canary
    • Promotion
    • Ongoing observation

The agent does not grade itself

The producing agent's words are useful context. They are not independent proof.

The strongest checks come from systems that can directly observe the requested result: the repo, test runner, browser, CI, API, database, or deployment.

How we talk about this

Held-out
Work a candidate setup never saw while it was being tuned, so its score can't be memorized. Read the definition.
Candidate
An alternate agent setup — prompt, model, tools, or rules — compared against the current one. Read the definition.
Promotion
Making a candidate the new default, only after it holds up on evidence it didn't see. Read the definition.
Verified / Returned / Needs a decision / Not checked
The four result states every check lands in — see the full definitions. Read the definition.

Run the first task

Copy the install command, run it in a repository you already use, and hand your agent its first task. The quickstart walks through it.

Read the quickstart