orchestrate

Files (22)

• .gitignore
• SKILL.md
• card-evidence · scripts/
• card-worktree · scripts/
• merge-card · scripts/
• orch-retro.py · scripts/
• test_card_scripts.py · scripts/
• test_chain.mjs · scripts/
• test_merge_card_branch_guard.py · scripts/
• test_merge_card_plan_sync.py · scripts/
• test_merge_card_wake.py · scripts/
• test_wave.mjs · scripts/
• test_workflow_harness.mjs · scripts/
• worker-sizes.py · scripts/
• workflow_harness.mjs · scripts/
• sizing.md
• qa-card.md · templates/
• re-review.md · templates/
• task-card.md · templates/
• workflows.md
• chain.js · workflows/
• wave.js · workflows/

SKILL.md (first lines)

# /orchestrate: a lead's deep mode

The lead owns the outcome: decomposition, routing, size watching, verification, integration,
final report. **Crew is the tracker and the voice** (`crew` skill): the run is a crew task, and
its progress, questions and result go through `crew`, so HQ, digests and phone alerts see it
like any other task. This skill adds what crew lacks: cards, waves, merges, QA. Model routing is in §5 here and
crew §2; permissions, rulings, `jw review`/`jw usage` and "workers never spawn agents" live in
CLAUDE.md ("Roles", "Delegation", "Execution discipline") and the crew skill; `/orchestrate` counts as
Workflow opt-in. Skill files are named where a step needs them. Companion: `jcode-workers`.

## 0. Worker, sub-lead, or orchestrate? (leads decide this themselves)

| The task | Use |
|---|---|
| Quick, and you already hold the context | do it yourself |
| One bounded change: one concern, one check | a crew worker (crew §2) |
| Complex work that would take too much of your time or context, or needs its own conversation with the user | `crew spawn` a sub-lead (crew §4); it runs `/orchestrate` if it needs to |
| Several workers, waves, or a verify/fix loop | `/orchestrate` (this skill) |

Apply it to every request; the user never has to ask. Balance cost against quality and
context: neither the cheapest nor the heaviest option is a default. Orchestrating also needs ≥ 2 cards that
are self-contained, checkable and worth the overhead. A typed `/orchestrate` is the decision:
orchestrate even small work, with the lightest launch that fits. State the verdict in one line
first: `§0: 6 cards, 2 waves + QA → orchestrating, mode B` or `§0: one bounded change → worker`.

## Rules that matter most

1. **The lead does not implement.** Inline work is limited to merge/integration fixes of
   ≤ ~20 lines and running checks. Everything else is a card, including QA and review fixes
   (inline fixes skip review: `jw review` found 2 real bugs in them in materials-v1); list any
   in the ledger for the final review. Never edit this skill mid-run; never route around a
   permission refusal: report it.
2. **Small cards** (one concern, ≤ ~5 owned files, one check, ≤ ~120k expected context; split
   before launch, `sizing.md`). **Same-file work is a chain** (`chain.js`), not one big worker.
3. **One approval, then keep going.** An approved plan covers every phase; never call
   ExitPlanMode again (sub-plans go in the ledger). Stop only for CLAUDE.md's stops ("Execution
   discipline", "Git and change safety") and gates the user set ("confirm cost before the full
   rerun"), each as a `crew hold`/`ask` (§3). Decide everything else as a ledger `Ruling:`.
4. **Always leave a wake-up** (crew §10). After a restart or compaction, reconcile before
   waiting: ledger → running cards → branches, notes, `jw` logs (live vs dead: `workflows.md`).

## 1. Mode

**A**: opus orchestrates; judgment-heavy work (unclear design, risky refactors, debugging).
**B** (recommend it whenever an approved plan exists and the work isn't design- or
debugging-heavy): sonnet orchestrates, a fresh **opus** subagent with the ledger path at
checkpoints (decomposition review, hard calls, escalations past sonnet, final review). Model
doesn't match the mode: say so once (`/model`), then continue.

## 2. Tracking: one crew task, plus the ledger for detail

**The run is a crew task.** A spawned sub-lead uses the task in its prompt; past ~100k at start,
§6 first (the spawn makes the task). Otherwise `crew new <slug> --shape ship --repo <repo>
"<user's words>"` and `crew log <id> running "orchestrate: mode B, <n> cards"`. Then
`jw init <slug> "<goal + success criteria>"` (makes `~/.claude/orchestration/<slug>/{ledger.md,
notes/,runs/,briefs/}`, registers the ledger for the re-inject hook), `crew meta <id> orch=<slug>`.

