Orcho in 5 Minutes for Agent Work

Plain-language start

Run one task. Watch Orcho plan, implement, reject false-ready work, repair it, and prove what is ready to deliver. This page follows that complete journey in plain words — including the moment when an agent says “done” and Orcho refuses to accept unfinished work as ready.

Run quickstartWatch the run

plain words firstcommands nextreference later

one task, start to finishwhat Orcho does

You ask        "Add validation to the login endpoint"

Orcho makes the agent:
1. plan it          before touching code
2. write the code
3. review the work   a second pass looks for problems
4. fix what's wrong   here: a missing test
5. final check        is this really ready to ship?

Result
Not "the agent said done."
"Reviewed, repaired, checked — and here is the proof."

The point: Orcho does not hide the work in one long chat. It turns the task into visible steps you can trust and re-read later.

01A taskIt starts from one clear task, not a loose chat thread.02How carefulA “profile” is just how strict Orcho should be for this task.03The stepsPlan, code, review, fix, final check — in order.04The proofFiles you can open afterward instead of trusting a message.

1. You give a task

It starts with one task — the thing you want done.

Add validation to the login endpoint

In a normal agent session, that task becomes one long chat. You have to remember what was planned, what changed, whether the tests ran, and whether the final “done” is true. Orcho keeps the task inside a run — a single tracked piece of work with a beginning, checks, and an end.

2. Pick how careful to be

Before anything happens, Orcho needs to know how careful to be. That is all a profile is: not a theme, not a setting screen — just the level of strictness for this task.

Tiny fix → lightFixing a typo or a label does not need a plan and a review. A small-task profile just does it.New feature → fullAdding real functionality deserves the whole journey: plan, code, review, repair, final check.Not sure → let Orcho pickDescribe the task and Orcho suggests the right profile for you.

For this story the task is a real feature, so it uses the feature profile — the careful one.

Orcho Run  20260629_1427  profile=feature

That single line means: this work gets planned, written, reviewed, repaired if needed, and checked before it counts as ready. Want the deeper model later? Read Profile semantics.

3. The steps

With feature, Orcho runs the task through a fixed set of steps, in order:

Each step has one job. Planning happens before code. Reviewing is separate from writing, so the work gets a real second look. The final check is its own gate, so “the code compiles” and “this is ready to ship” are not the same thing.

The shorthand you’ll see in the terminal

Orcho shows those same steps compressed into one line. It looks dense at first — here is how to read it:

⟳² (▶ plan [Claude] → · validate_plan [Codex]) → · implement [Claude]
→ ⟳² (· review_changes [Codex] → · repair_changes [Claude])
→ · final_acceptance [Codex]

⟳² this part can repeat (up to a limit)▶ the step running now· a step waiting its turn[Claude] the agent doing the work[Codex] a different agent doing the review

Two different agents on purpose: one writes, another reviews — so the work does not get to grade its own homework. Note that the plan is also written and validated inside a ⟳² loop, just like review and repair. And a loop never pushes through: if it uses up its rounds, the run pauses and hands you the decision. See Watch the run for the full live view.

4. The agent writes the code

The “write code” step is where the AI agent actually edits your project. Orcho does not replace the agent — it still does the real work.

The difference is that the agent is now boxed inside steps:

• the task already has a profile, so the agent knows how careful to be;
• the plan came first, so it is not improvising;
• the review step that comes next knows what to check;
• the proof at the end points to real files, not vibes.

[IMPLEMENT] edited api/auth.py and tests

5. Review catches what “done” hides

This is the moment that matters. Not when the agent says “done” — when a review step decides whether the work is actually ready.

This verdict is from a real run — the one that built Orcho’s own delivery-branch feature. The implementing agent finished with green tests. The reviewer then spent three minutes and 37 tool calls reading the full modules behind the diff, running targeted tests, and rejected anyway — press play, or scroll it into view:

review_changes · a real run · green tests, rejected anyway

▶ Play

implement — done · tests green ✓

review_changes — reading the modules behind the diff, running targeted tests…

0 tool calls 0:00 spent

verdict = REJECTED

Two contract defects — each with a file, a line, and a concrete fix — found in work that already passed its own tests, and repaired before the change shipped. A normal chat ends at a confident "done"; the review is the gate that decides whether the work is actually ready. Driven by the run's review_changes verdict.

Two contract defects, each with a file, a line, and a concrete fix — found in work that already “passed”. Both were repaired before the change shipped. A normal chat would have ended at a confident “done”. Orcho stopped, named the exact problems, sent them back to be fixed, and kept that decision in plain view. That is the whole pitch: it catches the “looks done but isn’t” case that costs you hours.

Want the deeper version of this idea? Read False-ready delivery.

6. The final check

The last step asks one question: is this really ready to ship?

[FINAL_ACCEPTANCE] verdict=APPROVED
  ship_ready  yes

If it says no, you do not get a vague failure. You get the blocker and the next move — fix it, follow up, or pause for your decision. Either way, nothing broken slips through wearing a “done” label.

7. The proof it leaves behind

When the run ends, you are not stuck trusting a chat scrollback. Orcho leaves files behind:

output.log     the full run, as it happened
events.jsonl   the timeline of what happened, in order
plan.md        the plan it agreed to follow
review.json    what the review found
diff.patch     exactly what changed in your code

You — or a teammate, or a tool — can open these later and see what happened, why it was accepted, and what was checked. No need to reconstruct it from memory.

Read Evidence bundle for what the proof contains, or Read the result for the first thing to open after a run.

Where to go next

Run quickstartInstall Orcho, run one task, and watch it happen for real.Let your agent drive itThe lighter way in: let the AI client you already use run Orcho over MCP.Watch a live runLearn to read the terminal stream as it works.Understand profilesThe one idea worth learning early: how strict each run should be.Open the docs mapPick your next layer when you want more depth.