orchestrate · diff
git:20260618.e5d9fc8 to git:20260922.5ace6ba
126 added, 49 removed. Audit A to A.
---
name: orchestrate
- description: 'Out-of-session orchestration instrument lane: route, preflight, verify before human atm/am procedure. Triggers: "orchestrate out-of-session", "route + preflight + verify a run", "orchestration preflight".'
- practices:
- - team-topologies
- - hexagonal-architecture
+ description: 'Coordinate authorized workers, prerequisites, isolated scopes and review capacity. Use when: dispatching, recovering or routing feedback. Not for implementation or judgment.'
+ practices: [team-topologies, evidence-based-engineering]
hexagonal_role: supporting
- consumes:
- - automation-shape-routing
- produces:
- - result.json
- context_rel:
- - kind: customer-of
- with: using-atm
+ consumes: [accepted-intent, native-work-state, candidate-evidence]
+ produces: [native-handoffs, reconciled-feedback]
+ context_rel: []
skill_api_version: 1
user-invocable: true
- context:
- window: isolated
- intent:
- mode: task
- sections:
- exclude:
- - HISTORY
metadata:
- tier: orchestration
- dependencies:
- - automation-shape-routing
- output_contract: schemas/orchestration-instrument.v1.schema.json
+ graph_root: true
+ tier: execution
+ dependencies: []
+ capabilities: [coordinate_native_work, recover_assignments, reconcile_feedback]
+ effects: [dispatch_authorized_workers, update_native_handoffs]
+ canonical_status: canonical
+ disposition: keep
+ output_contract: observed native assignments, exact candidate and judgment references, affected-work handoffs and explicit remaining gaps
---
- # Orchestrate — Out-of-Session Instrument Lane
+ # Orchestrate
- When work escalates **outside** the in-session loop, start with deterministic
- instruments — not a parallel spawn manual.
+ Coordinate caller-authorized work through its existing tracker and runtime.
+ Use the accepted task or conversation; a clear task needs zero mandatory skills.
+ Selecting Orchestrate adds in-session guidance, not an AgentOps scheduler, work
+ index, queue, ownership system, aggregate retry controller or delivery authority.
+ The caller's tracker owns assignments and dependencies; its runtime owns running
+ contexts, bounds and supervision; repository policy owns integration and delivery.
- ## Procedure
+ ## Recover the actual work
- 1. **Route** — `ao orchestrate route --json` (or `--writers N --models opus,codex,agy`)
- 2. **Preflight** — `ao orchestrate preflight --profile <name> --json`
- 3. **Spawn** — follow the profile in `docs/contracts/orchestration-profiles.yaml` using raw `atm` (human procedure; see `using-atm` / `dual-pane-atm`)
- 4. **Verify** — `ao orchestrate verify --session <name> --profile <name> --json`
+ Read the accepted outcome, examples and scope from their current owner. Recover
+ settled caller choices and rationale, completed history, consequential open
+ questions and the next investigation from the existing native handoff. Do not
+ repeat settled interviews or require the full transcript. Missing or contradictory
+ pointers require source investigation, not a guessed decision.
- Profiles contract is SOT; skills are drift-gated procedure, not CLI replacements.
+ Before dispatch, inspect actual prerequisite content in the intended checkout,
+ its identity and applicable evidence. A closed prerequisite whose bytes are
+ missing, stale or unavailable is not usable readiness. Resolve that gap before
+ dependent execution; preserve its native status and report the distinction.
- ## Commands
+ Inspect native assignments and runtime state together: task acceptance, observed
+ worker/context identity, workspace and starting content, occupied write scope,
+ pending checks and review, current candidate identity, and integration owner.
+ Include active validators as well as writers. An empty ready list does not prove
+ completion. A replacement coordinator reconciles these facts before resuming;
+ it must not duplicate an assignment because its prior conversation is absent.
- | Command | Role |
- |---------|------|
- | `ao orchestrate route` | Posture → profile recommendation |
- | `ao orchestrate preflight` | Admission gate before spawn |
- | `ao orchestrate verify` | Post-spawn windshield |
- | `ao orchestrate tools` | Tool matrix probe |
- | `ao orchestrate status` | Active ATM sessions |
- | `ao orchestrate shape` | Stamp execution-packet shape |
- | `ao orchestrate select` | Backend ladder (existing) |
+ ## Choose the next useful dispatch
- ## Non-goals
+ Concurrency follows the observed bottleneck. Inspect work waiting for checks,
+ repair, integration or independent judgment before adding implementation. A free
+ runtime slot alone is not a dispatch reason. Reserve capacity for integration,
+ review and repair; reduce new starts while candidates accumulate. Record only
+ the concrete constraint and next action in the existing native handoff, then
+ reassess when evidence changes. Do not add a capacity ledger or queue.
- - Does not replace `atm spawn` in Phase 1 (earn-it wrappers deferred)
- - Does not mandate orchestrate via hook on day one
+ Use [Agent Native](../agent-native/SKILL.md) for runtime mechanics: executor
+ selection, startup/engagement evidence, actual context identity, normalized
+ scopes, native waits and follow-up, bounds and cleanup. Its optional adapters
+ retain those methods; Orchestrate does not copy or replace them. Concurrent
+ writers require disjoint write scopes and separate isolation, including generated
+ companions and transitive effects. Serialize shared paths. A worktree separates
+ Git edits; it does not establish restricted-source or model-egress enforcement.
- ## References
+ Dispatch a genuinely fresh implementer for one coherent accepted task, without
+ the coordinator's accumulated transcript or unrelated research. A new goal,
+ role label, cleared summary or resumed author context is not a fresh context.
+ Pass the accepted examples, applicable constraints, exact starting content,
+ usable prerequisites, authorized write/output scope, relevant source pointers,
+ required checks, integration responsibility and real remaining bounds. Expand
+ pointers when needed; brevity cannot omit a constraint. Record observed native
+ identity at startup through Agent Native's existing association procedure.
- - Acceptance: `references/orchestrate.feature`
- - Contract: `docs/contracts/orchestration-profiles.yaml`
- - Playbook: `skills/dual-pane-atm/`
- - Substrate: `skills/using-atm/`
+ [Implement](../implement/SKILL.md) owns the complete change, meaningful checks
+ and direct repair. It is optional guidance for that worker, not a compulsory
+ stage. The handoff returns candidate identity, changed scope, check facts,
+ discoveries and gaps. Successful prompt delivery or worker exit proves neither
+ engagement nor acceptance.
+
+ ## Integrate and obtain judgment
+
+ Name the integration and final-validation responsibility before launch. Follow
+ the consumer repository's integration policy, include all changed paths and
+ generated companions, and run affected checks on the actual integrated subject.
+ Acceptance of a leaf does not establish the combined release.
+
+ Assign fresh author-distinct judgment of the exact candidate against unchanged
+ acceptance through [Validate](../validate/SKILL.md), the sole skill owner of
+ acceptance semantics. Its identity, freshness, complete checked scope and
+ evidence requirements remain authoritative; preserve every explicitly required
+ review leg. Advisory Review, Plan challenge and Council advice are not binding
+ acceptance, and must be refused when offered in place of that judgment.
+ Changed candidate bytes invalidate the old subject binding and require judgment
+ of the new exact subject. Deterministic green or convincing author rationale
+ cannot fill missing proof. No report format or persisted artifact is mandatory
+ unless the caller or an existing consumer requires one.
+
+ ## Reconcile feedback and resume
+
+ Preserve successful and failed evidence in the existing native task or handoff.
+ Identify affected unfinished work and update its native dependencies or handoff
+ within authority. Stop or explicitly re-scope an affected active assignment
+ before it continues on a disproven premise; obtain observable acknowledgment or
+ stopped runtime state before treating the revision as effective. Unaffected work
+ continues unchanged. Repeating reconciliation with unchanged facts creates no
+ new artifact or dispatch.
+
+ [Plan](../plan/SKILL.md) owns consequential uncertainty, optional challenge and
+ refining the next complete slice. Reuse settled decisions and accepted examples;
+ new evidence may change an approach within the accepted outcome. A different
+ promised outcome or authority choice returns to the caller. Agent advice cannot
+ supply that choice. Preserve completed history instead of reopening accepted
+ work merely to fit a revised story.
+
+ Known failures return to the responsible task for direct repair. On a genuine
+ causal stall, the existing operating contract permits at most one authorized
+ bounded fresh helper for that incident within remaining bounds; an unhelpful
+ answer ends that attempt. Cancellation, refusal or exhausted bounds skip help.
+ Replacement workers, retries, new subjects and compaction never reset those
+ bounds. Inspect native evidence before replacing a worker; use native waits for
+ unchanged pending state instead of repeated analysis or probes.
+
+ When maintained context could change the next action, selectively use
+ [Memory find/recall](../memory/references/recall.md). A supported correction may
+ use its [capture](../memory/references/mine-learn.md) and
+ [curation](../memory/references/curate.md) procedures. Memory retains admission,
+ support/disclosure review and context ownership; no automatic lesson, private
+ import or mandatory recall follows from coordination. No change is valid, and
+ context capture alone proves no benefit.
+
+ ## Selected external factory
+
+ Keep the selected factory's coordinator in control. Hand it the caller-authorized
+ source intent through its supported door; the coordinator creates its workflow
+ and dispatches internal runs. For Gas City, use the Mayor through
+ [Using GC](../using-gc/SKILL.md). Do not manufacture, scale or repair internal
+ sessions by hand, or mirror factory work in an AgentOps tracker. Doctor and
+ supervisor operations use the factory's supported external doors within caller
+ authority. Read native state, recover through that coordinator and judge the
+ returned exact content independently. Factory completion does not authorize
+ delivery or establish acceptance.