Add harness workflow and Material showcase design system
This commit is contained in:
@@ -0,0 +1,68 @@
|
||||
# Harness Foundation
|
||||
|
||||
- Status: `completed`
|
||||
- Owner: `codex`
|
||||
- Date: `2026-03-23`
|
||||
|
||||
## Goal
|
||||
|
||||
Introduce the first harness-engineering layer for Cadence UI so the repository becomes easier for
|
||||
agents to understand, plan against, and validate mechanically.
|
||||
|
||||
## Scope
|
||||
|
||||
- In scope:
|
||||
- document the harness workflow
|
||||
- add execution-plan conventions
|
||||
- expose shared validation suites from one entrypoint
|
||||
- add a pull request workflow that runs the PR validation suite
|
||||
- Out of scope:
|
||||
- full worktree orchestration
|
||||
- change-aware suite selection
|
||||
- fixing pre-existing lint and Storybook smoke issues discovered during baseline review
|
||||
|
||||
## Constraints
|
||||
|
||||
- Keep the existing package, registry, and Storybook workflows intact.
|
||||
- Avoid introducing a hard dependency on a specific coding-agent CLI.
|
||||
- Preserve the current release scripts while adding a richer harness path alongside them.
|
||||
|
||||
## Affected Surfaces
|
||||
|
||||
- `AGENTS.md`
|
||||
- `CONTRIBUTING.md`
|
||||
- `README.md`
|
||||
- `docs/harness-engineering.md`
|
||||
- `docs/exec-plans/*`
|
||||
- `package.json`
|
||||
- `.github/workflows/harness-validate.yml`
|
||||
- `scripts/harness/validate.mjs`
|
||||
|
||||
## Plan
|
||||
|
||||
1. Document what harness engineering means for this repository.
|
||||
2. Add versioned execution-plan guidance and a real example plan.
|
||||
3. Expose reusable validation suites behind a single script.
|
||||
4. Run the new PR suite from GitHub Actions.
|
||||
|
||||
## Validation
|
||||
|
||||
- `pnpm harness:suites`
|
||||
- `pnpm harness:validate:pr -- --dry-run`
|
||||
|
||||
Baseline findings captured during rollout:
|
||||
|
||||
- `pnpm test` passed
|
||||
- `pnpm typecheck` passed
|
||||
- `pnpm lint` failed on pre-existing story/test lint issues plus React Compiler hook lint
|
||||
- `pnpm test:e2e:smoke` reached a real Storybook drift failure in the button playground flow once
|
||||
browser launch permissions were provided
|
||||
|
||||
## Status Log
|
||||
|
||||
- `2026-03-23 12:18` inspected repo structure, QA stack, CI workflows, and agent guidance
|
||||
- `2026-03-23 12:24` confirmed `test` and `typecheck` pass; found pre-existing `lint` failures
|
||||
- `2026-03-23 12:26` reran Playwright smoke outside the sandbox and confirmed one real Storybook
|
||||
smoke failure instead of a harness-only environment failure
|
||||
- `2026-03-23 12:31` added harness docs, execution-plan conventions, validation script, and PR
|
||||
workflow
|
||||
@@ -0,0 +1,71 @@
|
||||
# Harness Rollout Completion
|
||||
|
||||
- Status: `completed`
|
||||
- Owner: `codex`
|
||||
- Date: `2026-03-23`
|
||||
|
||||
## Goal
|
||||
|
||||
Finish the next harness-engineering layer for Cadence UI by stabilizing baseline validation,
|
||||
adding diff-aware suite selection, and exposing worktree-oriented orchestration defaults.
|
||||
|
||||
## Scope
|
||||
|
||||
- In scope:
|
||||
- fix the current lint failures
|
||||
- stabilize the flaky Storybook smoke route
|
||||
- add suite selection from git diff and working tree changes
|
||||
- add orchestration wrapper docs and scripts
|
||||
- Out of scope:
|
||||
- automated plan-to-task decomposition
|
||||
- CI artifact uploads for harness JSON reports
|
||||
- stronger container or VM isolation around worker execution
|
||||
|
||||
## Constraints
|
||||
|
||||
- Keep the existing validation commands working as direct entrypoints.
|
||||
- Do not make the repository depend on a single hosted orchestration service.
|
||||
- Preserve simple local development workflows alongside the richer harness path.
|
||||
|
||||
## Affected Surfaces
|
||||
|
||||
- `apps/docs/src/components/*`
|
||||
- `packages/ui/src/components/*`
|
||||
- `tests/e2e/storybook-smoke.spec.ts`
|
||||
- `scripts/harness/*`
|
||||
- `.github/workflows/harness-validate.yml`
|
||||
- `docs/harness-engineering.md`
|
||||
- `docs/orchestration.md`
|
||||
|
||||
## Plan
|
||||
|
||||
1. Repair the failing lint issues in stories, tests, and hooks-heavy components.
|
||||
2. Stabilize Storybook smoke navigation so it waits for iframe story readiness.
|
||||
3. Add a shared diff-to-suite selector and a changed-suite validator.
|
||||
4. Expose a repository-local orchestration wrapper with strict worktree defaults.
|
||||
5. Update docs and workflow wiring around the new control plane.
|
||||
|
||||
## Validation
|
||||
|
||||
- `pnpm lint`
|
||||
- `pnpm harness:suites`
|
||||
- `pnpm harness:select -- --json`
|
||||
- `pnpm harness:validate:changed -- --dry-run`
|
||||
- `pnpm test`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm build:docs`
|
||||
- `pnpm test:e2e:smoke`
|
||||
|
||||
## Orchestration Task Sketch
|
||||
|
||||
- `T1`: stabilize validation surfaces
|
||||
- `T2`: add selector and reporting control plane
|
||||
- `T3`: wire worktree dispatch defaults and docs
|
||||
- `T4`: validate changed-suite and full smoke behavior
|
||||
|
||||
## Status Log
|
||||
|
||||
- `2026-03-23 12:36` fixed existing lint errors in stories, tests, and component hooks
|
||||
- `2026-03-23 12:43` stabilized Storybook smoke route readiness via story-title waits
|
||||
- `2026-03-23 12:50` added shared harness core, diff-aware suite selector, and changed-suite execution
|
||||
- `2026-03-23 12:55` added orchestration wrapper and repository docs for worktree-backed dispatch
|
||||
@@ -0,0 +1,77 @@
|
||||
# Material You Convergence
|
||||
|
||||
- Status: `completed`
|
||||
- Owner: `codex`
|
||||
- Date: `2026-03-23`
|
||||
|
||||
## Goal
|
||||
|
||||
Converge Cadence UI from a multi-skin showcase system into a single Material You inspired
|
||||
design language with dynamic seed-color theming, tonal surfaces, large-radius component
|
||||
defaults, and one consistent motion vocabulary plus a reduced/static accessibility override.
|
||||
|
||||
## Scope
|
||||
|
||||
- In scope:
|
||||
- replace the current `minimal / glass / pixel` skin contract with a single `material` skin
|
||||
- shift token defaults toward Material You roles and typography
|
||||
- introduce runtime dynamic color generation from a seed color
|
||||
- retune component surface variables around tonal containers instead of decorative skins
|
||||
- update Storybook preview and foundation stories away from multi-skin demos
|
||||
- update package and contract tests that exercise the public runtime styling API
|
||||
- promote `DESIGN.md` into the repository system of record
|
||||
- push the visual language further toward a showcase-grade Material presentation
|
||||
- Out of scope:
|
||||
- full wallpaper extraction from host operating systems
|
||||
- dark theme parity for every token role in this first convergence slice
|
||||
- a full component-by-component redesign of every docs story
|
||||
|
||||
## Constraints
|
||||
|
||||
- Keep the existing package import structure working for `@ai-ui/ui` and `@ai-ui/tokens`.
|
||||
- Preserve the reduced/static motion accessibility mode.
|
||||
- Prefer aliasing and runtime helpers over a sweeping component API rewrite.
|
||||
- Record the direction change explicitly instead of silently continuing the multi-skin RFC.
|
||||
|
||||
## Affected Surfaces
|
||||
|
||||
- `packages/tokens/src/*`
|
||||
- `packages/ui/src/lib/*`
|
||||
- `packages/ui/src/skins.css`
|
||||
- `packages/ui/src/styles.css`
|
||||
- `apps/docs/.storybook/preview.ts`
|
||||
- `apps/docs/src/*.stories.tsx`
|
||||
- `DESIGN.md`
|
||||
- `AGENTS.md`
|
||||
- `README.md`
|
||||
- `tests/package-consumer/*`
|
||||
- `docs/exec-plans/*`
|
||||
|
||||
## Plan
|
||||
|
||||
1. Replace the style runtime contract with Material-centric theme and motion semantics.
|
||||
2. Add a seed-color palette generator and map generated roles onto existing component tokens.
|
||||
3. Collapse skin CSS to a single Material skin and retune shared component variables.
|
||||
4. Update Storybook docs to demonstrate dynamic color, tonal surfaces, and the single motion language.
|
||||
5. Promote `DESIGN.md` into the repository's official design system of record.
|
||||
6. Push the showcase styling and motion layer until the docs feel closer to a Material launch demo.
|
||||
7. Run focused validation on package contracts, docs build, and consumer smoke.
|
||||
|
||||
## Validation
|
||||
|
||||
- `pnpm test`
|
||||
- `pnpm typecheck`
|
||||
- `pnpm build:docs`
|
||||
- `pnpm test:package:consumer`
|
||||
|
||||
## Orchestration Task Sketch
|
||||
|
||||
- `T1`: token/runtime contract shift
|
||||
- `T2`: shared component surface restyle
|
||||
- `T3`: docs and consumer validation updates
|
||||
|
||||
## Status Log
|
||||
|
||||
- `2026-03-23 14:18` started convergence plan after product direction changed from multi-skin showcase to Material You
|
||||
- `2026-03-23 16:15` promoted `DESIGN.md` to the active design-system source of truth and started a second-pass visual polish toward a more animated Material showcase
|
||||
- `2026-03-23 16:58` completed the second-pass polish across tokens, shared skin variables, Storybook showcase pages, and package-consumer validation
|
||||
@@ -0,0 +1,44 @@
|
||||
# Execution Plans
|
||||
|
||||
Execution plans make non-trivial work resumable and reviewable by both humans and agents.
|
||||
|
||||
## Naming
|
||||
|
||||
Use `YYYY-MM-DD-short-name.md`.
|
||||
|
||||
Examples:
|
||||
|
||||
- `2026-03-23-harness-foundation.md`
|
||||
- `2026-03-24-date-picker-accessibility.md`
|
||||
|
||||
## When To Add One
|
||||
|
||||
Create or update a plan when the change:
|
||||
|
||||
- spans multiple directories or validation surfaces
|
||||
- alters public contracts, release behavior, or build pipelines
|
||||
- is large enough that another person or agent may continue it later
|
||||
|
||||
## Status Model
|
||||
|
||||
Prefer one of these status values near the top of the plan:
|
||||
|
||||
- `proposed`
|
||||
- `in-progress`
|
||||
- `blocked`
|
||||
- `completed`
|
||||
- `abandoned`
|
||||
|
||||
## Minimum Contents
|
||||
|
||||
Every plan should cover:
|
||||
|
||||
- goal
|
||||
- scope
|
||||
- constraints or non-goals
|
||||
- affected surfaces
|
||||
- implementation steps
|
||||
- validation strategy
|
||||
- status log
|
||||
|
||||
Start from [TEMPLATE.md](./TEMPLATE.md).
|
||||
@@ -0,0 +1,46 @@
|
||||
# <Plan Title>
|
||||
|
||||
- Status: `proposed`
|
||||
- Owner: `<name or agent>`
|
||||
- Date: `YYYY-MM-DD`
|
||||
|
||||
## Goal
|
||||
|
||||
Describe the outcome in one short paragraph.
|
||||
|
||||
## Scope
|
||||
|
||||
- In scope:
|
||||
- Out of scope:
|
||||
|
||||
## Constraints
|
||||
|
||||
- List technical or product constraints.
|
||||
|
||||
## Affected Surfaces
|
||||
|
||||
- `packages/ui`
|
||||
- `apps/docs`
|
||||
- `tests`
|
||||
- `registry`
|
||||
- other paths as needed
|
||||
|
||||
## Plan
|
||||
|
||||
1. Step one.
|
||||
2. Step two.
|
||||
3. Step three.
|
||||
|
||||
## Validation
|
||||
|
||||
- `pnpm harness:validate:component`
|
||||
- `pnpm harness:validate:docs`
|
||||
- Add or remove commands for the actual task
|
||||
|
||||
## Orchestration Task Sketch
|
||||
|
||||
- Optional task IDs and dependencies when the work should be dispatched through `pnpm harness:orch`
|
||||
|
||||
## Status Log
|
||||
|
||||
- `YYYY-MM-DD HH:MM` initial note
|
||||
@@ -0,0 +1,138 @@
|
||||
# Harness Engineering
|
||||
|
||||
Cadence UI already has good validation primitives. Harness engineering makes those primitives
|
||||
agent-usable by turning the repo into a system that can explain itself, accept explicit execution
|
||||
plans, and expose repeatable machine-runnable feedback loops.
|
||||
|
||||
## What it means in this repo
|
||||
|
||||
For Cadence UI, harness engineering means:
|
||||
|
||||
- the repository has clear system-of-record files for architecture, contracts, and release rules
|
||||
- non-trivial work starts with an execution plan checked into git
|
||||
- validation is exposed as stable suites that humans, agents, and CI can run the same way
|
||||
- known gaps are recorded explicitly instead of being rediscovered by every new task
|
||||
|
||||
This follows the direction described in OpenAI's harness engineering guidance: repositories should
|
||||
be more legible to agents, use explicit execution plans, and prefer faster feedback loops over
|
||||
purely ad hoc prompting.
|
||||
|
||||
## System Of Record
|
||||
|
||||
Agents and contributors should treat these files as the repository's baseline knowledge:
|
||||
|
||||
- `DESIGN.md`: active visual language, dynamic color direction, and motion rules
|
||||
- `README.md`: repo purpose, workspace layout, distribution modes, and QA surface
|
||||
- `CONTRIBUTING.md`: component contract, review expectations, and definition of done
|
||||
- `roadmap.md`: current system direction and planned component work
|
||||
- `packages/ui/src/lib/contracts.ts`: public authoring contract for components
|
||||
- `apps/docs/src/component-authoring.stories.tsx`: review surface for authoring rules
|
||||
- `docs/registry.md`: source-copy registry contract
|
||||
- `docs/releasing.md`: package release contract
|
||||
- `docs/rfcs/*`: design decisions that should not be silently bypassed
|
||||
- `AGENTS.md`: agent operating mode for this repository
|
||||
|
||||
## Execution Plans
|
||||
|
||||
Non-trivial changes should start with an execution plan under `docs/exec-plans/`.
|
||||
|
||||
Use an execution plan when the work:
|
||||
|
||||
- touches multiple repo surfaces such as `packages/ui`, `apps/docs`, `tests`, or `registry`
|
||||
- changes public component contracts or release behavior
|
||||
- introduces new dependencies, workflows, or automation
|
||||
- is large enough that another engineer or agent may need to resume it later
|
||||
|
||||
Plans should state:
|
||||
|
||||
- the problem or goal
|
||||
- constraints and non-goals
|
||||
- affected surfaces and likely files
|
||||
- validation suites to run
|
||||
- a status log with concrete checkpoints
|
||||
|
||||
## Validation Suites
|
||||
|
||||
Harness validation is exposed through `scripts/harness/validate.mjs` and root `pnpm` scripts.
|
||||
|
||||
Primary suites:
|
||||
|
||||
- `pnpm harness:validate:static`
|
||||
- lint and workspace typecheck for general repo changes
|
||||
- `pnpm harness:validate:component`
|
||||
- lint, typecheck, and unit coverage for normal component work
|
||||
- `pnpm harness:validate:docs`
|
||||
- Storybook build for docs-surface changes
|
||||
- `pnpm harness:validate:docs-smoke`
|
||||
- Playwright smoke coverage for high-value Storybook flows
|
||||
- `pnpm harness:validate:consumers`
|
||||
- registry metadata plus consumer smoke validation
|
||||
- `pnpm harness:validate:pr`
|
||||
- baseline pull request gate for packages, docs build, and consumer surfaces
|
||||
- `pnpm harness:validate:release`
|
||||
- full release gate, including browser-driven smoke coverage
|
||||
- `pnpm harness:validate:changed`
|
||||
- selects suites from git diff or working tree changes before validating
|
||||
|
||||
Each run writes a JSON report to `.artifacts/harness/<suite>.json`.
|
||||
|
||||
## Working Loop
|
||||
|
||||
Recommended change loop:
|
||||
|
||||
1. Read the relevant system-of-record files.
|
||||
2. Create or update an execution plan when the change is non-trivial.
|
||||
3. Modify the smallest surface that can prove the change.
|
||||
4. Run the narrowest useful harness suite first.
|
||||
5. Escalate to broader suites before merge.
|
||||
6. Record any skipped checks or known failures in the execution plan or PR.
|
||||
|
||||
## Diff-aware Selection
|
||||
|
||||
Harness selection is exposed through `pnpm harness:select` and `pnpm harness:validate:changed`.
|
||||
|
||||
- `pnpm harness:select`
|
||||
- reads the current working tree diff by default
|
||||
- `pnpm harness:select -- --from <ref> --to <ref>`
|
||||
- selects suites from an explicit git range
|
||||
- `pnpm harness:validate:changed`
|
||||
- runs the selected suites with a JSON report
|
||||
|
||||
Selection intentionally maps repo surfaces to validation surfaces:
|
||||
|
||||
- package source changes select `component`, `docs`, `docs-smoke`, and `consumers`
|
||||
- docs/story changes select `static`, `docs`, and `docs-smoke`
|
||||
- registry/consumer changes select `static` and `consumers`
|
||||
- doc-only or metadata-only changes may select no suites
|
||||
|
||||
## Worktree Orchestration
|
||||
|
||||
Cadence UI also exposes an orchestration wrapper:
|
||||
|
||||
- `pnpm harness:orch -- <orch command>`
|
||||
|
||||
The wrapper keeps orchestration state under `.artifacts/orch/` and applies worktree defaults for
|
||||
dispatch. Details live in [docs/orchestration.md](/Users/xd/project/cadence-ui/docs/orchestration.md).
|
||||
|
||||
## Current Rollout Scope
|
||||
|
||||
This repository is adding harness engineering in phases.
|
||||
|
||||
Phase 1 establishes:
|
||||
|
||||
- a documented harness workflow
|
||||
- execution-plan conventions
|
||||
- shared validation suites
|
||||
- a pull request workflow that runs the PR suite
|
||||
|
||||
Phase 2 adds:
|
||||
|
||||
- change-aware suite selection from git diff
|
||||
- a stabilized Storybook smoke harness
|
||||
- worktree-oriented orchestration defaults
|
||||
|
||||
Future phases can layer on:
|
||||
|
||||
- richer browser/app harnesses for interactive review
|
||||
- deeper plan-to-task automation for orchestration runs
|
||||
- stronger safety rails for agent-owned automation
|
||||
@@ -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
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## Status
|
||||
|
||||
Proposed
|
||||
Superseded by the Material You convergence work started on 2026-03-23.
|
||||
|
||||
## Last Updated
|
||||
|
||||
@@ -10,6 +10,10 @@ Proposed
|
||||
|
||||
## Why this document exists
|
||||
|
||||
This RFC is now a historical record of the repo's multi-skin exploration. The active
|
||||
direction has changed: Cadence UI is converging on one Material-centric design language
|
||||
with dynamic seed color instead of continuing to expand multiple visual skins.
|
||||
|
||||
This document records the current plan for making Cadence UI support multiple visual
|
||||
styles without forking component behavior or losing the existing source-owned model.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user