---
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 <path> --trust "<fixer prompt>" --task-slug <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 <SHORT repo/worktree path> \
  --trust "<scope + 'source of truth: <spec>'>" --task-slug <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.
