add-orchestrator

name	add-orchestrator
description	Make any agent a system-aware orchestrator — installs /discover-agents (discover the fleet from live Trinity and/or a repo list into a descriptive fleet/system-map.yaml), /compose-system (turn the map into a Trinity SystemManifest and deploy_system), and /orchestrate (route, fan out, and run ephemeral agents via Trinity MCP). Aligns with Trinity's existing SystemManifest; no parallel standard.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill
user-invocable	true
argument-hint	[--check]
metadata	{"version":"1.26","created":"2026-07-01T00:00:00.000Z","author":"Ability.ai","changelog":["1.26: Bundled templates learn the deploy-as-is → onboard-in-place ladder for spec-less catalog repos (trinity#1704 / ent#411): discover-agents 1.9 reports them under `no spec:` with the fix, compose-system 1.4 resolves them to `github:Org/repo` anyway and hands each a post-deploy `/trinity:onboard in-place` playbook call, orchestrate 1.15 states what a spec-less ephemeral arrives without and when the ladder (not an ephemeral) is the right tool. Companion to trinity plugin 2.8.0 (onboard 6.0 in-place mode + plugins: block, sync 2.7.0 plugin reconcile)","1.25: Refresh the Check-mode illustrations to the post-back-port bundle (1.23 moved profile-fleet to 1.6 and sync-fleet-to-head to 1.4; 1.21 moved discover-agents to 1.8 and orchestrate to 1.14), so the example report and the Step 4 overwrite-prompt samples no longer show version pairs that contradict the versions this bundle actually ships. Illustration-only — no logic change. The `--autonomous` gate the 1.24 convention section promises is now live in the marketplace manager's /audit-wizards v1.3 (abilities#6)","1.24: Document the bundle-wide `--autonomous` run-mode convention (issue #6) — the canonical contract the per-skill instances (`/sync-fleet-to-head` v1.4, `/profile-fleet` v1.6, back-ported in #5) now point at instead of each re-deriving it: mode comes from `$ARGUMENTS` never a caller's prose; in autonomous mode the skill never calls `AskUserQuestion`, takes the safe default at each gate, never takes a destructive/irreversible path a gate was protecting, and turns a non-trivial decision into a `needs-attention` line rather than a guess. The invariant that *earns* the mode is that every below-the-gate action is non-destructive by construction. Promotes what corbin invented per-skill on live crons into a documented marketplace convention, so a gated skill on an unattended cron stops blocking on an unseen prompt and burning its whole timeout. Enforcement is mechanical: `/audit-wizards` flags any `automation: gated` skill listed in a `schedules:` block without a declared autonomous mode. (Versions 1.21–1.23 are the other in-flight PRs #9/#8/#5.)","1.23: Back-port the two stranded runtime skills from the production orchestrator (issue #5), closing the field-hardening back-flow gap. /sync-fleet-to-head 1.0 → 1.4 (post-pull sync-state cache-lag note, two 409 subtypes — unstaged vs unmerged files, 400 submodule-fetch recovery row, and a --autonomous run mode). /profile-fleet 1.4 → 1.6 (autonomy-toggle cross-check — enabled schedules + autonomy_enabled:false is a silent no-op — and a --autonomous run mode; allowed-tools gains get_schedule_executions to match the new body). Universalized rather than swapped verbatim: dropped the corbin-specific Step 0 refresh_workspace.sh scaffolding and re-homed profile-fleet's autonomous correction queue from corbin's fleet-gap-analysis/status.yaml onto the bundle's own /fleet-reconcile convention (.claude/skills/profile-fleet/status.yaml). The --autonomous mode is landed per-skill here; its promotion to a bundle-wide convention + an /audit-wizards gate is issue #6. (Version takes 1.23 to sit above the in-flight 1.21 reserved for PR #7/#9 and 1.22 for issue #8.)","1.22: Install-time divergence detection (issue #8) — a read-only `--check` mode compares every installed runtime skill against its bundled template on three axes: `installed < bundled` (upgrade available), `installed > bundled` (BACK-PORT candidate — the field-hardened copy the marketplace should pull from, the signal issue #5 went weeks without), and equal version but differing content (local customization). Reported in the canon-doctor PASS/WARN/FAIL shape with a one-line fleet-readable verdict. Step 4's per-skill overwrite prompt now runs the same comparison, so the warning — a silent downgrade or an about-to-be-clobbered local edit — arrives at the moment of decision, not after. Deliberately scoped to add-orchestrator's own bundle and stateless; the plugin-framework-wide version is a separate follow-up. (Version skips 1.21, reserved for the open PR #7/#9.)","1.21: allowed-tools↔body drift fixes (issue #7) — /discover-agents v1.8 adds mcp__trinity__report to its grant (the Step 7 fleet_scan report was in the body but ungranted, silently never publishing under enforcement); /orchestrate v1.14 drops the three vestigial schedule tools (create/delete/list_agent_schedule) the v1.7 watchdog stopped using. Both are grant-vs-body hygiene, no behaviour change","1.20: orchestrate template 1.13 — dispatch is a one-line playbook call resolved from the target's live get_agent_skills catalog (fleet convention protocols/playbook-call.md); prose briefs are the recorded exception","1.19: Platform caveat rewritten for ent#89 (materialized at creation, disabled unless a literal YAML true, max 20, deduped by name, never re-applied on recreate) and the steward entry now scaffolds enabled: false so a template-derived agent cannot silently inherit an armed unattended sweep. Dropped the non-schema `id:` key in favour of `name:` as the identity key. Steward cadence no longer claims 'server-local time' — schedules and the container clock are both UTC (#1795), and legacy IANA aliases now 500 on create (#1823). Bundled /orchestrate → v1.12 (rooms + A2A routing)","1.18: Bundled /orchestrate v1.11 — event-choreography layer for standing 'whenever X happens, have Y react' asks (fourth routing pattern next to Single/Fan-out/Chain): custom domain events via emit_event alongside the #1578 backend terminals, subscriptions wired SELF-SERVICE (subscribe_to_event always subscribes the caller — the orchestrator dispatches the setup task to the subscriber, never subscribes on-behalf), edges recorded in orchestration.md §6, and four unenforced design rules (exact-triple match/no wildcards; no loop guard outside agent.task.* — custom event graphs must stay acyclic; wakes reach only running subscribers, at-most-once/no replay; interpolated payloads are a cross-agent injection surface). Allowed-tools catches up: event tools + the set_reminder/cancel_reminder the v1.7 watchdog already instructed","1.17: Step 9 summary separates the two GitHub tokens a deployed orchestrator depends on — the INSTANCE token (Settings → GitHub token) is what Trinity clones `github:` members with (the default create_agent/deploy_system path, required for private repos), while GH_TOKEN in the agent's .env only authenticates the agent's own gh/git calls; a private-repo fleet needs both. Bundled runtime skills: compose-system 1.3 + orchestrate 1.10 (repository-first members and rollouts)","1.16: Loop closure across the bundle — fleet/project-standard.md gains §12 (silence is a failure mode, both directions: the agent closes its loops with the operator; the operator is handed the loops only a human can close with people or agents outside the fleet), a waiting-on:<actor> label, the ### Waiting on / ### Loop closed comment formats, and a 3d/7d/14d nudge ladder in §8; bundled /project-steward v1.2 (Step 4b open-loop pass, digest opens with the closing statement and carries Your open loops, operator-initiated results notify the operator) and /orchestrate v1.9 (a run isn't done until delivery to the requester succeeds; every report ends with Your open loops / Waiting on you / Next without you). The agent drafts follow-ups, the human sends them — nothing here contacts a third party. Re-runs offer the §12 insert into an existing standard","1.15: Access-verification guidance — preflight flags an installed-but-unauthenticated gh (private github: sources, /sync-fleet-to-head pushes, and registry ops all depend on it); Q3's project layer verifies registry-repo write access + issues enabled via gh api before wiring the autonomous steward (a bad grant would otherwise surface as a silently failing schedule); Step 9's summary documents the deployed-credential story — GH_TOKEN via .env + inject_credentials, same convention as /add-canon Step 6b — for GitHub-touching skills on a Trinity instance","1.14: Bundled /discover-agents v1.7 — canon coverage line in the scan report (N/M mapped agents enrolled when the fleet has a canon), so an orchestrator that adopted /add-canon alone sees exactly which members are not yet aligned; /add-canon v1.1's fleet-enrollment step closes the gap from the orchestrator side","1.13: Canon-aware bundle — /discover-agents v1.6 scans each agent's x-canon: declaration (the shared canonical-data layer installed by the new sibling /add-canon) into a canon: field per map node with a cheap declared-folder drift check; /orchestrate v1.8 serves reads of published business facts from the canon repo (cited at canon@<sha>, staleness-flagged) instead of a chat turn and briefs the canon pointer into dispatches; orchestration.md gains a §3c data-layer subsection (offered as an upgrade insert on re-run, like §3b)","1.12: Bundled /orchestrate v1.7 — report-back subscriptions target the backend-emitted agent.task.completed/failed terminal events (trinity#1578) instead of a worker-emitted completion trailer, the deterministic fallback is a re-arming set_reminder one-shot (trinity#1296) instead of an orch-watch cron schedule, and teardown documents the #1580 spawn-provenance rule (agent keys can delete only agents they spawned); project-steward notes the agent.task.completed subscription as the push-style alternative to chat-history polling","1.11: Bundled /orchestrate v1.6 — dispatch is duration-aware and fire-and-park (never block-and-wait): quick tasks stay sync; long ones (or a queued_timeout receipt) go out chat_with_agent(parallel=true, async=true) with the execution_id parked in a run ledger (fleet/.orchestrate-runs.yaml) and the turn ended; dual wake-up — workers emit orchestration.task_completed via a standard prompt trailer the orchestrator pre-subscribes to ({{payload.task_id}}-templated message), plus a self-deleting orch-watch-<execution_id> watchdog schedule as deterministic fallback; new Step 6b report-back fetches the result, delivers via send_message (send_notification fallback), resumes parked chains, cleans up watcher + ledger, and only then tears down ephemerals","1.10: Bundled /discover-agents v1.5 — discovery source is asked up front when Trinity MCP is connected (live Trinity fleet as the Recommended default · sources.yaml repo scan · both/union); trinity/both runs roster from list_agents, so live agents missing from sources.yaml are no longer invisible (they land as live-only entries, match: live) and fleet/sources.yaml is required only for the repo-scan sources; Step 8's first scan now also fires when Trinity is connected even if sources.yaml is still the example","1.9: Platform-alignment fixes, verified against Trinity source — Step 7b calls create_agent_schedule with its real params (agent_name/name/cron_expression/message; schedule_name/cron/skill never existed) and documents that Trinity never reads template.yaml schedules: at agent creation (only /trinity:onboard//sync materialize it); Step 7's dashboard fleet panel now uses Trinity's real sections[]→widgets[] schema with rows /discover-agents materializes (the top-level fleet_map/panel_type block was silently never rendered); bundled templates: /discover-agents v1.4 sources topology edges from DECLARED intent (system.yaml permissions / §5) since agent_permissions are not exposed over MCP (get_agent_auth is subscription auth, not permissions) and materializes the dashboard Fleet rows; /orchestrate v1.5 makes ephemeral names rollout-unique via a persisted counter (delete_agent is a soft delete — names stay reserved until purge, ~180 days)","1.8: Ownership matrix (RACI-lite) — orchestration.md gains §3b, one fleet-wide informational table (domain → responsible/consulted/informed; A is structural: manager owns the record, operator owns escalations); loaded at session start via the existing @import, so the orchestrator routes by R and treats C/I as consult/notify etiquette — defaults, never gates; /orchestrate, /project-init, /project-steward, /profile-fleet read it advisorily; re-runs offer to insert §3b into an existing orchestration.md that predates it","1.7: Adopt the project-management layer (opt-in Q3) — /project-init + /project-steward (autonomous driver, from a production orchestrator's field-hardened v1.6) + a fleet/project-standard.md template; registry repo, operator, and cadence parameterized at install; steward schedule recorded in template.yaml schedules:; dispatches resolve owners via the map's deployed_name and respect orchestration.md §5; deliberately does NOT compose /orchestrate (transitive autonomy — its interactive disambiguation would hang an unattended run)","1.6: Internalize the production orchestrator's profile-fleet field lesson — §3 role corrections route to a §3a prose subsection (the §3 roster is GENERATED and must not be hand-edited); orchestration.md.template now ships the §3a stub; fleet-reconcile references it; /align-agent-permissions referenced when installed","1.5: Adopt /fleet-reconcile into the bundle (sixth skill) — gated doc-reconciliation that folds already-verified deltas (session fixes, audit corrections_pending queues) into orchestration.md prose, dossier addenda, CLAUDE.md, and memory, then makes one focused commit; universalized from a production orchestrator (optional convention-based audit queue, memory-system-agnostic, section refs aligned to the bundle's orchestration.md template)","1.4: Integrate with /add-pipeline (the intra-agent sibling) — /discover-agents scans each repo's projects/*/pipeline.yaml into a pipelines: field per map node, /orchestrate routes pipeline-shaped work to the owning agent instead of re-sequencing its stages as a chain, /profile-fleet degrades gracefully on Trinity builds without the pipeline MCP introspection tools; cross-pointers added both ways","1.3: Adopt two fleet-maintenance skills into the bundle — /sync-fleet-to-head (non-destructively bring in-scope agents to their GitHub HEAD; pull-only clean→stash_reapply ladder, conflict gates) and /profile-fleet (interview + introspect agents, reconcile self-report vs declared config, correct orchestration.md prose behind a gate; writes fleet/agent-profiles/). Both are narrative-scoped and compose /discover-agents","1.2: Add the orchestration-narrative layer — scaffolds fleet/orchestration.md (hybrid: human prose + tool-refreshed roster/topology blocks) as the standard home for the who-calls-whom-and-why intent, imports it into CLAUDE.md via @fleet/orchestration.md so it loads at session start; /discover-agents refreshes its roster+topology from live agent_permissions, /compose-system sources agent_permissions from its §5, /orchestrate routes by its edges/patterns","1.1: Self-description moves to x-capabilities: (no longer collides with Trinity's native flat capabilities: keyword list); scanner is zsh-safe and matches Trinity repo-first with an explicit deployed_name; two explicit modes up front — describe an existing fleet (map-only, read-only) vs provision a new system (map→manifest→deploy)","1.0: Initial version — installs /discover-agents, /compose-system, /orchestrate into a target agent; scans local + github:Org/repo repos for template.yaml/system.yaml into fleet/system-map.yaml; composes a Trinity SystemManifest; defines the optional self-description block"]}

