67 lines
3.9 KiB
Markdown
67 lines
3.9 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`.
|
|
|
|
## 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.
|
|
- 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.
|
|
- Reconcile inbox state before making new dispatch decisions.
|
|
- If nothing is actionable, use `wait` instead of manual sleep loops.
|
|
- For code tasks, dispatch 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.
|
|
|
|
## Typical Commands
|
|
|
|
```bash
|
|
./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 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 reconcile --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
|
|
- `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`: inspect the full run summary and task list
|
|
|
|
## Notes
|
|
|
|
- `dispatch` supports `--repo-path`, `--workspace-root`, `--strict-worktree`, and `--base-ref` for worktree-backed code execution.
|
|
- `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.
|