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.

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. status: completed on disk is the only accepted proof — the worker's closing message never completes a task.

If the status is anything else, 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 reads completed on disk, or it is marked blocked with the log path cited.

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>/.

Required skills:

• cy-workflow-memory: use before editing code. 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: use before any completion claim, to identify and run the repository's real verification commands.

Read the repository AGENTS.md/CLAUDE.md and surface-specific instructions, then .compozy/tasks/<slug>/_spec.md and _tasks.md; treat those plus the task file body as the source of truth. Keep scope tight to this task and record follow-up work instead of widening it. Preserve unrelated worktree changes. Run every Validation, Test Plan, or Testing item the task body lists and fix what fails. 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.