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.

The child starts with no delegated tools when permission atoms are omitted. Before spawning, inspect this conductor's session lineage permission policy and the worker's required operations. Pass an explicit subset of the parent's concrete tool IDs: the bootstrap set below supports native discovery, descriptor reads, skill lookup, and retained-reference reads. Add only task-required tools the parent can delegate. If a required tool is absent from the parent budget, block with that missing ID; do not retry without permissions, grant wildcards, or bypass a denial through files/CLI. Other permission categories remain empty unless the task needs an explicit parent-authorized subset.

For native compozy__session_spawn, put these same IDs in tools; use the live descriptor for any additional fields. The equivalent CLI recipe is:

IMPLEMENTER="<exact implementer identifier from the Goal>"
compozy spawn --agent "$IMPLEMENTER" \
  --name "orchestrate-<slug>-<task_id>" \
  --role worker \
  --tool compozy__tool_search \
  --tool compozy__tool_info \
  --tool compozy__tool_artifact_read \
  --tool compozy__skill_search \
  --tool compozy__skill_view \
  --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.