ai-workflow-skill/docs/tests/orch-skill/leader-dispatches-and-launches-worker-through-codex-bridge.md

Case: leader-dispatches-and-launches-worker-through-codex-bridge

Test Type

This is a forward-test and a leader-side launch-bridge validation.

The goal is to verify that a leader using the packaged orch skill can dispatch work, render a standardized worker brief through the skill assets, and launch a worker subagent from the same Codex thread without hand-writing the inbox handoff.

Purpose

Validate that all of the following can be true at the same time:

• the leader can use the bundled ./assets/orch CLI through the skill
• the leader can save dispatch --json output and turn it into a stable worker brief through ./assets/orch-worker-brief
• the leader can spawn a worker subagent that uses skills/inbox/ instead of ordinary chat
• the launched worker claims the dispatched thread and completes it
• the final orch run state and inbox thread state both reach done

Preconditions

• orch skill path exists: ORCH_SKILL_PATH=skills/orch
• inbox skill path exists: INBOX_SKILL_PATH=skills/inbox
• bundled CLI executables exist at ORCH_SKILL_PATH/assets/orch and INBOX_SKILL_PATH/assets/inbox
• the helper asset exists at ORCH_SKILL_PATH/assets/orch-worker-brief
• use an empty temporary directory TMPDIR
• initialize TMPDIR/coord.db before launching role agents through INBOX_SKILL_PATH/assets/inbox --db TMPDIR/coord.db --json init

Agent Topology

• leader

The leader is responsible for spawning the worker subagent after dispatch.

Inputs

Leader Prompt

Use $orch at ORCH_SKILL_PATH to act as leader on the already initialized SQLite DB TMPDIR/coord.db. Only coordinate through the bundled orch CLI from the skill. Workflow: 1) create run run_blog_skill_launch_001, 2) add exactly one task T1 assigned to worker-a, 3) dispatch it with --json saved to TMPDIR/dispatch.json, 4) render a worker brief with ORCH_SKILL_PATH/assets/orch-worker-brief into TMPDIR/worker-brief.txt, 5) spawn one worker subagent that uses INBOX_SKILL_PATH and the generated worker brief, 6) wait or poll until the worker reports completion, 7) inspect final status, 8) stop after reporting RUN_ID and THREAD_ID. Do not use ordinary chat to coordinate with the worker; the launched worker must use inbox only.

Execution Parameters

• use the shared execution contract from README.md
• use the shared timeout defaults from README.md
• do not override the default cleanup policy

Execution Steps

1. Initialize TMPDIR/coord.db once through the bundled inbox CLI before launching agents
2. Inject skills/orch/ into leader
3. Ensure leader can also reference skills/inbox/ by path when it spawns the worker subagent
4. Point the leader at the same database path TMPDIR/coord.db
5. Launch leader
6. Wait for leader and any spawned worker subagent(s) to finish
7. Resolve RUN_ID=run_blog_skill_launch_001 and THREAD_ID from the leader output
8. Independently run the validation commands from the main thread

Validation Commands

ORCH_SKILL_PATH/assets/orch --db TMPDIR/coord.db --json status --run run_blog_skill_launch_001
INBOX_SKILL_PATH/assets/inbox --db TMPDIR/coord.db --json show --thread THREAD_ID
test -f TMPDIR/dispatch.json
test -f TMPDIR/worker-brief.txt

Expected Outcomes

• the leader successfully creates run_blog_skill_launch_001
• the leader successfully dispatches T1 and saves the JSON response
• the leader successfully renders a non-empty worker brief from that JSON response
• the leader successfully spawns a worker subagent that uses skills/inbox/
• the launched worker successfully claims the dispatched thread
• the launched worker completes the thread with done
• the final run state is done

Assertions

• status.data.run.run_id == "run_blog_skill_launch_001"
• status.data.run.status == "done"
• status.data.tasks contains exactly one task T1
• status.data.tasks[0].status == "done"
• status.data.tasks[0].latest_attempt.assigned_to == "worker-a"
• show.data.thread.status == "done"
• show.data.messages[*].kind includes task, progress, and result
• TMPDIR/worker-brief.txt mentions the expected thread_id

Cleanup

• use the default cleanup policy from README.md
• if the run fails, retain TMPDIR and coord.db for replay and manual inspection

Recorded Example Run

• no recorded run yet
• this case should be captured with a real leader agent plus leader-launched worker subagent after the launch bridge assets are adopted