--- name: north-orchestrator description: > Use when executing an implementation plan (waves/tasks) with the free north-mini-code model as the coding engine instead of cursor-agent or Claude subagents — invoked by /north-orchestrator, by bs-north after planning, or when the user asks to "build this with north", "run the plan on the free model", "use north to code". Also when gating north-authored diffs (deterministic build/test gate, then codex code-review every wave). --- # North Orchestrator audience: AI coding agents first. Imperative, BLUF. Execute a plan wave-by-wave with **north (`cohere/north-mini-code:free`)** in the implementer seat. north codes for $0; a deterministic build/test gate catches its clerical bugs; **fixes are made by a composer (cursor-agent) fixer via `ca.sh` — never by north**; **codex (`Skill("ask-codex")`, `gpt-5.5/low`) gates every wave**. Same chain as cursor-orchestrator (read it for the shared mechanics) with a $0 coder under a deterministic pre-filter. ## Multi-wave gate — check FIRST before any inline work Handed a PLAN_SLUG or JSONL? Classify shape before executing anything: - **Multi-wave/multi-phase** (>1 wave/phase OR any wave has parallel tasks) → **STOP. Invoke `Skill("run-plan")` with the slug.** Do NOT proceed inline. - **Single-wave single-phase** → proceed below. Multi-wave inline = context saturation across sessions → **$5.13/task** (measured). run-plan Workflow = **$1.985/task** + resumable + parallel. Break-even = first task. Inline orchestrators are single-wave engines only. --- ## Seat map vs cursor-orchestrator | seat | cursor-orchestrator | **north-orchestrator** | |------|--------------------|------------------------| | implementer | cursor-agent | **north** (`cohere/north-mini-code:free`) | | build/test gate | scattered in rules | **Gate 0 — FIRST, before codex** | | code-review gate | codex every wave | **codex (`gpt-5.5/low`) every wave** — applies its own sub-threshold (≤LOP) fixes inline (`advisor()`-checked in-session), reports the rest | | fixer | cursor-agent | **composer (cursor-agent) via `ca.sh`** for above-threshold findings + Gate-0 failures — never north | | process gate | `advisor()` | `advisor()` | | **NEVER** | — | **north holds any gate** (review/judge/sign-off) | ## IRON LAW — active every turn, survives compaction **Claude never writes implementation code. north writes the FIRST draft only. The fixer is composer (cursor-agent via `ca.sh`); the reviewer is codex (`Skill("ask-codex")`, `gpt-5.5/low`). NEVER north for either.** 1. **Claude does not code.** About to Edit a source file, write impl, or run a build to "verify a fix"? STOP — dispatch north (first draft) or the composer fixer. **LOC≤LOP rule (verbatim from cursor-orchestrator), generalized to whoever HOLDS the code in context: when the LOC to change ≤ the LOC of the prompt it would take to delegate the change → the holder edits inline instead of emitting a finding/dispatch.** The codex reviewer holds the file, so a sub-threshold fix it finds → codex fixes inline (a report-only finding for a 1-line fix IS a LOC≤LOP violation). The orchestrator rarely holds code (it sees findings, not the diff), so it rarely triggers this. Does NOT apply to logic, multi-line, multi-file, or any change needing judgment. 2. **north never holds a gate and never fixes.** north is a weak, noisy reviewer and an unreliable fixer — it misses review-findable logic bugs and re-loops clerical errors. north writes the first draft, then steps out. Every above-threshold fix goes to a **composer fixer via `ca.sh`**; every review to codex. If codex is unavailable, BLOCK — never fall back to north-as-reviewer. north re-dispatch is allowed ONLY to retry a non-completion (rc=124 timeout / 429), never to fix a defect. **Violating the letter of these rules violates the spirit.** No "north can self-check this once." **Plans are contract-level (see `plan`).** A task tagged `apply inline (LOC≤LOP), no dispatch` carries literal code shorter than its dispatch prompt → the holder applies it directly. Every other task gives a Contract (seam + behavior + acceptance), NOT a body → dispatch north, which writes the body from the repo. A plan that hands a full implementation body for a dispatched task is a planning defect — do not transcribe it; dispatch the contract. ## The gate ladder — run in order Per wave, after north produces a diff: 1. **Gate 0 — deterministic, FIRST.** Run the repo's own checks against north's diff: `tsc`/typecheck, lint (incl. `noUnusedLocals`), build, and the package's integration/unit tests. Catches north's clerical failure profile — wrong import path (→ tsc), missing early-`return` / invalid SQL keyword (→ integration test), dropped table (→ the spec's own coverage test). **RED → dispatch a composer fixer via `ca.sh`** with the exact failure output (NOT north). Re-run Gate 0 after each fix; loop until green. 2. **Codex code-review gate — EVERY wave**, only after Gate 0 green (never pay the gate to find what the build finds free). Invoke `Skill("ask-codex")` (`gpt-5.5/low`) WITH edit+commit capability (it must be able to apply sub-threshold fixes); for sensitive diffs ALSO run `security-guard`. Instruct it: **fix ≤ LOP → apply inline + commit yourself (LOC≤LOP), then call `advisor()` IN THE SAME SESSION to independently review that fix** (advisor sees the session — the file, the finding, the edit; no fresh subagent re-reads the diff cold); **fix > LOP → report-only**. Then: **report-only findings → composer fixer via `ca.sh`** → re-run Gate 0 → re-invoke codex to re-scan. **No iteration cap** — loop until codex reports CLEAN. 3. **Process gate — `advisor()`** between waves and before declaring the wave/plan done. **Composer fixer dispatch.** Use cursor-orchestrator's fixer exactly — `ca.sh --workspace --trust "" --task-slug `, fixer prompt template + triage from cursor-orchestrator (paste gate findings verbatim; fixer commits the fix; read its STATUS line). FOREGROUND only. The fixer reads/edits/commits; it never reviews its own work — the gate re-runs after. ## Task-class routing — match the task to north's ability | class | north fit | action | |-------|-----------|--------| | mechanical multi-file refactor | strong | north, expect first-pass-clean | | small described-add | strong, minor clerical warts | north, lean on Gate 0 | | structural multi-import composition to detailed spec | weak (clerical, gate-catchable) | north first draft + EXPECT a Gate-0 fix cycle (composer fixer) | | latent-failure-mode reasoning (security correctness) | weak | the gate certifies, NOT north | ## Dispatching north — the `na.sh` wrapper (north's `ca.sh` twin; NOT ca.sh itself) Dispatch north with ONE tested command. Do NOT inline the env exports or the `claude -p` line — that rig is prose-as-executable (re-derivation = reformulation = the `ccr start &` hang class, ~46min, see [[workflow-daemon-dispatch-hang]]). `na.sh` sources `NORTH.env` in its OWN subprocess (exports never leak to your real-Anthropic shell), ensures ccr is up via the tested `ccr-up.sh` (fail-closed), and runs north FOREGROUND, bounded, stdin-closed — it CANNOT hang. ```bash ~/.claude/skills/north-orchestrator/na.sh --workspace \ --trust "'>" --task-slug [--timeout 360] ``` Exit codes: `0` ok · `124` timeout/non-completion → retry ONCE or wait out a 429 · `3` ccr down → STOP, do not dispatch · `2` usage error. After it returns, VERIFY files landed where expected — short CWD only (long absolute paths trigger north's phantom-tree write bug). Give north the SAME spec the gate has; let it discover import paths by reading the repo (don't hand-feed symbol lists — that's Gate 0's job). Full background + `NORTH.env` rationale: `[[openrouter-via-claude-code-harness]]`. ## north operational failure modes — dispatch hygiene What the ladder absorbs; design around them: - **clerical precision misses** (wrong import, missing early-`return`, invalid SQL keyword) — the layer tsc/tests check → Gate 0 catches all, composer fixer corrects (NOT north). - **free-tier latency + non-termination** — makes the correct edit then loops past timeout (rc=124) → `timeout -k 5 360`, bounded fix-rounds, retry on rc=124. - **429 rate-limit** on longer multi-call tasks → retry in a window; the wave waits, it does NOT fall to north-as-reviewer or to Claude coding. - **long-absolute-path corruption** (drops a path segment, writes to a phantom tree, claims success) → short CWD + relative edit targets; verify files landed where expected. - **stale-doc tail** — correct code, leaves a now-contradicting comment → prompt "update ALL related comments"; codex catches residue. - foreground-only; the harness-reported `total_cost_usd` is FAKE here (real :free cost = $0). **Excluded:** cursor-orchestrator's cursor-as-IMPLEMENTER rules do NOT apply (north implements here). `ca.sh` IS used — for the composer FIXER (see the ladder). ## Shared mechanics — cross-ref cursor-orchestrator, do NOT re-inline Model-agnostic; follow cursor-orchestrator verbatim (point, don't copy): per-wave execution loop + wave gating · spec-is-source-of-truth · fixer-loop SHAPE (dispatch → gate → feed exact failure back → re-dispatch) · foreground-dispatch-only · return-size discipline · `advisor()` cadence. ## Common mistakes - Paying codex to review a diff that fails `tsc` → run Gate 0 FIRST. - Letting north self-review when codex is unavailable → BLOCK; never north-as-gate. - codex emitting a report-only finding for a sub-threshold (≤LOP) fix → that breaks LOC≤LOP; codex already holds the file, so it fixes it inline + commits. - Re-looping north to fix a Gate-0 failure or above-threshold codex finding → fixes go to the composer fixer via `ca.sh`; north re-dispatch only retries a non-completion (rc=124/429). - Dispatching north or the fixer in the background → failure; foreground only.