145 lines
8.5 KiB
Markdown
145 lines
8.5 KiB
Markdown
---
|
|
name: orch
|
|
description: Leader-side orchestration through a bundled orch CLI. Use when an agent needs to create runs, add tasks and dependencies, find ready work, dispatch tasks, reconcile worker progress, wait for run events, inspect blocked tasks, answer them, retry or reassign failures, or clean up attempt worktrees through a SQLite-backed orchestration database instead of hand-driving inbox threads.
|
|
---
|
|
|
|
# Orch
|
|
|
|
Use the bundled `./assets/orch` CLI to control leader-side orchestration through `orch`.
|
|
|
|
## Mental Model
|
|
|
|
- `orch` is the leader control plane. It owns runs, tasks, attempts, dependencies, and scheduling state.
|
|
- `dispatch` creates an attempt and an `inbox` thread. It does not launch a worker by itself.
|
|
- After `dispatch`, a separate worker runtime or worker agent should consume the assigned thread through `skills/inbox/`.
|
|
- Use `orch` for planning and control. Use `inbox` for claim, progress, blocked questions, replies, and final results.
|
|
|
|
## Good Fit
|
|
|
|
- parallel work with `2` to `5` bounded subtasks
|
|
- runs that may block, retry, or need reassignment
|
|
- work where durable task state matters more than ad hoc chat coordination
|
|
|
|
## Bad Fit
|
|
|
|
- one tiny exploratory subtask
|
|
- work with no need for a run, thread, or retryable attempt record
|
|
- flows where leader-side scheduling would be more ceremony than value
|
|
|
|
## Quick Start
|
|
|
|
- Invoke `./assets/orch` relative to this skill directory.
|
|
- Pass `--db` explicitly for every command.
|
|
- Prefer `--json` whenever another agent or script will read the output.
|
|
- The bundled CLI help is intended to be self-describing; start with `./assets/orch --help` or `./assets/orch <command> --help` when you need command usage.
|
|
- 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
|
|
|
|
- Prefer `orch` over hand-written `inbox send` for normal leader operations.
|
|
- Treat `dispatch` as handoff, not execution. After dispatch, arrange a separate worker runtime or worker agent to claim the mapped inbox thread.
|
|
- For analysis, review, or other read-only tasks, dispatch with `--execution-mode analysis`.
|
|
- If nothing is actionable, use `wait` instead of manual sleep loops.
|
|
- For code tasks, dispatch with `--execution-mode code` from a committed base and allocate a fresh worktree per attempt.
|
|
- Use `blocked` and `answer` to resolve worker questions through the active attempt thread.
|
|
- Use `retry` or `reassign` only after checking the latest task and attempt state.
|
|
- Use `inbox` directly only for inspection or manual repair, not routine scheduling.
|
|
- If the local sandbox blocks SQLite writes, request escalation before the first real `orch` or `inbox` run against the shared DB.
|
|
|
|
## Leader Loop
|
|
|
|
1. Initialize the shared DB once with `../inbox/assets/inbox --db PATH --json init`.
|
|
2. Create the run and tasks through `run init`, `task add`, and `dep add`.
|
|
3. Use `ready` to find dispatchable work.
|
|
4. `dispatch` a task and capture the returned attempt metadata such as `thread_id`, `assigned_to`, and any worktree fields.
|
|
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 --execution-mode analysis > 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.
|
|
- The leader should pass or preserve the `dispatch` result, especially `attempt.thread_id`, `attempt.assigned_to`, and worktree metadata when present.
|
|
- Code-writing workers should execute inside the assigned worktree path from the task payload or attempt metadata.
|
|
- Read-only or analysis workers should be dispatched with `--execution-mode analysis` and stay on the normal thread-only path with no worktree.
|
|
|
|
## Typical Commands
|
|
|
|
```bash
|
|
../inbox/assets/inbox --db ./coord.db --json init
|
|
./assets/orch --db ./coord.db --json run init --run blog_mvp_001 --goal "Build blog MVP" --summary "Public blog plus admin CRUD"
|
|
./assets/orch --db ./coord.db --json task add --run blog_mvp_001 --task T1 --title "Project skeleton" --summary "Initialize app structure and database wiring" --default-to foundation-worker
|
|
./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 --execution-mode code --to foundation-worker --base-ref main --workspace-root .orch/worktrees --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 --execution-mode analysis --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
|
|
./assets/orch --db ./coord.db --json answer --run blog_mvp_001 --task T2 --body "MVP supports draft and published only."
|
|
./assets/orch --db ./coord.db --json retry --run blog_mvp_001 --task T7a --to backend-worker --body "Retry after fixing the contract mismatch."
|
|
./assets/orch --db ./coord.db --json cleanup --run blog_mvp_001 --all-completed
|
|
```
|
|
|
|
## Command Map
|
|
|
|
- `run init`: create a new orchestration run
|
|
- `run show`: inspect run metadata and aggregate task counts
|
|
- `task add`: add a task to a run
|
|
- `dep add`: record a task dependency
|
|
- `ready`: list tasks that are ready for dispatch
|
|
- `dispatch`: create an attempt and inbox thread for a ready task
|
|
- `reconcile`: fold worker thread state back into orch task state explicitly
|
|
- `wait`: block until matching run events arrive
|
|
- `blocked`: list blocked tasks and their latest questions
|
|
- `answer`: send a leader answer into the active blocked attempt
|
|
- `retry`: create a fresh attempt for a failed task
|
|
- `reassign`: cancel the current attempt and dispatch a new one to another worker
|
|
- `cancel`: cancel a task or entire run
|
|
- `cleanup`: remove completed or abandoned worktrees
|
|
- `status`: reconcile first, then inspect the full run summary, task list, latest attempt, and latest message context
|
|
|
|
## Notes
|
|
|
|
- `dispatch` requires `--execution-mode analysis|code`.
|
|
- `dispatch` supports `--repo-path`, `--workspace-root`, and `--base-ref` for `--execution-mode code`.
|
|
- `./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.
|