Add Orchestrator

ℹ️ First, set expectations: before anything else, print one short line with this skill's version and its most recent change — the top entry of metadata.changelog above — e.g. add-orchestrator vX.Y — recent: <summary>. Then proceed.

Turn any Trinity-compatible agent into a system-aware orchestrator: an agent that knows what other agents exist (deployed or just sitting in a GitHub repo), what each can do, and can route work to them, batch across them, or roll one out ephemerally, use it, and spin it back down.

🔍 Already installed? /add-orchestrator --check runs a read-only divergence report — per installed skill: upgrade available, back-port candidate (your copy is ahead of the bundle), or a local customization about to be clobbered — before you re-run and overwrite anything. See Check mode below.

Two modes — pick by whether the fleet already exists. Don't force a linear pipeline.

Mode A · Describe & route over an EXISTING fleet   (read-only — the common case)
  live Trinity and/or fleet/sources.yaml ──/discover-agents──▶ system-map.yaml (+ orchestration.md) ──/orchestrate──▶ work
  The map (facts) + orchestration.md (intent) ARE the read surface. No manifest, no deploy. Skip /compose-system.

Mode B · Provision a NEW system   (create agents that today are only catalog repos)
  author orchestration.md §5 ──/compose-system──▶ fleet/system.yaml (SystemManifest) ──deploy──▶ /orchestrate

