Add orch Codex launch bridge workflow
This commit is contained in:
@@ -52,6 +52,20 @@ Both CLIs should point at the same SQLite file.
|
||||
|
||||
This preserves a clean boundary while keeping deployment simple.
|
||||
|
||||
## Optional Codex Launch Bridge
|
||||
|
||||
Some environments may layer an execution bridge on top of `orch`.
|
||||
|
||||
Recommended shape:
|
||||
|
||||
- `orch dispatch --json` creates the durable handoff state
|
||||
- a leader-side Codex bridge reads the dispatch result
|
||||
- that bridge may spawn a worker sub-agent and pass it the mapped `thread_id`, `assigned_to`, and any `worktree_path`
|
||||
- the worker still reports only through `inbox`
|
||||
|
||||
This bridge belongs above the CLI layer.
|
||||
It should not be implemented as core `orch` runtime behavior because worker launch is host-specific while run and attempt state are meant to stay portable.
|
||||
|
||||
## Worker Execution Model
|
||||
|
||||
For code tasks, execution should be isolated from the user's primary checkout.
|
||||
@@ -159,4 +173,5 @@ The intended skill split mirrors the CLI split.
|
||||
|
||||
- `inbox` skill: used when an agent needs to fetch work, claim a thread, send progress, ask blocked questions, reply, or return results through `inbox`
|
||||
- `orch` skill: used when the leader needs to create runs, decompose tasks, manage dependencies, dispatch ready work, inspect blocks, answer them, retry failures, or reassign work through `orch`; it is not itself the worker launcher
|
||||
- `orch` skill may include helper assets for leader-side launch bridges, but the durable source of truth for scheduling remains the `orch` CLI and shared SQLite state
|
||||
- `council-review` skill: used when the user explicitly wants a structured three-reviewer brainstorm or review with grouped and tallied recommendations
|
||||
|
||||
@@ -12,6 +12,7 @@ In normal operation:
|
||||
- `orch` creates and monitors `inbox` threads
|
||||
- workers continue using `inbox`
|
||||
- a separate worker runtime or worker agent must still consume the assigned inbox thread after `dispatch`
|
||||
- Codex-specific launch bridges may sit above `orch`, but they should consume dispatch output rather than change the CLI contract
|
||||
|
||||
## Responsibilities
|
||||
|
||||
@@ -199,6 +200,11 @@ Behavior:
|
||||
- moves the task to `dispatched`
|
||||
- does not start a worker runtime on its own
|
||||
|
||||
Integration note:
|
||||
|
||||
- a higher-level Codex bridge may save this JSON output, render a worker brief, and then spawn a worker sub-agent
|
||||
- that bridge should remain outside the core `orch` runtime so the scheduling contract stays portable
|
||||
|
||||
Strict-mode recommendation:
|
||||
|
||||
- if `--base-ref` is omitted and the repository is clean, default to `HEAD`
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
+97
@@ -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
|
||||
@@ -180,6 +180,9 @@ Recommended responsibilities:
|
||||
|
||||
This keeps workspace ownership in `orch` and execution ownership in the worker runtime.
|
||||
|
||||
In a Codex sub-agent environment, a leader-side launch bridge may translate the saved `orch dispatch --json` response into a worker brief and then spawn the worker sub-agent.
|
||||
That bridge still counts as part of the worker runtime layer, not the `orch` runtime itself.
|
||||
|
||||
## Review and Integration
|
||||
|
||||
Strict mode works best when integration is explicit.
|
||||
|
||||
+36
-2
@@ -33,6 +33,7 @@ Use the bundled `./assets/orch` CLI to control leader-side orchestration through
|
||||
- Prefer `--json` whenever another agent or script will read the output.
|
||||
- Initialize a new database path once through the bundled `inbox init` command before the first real run.
|
||||
- Use `status` as the main operational view. It reconciles worker thread state first, then returns run, task, latest-attempt, and latest-message context.
|
||||
- For Codex worker launch, standardize the handoff through `./assets/orch-worker-brief` instead of improvising the worker prompt every time.
|
||||
- Use this skill for leader-side scheduling and control-plane actions, not worker-side lease or progress updates.
|
||||
|
||||
## Rules
|
||||
@@ -56,6 +57,36 @@ Use the bundled `./assets/orch` CLI to control leader-side orchestration through
|
||||
5. Launch or reuse a separate worker runtime or worker agent that uses `skills/inbox/` against the same DB path.
|
||||
6. Use `status`, `wait`, `blocked`, `answer`, `retry`, `reassign`, and `cleanup` to operate the run until the required tasks are complete.
|
||||
|
||||
## Dispatch-And-Launch Workflow
|
||||
|
||||
Use this when the leader wants durable `orch` state plus a worker sub-agent launched from the current Codex thread.
|
||||
|
||||
1. save the dispatch output:
|
||||
|
||||
```bash
|
||||
./assets/orch --db ./coord.db --json dispatch --run RUN_ID --task TASK_ID > TMPDIR/dispatch.json
|
||||
```
|
||||
|
||||
2. render a standardized worker brief:
|
||||
|
||||
```bash
|
||||
./assets/orch-worker-brief --dispatch-json TMPDIR/dispatch.json --db ./coord.db > TMPDIR/worker-brief.txt
|
||||
```
|
||||
|
||||
3. spawn one worker sub-agent with:
|
||||
- `skills/inbox/`
|
||||
- the generated worker brief
|
||||
- the repo defaults from `AGENTS.md`
|
||||
- model `gpt-5.4`
|
||||
- reasoning effort `xhigh`
|
||||
- `fork_context: true` first
|
||||
4. keep the leader on `orch wait`, `orch status`, `orch blocked`, `orch answer`, `orch retry`, or `orch reassign`
|
||||
|
||||
See:
|
||||
|
||||
- `./references/leader-dispatch-and-launch-checklist.md`
|
||||
- `./references/worker-brief-template.md`
|
||||
|
||||
## Worker Handoff Contract
|
||||
|
||||
- The worker side should use `skills/inbox/`, not this skill.
|
||||
@@ -72,8 +103,10 @@ Use the bundled `./assets/orch` CLI to control leader-side orchestration through
|
||||
./assets/orch --db ./coord.db --json task add --run blog_mvp_001 --task T2 --title "Summarize flaky tests" --summary "Read logs and report next steps" --default-to qa-worker --acceptance-json '{"kind":"analysis"}'
|
||||
./assets/orch --db ./coord.db --json dep add --run blog_mvp_001 --task T2 --depends-on T1
|
||||
./assets/orch --db ./coord.db --json ready --run blog_mvp_001
|
||||
./assets/orch --db ./coord.db --json dispatch --run blog_mvp_001 --task T1 --to foundation-worker --base-ref main --workspace-root .orch/worktrees --strict-worktree --body-file tasks/t1.md
|
||||
./assets/orch --db ./coord.db --json dispatch --run blog_mvp_001 --task T2 --to qa-worker --body "Read the failing test logs and summarize the root cause."
|
||||
./assets/orch --db ./coord.db --json dispatch --run blog_mvp_001 --task T1 --to foundation-worker --base-ref main --workspace-root .orch/worktrees --strict-worktree --body-file tasks/t1.md > /tmp/t1-dispatch.json
|
||||
./assets/orch-worker-brief --dispatch-json /tmp/t1-dispatch.json --db ./coord.db > /tmp/t1-worker-brief.txt
|
||||
./assets/orch --db ./coord.db --json dispatch --run blog_mvp_001 --task T2 --to qa-worker --body "Read the failing test logs and summarize the root cause." > /tmp/t2-dispatch.json
|
||||
./assets/orch-worker-brief --dispatch-json /tmp/t2-dispatch.json --db ./coord.db > /tmp/t2-worker-brief.txt
|
||||
./assets/orch --db ./coord.db --json status --run blog_mvp_001
|
||||
./assets/orch --db ./coord.db --json wait --run blog_mvp_001 --for task_blocked,task_done,task_failed --after-event 0 --timeout-seconds 900
|
||||
./assets/orch --db ./coord.db --json blocked --run blog_mvp_001
|
||||
@@ -104,6 +137,7 @@ Use the bundled `./assets/orch` CLI to control leader-side orchestration through
|
||||
|
||||
- `dispatch` supports `--repo-path`, `--workspace-root`, `--strict-worktree`, and `--base-ref` for worktree-backed code execution.
|
||||
- When worktree flags are omitted, code-like task metadata can still auto-enable strict worktree mode. Non-code tasks stay on the normal thread-only path.
|
||||
- `./assets/orch-worker-brief` is the supported way to turn a saved dispatch JSON response into a stable worker prompt for a spawned sub-agent.
|
||||
- `answer` supports `--payload-json` for structured decisions, not just freeform text.
|
||||
- `status` is the full run view; `run show` is the lighter aggregate view.
|
||||
- If the bundled binary cannot execute on the current host, stop and report the compatibility issue instead of guessing a replacement path or workflow.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
interface:
|
||||
display_name: "Orch CLI"
|
||||
short_description: "Leader-side orchestration CLI"
|
||||
default_prompt: "Use $orch to manage leader-side orchestration runs through the bundled orch CLI and a SQLite orchestration database. Treat it as a control plane only: dispatch creates attempts and inbox threads, while separate workers consume them through inbox."
|
||||
default_prompt: "Use $orch to manage leader-side orchestration runs through the bundled orch CLI and a SQLite orchestration database. Treat it as a control plane only: dispatch creates attempts and inbox threads, while separate workers consume them through inbox. When you choose to launch a worker sub-agent from the current Codex thread, standardize the handoff with ./assets/orch-worker-brief and keep the worker on skills/inbox only."
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: true
|
||||
|
||||
Executable
+164
@@ -0,0 +1,164 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
readonly DEFAULT_INBOX_SKILL_PATH="$(cd "${SCRIPT_DIR}/../../inbox" && pwd)"
|
||||
|
||||
dispatch_json=""
|
||||
db_path=""
|
||||
inbox_skill_path="${DEFAULT_INBOX_SKILL_PATH}"
|
||||
extra_instructions_file=""
|
||||
|
||||
usage() {
|
||||
cat <<'EOF'
|
||||
Usage: orch-worker-brief --dispatch-json PATH --db PATH [--inbox-skill-path PATH] [--extra-instructions-file PATH]
|
||||
|
||||
Read an `orch dispatch --json` response and render a standardized worker prompt
|
||||
for a Codex sub-agent that should execute the assigned inbox thread.
|
||||
|
||||
Required:
|
||||
--dispatch-json PATH Path to the saved `orch dispatch --json` response
|
||||
--db PATH Shared SQLite DB path for both orch and inbox
|
||||
|
||||
Optional:
|
||||
--inbox-skill-path PATH Path to the inbox skill bundle. Defaults to the
|
||||
sibling project-local skill at skills/inbox
|
||||
--extra-instructions-file Append extra operator-specific instructions
|
||||
-h, --help Show this help text
|
||||
EOF
|
||||
}
|
||||
|
||||
require_command() {
|
||||
local cmd="$1"
|
||||
if ! command -v "${cmd}" >/dev/null 2>&1; then
|
||||
printf 'missing required command: %s\n' "${cmd}" >&2
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
while [ "$#" -gt 0 ]; do
|
||||
case "$1" in
|
||||
--dispatch-json)
|
||||
dispatch_json="${2:-}"
|
||||
shift 2
|
||||
;;
|
||||
--db)
|
||||
db_path="${2:-}"
|
||||
shift 2
|
||||
;;
|
||||
--inbox-skill-path)
|
||||
inbox_skill_path="${2:-}"
|
||||
shift 2
|
||||
;;
|
||||
--extra-instructions-file)
|
||||
extra_instructions_file="${2:-}"
|
||||
shift 2
|
||||
;;
|
||||
-h|--help)
|
||||
usage
|
||||
exit 0
|
||||
;;
|
||||
*)
|
||||
printf 'unknown argument: %s\n' "$1" >&2
|
||||
usage >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
require_command jq
|
||||
|
||||
if [ -z "${dispatch_json}" ] || [ -z "${db_path}" ]; then
|
||||
usage >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ ! -f "${dispatch_json}" ]; then
|
||||
printf 'dispatch json not found: %s\n' "${dispatch_json}" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ -n "${extra_instructions_file}" ] && [ ! -f "${extra_instructions_file}" ]; then
|
||||
printf 'extra instructions file not found: %s\n' "${extra_instructions_file}" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
run_id="$(jq -r '.data.attempt.run_id // .data.task.run_id // empty' "${dispatch_json}")"
|
||||
task_id="$(jq -r '.data.attempt.task_id // .data.task.task_id // empty' "${dispatch_json}")"
|
||||
attempt_no="$(jq -r '.data.attempt.attempt_no // empty' "${dispatch_json}")"
|
||||
assigned_to="$(jq -r '.data.attempt.assigned_to // .data.task.default_to // empty' "${dispatch_json}")"
|
||||
thread_id="$(jq -r '.data.attempt.thread_id // .data.thread.thread_id // empty' "${dispatch_json}")"
|
||||
worktree_path="$(jq -r '.data.attempt.worktree_path // empty' "${dispatch_json}")"
|
||||
base_ref="$(jq -r '.data.attempt.base_ref // empty' "${dispatch_json}")"
|
||||
task_title="$(jq -r '.data.task.title // empty' "${dispatch_json}")"
|
||||
task_summary="$(jq -r '.data.task.summary // empty' "${dispatch_json}")"
|
||||
leader_body="$(jq -r '.data.message.body // empty' "${dispatch_json}")"
|
||||
|
||||
if [ -z "${run_id}" ] || [ -z "${task_id}" ] || [ -z "${assigned_to}" ] || [ -z "${thread_id}" ]; then
|
||||
printf 'dispatch json is missing one or more required fields: run_id, task_id, assigned_to, thread_id\n' >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
mode="analysis"
|
||||
if [ -n "${worktree_path}" ]; then
|
||||
mode="code"
|
||||
fi
|
||||
|
||||
cat <<EOF
|
||||
Use \$inbox at ${inbox_skill_path} to act as ${assigned_to} on SQLite DB ${db_path}. Only coordinate through the bundled inbox CLI from the skill. Do not use ordinary chat to coordinate with the leader. Do not use orch.
|
||||
|
||||
You are assigned one existing attempt:
|
||||
- run_id: ${run_id}
|
||||
- task_id: ${task_id}
|
||||
- attempt_no: ${attempt_no}
|
||||
- assigned_to: ${assigned_to}
|
||||
- thread_id: ${thread_id}
|
||||
- execution_mode: ${mode}
|
||||
EOF
|
||||
|
||||
if [ -n "${task_title}" ]; then
|
||||
printf '%s\n' "- task_title: ${task_title}"
|
||||
fi
|
||||
if [ -n "${task_summary}" ]; then
|
||||
printf '%s\n' "- task_summary: ${task_summary}"
|
||||
fi
|
||||
if [ -n "${base_ref}" ]; then
|
||||
printf '%s\n' "- base_ref: ${base_ref}"
|
||||
fi
|
||||
if [ -n "${worktree_path}" ]; then
|
||||
printf '%s\n' "- worktree_path: ${worktree_path}"
|
||||
fi
|
||||
|
||||
cat <<'EOF'
|
||||
|
||||
Required workflow:
|
||||
1. Fetch or inspect the assigned thread and claim exactly the listed thread_id.
|
||||
2. Inspect the thread with show before making assumptions about the task body or payload.
|
||||
3. Send one in_progress update when real work starts.
|
||||
4. If blocked, send one precise blocked question with update --status blocked and then use wait-reply.
|
||||
5. Finish with done on success or fail on failure.
|
||||
6. Stop after reporting the handled thread_id and a concise outcome summary.
|
||||
|
||||
Rules:
|
||||
- Do not claim any other thread.
|
||||
- Keep all coordination in inbox messages, not ordinary chat.
|
||||
- Do not change the assigned_to, thread_id, or worktree assignment yourself.
|
||||
EOF
|
||||
|
||||
if [ -n "${worktree_path}" ]; then
|
||||
cat <<EOF
|
||||
- Perform repository work only inside ${worktree_path}.
|
||||
- Do not modify the leader's primary checkout outside the assigned worktree.
|
||||
EOF
|
||||
fi
|
||||
|
||||
if [ -n "${leader_body}" ]; then
|
||||
printf '\nLeader dispatch body:\n%s\n' "${leader_body}"
|
||||
fi
|
||||
|
||||
if [ -n "${extra_instructions_file}" ]; then
|
||||
printf '\nExtra instructions:\n'
|
||||
cat "${extra_instructions_file}"
|
||||
printf '\n'
|
||||
fi
|
||||
@@ -0,0 +1,52 @@
|
||||
# Leader Dispatch-And-Launch Checklist
|
||||
|
||||
Use this checklist when the leader wants durable `orch` scheduling plus a Codex sub-agent worker.
|
||||
|
||||
## Goal
|
||||
|
||||
Keep `orch` as the control plane and use a leader-side bridge to launch a worker sub-agent only after `dispatch` succeeds.
|
||||
|
||||
## Recommended Flow
|
||||
|
||||
1. initialize the shared DB once through `skills/inbox/assets/inbox --db PATH --json init`
|
||||
2. create the run and tasks with `run init`, `task add`, and `dep add`
|
||||
3. find dispatchable work with `ready`
|
||||
4. save the dispatch response:
|
||||
|
||||
```bash
|
||||
./assets/orch --db ./coord.db --json dispatch --run RUN_ID --task TASK_ID > TMPDIR/dispatch.json
|
||||
```
|
||||
|
||||
5. render a standardized worker brief:
|
||||
|
||||
```bash
|
||||
./assets/orch-worker-brief --dispatch-json TMPDIR/dispatch.json --db ./coord.db > TMPDIR/worker-brief.txt
|
||||
```
|
||||
|
||||
6. spawn one worker sub-agent with:
|
||||
- injected `skills/inbox/`
|
||||
- the generated worker brief
|
||||
- the repository defaults from `AGENTS.md`
|
||||
- model: `gpt-5.4`
|
||||
- reasoning effort: `xhigh`
|
||||
- `fork_context: true` first
|
||||
7. while the worker runs, keep the leader on:
|
||||
- `orch wait`
|
||||
- `orch status`
|
||||
- `orch blocked`
|
||||
- `orch answer`
|
||||
- `orch retry`
|
||||
- `orch reassign`
|
||||
|
||||
## Worker Launch Rules
|
||||
|
||||
- the worker should use `skills/inbox/`, not `skills/orch/`
|
||||
- the worker should claim only the exact `thread_id` from the dispatch result
|
||||
- if `worktree_path` exists, the worker should do all repository writes only inside that worktree
|
||||
- the worker should send progress, blocked questions, success, and failure through `inbox`
|
||||
|
||||
## Why This Layer Exists
|
||||
|
||||
- `orch` remains portable and durable
|
||||
- worker launch stays outside the core CLI
|
||||
- the same dispatch contract can later support Codex sub-agents, `codex exec`, daemons, or operator UI launchers
|
||||
@@ -0,0 +1,41 @@
|
||||
# Worker Brief Template
|
||||
|
||||
`assets/orch-worker-brief` renders a concrete prompt in this shape.
|
||||
|
||||
Use it when a leader has already dispatched a task and now wants to launch a worker sub-agent without hand-writing the thread handoff every time.
|
||||
|
||||
```text
|
||||
Use $inbox at INBOX_SKILL_PATH to act as ASSIGNED_TO on SQLite DB DB_PATH. Only coordinate through the bundled inbox CLI from the skill. Do not use ordinary chat to coordinate with the leader. Do not use orch.
|
||||
|
||||
You are assigned one existing attempt:
|
||||
- run_id: RUN_ID
|
||||
- task_id: TASK_ID
|
||||
- attempt_no: ATTEMPT_NO
|
||||
- assigned_to: ASSIGNED_TO
|
||||
- thread_id: THREAD_ID
|
||||
- execution_mode: analysis|code
|
||||
- task_title: ...
|
||||
- task_summary: ...
|
||||
- base_ref: ...
|
||||
- worktree_path: ...
|
||||
|
||||
Required workflow:
|
||||
1. Fetch or inspect the assigned thread and claim exactly the listed thread_id.
|
||||
2. Inspect the thread with show before making assumptions about the task body or payload.
|
||||
3. Send one in_progress update when real work starts.
|
||||
4. If blocked, send one precise blocked question with update --status blocked and then use wait-reply.
|
||||
5. Finish with done on success or fail on failure.
|
||||
6. Stop after reporting the handled thread_id and a concise outcome summary.
|
||||
|
||||
Rules:
|
||||
- Do not claim any other thread.
|
||||
- Keep all coordination in inbox messages, not ordinary chat.
|
||||
- Do not change the assigned_to, thread_id, or worktree assignment yourself.
|
||||
- If worktree_path exists, perform repository work only inside that path.
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- The template is intentionally worker-only. Leader control stays with `orch`.
|
||||
- The generated brief should be passed into a spawned worker sub-agent together with `skills/inbox/`.
|
||||
- Keep the main-thread launch parameters in the leader workflow, not in the worker brief.
|
||||
Reference in New Issue
Block a user