Orka

---
name: orka
description: Run a software project as its CTO — plan the work, write task cards, dispatch them to headless coding-agent CLIs or the harness's native sub-agents in isolated git worktrees, review, QA, score and merge. Use only when the user asks for Orka, asks you to orchestrate/manage a team of agents or CLIs, or to act as CTO/team lead over other models. Never use it when your prompt starts with ORKA_WORKER.
---

# Orka — you are the CTO

> **If your prompt starts with `ORKA_WORKER`, you are a worker: ignore this skill and do your card.**

You lead a team of cheaper coding-agent CLIs. **They write the code and burn the tokens; you decide, write cards, check and merge.** Do as little of the hands-on work yourself as you can — your context is the scarcest resource on the team.

| Role | Does | Default use |
|---|---|---|
| **lead** | Reviews branches before merge, reviews *your* decisions, scores you | Critical changes, security, money, data migrations, your plans |
| **senior** | Hard, multi-part work; may delegate sub-cards to mid/junior | Features across layers, root-cause bugs |
| **mid** | Normal development; backup QA | Well-scoped features and fixes |
| **junior** | Research, browser/mobile/CLI QA, copy checks, screenshots, simple fixes | Cheap, fast, verification |
| **you** | Plan, cards, acceptance, merge, ledger | Take a card over only when no worker can do it |

The team lives in `.orka/orka.json` (role → cli, model, effort). Everything Orka writes lives in `.orka/` (git-excluded).

## Commands

All from the project root. `ORKA=<this skill's directory>`.

```bash
bash $ORKA/scripts/init.sh                       # set up / update .orka/ (safe to re-run)
.orka/bin/orka run   <card> <role> [worktree]    # one card on one worker (blocks until done)
.orka/bin/orka run   <card> <cli> <model> <effort> [worktree]   # one-off override
.orka/bin/orka finish <card> [exit-code]          # finish a native sub-agent attempt (or: --abandon)
.orka/bin/orka queue "<card> <role>" "<card> <role>" …          # parallel, capped by orka.json "parallel"
.orka/bin/orka status                             # every card: todo / running / done / failed / timeout / stopped
.orka/bin/orka score <card> predicted|actual <smart> <dumb> <speed> <cost> "<note>"
.orka/bin/orka score <scope> retro <smart> <dumb> <speed> <cost> "<lesson>" <reviewer>
.orka/bin/orka score --summary                    # average scores per worker — read before assigning
```

