Guide 02 · Harnesses

Plan, review, implement

Three agent sessions per task, each with one job, in a separate worktree, directed from one control session.

Related exhibit:

05 · One directs, three work

Checked against the source:

Nov 4, 2026

Tools:

Orca 1.4.247 · OMP 18.14.1 · Git

What it is for

A session that writes its own plan and then carries it out has no one to check the plan. Here a task has three steps and each one is a different session: PLAN writes the prompt, REVIEW compares it with the brief, IMPL carries it out. Whoever wrote the prompt does not carry it out.

The control session directs the workers through Orca, but the work runs in the target repo. The repo's rules apply only in a session that runs there: OMP reads AGENTS.md and CLAUDE.md from the working directory and its parent folders.

Not every change needs all three steps. A fix in one place, with no new behavior, no database, migrations, auth or payments, goes to one session with a short brief. In our setup, widening a text field took about 70 minutes through the full process; the follow-up fix with a short brief took about 5.

What you need

• Orca with your repo added. We use 1.4.247.
• An agent CLI that Orca can start in a terminal. We use OMP.
• A remote with origin/main, because Orca creates the task branch from it.
• A folder for briefs outside the target repo.

Other agent CLIs have their own hook and permission systems; we have not tested them.

Steps

1. Check what the worker will see

   Orca creates the branch from origin/main, not from your local main. Unpushed commits and uncommitted changes are not in the worker's copy. Check both before you start.

   git rev-list --left-right --count origin/main...main
   git status --short

2. Write the brief to a file

   The brief says the goal, the acceptance criteria and what is out of scope. Each claim in it is marked verified (with its source), inferred or unverified. It asks the worker to return decisions the brief does not settle as a question, a recommendation and the impact. Keep it in a file and send the agent a one-line pointer to it.

3. PLAN: a worktree with an agent

   Create the worktree with --surface terminal, send the pointer, and check with terminal read that it arrived. Silence after a send is not a reason to send again. The PLAN session writes the prompt and saves it in the worktree, where the repo keeps prompts. It does not change code and does not commit.

   orca worktree create --repo path:/repo --name menu --agent omp --surface terminal --json
   orca terminal send --terminal term-menu --text "Phase PLAN: read briefs/menu.md" --enter --json
   orca terminal read --terminal term-menu --json

4. REVIEW: compare the prompt with the brief

   The control session compares the prompt with the brief, with what the person literally asked for and with the target repo's rules. It returns only problems it can show. Scope added without evidence that it is needed is a problem. Anything the control session added to the brief on its own is an assumption, and a person confirms it before IMPL.

5. IMPL: a new session in the same worktree

   Start a new session in the same worktree and give it the reviewed prompt. It carries out the prompt and commits the prompt together with the implementation. If the prompt does not match the state of the repo, it stops and reports. End the PLAN session once IMPL starts.

   orca terminal create --worktree path:/worktree-menu --command omp --json

6. Track the work, then merge

   orca worktree ps shows the worktrees and the agents running in them. A task is done when the output and git show the result the brief asked for, not when the terminal goes idle. Before the merge, check that the target repo's required checks really ran. The control session merges the verified branch in the target repo's main checkout. End each session before you delete its worktree or branch.

   orca worktree ps --json

How to check it works

1. orca worktree ps --json lists the task's worktree and the agent in it.
2. After PLAN, git log origin/main..HEAD in the worktree prints nothing: the PLAN session did not commit.
3. After IMPL, git show --stat on its commit lists the prompt file next to the implementation.

What to watch out for

• observed Oct 17, 2026

  A double quote cut the brief short

  On Windows, a brief passed with --prompt was cut at the first double quote, and the rest reached the agent word by word as new messages. PLAN wrote a good-looking prompt with a different scope from the cut brief; REVIEW caught it only by comparing the prompt with the brief. That is why the brief lives in a file and the agent gets a one-line pointer.

• observed Oct 8, 2026

  Text in angle brackets disappeared

  Placeholders, tags and HTML comments sent with --prompt were lost together with their content. Another reason to send only a pointer.

• observed Oct 8, 2026

  Idle is not done

  terminal wait --for tui-idle was satisfied in the middle of the work for three of four workers. We check the result in the output and in git instead.

• observed Oct 31, 2026

  A chat handle does not take terminal input

  Without --surface terminal, Orca started the agent the way our settings said, as a chat, and terminal send to its handle returned terminal_handle_stale.

• observed Oct 18, 2026

  The control session broke its own rule

  The rule said the control session does not change another repo and does not write the prompts it runs. It edited a file in the target folder and wrote the implementation prompts itself anyway. A rule held only as text did not hold; separation of roles should be held by permissions.

• observed Oct 8, 2026

  Workers skipped a required check

  Workers left out a check the target repo requires before a commit, each with its own reason. An exception can come only from a person, which is why the control session checks before the merge that the checks ran.

Sources

• AGENTS.md in GhostFactory's knowledge repo (K-B), sections “Control harness” and “Commands”
• K-B sprint notes and project notes, Oct 8 to Nov 1, 2026
• orca --help for each command, Orca 1.4.247

← All guides