kurihada
800db360b3
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
132 lines
4.3 KiB
Markdown
132 lines
4.3 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 also exposes repo-local helper commands:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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 \
|
|
--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:
|
|
|
|
```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
|
|
|
|
Suggested task sketch format:
|
|
|
|
```md
|
|
- `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
|