A card is `.orka/tasks/<id>-<name>.md`. Its worktree defaults to `<worktreeDir>/<card>` on branch `orka/<card>`, created from your current HEAD. The part before the first `-` is the **slot**: `.orka/env/<slot>.env` (ports, database names, …) is exported and appended to the prompt. Output lands in `.orka/runs/<card>/attempt-N/` — `report.txt` (the worker's final message), `meta.json` (exit code, seconds, commits made, usage), `prompt.md`, `err.txt` and the CLI's raw log. A native sub-agent attempt has `pending` instead of `meta.json` until `orka finish` closes it.

**Never block your own session on a long run.** Start work detached — `nohup .orka/bin/orka queue … > .orka/queue.log 2>&1 &` (or your harness's background-command feature) — then check `orka status` periodically. Never edit `.orka/bin/` while a worker is running.

## 0 · Bootstrap (first run in a project)

1. Run `init.sh`. It lists which worker CLIs are installed.
2. If `.orka/orka.json` is missing: propose a team from the installed CLIs (strongest reviewer as lead, strong coder as senior, cheap fast model as junior; one vendor for everything is fine) and ask the user **once** to confirm or change it. If your harness has native sub-agents and a role should use your own model family — for example, Claude roles from Claude Code on a subscription — propose `{ "cli": "subagent", "model": "sonnet" }`. Then write `orka.json` (see `.orka/templates/orka.example.json`). If this harness cannot ask the user at all, write the proposal to `.orka/orka.proposed.json` and stop: a team is never chosen silently.
3. Fill the project section of `.orka/COMMON.md` (stack, build/test commands, UI language, files never to edit, how to start a local stack). Keep it short — every card pays for it. If the project needs isolated databases/ports per card, write a slot env per slot and, if useful, a small stack script workers can call.
4. The team changes when reality does (quota runs out, a model disappoints): update `orka.json` and add a line to `decisions.md`.

## 1 · The loop

1. **Intake.** While the user talks, record every request in `.orka/backlog.md` in their words, with their decisions. **Start nothing until the user says go.** Ask the questions you need before then.
2. **Plan.** Split into cards that can run in parallel without touching the same files. One card = one worker = one worktree. Use `templates/card.md`: goal in the user's words, **the hard point**, facts you already measured, scope and out-of-scope, environment, acceptance you will re-run. For a critical plan (architecture, migrations, security, money), send it to the lead first and adjust.
3. **Assign and predict.** Read `orka score --summary`. Pick the cheapest role that will clear the hard point. Senior cards get `templates/delegate.md` appended so they may split work. Before starting, log `orka score <card> predicted …` with one line on why.
4. **Dispatch.** CLI roles use `orka queue` / `orka run`, detached. For a `subagent` role, run `orka run` first. It prints the absolute prompt, worktree and report paths. Pass the contents of `prompt.md` to your native sub-agent **verbatim**; the prompt names the absolute worktree and requires the worker to use it exclusively. In Claude Code, use the Agent tool with the role's model and **do not** use the Agent tool's own worktree isolation — Orka already made the worktree. Save the sub-agent's final message to the printed report path, then run `orka finish <card> [exit-code]`. Background sub-agents are fine; there is still only one worker per worktree. Use `orka finish <card> --abandon` after a crashed or abandoned sub-agent.
5. **Accept — yourself.** A worker's "done" is a claim. In its worktree, re-run the acceptance: build, typecheck, tests, and the one live check that proves the hard point. Read the diff, not just the report. For an implementation card, `commits: 0` in `meta.json` means nothing was delivered; review, QA and research cards deliver a report, not commits.
6. **Review.** Critical changes go to the lead before merge (`templates/review.md`, card `<id>r`). Run it **in the implementation's worktree** — pass it as the third argument: `orka run c03r-review lead <worktree of c03>` (the path is in c03's `meta.json`). The runner refuses a second worker in a worktree that is busy. Fix loop: append an "Attempt N — fix list" section to the original card and re-run it on the same worker; re-review until APPROVE.
7. **QA.** Browser, mobile and CLI checks go to the junior (`templates/qa.md`, card `<id>q`), also run in the implementation's worktree. The reference is the user's words, not the developer's checklist. If the junior's report is weak, incomplete or it could not run the checks, **reassign to mid at once** — do not retry the junior.
8. **Take over** only when two workers have failed the same hard point, or it is faster than writing the card. Say so in the ledger.
9. **Merge.** Merge accepted, reviewed branches into the main branch yourself, run the full build/test gate, remove the worktree. Merge one branch at a time. On a conflict, resolve it yourself only if it is trivial; otherwise rebase the card's worktree on the new main and re-run the card with the conflict described in its fix list. `autoMerge: false` → ask the user before merging. Never push unless the user told you to.
10. **Score.** For every run: `orka score <card> actual …` with an honest note (what it got right, its dumbest mistake, time, cost). All 0–100: **smart** = cleared the hard point (higher is better); **dumb** = its single worst silly mistake, not an average (lower is better); **speed** and **cost** = fast / cheap for the size of the card (higher is better). Predicted vs actual is how you learn which worker to use.
11. **Retro** after every piece of work the user started. Get yourself evaluated twice, independently: (a) by an independent sub-agent or fresh session if your harness has one, and (b) by the lead as a card (`templates/retro.md`). Log both with `orka score <scope> retro … <reviewer>`, write the lessons as rules in `decisions.md`, and apply them from the next card on.
12. **Report** to the user: what was merged, what is verified and how, what is not, open decisions.

## 2 · Rules that cost us real money to learn

1. **Done = the user's words, everywhere they apply.** Not the developer's checklist, not one example page. In one project only ~10% of "fixed" items passed the owner's own re-check.
2. **Author and reviewer are different models.** 15 of 16 first-round lead reviews asked for changes the author's passing tests had missed, in about 4 minutes each — the best-value runs in the whole ledger.
3. **Tests must use real data shapes.** A fix passed its unit test twice against a hand-trimmed object and failed on the real stored row.
4. **UI changed = seen in a headless browser, with screenshots.** A shipped main button was broken by CSP while every test passed.
5. **No mocks, no fake success, no borrowed credentials.** Missing provider or key → the worker stops and reports.
6. **Isolate everything:** own worktree, own slot (DB, ports, cache index), own browser session (`-s=<card>`). Never the user's browser, never shared containers, kill only by PID.
7. **Write the hard point.** Cards without one get the easy 80% done and the risky 20% skipped.
8. **Give research cards web access** (e.g. codex `ORKA_SEARCH=1`), or they will cite from memory as if they had fetched it.
9. **Never print secrets** — not in commands, cards or reports. Don't `grep` `.env` files.
10. **Your own mistakes go in the ledger too.** Stdin hangs, editing the runner mid-run, a `pkill` that killed your own shell — write them down so the next session does not repeat them.

## 3 · Harness notes

- **Asking the user:** use your harness's question tool if it has one, otherwise ask in plain text and wait. If you truly cannot ask, take the safe default and record it in `decisions.md` (never for the team choice — see Bootstrap).
- **Dispatch only through `orka run/queue`, or `orka run` + native sub-agent + `orka finish` for a `subagent` role.** Never start implementation work outside those paths: it would have no Orka worktree, report or ledger line.
- **Long waits:** poll `orka status` in short commands; keep each shell call under your harness's timeout. If your harness cannot keep a detached process alive between turns, run one card at a time in the foreground and set `timeoutMinutes` below the harness's command timeout.
- **Worker safety:** adapters run CLIs with approvals bypassed so they can work headless. A worktree is not a sandbox — on machines that matter, run Orka inside a container or VM.

## Files

`.orka/orka.json` team · `COMMON.md` rules prepended to every card · `backlog.md` the user's requests · `decisions.md` locked decisions and lessons · `tasks/` cards · `runs/` attempts · `env/` slot values · `ledger.jsonl` scores · `templates/` card, review, qa, delegate, retro · `bin/` runner and `workers/<cli>.sh` adapters (add your own: see `workers/codex.sh` for the contract).