# Cy Orchestrate Tasks > Conducts one spec's tasks by delegation — spawns a dedicated bounded worker session per task, dispatches the briefing, and uses the task file on disk for completion state and checks its verification evidence. Use when a prompt names a spec slug under .compozy/tasks/ and asks for its tasks to be orchestrated across worker sessions. Do not use for implementing a task directly, for review remediation, or for QA and pull-request work. - Skill: `compozy/cy-orchestrate-tasks` (Agent Skill) - Install (CLI): `npx skillmds@latest add compozy/cy-orchestrate-tasks` - Raw SKILL.md: https://api.skillmd.com/api/skills/compozy/cy-orchestrate-tasks/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: compozy (https://skillmd.com/u/compozy) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/compozy/cy-orchestrate-tasks --- # Orchestrate Spec Tasks This session is the **conductor** of the spec: it conducts, it does not play. Every task under `.compozy/tasks//` is implemented by a dedicated CompozyOS worker session. ## Required Inputs - `slug` — the directory name under `.compozy/tasks//`, holding `_tasks.md` (the task graph) and `task_NN.md` files whose frontmatter carries `status`, `title`, and `type`. - `implementer` — the exact validated Agent identifier supplied in the Goal objective. The Loop defaults it to `code_implementer`; the conductor never substitutes that default. - `backend_runtime`, `frontend_runtime`, and `default_runtime` — optional runtime objects supplied in the Goal objective. Each can carry `provider`, `model`, `reasoning`, and `speed`. ## Workflow ### 1. Load the task graph Read `.compozy/tasks//_tasks.md` and derive the execution order from `graph.edges`. Read the frontmatter of every `task_NN.md`. Queue only tasks whose `status` is `pending` or `in_progress`, in graph order. Treat `completed`, `complete`, `done`, and `finished` as already completed, ignoring case and surrounding whitespace. Stop on unknown or missing statuses before spawning workers; report the task file and invalid value instead of guessing. _Done when:_ the queue lists the id, `title`, and `status` of every queued task, in execution order. ### 2. Spawn the worker session Choose the worker runtime by exact frontmatter type: `backend` uses `backend_runtime`, `frontend` uses `frontend_runtime`, and every other value uses `default_runtime`. Merge the task's own frontmatter `runtime` over that category object field by field before building spawn flags. Create one bounded `spawned` session bound to this conductor. Bind the exact `implementer` value from the Goal once, then pass it as one quoted argument. TTL and parent-stop are the containment contract; `--ttl-seconds` is mandatory: ```bash IMPLEMENTER="" compozy spawn --agent "$IMPLEMENTER" \ --name "orchestrate--" \ --role worker \ --ttl-seconds 3600 \ --auto-stop-on-parent=true \ --idempotency-key "orchestrate--" \ -o json ``` Append `--provider`, `--model`, `--reasoning-effort`, and `--speed` only for non-empty fields in the selected runtime object; `reasoning` maps to `--reasoning-effort`. When every field is empty, omit provider, model, and reasoning flags so the child resolves them through the selected Agent and workspace. Under current spawn behavior, omitted speed inherits the parent session. Capture `.session.id`. When the spawn response is lost or ambiguous, reconcile before acting — a blind respawn creates a second worker for one task: ```bash compozy session list \ --parent "$COMPOZY_SESSION_ID" \ --type spawned \ --state active \ --query "orchestrate--" \ -o json ``` Reuse the id only when exactly one returned session has `name` equal to `orchestrate--` and `agent_name` equal to `$IMPLEMENTER`. Zero results after a confirmed spawn failure blocks the task. A mismatched `agent_name` is never adopted or followed by a blind respawn: stop the session only when its parent and exact name prove conductor ownership, then block the task. More than one exact match: stop every conductor-owned match and block the task. _Done when:_ exactly one worker session id is held for this task, or the task is marked blocked. ### 3. Dispatch the briefing and wait Send the briefing and wait in the same command. `compozy session prompt` blocks until the worker's turn ends in every output mode; `-o jsonl` is the form that also leaves a durable per-task event log as evidence: ```bash mkdir -p .compozy/tasks//logs compozy session prompt "" \ -o jsonl > .compozy/tasks//logs/.jsonl 2>&1 ``` `--queue`, `--interrupt`, and `--steer` return at admission instead of at turn end, so they cannot carry a briefing this workflow waits on. _Done when:_ the command has returned and its outcome is recorded, including a failed prompt. ### 4. Check the proof Re-read the task file frontmatter. Workers write `status: completed`; the importer also accepts `complete`, `done`, and `finished` (ignoring case and surrounding whitespace). The worker's closing message alone never completes a task. Check the referenced verification evidence against the task contract and current inputs; a status label is not proof that checks passed. Reuse valid worker evidence instead of rerunning the same suite. If the status is not a recognized completion state, send one corrective prompt in the **same** session, using the same blocking form, naming exactly what is missing. A second failure produces a `blocked` result citing `.compozy/tasks//logs/.jsonl` as evidence. _Done when:_ the task has a recognized completion state on disk and verified evidence, or the Goal result is blocked with the log path cited. Do not write Goal result statuses into task files. ### 5. Stop the worker session Run `compozy session stop -o json` before advancing to the next task and before reporting any result — after success, after a prompt failure, after the corrective attempt, and after a block. A failed stop is itself a `blocked` result and must be recorded with its error. TTL and parent-stop contain abrupt cancellations; they do not replace this stop. _Done when:_ the worker session is no longer active and the stop outcome is recorded. ### 6. Report Answer with the structured result the loop asks for: `status`, optional `summary` (1–3 sentences), and optional `tasks` — each task entry names the worker session that executed it. Use `complete` or `blocked`; task-file frontmatter continues to use `completed`. _Done when:_ every task in the queue appears in the report with its task id and session id. ## Worker briefing Fill the fields and send this as the prompt body: > Implement exactly task `` — `` — of the spec `.compozy/tasks/<slug>/`. > > Execution guidance: > > - `cy-workflow-memory`: use for continuity across workers or interruptions. Memory directory > `.compozy/tasks/<slug>/memory`, shared memory `.compozy/tasks/<slug>/memory/MEMORY.md`, task > memory `.compozy/tasks/<slug>/memory/<task_id>.md`. > - `cy-execute-task`: the end-to-end execution workflow for this task. > - `cy-final-verify`: assess task-scope evidence within the existing validation step; run only > missing or invalidated checks. Name remaining workflow-owned integration/QA obligations > without starting another verification cycle for the same evidence. > > Read the repository `AGENTS.md`/`CLAUDE.md` and surface-specific instructions, then > the task file, `_tasks.md` dependencies, and relevant `_spec.md` sections; reuse grounding > already supplied in the briefing. These contracts remain the source of truth. Keep scope tight to this task and record follow-up work instead of widening it. > Preserve unrelated worktree changes. Satisfy the Validation, Test Plan, or Testing items the task > body requires; reuse evidence only when the same inputs and project policy allow it. Fix failures. With verification clean, set the task file frontmatter to > `status: completed`. Leave the changes uncommitted — commit and pull request belong to other > surfaces. ## Rules - The conductor conducts: in this session the work is spawn, dispatch, wait, check, stop. Code edits belong to workers. - One task at a time, in graph order, with one worker session per task — reused only for that task's corrective prompt.