Add harness workflow and Material showcase design system

docs/orchestration.md

@@ -0,0 +1,97 @@
+# 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