Examples

Copy-paste recipes for common orch workflows. Each includes when to use it, the command, and the expected outcome.

1. Tiny fix (auto quick-fix)

When to use: Small typo or one-line edit — let triage decide.

orch "fix the typo in the README"

Expected: Triage → quick-fix in the current tree; run.json only; no worktree or commit.

When to use: You already know it's a tiny, direct edit.

orch --quick "rename foo to bar in utils.ts"

Expected: Skips triage; same footprint as quick-fix (job record only).

When to use: You want an answer about the codebase, not a change.

orch --ask "where is the CLI entrypoint?"

Expected: Read-only answer printed; no writes to the repo; run.json only.

When to use: Multi-file work that needs tests and an isolated branch.

orch "add a --verbose flag that streams agent output to stderr"

Expected: Research → plan → worktree → test loop → code loop → commit on orch/<slug>.

When to use: You want a specific agent CLI for the same small task.

orch "fix the typo in the README" --agent claude
orch "fix the typo in the README" --agent cursor

Expected: Same task routed through at least two backends (claude / cursor).

When to use: You want thinking/output deltas on stderr while the pipeline runs.

orch "fix the bug described in task.md" --agent cursor -v

Expected: Pipeline runs with -v streaming agent deltas to stderr.

When to use: Confirm the agent CLI is on PATH before a real run.

orch "noop" --dry-run --agent cursor

Expected: PATH check only; writes nothing under .orch/ — no job record.

When to use: Kick off work and keep using your shell.

orch "implement the local spec" --agent claude --detach
orch status <slug>
orch logs <slug> -f

Expected: Detached pipeline; manage with orch status and orch logs until it finishes.

When to use: A verify loop hit --max-rounds and exited non-zero.

# inspect leftover worktree + status
cat .orch/<slug>/status.md

Expected: Worktree and status.md remain after a failed or exhausted loop for inspection.

When to use: The pipeline committed on orch/<slug> and left the worktree in place.

# merge or checkout is manual — orch does not auto-merge
git merge orch/<slug>

Expected: Worktree is left in place; merge/checkout is manual — orch does not auto-merge into your main branch.