| Where | Holds | Not there |
|---|---|---|
| crew task (`crew show`) | run state, progress notes, user decisions (D-ids), `agent_<card>=`, `workflow_run=`, final summary | card detail |
| `ledger.md` | Goal + success criteria, Mode, Baseline, Review Focus, Tasks table (id, concern, worker, owns, check, status, rework, peak), `Ruling:`/`Minor (deferred):`/`Advisor:` lines, watch decisions, Next step | overall state, user questions |
| `board.md` | contracts between cards; workers' QUESTION/BLOCKER posts to you | questions for the user |
| `notes/<card>.md` | each worker's progress and HANDOFF | |

The ledger is the source of truth for detail: update it at every milestone, in the same call
as the work where you can; < ~200 lines. Formats: `Baseline: <command> → <result>` (full
validation on base before launch), `Ruling: <what> — <why> — <cost if wrong>`, `Minor
(deferred): <one-liner>`. Read `~/.claude/orchestration/routing-lessons.md` before routing.

## 3. Reporting through crew

- **Progress:** `crew log <id> running "<milestone>"` at each wave/chain launch and return, each
  wave merged, each QA gate, and at least every ~20 min. HQ shows the note; never message HQ.
- **User questions:** `crew hold <id> "<question; options; recommendation>"` when the run can't
  go on, `crew ask` when it can; keep working (D-id and phone alert: crew §5). Worker questions
  stay on the board (§7) unless only the user can answer them.
- **Sub-lead:** report up at milestones only, per crew §4 "Chain of command". **Result:** §10.

## 4. Decompose into task cards

First the ledger's **Review Focus**: the 3–5 real inputs or failure modes most likely to bite a
user that no card's check exercises, most likely first (a real PDF with control glyphs, two
skills at once, reload with unsaved edits, the LLM returning fenced JSON). Pin each to the card
owning that code (it joins that card's check) or to the wave's QA card. Empty = you looked.

Each card (format `templates/task-card.md`): one concern and its owned files (parallel cards own
**disjoint** files); the acceptance check written first (failing test, script, or command +
expected output); the brief from the template (WORKER RULES verbatim, kill rule included; a card using another
card's new interface names its exact signatures in CONTEXT); a ledger row; shared contracts
posted to the board (`jw post <slug> orchestrator DECISION "..."`). Pilot first: a kind of card
you haven't routed before runs once and gets its brief fixed before you fan out.

## 5. Route and launch

| Work | Worker (always pass `model`) |
|---|---|
| Exploration, search, log reading | `jw ask`, or `Explore` on haiku (`effort: high` across many files) |
| Mechanical or fully specified edits | sonnet; haiku at `effort: high` when every change is named |
| Features, tests, refactors; QA cards | sonnet, or jcode gpt-6.1-sol when Claude usage is tight (QA: sonnet) |
| Hard design, gnarly debugging, escalations | opus (Mode B) or yourself (Mode A, edits still via cards) |
| Only after sol **and** opus fell short | gpt-6-astra, with a one-line ledger justification |

Haiku at `effort: high`/`xhigh` usually suffices for read-heavy or fully specified work with an
easy-to-check output; effort buys depth, not judgment. Set it per card (`"effort"`); Claude cards default to
`"high"` (crew §2).

- **1–2 cards:** Agent (`isolation: "worktree"` for writers, `run_in_background: true`) or
  `jw run` in background Bash. `isolation: "worktree"` branches off the session's cwd repo, which may
  be the wrong one: for another repo make the worktree with `git -C <target repo> worktree add`, pass its path.
  Record each: `crew meta <id> agent_<card>=<agent id or jw task>`
  (`crew save <id> <card>` can then recover its reply).
- **≥ 3 independent cards:** `wave.js` (`{slug, repo, base, home, cards}`); **same-file sequence:**
  `chain.js` (`{slug, id, repo, base, home, cards}`); `home` is your absolute `$HOME` (scripts
  can't read it); both create the card worktrees in `repo` themselves.
  Copy the script to the session scratchpad and pass
  that copy as `scriptPath` (Workflow rejects paths outside the working directory). In crew:
  `crew log <id> running "wave 2: 5 cards (wave.js)"` at launch, `crew meta <id>
  workflow_run=<runId>`, and `crew log <id> running "wave 2 back: 4 done, 1 blocked"` on return.
- `base` is your HEAD sha; **commit** contracts and shared setup first. Run from the target

From ritamgh/claude-skills, MIT.

More from ritamgh/claude-skills