Add orch and council-review skills
This commit is contained in:
@@ -157,5 +157,5 @@ Do not put these into `orch`:
|
||||
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`
|
||||
- `orchestrator` 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`
|
||||
- `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`
|
||||
- `council-review` skill: used when the user explicitly wants a structured three-reviewer brainstorm or review with grouped and tallied recommendations
|
||||
|
||||
@@ -35,7 +35,7 @@ Dependencies:
|
||||
|
||||
## Who Uses What
|
||||
|
||||
- leader uses the `orchestrator` skill and `orch` CLI
|
||||
- leader uses the `orch` skill and `orch` CLI
|
||||
- workers use the `inbox` skill and `inbox` CLI
|
||||
- `orch` is the leader's main interface
|
||||
- `inbox` is the worker's main interface
|
||||
|
||||
@@ -23,8 +23,10 @@ As of now:
|
||||
- a human-readable inbox command test-plan set has been authored under `docs/tests/inbox/`
|
||||
- a human-readable `orch` test-plan set has now been authored under `docs/tests/orch/`, with a `ROADMAP.md`, shared conventions, workflow scenarios, per-command indexes, and concrete case documents aligned to the current CLI surface, including supplemental coverage for key flag validation, ordering/limit behavior, payload-only answers, cleanup errors, and council report default/error contracts
|
||||
- a reusable Codex skill package for `inbox` now exists under `skills/inbox/`, with a formal `SKILL.md`, `agents/openai.yaml`, and a bundled CLI binary asset
|
||||
- reusable Codex skill packages for `orch` and `council-review` now exist under `skills/orch/` and `skills/council-review/`, both using bundled copies of the `orch` CLI binary asset
|
||||
- an inbox skill forward-test plan directory now exists under `docs/tests/inbox-skill/`, with a shared execution template and multiple scenario cases
|
||||
- an execution-roadmap workflow now exists under `docs/roadmaps/active/` and `docs/roadmaps/archive/` for agent-level work traces and completion archives
|
||||
- a repo-local `scripts/package_skill_clis.sh` packaging flow now builds bundled skill CLI assets for `inbox`, `orch`, and `council-review`
|
||||
- `orch` now implements `run init/show`, `task add`, `dep add`, `ready`, `dispatch`, `reconcile`, `wait`, `blocked`, `answer`, `retry`, `reassign`, `cancel`, `cleanup`, and `status`
|
||||
- `orch` can create runs, gate tasks through dependencies, dispatch work through `inbox`, reconcile worker thread state back into task state, answer blocked tasks, retry or reassign work, cancel tasks or runs, clean attempt worktrees, and create per-attempt Git worktrees during strict dispatch
|
||||
- `orch dispatch` now supports `--repo-path`, `--workspace-root`, and `--strict-worktree`, auto-enables strict worktree mode for code-like tasks inferred from task metadata, resolves committed base revisions, records workspace metadata on attempts, and writes that metadata into inbox task payloads
|
||||
|
||||
+1
-1
@@ -476,7 +476,7 @@ The following block is a draft `SKILL.md` for the `inbox` skill.
|
||||
```markdown
|
||||
---
|
||||
name: inbox
|
||||
description: Use this skill when an agent needs durable communication through the local inbox CLI. It is for fetching work, claiming a thread, sending progress updates, raising blocked questions, waiting for replies, replying inside a thread, returning results, and watching inbox activity. Do not use it for task decomposition or scheduling decisions; use the orchestrator skill for that.
|
||||
description: Use this skill when an agent needs durable communication through the local inbox CLI. It is for fetching work, claiming a thread, sending progress updates, raising blocked questions, waiting for replies, replying inside a thread, returning results, and watching inbox activity. Do not use it for task decomposition or scheduling decisions; use the orch skill for that.
|
||||
---
|
||||
|
||||
# Inbox
|
||||
|
||||
+3
-3
@@ -555,16 +555,16 @@ CREATE INDEX IF NOT EXISTS idx_events_run_event
|
||||
|
||||
## Embedded Skill Draft
|
||||
|
||||
The following block is a draft `SKILL.md` for the leader-facing orchestration skill.
|
||||
The following block is a draft `SKILL.md` for the leader-facing `orch` skill.
|
||||
|
||||
````markdown
|
||||
```markdown
|
||||
---
|
||||
name: orchestrator
|
||||
name: orch
|
||||
description: Use this skill when the leader needs to plan and schedule work through the orch CLI. It is for creating runs, adding tasks and dependencies, finding ready work, dispatching tasks to workers, allocating task worktrees, reconciling inbox state, waiting for worker events, reviewing blocked tasks, answering them, retrying failures, reassigning work, and cleaning up attempt worktrees. Do not use this skill for worker-side claim or progress updates; use inbox for that.
|
||||
---
|
||||
|
||||
# Orchestrator
|
||||
# Orch
|
||||
|
||||
Use this skill when you are the leader and need to control the task graph through the `orch` CLI.
|
||||
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
# Title
|
||||
|
||||
Add Orch And Council Review Skills With Bundled CLI Assets
|
||||
|
||||
## Status
|
||||
|
||||
- `completed`
|
||||
|
||||
## Owner
|
||||
|
||||
- Codex main agent
|
||||
|
||||
## Started At
|
||||
|
||||
- `2026-03-19`
|
||||
|
||||
## Goal
|
||||
|
||||
- Add project-local skill packages for `orch` and `council-review`.
|
||||
- Add a repeatable packaging flow that builds the `orch` CLI binary and installs it into both skills as bundled assets.
|
||||
|
||||
## Scope
|
||||
|
||||
- Create `skills/orch/` with `SKILL.md`, `agents/openai.yaml`, and bundled `assets/orch`.
|
||||
- Create `skills/council-review/` with `SKILL.md`, `agents/openai.yaml`, and bundled `assets/orch`.
|
||||
- Add a repo-local packaging script for building and copying the `orch` CLI binary into both skill asset directories.
|
||||
- Update implementation progress docs to reflect the new skill packages and packaging flow.
|
||||
|
||||
## Checklist
|
||||
|
||||
- [x] Review current skill structure, embedded skill drafts, and bundling expectations.
|
||||
- [x] Create `orch` skill package files.
|
||||
- [x] Create `council-review` skill package files.
|
||||
- [x] Add and validate the CLI packaging script.
|
||||
- [x] Build bundled `orch` binaries into both skills and smoke-check them.
|
||||
- [x] Update roadmap docs and archive this execution roadmap.
|
||||
|
||||
## Files
|
||||
|
||||
- `skills/orch/SKILL.md`
|
||||
- `skills/orch/agents/openai.yaml`
|
||||
- `skills/orch/assets/orch`
|
||||
- `skills/council-review/SKILL.md`
|
||||
- `skills/council-review/agents/openai.yaml`
|
||||
- `skills/council-review/assets/orch`
|
||||
- `scripts/package_skill_clis.sh`
|
||||
- `docs/architecture.md`
|
||||
- `docs/blog-project-example.md`
|
||||
- `docs/inbox-cli.md`
|
||||
- `docs/orch-cli.md`
|
||||
- `docs/implementation-roadmap.md`
|
||||
- `docs/roadmaps/archive/orch-council-skills.md`
|
||||
|
||||
## Decisions
|
||||
|
||||
- Use one underlying `orch` binary for both skills, because `council` is an `orch` subcommand rather than a separate executable.
|
||||
- Keep each skill self-contained by bundling its own copy of the `orch` binary asset.
|
||||
- Keep the packaging script able to refresh the existing `inbox` skill binary as well, so all bundled CLIs can be rebuilt through one entrypoint.
|
||||
- Standardize on the actual implemented skill name `orch` rather than the older draft term `orchestrator`.
|
||||
|
||||
## Blockers
|
||||
|
||||
- none
|
||||
|
||||
## Next Step
|
||||
|
||||
- none
|
||||
|
||||
## Completion Summary
|
||||
|
||||
- Added `skills/orch/` and `skills/council-review/`, each with `SKILL.md`, `agents/openai.yaml`, and a bundled `assets/orch` binary.
|
||||
- Added `scripts/package_skill_clis.sh` to rebuild bundled skill CLIs for `inbox`, `orch`, and `council-review`.
|
||||
- Built and smoke-checked the new `orch` skill assets with `./skills/orch/assets/orch --help` and `./skills/council-review/assets/orch council --help`.
|
||||
- Updated implementation and reference docs to use the actual `orch` skill name and to record the new skill packages and packaging flow.
|
||||
Executable
+72
@@ -0,0 +1,72 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
readonly REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||
readonly BUILD_DIR="$(mktemp -d "${TMPDIR:-/tmp}/skill-clis.XXXXXX")"
|
||||
|
||||
cleanup() {
|
||||
rm -rf "${BUILD_DIR}"
|
||||
}
|
||||
|
||||
trap cleanup EXIT INT TERM
|
||||
|
||||
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
|
||||
}
|
||||
|
||||
build_binary() {
|
||||
local name="$1"
|
||||
local package_path="$2"
|
||||
local output_path="${BUILD_DIR}/${name}"
|
||||
|
||||
printf 'building %s from %s\n' "${name}" "${package_path}" >&2
|
||||
(
|
||||
cd "${REPO_ROOT}"
|
||||
go build -trimpath -o "${output_path}" "${package_path}"
|
||||
)
|
||||
|
||||
printf '%s\n' "${output_path}"
|
||||
}
|
||||
|
||||
install_binary() {
|
||||
local source_path="$1"
|
||||
shift
|
||||
|
||||
local destination_path
|
||||
for destination_path in "$@"; do
|
||||
mkdir -p "$(dirname "${destination_path}")"
|
||||
install -m 0755 "${source_path}" "${destination_path}"
|
||||
printf 'installed %s\n' "${destination_path}"
|
||||
done
|
||||
}
|
||||
|
||||
main() {
|
||||
require_command go
|
||||
require_command install
|
||||
require_command mktemp
|
||||
|
||||
local inbox_binary
|
||||
local orch_binary
|
||||
|
||||
inbox_binary="$(build_binary inbox ./cmd/inbox)"
|
||||
orch_binary="$(build_binary orch ./cmd/orch)"
|
||||
|
||||
install_binary \
|
||||
"${inbox_binary}" \
|
||||
"${REPO_ROOT}/skills/inbox/assets/inbox"
|
||||
|
||||
install_binary \
|
||||
"${orch_binary}" \
|
||||
"${REPO_ROOT}/skills/orch/assets/orch" \
|
||||
"${REPO_ROOT}/skills/council-review/assets/orch"
|
||||
|
||||
printf 'skill CLI packaging complete\n'
|
||||
}
|
||||
|
||||
main "$@"
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: council-review
|
||||
description: Structured three-reviewer brainstorming and review through a bundled orch CLI. Use when an agent needs a high-level council workflow on top of orch to launch reviewer roles, wait for their outputs, tally grouped recommendations, and report consensus, majority, and minority findings.
|
||||
---
|
||||
|
||||
# Council Review
|
||||
|
||||
Use the bundled `./assets/orch` CLI to run the high-level `orch council ...` workflow.
|
||||
|
||||
## 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.
|
||||
- Treat this skill as a high-level workflow on top of `orch`, not as a separate infrastructure layer.
|
||||
|
||||
## Reviewer Roles
|
||||
|
||||
- `architecture-reviewer`
|
||||
- `implementation-reviewer`
|
||||
- `risk-reviewer`
|
||||
|
||||
## Rules
|
||||
|
||||
- Use this skill when the user explicitly wants a multi-reviewer brainstorm or review.
|
||||
- Treat the workflow as analysis-first unless the user explicitly asks for patch proposals or code-change recommendations.
|
||||
- Use `orch council` as the execution surface for start, wait, tally, and report.
|
||||
- Default to the fixed reviewer roles architecture, implementation, and risk.
|
||||
- Collect all three reviewer outputs before tallying.
|
||||
- Use `normal` similarity unless the user asks for stricter grouping.
|
||||
- If the user asks for unanimous-only output, rely on `--only-unanimous` and expect default report output to show only `consensus`.
|
||||
- Otherwise present `consensus` first, then `majority`, and include `minority` when requested.
|
||||
- Support text, repository, mixed, or task-target context when available.
|
||||
|
||||
## Typical Commands
|
||||
|
||||
```bash
|
||||
./assets/orch --db ./coord.db --json council start --run council_blog_001 --target-file brief.md --target-type mixed --mode brainstorm --output both
|
||||
./assets/orch --db ./coord.db --json council wait --run council_blog_001 --timeout-seconds 900
|
||||
./assets/orch --db ./coord.db --json council tally --run council_blog_001 --similarity normal
|
||||
./assets/orch --db ./coord.db --json council report --run council_blog_001 --show consensus,majority
|
||||
```
|
||||
|
||||
## Command Map
|
||||
|
||||
- `council start`: create the council run and dispatch the three reviewer tasks
|
||||
- `council wait`: block until all reviewers finish or timeout is reached
|
||||
- `council tally`: parse reviewer outputs, group similar findings, and count support
|
||||
- `council report`: render the final grouped council output and persist report metadata
|
||||
|
||||
## Notes
|
||||
|
||||
- This skill depends on the underlying `orch` orchestration model and persists its run state, grouped findings, and report metadata there.
|
||||
- Use `council wait` before `council tally`, and `council tally` before `council report`.
|
||||
- `council report` defaults to `consensus,majority`, except unanimous-only runs where the default is `consensus`.
|
||||
- If the bundled binary cannot execute on the current host, stop and report the compatibility issue instead of guessing a replacement path or workflow.
|
||||
@@ -0,0 +1,7 @@
|
||||
interface:
|
||||
display_name: "Council Review CLI"
|
||||
short_description: "Three-reviewer workflow on top of orch"
|
||||
default_prompt: "Use $council-review to run the high-level orch council workflow through the bundled orch CLI and a SQLite orchestration database."
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: true
|
||||
Executable
BIN
Binary file not shown.
@@ -0,0 +1,66 @@
|
||||
---
|
||||
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.
|
||||
@@ -0,0 +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."
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: true
|
||||
Executable
BIN
Binary file not shown.
Reference in New Issue
Block a user