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

Improve orch status reconciliation view

Browse Source
This commit is contained in:
kurihada
2026-03-20 17:57:58 +08:00
parent 693a79345b
commit cf3c3cbe60
11 changed files with 374 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/orch/SKILL.md
+47 -4
View File
@@ -7,32 +7,74 @@ description: Leader-side orchestration through a bundled orch CLI. Use when an a
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.
- 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.
- 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.
- 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, omit worktree flags so dispatch stays thread-only and light.
- 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.
- 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.
## 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 can 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 --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 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 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."
@@ -48,7 +90,7 @@ Use the bundled `./assets/orch` CLI to control leader-side orchestration through
- `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
- `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
@@ -56,11 +98,12 @@ Use the bundled `./assets/orch` CLI to control leader-side orchestration through
- `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
- `status`: reconcile first, then inspect the full run summary, task list, latest attempt, and latest message context
## Notes
- `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.
- `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.
skills/orch/agents/openai.yaml
+1 -1
View File
@@ -1,7 +1,7 @@
interface:
display_name: "Orch CLI"
short_description: "Leader-side orchestration CLI"
default_prompt: "Use $orch to manage orchestration runs through the bundled orch CLI and a SQLite orchestration database."
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."
policy:
allow_implicit_invocation: true