Artifacts (four layers):
  fleet/sources.yaml       you curate — local paths + github:Org/repo (optional when discovering from live Trinity)
  fleet/system-map.yaml    FACTS (nodes) — descriptive, written by /discover-agents      (Mode A stops here)
  fleet/orchestration.md   NARRATIVE (edges + intent) — human prose + tool-refreshed blocks; imported into CLAUDE.md
  fleet/system.yaml        Trinity SystemManifest — prescriptive, written by /compose-system   (Mode B only)

Maintenance (keep the fleet + its narrative honest over time):
  /sync-fleet-to-head   non-destructively bring in-scope agents to their GitHub HEAD
  /profile-fleet        interview + introspect agents, reconcile reality, correct orchestration.md
  /fleet-reconcile      fold already-verified deltas into every doc surface — no new evidence, one gate

Drive (opt-in project-management layer — Q3 at install):
  /project-init         create/adopt a managed project (epic + workspace) per fleet/project-standard.md
  /project-steward      autonomous sweep: reconcile dispatches, dispatch next work to labeled owners,
                        escalate stalls, age the operator's open loops, write a daily digest —
                        never asks mid-run

Loop closure (standard §12) runs through the whole bundle. Silence is a failure mode, not an outcome, in both directions. Inbound: isn't done until the requester has actually been told the outcome — including when the run failed — and the steward's digest opens with what's now true, what's waiting on the operator, and what happens next unprompted. Outbound: work parked on somebody the fleet can't dispatch to — a client, a vendor, a colleague, an agent in another fleet — is labeled , aged in every digest under , and handed to the operator with a drafted follow-up. — nothing in this bundle contacts a third party on the operator's behalf.