diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index 6c0b8349..5a7da97b 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -197,6 +197,17 @@ Everything you paste into a dispatch prompt — and everything a subagent prints back — stays resident in your context for the rest of the session and is re-read on every later turn. Hand artifacts over as files. +**Waiting on dispatched subagents:** never poll a wait interface with +short timeouts, and never sit in one silent, open-ended wait either. +While you have local work — ledger updates, packaging the next review, +reading reports — keep working; child results arrive on their own. +When you are genuinely idle, wait in bounded stretches (five to ten +minutes, where your platform allows), and between stretches post one +line of status and reconcile your live children: list them, and chase +any that finished without reporting. A bounded stretch keeps nearly +all of a long wait's efficiency while guaranteeing a stuck or lost +child is noticed within minutes, not at the end of the session. + ### 1. Dispatch the implementer Record BASE (`git rev-parse HEAD`) before dispatching — the review package diff --git a/skills/using-superpowers/references/codex-tools.md b/skills/using-superpowers/references/codex-tools.md index 415638f6..077550e0 100644 --- a/skills/using-superpowers/references/codex-tools.md +++ b/skills/using-superpowers/references/codex-tools.md @@ -36,6 +36,29 @@ disagree. spawn allowlist — V2 accepts only V2-capable presets and hard-errors on the rest. +## Waiting on children + +`wait_agent` is an event subscription, not a poll: a long wait wakes +the moment a child produces mailbox activity, with the same latency as +a short one. Short-timeout polling buys nothing and costs a tool call — +and a context rebill — per poll. In measured sessions, roughly +two-thirds of all wait calls were short polls that timed out. + +- While you still have local work, do not wait at all. A completed + child's final answer is pushed into your mailbox and arrives with + your next turn. +- When you are genuinely idle with children outstanding, wait in + bounded stretches: `wait_agent` with `timeout_ms` 300000-600000 + (5-10 minutes). After each stretch — wake or timeout — post one + status line, run `list_agents`, and chase any child that finished + without reporting. Never stack polls shorter than five minutes; the + event subscription wakes a bounded stretch just as fast as a short + one. +- Completion mail cannot wake an idle controller (it is delivered + without triggering a turn); covering that idle window is + `wait_agent`'s only job. A stretch that times out with no activity + is your cue to reconcile, not to shorten the next stretch. + ## Environment Detection Skills that create worktrees or finish branches should detect their