98 lines
2.9 KiB
Markdown
98 lines
2.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
pnpm harness:orch -- dispatch \
|
|
--run cadence_ui_harness_001 \
|
|
--task T1 \
|
|
--to default-worker \
|
|
--body-file docs/exec-plans/task-t1.md
|
|
```
|
|
|
|
Inspect status:
|
|
|
|
```bash
|
|
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
|