skill(writing-agent-relay-workflows): lessons from multi-CLI game test

Closed
KH
1mo ago
+22-1

Summary

Four additions to the writing-agent-relay-workflows skill, surfaced by running a real multi-turn workflow end-to-end across claude, codex, and opencode as peer players.

  • New coordination shape: Per-turn interactive spawn. A third row in the Conversation/Pipeline table. Interactive PTY agents (no preset), but each step is bounded to one turn that exits when its file/message is produced. Use when turns are short and well-defined; avoids the idle-detection-vs-wait-for-event race that bites long-running interactive agents.

  • Idle-detection caveat at top of Chat-Native Coordination Recipes. The runtime's ~30s idle threshold beats every recipe below — Q/A, Broadcast/Ack, Peer Review, Hand-Off all encode a wait. Two handling options:

    1. Per-agent escape hatch: idleThresholdSecs on the agent (default 30s; 0 disables). Pairs with the SDK JSDoc expansion in AgentWorkforce/relay#TBD.
    2. Restructure to Per-turn interactive spawn (above) when the whole flow is turn-taking.

  • New Common Mistakes row: LLM-as-oracle anti-pattern. Observed in the wild: an LLM oracle drove timing with shell sleep 30 calls because PTY agents have no real wait API. If the comparison is computable (guess vs secret, test pass/fail, regex match), grade it deterministically. LLMs should produce, not adjudicate fixed rules.

  • Counterweight to "Workflows Repair Before They Fail." Skip the repair step when the gate sits downstream of deterministic work and has no agent-fixable failure mode. Otherwise the workflow burns a spawn cycle (and often a follow-on idle-timeout wait) on a guaranteed no-op.

Test plan

  • Authoritative source for the lessons: a real captured run in AgentWorkforce/workflows — tests/guessing-game/workflow.ts — which exhibited all four issues before the fixes.
  • No source files renamed/moved; only skills/writing-agent-relay-workflows/SKILL.md modified (+21 lines).
  • Reviewer sanity-check: read the new Chat-Native idle-detection block (around line 1462) — does the "two handling options" framing land?

🤖 Generated with Claude Code