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

Suggested Workflow

1. Write or update an execution plan in docs/exec-plans/.
2. Create an orchestration run.
3. Add tasks and dependencies that map to the execution plan.
4. Dispatch ready tasks into isolated worktrees.
5. 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 \
  --body-file docs/exec-plans/task-t1.md

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

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