kurihada/ai-workflow-skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add orch Codex launch bridge workflow

Browse Source
This commit is contained in:
kurihada
2026-03-20 18:28:48 +08:00
parent cf3c3cbe60
commit 7840b2767f
11 changed files with 523 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tests/orch-skill/README.md
+11
View File
@@ -29,6 +29,7 @@ Use these defaults unless a case file explicitly overrides them:
- initialize the shared SQLite DB before launching role agents with `INBOX_SKILL_PATH/assets/inbox --db TMPDIR/coord.db --json init`
- require the leader to coordinate through the bundled `./assets/orch` CLI from the skill instead of ordinary chat
- require workers to coordinate through the bundled `./assets/inbox` CLI from their skill instead of ordinary chat
- launch-bridge cases may use a leader-only topology where the leader spawns worker subagents after dispatch instead of relying on the test-runner to launch separate worker roles
- validate final run and thread state independently from the main thread after the agents stop
- create any required Git repo fixture before launching agents for worktree cases
@@ -59,6 +60,12 @@ The role agents are responsible for:
- coordinating through the bundled CLI and shared DB
- reporting concrete run ids, thread ids, worktree paths, and key command outcomes back to the test-runner agent
For launch-bridge cases:
- the leader may be the only top-level role agent
- that leader is responsible for spawning any worker subagents itself after `dispatch`
- spawned worker subagents should use the generated worker brief plus `skills/inbox/`, not ordinary chat
The test-runner agent should treat a case as passed only when:
- all role agents reach a final state without violating the case contract
@@ -173,6 +180,8 @@ Each case file should use this structure:
| `leader-answers-blocked-task-with-payload-json-through-bundled-cli` | [leader-answers-blocked-task-with-payload-json-through-bundled-cli.md](./leader-answers-blocked-task-with-payload-json-through-bundled-cli.md) | validates that a leader can answer a blocked task with structured payload data only and still drive the run to completion |
| `leader-retries-failed-task-through-bundled-cli` | [leader-retries-failed-task-through-bundled-cli.md](./leader-retries-failed-task-through-bundled-cli.md) | validates that a leader can reconcile a failed attempt and create a successful retry through the packaged orch skill |
| `leader-reassigns-blocked-task-through-bundled-cli` | [leader-reassigns-blocked-task-through-bundled-cli.md](./leader-reassigns-blocked-task-through-bundled-cli.md) | validates that a leader can reassign a blocked task from one worker to another and close the run through the packaged orch skill |
| `leader-dispatches-and-launches-worker-through-codex-bridge` | [leader-dispatches-and-launches-worker-through-codex-bridge.md](./leader-dispatches-and-launches-worker-through-codex-bridge.md) | validates that a leader can dispatch a task, render a standardized worker brief, and launch a worker subagent from the same Codex thread |
| `strict-worktree-dispatch-launches-worker-through-codex-bridge` | [strict-worktree-dispatch-launches-worker-through-codex-bridge.md](./strict-worktree-dispatch-launches-worker-through-codex-bridge.md) | validates that a leader can launch a code-writing worker subagent from saved dispatch metadata while preserving the assigned worktree contract |
## Scope
@@ -182,6 +191,7 @@ In scope:
- bundled `./assets/orch` CLI usage
- leader-side run, task, dependency, dispatch, reconcile, answer, retry, reassign, wait, status, and cleanup flows
- interaction between a leader using `skills/orch/` and workers using `skills/inbox/`
- leader-side launch-bridge workflows where the leader spawns worker subagents after `dispatch`
- worktree-backed dispatch and cleanup validation
- end-to-end run state and thread history validation
@@ -191,6 +201,7 @@ Out of scope:
- worker-only skill behavior that already belongs under [../inbox-skill/](../inbox-skill/)
- the separate `council-review` skill package
- implicit skill triggering without `$orch`
- changing the core `orch` CLI so it launches workers by itself
## Relationship To Other Test Docs
docs/tests/orch-skill/leader-dispatches-and-launches-worker-through-codex-bridge.md
+97
View File
@@ -0,0 +1,97 @@
# 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
```text
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](./README.md)
- use the shared timeout defaults from [README.md](./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
```bash
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](./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
docs/tests/orch-skill/strict-worktree-dispatch-launches-worker-through-codex-bridge.md
+97
View File
@@ -0,0 +1,97 @@
# Case: `strict-worktree-dispatch-launches-worker-through-codex-bridge`
## Test Type
This is a `forward-test` and a worktree launch-bridge validation.
The goal is to verify that a leader using the packaged `orch` skill can dispatch a code task, render a standardized worker brief from the saved dispatch JSON, and launch a worker subagent that respects the assigned worktree contract.
## Purpose
Validate that all of the following can be true at the same time:
- the leader can dispatch a code task with `--strict-worktree` through the bundled orch skill
- the leader can turn that dispatch JSON into a stable worker brief through `./assets/orch-worker-brief`
- the launched worker subagent uses `skills/inbox/` and reports through inbox
- the launched worker observes the assigned `worktree_path` and completes the attempt
- the leader can reconcile the finished task and clean the attempt worktree
## 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`
- create `TMPDIR/repo` as a Git repository with one committed file before launching agents
## Agent Topology
- `leader`
The leader is responsible for spawning the code-writing worker subagent after dispatch.
## Inputs
### Leader Prompt
```text
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_worktree_001, 2) add one code task T1 for worker-a, 3) dispatch it with --repo-path TMPDIR/repo --workspace-root .orch/worktrees --strict-worktree while saving --json 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 until the worker completes, 7) inspect final status, 8) clean up attempt 1, 9) stop after reporting RUN_ID, THREAD_ID, and WORKTREE_PATH. Do not use ordinary chat to coordinate with the worker; the launched worker must use inbox only and should respect the assigned worktree.
```
## Execution Parameters
- use the shared execution contract from [README.md](./README.md)
- use the shared timeout defaults from [README.md](./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. Create `TMPDIR/repo` with an initial commit before launching agents
3. Inject `skills/orch/` into `leader`
4. Ensure `leader` can also reference `skills/inbox/` by path when it spawns the worker subagent
5. Point the leader at the same database path `TMPDIR/coord.db`
6. Launch `leader`
7. Wait for `leader` and any spawned worker subagent(s) to finish
8. Resolve `THREAD_ID` and `WORKTREE_PATH` from the leader output
9. Independently run the validation commands from the main thread
## Validation Commands
```bash
ORCH_SKILL_PATH/assets/orch --db TMPDIR/coord.db --json status --run run_blog_skill_launch_worktree_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
test ! -d WORKTREE_PATH
```
## Expected Outcomes
- the leader reports a non-empty `WORKTREE_PATH` from dispatch
- the rendered worker brief includes that same `worktree_path`
- the launched worker subagent claims the assigned thread and completes it through inbox
- the final run status is `done`
- the cleanup step removes the worktree directory
## Assertions
- `status.data.run.status == "done"`
- `status.data.tasks[0].status == "done"`
- `status.data.tasks[0].latest_attempt.worktree_path == WORKTREE_PATH`
- `show.data.thread.status == "done"`
- the task-side thread history includes a payload field or body content referencing the worktree path
- `TMPDIR/worker-brief.txt` mentions the expected `WORKTREE_PATH`
- `WORKTREE_PATH` does not exist after cleanup
## Cleanup
- use the default cleanup policy from [README.md](./README.md)
- if the run fails, retain `TMPDIR`, `coord.db`, and the Git repo fixture 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