handoff

Files (1)

• SKILL.md

SKILL.md (first lines)

# Handoff

## When: a judgment at task boundaries, not a reflex
Every handoff throws away a warm cache and re-pays setup (CLAUDE.md, skills, HANDOFF, re-reading files).
Frequent handoffs cancel out caching. So hand off only when **both** hold:
1. **The next task does not need this conversation.** It is a different area/repo/problem, and what
   matters from here fits in HANDOFF.md. A follow-up, correction, review of work just done, or anything
   that uses files/decisions/run ids from this session → **stay**, whatever the size.
2. **Carrying the context costs real money.** Signals from the `CONTEXT BUDGET` line
   (token-weather-usage): past ~250k tokens or ≥$1.50/turn. Below ~150k, carrying context is cheap
   even if unrelated — stay unless the user asks.

Never hand off: mid-task, after a small milestone, or just because a number crossed a line.
At ~400k+ with the next task still dependent, keep going but trim: delegate harder, avoid big reads.

When you decide to hand off, say so in one line with the reason ("next task is unrelated to this
context, we're at 268k / $0.75 per turn") and do steps 1–3. If unsure whether the next task depends
on this context, stay.
Milestones: refresh HANDOFF.md quietly (steps 1–2), no starter prompt, keep working.
5h limit ≥80%: tell the user; shift remaining work to Codex/agy.
Check anytime: `node ~/orchestra/bin/context-budget.mjs <session-id-prefix>`.

## Steps
1. Rewrite `~/orchestra/HANDOFF.md` (replace stale content, don't append history — git log holds history). Max ~80 lines:
   - **Project:** repo path, stack, how to run, gate commands.
   - **Goal / current milestone.**
   - **Done:** landed items with commit short-hashes.
   - **In flight:** tasks with tier, run id / session id (for `--session` resume), what is pending review.
   - **Next:** ordered, each tagged with intended tier.
   - **Decisions & constraints:** things a new session must not re-litigate.
   - **Agent notes:** quota state (`state/quota.json`), which tasks agy failed at, recent incidents.
2. `node ~/orchestra/bin/orch.mjs milestone "<name>"` so the dashboard marks it.
3. (Over budget / user asked only) End your reply with a fenced starter prompt:

```text
/orchestrator Continue from ~/orchestra/HANDOFF.md. Next: <first Next item>. Keep effort caps and tiers from the skill.
```

From ahmedashraf0001/claude-orchestra, MIT.

More from ahmedashraf0001/claude-orchestra