How it works

Every run starts at triage. From there, either a short quick-fix path or the full phase sequence runs.

Phases

Triage: Classifies the task as a quick-fix or complex work needing the full pipeline.
Quick-fix: A single agent edits the current working tree directly; no markdown artifacts, no worktree.
Research: Reads the codebase and writes research.md.
Plan: Turns research into a concrete checklist, writes task.md.
Worktree: Creates a sibling git worktree and an orch/<slug> branch.
Test loop: test-writer ⇄ test-critic iterate until tests/acceptance criteria are frozen.
Code loop: code-writer ⇄ test-runner iterate until the runner passes.
Commit: Commits the passing state on the run's branch inside the worktree.

Verification loops

test-writer ⇄ test-critic   →  tests frozen
code-writer ⇄ test-runner   →  commit on pass

Both loops iterate up to --max-rounds (default 5). If a loop exhausts its rounds, orch exits non-zero and leaves the worktree and status.md in place so you can inspect what was tried.

Artifacts and worktrees

<invocation-cwd>/.orch/<slug>/
  research.md
  task.md
  status.md
  run.json                            # written for every run
  orch.log                            # --detach only

<parent-of-repo>/<repo-name>-<slug>   # worktree
orch/<slug>                           # branch

The worktree is never auto-deleted. Default quick-fix, --quick, and --ask still get a job record (run.json) but no research/task/status markdown, no worktree, and no commits. orch.log is --detach only.

Next → Execution modes