Agent Orchestration Workflow

AOW is a small, route-controlled orchestration package for Codex and Orca projects. It keeps run state, dispatch contracts, handoffs, evidence, gates, and worker-resource lifecycle records as plain files in .orchestration/.

Quick start

npm install -g agent-orchestration-workflow
cd /path/to/project
aow install
aow config init
aow doctor

The package has one command entrypoint. Running aow prints the compact guide; there is no interactive control surface.

Route ownership

The user selects the route in the task. No explicit route means Light and the root works directly. route medium keeps work in the root; route hard allows bounded leaf workers. Task size, model, and reasoning are dispatch metadata and never select or change the route.

Bundled worker roles are examples; .orca/agents.yaml may declare any number of ordered profiles and may repeat a role:

| Role | Responsibility | Permission | | --- | --- | --- | | planner | Scoped mapping and contract research | read-only | | implementer | Bounded code changes and checks | workspace-write | | verifier | Tests, builds, and bounded evidence | workspace-write | | reviewer | Regression, security, and acceptance review | read-only |

Model and reasoning are selected at dispatch time. Worker terminal names use {size}-{stage}-{model}-{reasoning}, for example s-impl-gpt-5-6-luna-medium.

Each version 2 profile declares role, provider, agent_cli, model_name, default_effort, allowed_efforts, and permissions. The top-level agent_clis mapping owns executable names and operation/permission-specific argv templates. AOW renders those templates directly (without a shell), with only {model}, {effort}, and {prompt} placeholders; malformed or missing metadata fails closed and never falls back to another CLI or profile. Version 1 configs are not auto-upgraded: aow config migrate previews a version 2 file, while aow config migrate --write performs an atomic, rollback-safe update.

Before a Hard launch, the root prints Tôi sẽ triển khai x tasks như sau: and one line per task with Effort, Implementer, and Reviewer values from the selected profile snapshots.

Command surface

aow                         compact orchestration guide
aow install [path]          install or update project artifacts
aow config [check|init]     inspect or create route configuration
aow init "task"             create a run
aow dispatch [options]      compile a bounded worker contract
aow events                  inspect orchestration events
aow gates                   inspect STOP gates
aow stats                   show run and worker lifecycle facts
aow doctor                  check core files and worker runtime support
aow uninstall --repo PATH   remove managed project artifacts safely

Every dispatch contract is compact and scoped. It contains the objective, owned paths, one to four exact must-read entries, confirmed facts, acceptance, validation, stop conditions, and a return format. The normal packet target is 2,500 characters and the hard limit is 4,000 characters. Missing context stops the worker with ESCALATE_TO_PARENT; workers do not expand the root context.

Install and update safety

aow install creates .skills/agent-orchestration-skill, .subagents, .orca/agents.yaml, and .orchestration/bin/aow. The bundled subagent files remain compatibility examples; the ordered project profile list is the launch authority. A modified or custom profile is preserved, and the project configuration is never overwritten.

Global Codex skill updates are staged and validated before activation. A successful update retains one timestamped .aow-backup-* rollback directory; activation failures restore the previous skill.

The installer records hashes in .orchestration/install-manifest.json so an update can distinguish AOW-owned bytes from local changes. Uninstall uses the same manifest and preserves user-owned files.

State and lifecycle

Runs, events, dispatches, handoffs, evidence, gates, and worker-resource actions remain plain JSON or JSONL files. A worker resource is explicitly stopped or released after the root validates its handoff; task completion alone does not imply resource release. The root owns routing, conflict detection, handoff synthesis, and finalization.

See the orchestration-only design, command reference, and validation guide.