kurihada/cadence-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(harness): document control plane workflow

Browse Source 
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
kurihada
2026-03-24 18:34:56 +08:00
parent 704cacfd8d
commit 800db360b3
4 changed files with 168 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/orchestration.md
+39 -5
View File
@@ -12,6 +12,14 @@ Use the repository wrapper instead of calling `orch` directly:
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`
@@ -20,13 +28,24 @@ The wrapper applies these defaults:
- 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. 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.
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
@@ -67,9 +86,13 @@ pnpm harness:orch -- dispatch \
--run cadence_ui_harness_001 \
--task T1 \
--to default-worker \
--body-file docs/exec-plans/task-t1.md
--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
@@ -89,9 +112,20 @@ the plan:
- 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