Orch Report

orch-report

Worker reporting skill: emit task progress and completion events to the orchestration log.

Security boundary

emit.py enforces a hard guard-rail: only task_progress, task_completed, and task_failed are accepted. Any other event type is rejected unconditionally. This constraint is enforced in code, independent of the calling prompt.

Worker identity is read from the ORCH_WORKER_ID environment variable. The caller cannot override it.

scripts/emit.py

Usage

ORCH_WORKER_ID= python3 .claude/skills/orch-report/scripts/emit.py \
  --kind progress|completed|failed \
  --task-id  \
  [--attempt ] \
  [--data '']

Environment variables (set by orchestrator in spawn prompt)

| Variable | Required | Description | |----------|----------|-------------| | ORCH_WORKER_ID | Yes | Worker identity — used as agent field in every emitted event | | ORCH_TASK_ID | Yes | Task assigned to this worker invocation | | ORCH_ATTEMPT | Yes | Current attempt number (1-based) | | ORCH_PROJECT_DIR | Yes | Absolute path to project root — used to resolve artifact paths | | SPECS_DIR | Phase-specific | Relative path to specs directory (set by sdd/dev/review orchestrators) |

Workers must export all five variables as shell env vars before calling emit.py.

Why phase is required in every event

All three event types (task_progress, task_completed, task_failed) require phase in their data payload. This is intentional, not redundant:

• The on_subagent_stop hook synthesizes task_failed when a worker stops silently. It needs phase to build a valid payload without replaying the log (which may be unavailable or slow).
• task_claimed also carries phase for the same reason — the registry entry written by register_worker() stores it for hook recovery.

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | ORCH_WORKER_ID | Yes (env) | Worker identifier — set by orchestrator before spawning | | --kind | Yes | progress, completed, or failed | | --task-id | Yes | Task being reported on | | --attempt | No | Attempt number, default 1 | | --data | No | JSON object payload, default {} |

Kind → event_type mapping

| Kind | Event type emitted | |------|--------------------| | progress | task_progress | | completed | task_completed | | failed | task_failed |

--data schema by kind

progress — intermediate status update:

{
  "phase": "",
  "note":  ""
}

completed — terminal success:

{
  "phase":     "",
  "artifacts": [""],
  "summary":   ""
}

artifacts paths are relative to ORCH_PROJECT_DIR — absolute paths and .. traversals are rejected by emit.py. Exit criteria scripts read these paths to evaluate phase completion. Use the conventions below:

• Dev workers: /delivery/-delivery.md
• QA workers: /qa/-qa.md
• Planning workers: /backlog/backlog.json

failed — terminal failure:

{
  "phase":     "",
  "reason":    "",
  "retryable": true,
  "error":     ""
}

Set retryable: false only for permanent failures (spec ambiguity, missing input, permission). Leave true for transient errors (tool failure, timeout, context overflow). The error field is optional but recommended — the reducer stores it in task.last_error for diagnostics and DLQ triage.

Output

On success (exit 0): JSON object of the created event.

On error (exit 1): JSON error envelope:

{"status": "error", "reason": "", "detail": ""}

Error reason codes:

• missing_env — ORCH_WORKER_ID not set
• invalid_json — --data is not valid JSON or not an object
• validation_error — payload fails schema validation
• internal_error — unexpected I/O or lock failure

Examples

# Report progress
ORCH_WORKER_ID=worker-42 python3 .claude/skills/orch-report/scripts/emit.py \
  --kind progress --task-id t_001 --data '{"phase":"dev","note":"running tests"}'

# Report success
ORCH_WORKER_ID=worker-42 python3 .claude/skills/orch-report/scripts/emit.py \
  --kind completed --task-id t_001 \
  --data '{"phase":"dev","artifacts":["src/foo.py"],"summary":"implemented foo"}'

# Report failure
ORCH_WORKER_ID=worker-42 python3 .claude/skills/orch-report/scripts/emit.py \
  --kind failed --task-id t_001 \
  --data '{"phase":"dev","reason":"spec_unclear","retryable":true}'

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zig999
• Source: zig999/siegard-code
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.