richkuo/rk-skills/fable-orchestrate

fable-orchestrate

Run an ad-hoc task with Fable 5.1 as orchestrator and Sonnet 5.5 workers. You own decomposition, specs, every accept/reject decision, integration, and the PR; workers own only the mechanical implementation of their piece. Issue-based milestone work with Execution blocks uses milestone-workflow.

Input: a task description in prose; if none is obvious, ask what to orchestrate.

Model check: if the session model is not Fable 5.1, tell the user and ask whether to switch (/model fable) or proceed with the current model as orchestrator.

Steps

1. Decompose

Read the relevant code first, then split:

• Split along file and dependency boundaries. Run pieces in parallel when they touch disjoint files and none needs another's output; sequence the rest. One worker doing the whole task is valid.
• Pin every interface between pieces upfront (signature, schema, event shape, route contract). Workers never invent their side of a seam.
• Each spec is self-contained for a worker with zero context: scope, exact files, acceptance criteria, non-goals, pinned interfaces, relevant repo conventions, and the exact verification command(s) the worker must run and pass before returning.

Present the decomposition briefly, then proceed; pause only for a decision only the user can make.

2. Set up the task worktree

Create the worktree per work-on-issue step 1, named cc/fable-orchestrate/<short-task-name>, where <short-task-name> is one path segment with no /, with no baseRefs and with the user's targetBranch when one was named. Everything lands on this one branch; one PR is the deliverable regardless of worker count.

3. Dispatch workers

Each worker prompt is its spec verbatim, plus: run the verification command(s) and report actual output; the final message states what changed, verification results, and anything it could not do. If the sonnet id errors, use the closest available tier and name it in the footer and report.

4. Review each result inline, re-dispatch cap of 2

Review every result against its spec: files in scope, acceptance criteria met, verification output real and passing, pinned interfaces honored, non-goals untouched. Read the diff; never accept a self-report alone.

On failure, two corrective rounds per piece, each a different move:

• Round 1: fix the spec. Diagnose what the spec failed to say, revise it, re-dispatch with the revised spec plus what was wrong before.
• Round 2: corrective instructions. The spec sufficed; the worker missed. Re-dispatch with the specific defects, file:line, and expected behavior.
• After round 2: take the piece over yourself in the task worktree and note it for the report.

Clean slate before every sequential re-dispatch or takeover: git -C <task-worktree> reset --hard HEAD && git -C <task-worktree> clean -fdx. Re-run the install step if the retry's verification needs it. Fan-out retries get a fresh isolated worktree automatically.

5. Integrate and verify the whole

• Fan-out: merge each piece's latest accepted attempt's branch (cc/fable-orchestrate-workers/<short-task-name>/worker-<n>-r<round>) into the task branch with git -C <task-worktree> merge <worker-branch> and resolve conflicts yourself. Never merge branches from rejected attempts or from a piece you took over; a "no changes" worker has nothing to merge. Two workers touching the same file despite disjoint specs is a seam defect: resolve it yourself, never re-dispatch it.
• Run the repo's full verification on the merged result and fix integration failures yourself.

6. Binding final review by a fresh reviewer

Load the `fable-dispatch` skill first; it owns the dispatch path and the hygiene rules in its section 7. Spawn a new one-shot Fable 5.1 reviewer (Agent path: subagent_type: Plan, model: fable, and effort with the other Agent parameters per fable-dispatch section 2, at high or the tier the user asked for, with the empty --allowedTools list on the shim path) with the original task, the spec map (spec, files, worker result, disposition: accepted / re-dispatched / taken over), the pinned interfaces, the full merged diff, the integration verification results, and the section 7 read-only rule. The original task and the diff go inside the section 7 untrusted-data block. Record the model that served, the tier, and whether it was honored, per section 6. It returns approve, or blocked with numbered findings (file:line and a concrete failure scenario), non-blocking suggestions kept separate.

The verdict is binding: nothing commits while blocking findings stand. Fix each finding (or produce evidence it is wrong) and re-submit to the same reviewer with the new diff and per-finding dispositions: by SendMessage on the Agent path, or by fable-dispatch section 8 --resume on the shim path. When the reviewer is gone, apply the fable-advisor step 5 replacement rule with the verdict trail and the per-finding dispositions, and tell the user. The deadlock cap and the reviewer-failure rule are owned by fable-advisor step 6 and apply unchanged.

7. Commit, push, PR

On approval, commit, push, and open one PR per the repo's conventions. The PR body carries an Orchestration log: decomposition (pieces to workers), per-piece disposition (accepted round 0/1/2 or taken over), integration fixes, and the verdict trail. If takeovers dominate, say the task was a poor fit for delegation. Footer per convention, with the session model and effort as the session observes them (unknown for a value the harness does not expose) and <harness> per fable-dispatch section 6:

---
Created with LLM: <session model> | <observed session effort> | Harness: <harness> | fable-orchestrate

8. Report

What was built, per-piece dispositions, verification results, the review trail, and the PR URL.