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/<slug>/ is implemented by a dedicated CompozyOS worker session.

Required Inputs

• slug — the directory name under .compozy/tasks/<slug>/, 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/<slug>/_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:

IMPLEMENTER="<exact implementer identifier from the Goal>"
compozy spawn --agent "$IMPLEMENTER" \
  --name "orchestrate-<slug>-<task_id>" \
  --role worker \
  --ttl-seconds 3600 \
  --auto-stop-on-parent=true \
  --idempotency-key "orchestrate-<slug>-<task_id>" \
  -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:

compozy session list \
  --parent "$COMPOZY_SESSION_ID" \
  --type spawned \
  --state active \
  --query "orchestrate-<slug>-<task_id>" \
  -o json

Reuse the id only when exactly one returned session has name equal to orchestrate-<slug>-<task_id> 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:

mkdir -p .compozy/tasks/<slug>/logs
compozy session prompt <session_id> "<briefing>" \
  -o jsonl > .compozy/tasks/<slug>/logs/<task_id>.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/<slug>/logs/<task_id>.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 <session_id> -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 <task_id> — <title> — 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.