cadence-ui/docs/orchestration.md

Worktree Orchestration

Cadence UI uses worktree-oriented orchestration as an optional layer on top of the harness validation suites. The goal is to let a leader agent or operator dispatch isolated implementation attempts without making the repository depend on one specific orchestration service.

Wrapper Command

Use the repository wrapper instead of calling orch directly:

pnpm harness:orch -- <orch command> [flags]

The wrapper also exposes repo-local helper commands:

pnpm harness:orch -- doctor --plan-file docs/exec-plans/my-plan.md
pnpm harness:orch -- plan inspect --plan-file docs/exec-plans/my-plan.md
pnpm harness:orch -- plan body --run cadence_ui_demo --task T1 --plan-file docs/exec-plans/my-plan.md

The wrapper applies these defaults:

• orchestration database: .artifacts/orch/coord.db
• worktree root: .artifacts/orch/worktrees
• repo path for dispatch: the current Cadence UI repository root
• strict worktree mode for dispatch
• --base-ref defaults to the current branch if not provided

Binary resolution order:

1. CADENCE_UI_ORCH_BIN
2. orch on PATH
3. the legacy ~/.codex/skills/orch/assets/orch location

If no binary is found, pnpm harness:orch -- doctor prints the checked locations and exits non-zero so the failure is explicit instead of looking like a broken wrapper.

Suggested Workflow

1. Write or update an execution plan in docs/exec-plans/.
2. Inspect the plan task sketch with pnpm harness:orch -- plan inspect --plan-file <plan>.
3. Create an orchestration run.
4. Add tasks and dependencies that map to the execution plan.
5. Dispatch ready tasks into isolated worktrees, ideally with --plan-file so the wrapper can generate the task body from the plan automatically.
6. Reconcile worker state and run the relevant harness suites before merge.

Example

Create a run:

pnpm harness:orch -- run init \
  --run cadence_ui_harness_001 \
  --goal "Complete the next Cadence UI release slice" \
  --summary "Break the work into isolated component, docs, and validation tasks"

Add tasks:

pnpm harness:orch -- task add \
  --run cadence_ui_harness_001 \
  --task T1 \
  --title "Implement component change" \
  --summary "Update the component source and unit tests"

pnpm harness:orch -- task add \
  --run cadence_ui_harness_001 \
  --task T2 \
  --title "Update docs and smoke coverage" \
  --summary "Refresh stories and keep Storybook smoke stable"

pnpm harness:orch -- dep add \
  --run cadence_ui_harness_001 \
  --task T2 \
  --depends-on T1

Dispatch a task into a strict worktree:

pnpm harness:orch -- dispatch \
  --run cadence_ui_harness_001 \
  --task T1 \
  --to default-worker \
  --plan-file docs/exec-plans/2026-03-24-harness-control-plane-hardening.md

When --plan-file is provided without --body-file, the wrapper parses the plan's ## Orchestration Task Sketch, finds the matching task id, and writes a generated task body under .artifacts/orch/task-bodies/<run>/<task>.md before dispatching.

Inspect status:

pnpm harness:orch -- status --run cadence_ui_harness_001
pnpm harness:orch -- blocked --run cadence_ui_harness_001
pnpm harness:orch -- reconcile --run cadence_ui_harness_001
pnpm harness:orch -- cleanup --run cadence_ui_harness_001 --all-completed

Mapping Plans To Tasks

Execution plans are still the source of intent. Orchestration tasks should be a thin translation of the plan:

• one task per independently dispatchable slice
• dependencies only where integration would otherwise conflict
• task bodies should point back to the execution plan and the relevant harness suites
• workers should validate the narrowest useful suites first, then report what remains

Suggested task sketch format:

- `T1`: stabilize docs smoke coverage
- `T2 -> T1`: reconcile a11y coverage and docs after the smoke slice lands

T2 -> T1 means task T2 depends on T1.

Safety Notes

• dispatch from a committed or otherwise reviewable base when possible
• keep shared integration files on the leader side when multiple workers are active
• prefer one task per isolated write scope
• use status, blocked, answer, and reconcile instead of ad hoc coordination
• run pnpm harness:orch -- doctor before the first dispatch on a new machine so binary discovery, defaults, and plan parsing all fail fast