diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 2acc782c6..8925bd702 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -52,7 +52,7 @@ { "name": "aidd-ui", "source": "./plugins/aidd-ui", - "description": "ALPHA, not ready for use. UI and UX concern: design, review, and improve frontend interfaces.", + "description": "ALPHA. Shared UI systems, feature experience contracts, UX review, accessibility, and interface adaptation.", "strict": true, "recommended": false } diff --git a/README.md b/README.md index d08a2c210..1ba8044e8 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ _(Already tested on `Legacy` codebases)_ [![Made in France](https://img.shields.io/badge/made%20in-France-0055A4?labelColor=EF4135)](https://www.ai-driven-dev.fr/)

- 7 plugins · 47 skills · 2 agents · MIT + 7 plugins · 51 skills · 2 agents · MIT

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) @@ -277,9 +277,9 @@ Synchronous feature flow, async issue-to-PR automation, and product backlog. ### 🎨 [aidd-ui](plugins/aidd-ui/README.md) 🚧 -`1 skill` · **alpha** +`5 skills` · **alpha** -UI / UX design — smoke-test only, not ready for use. +Versioned UI system contracts, feature experience decisions, specialist verdicts, and evidence-pinned review. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 56508cc01..3e8377222 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -55,10 +55,11 @@ Every capability lives in exactly one plugin, chosen by **concern**. This taxono | `aidd-orchestrator` | Orchestration | Coordination | | `aidd-ui` 🚧 | UI/UX design | Execution | -`aidd-ui` is alpha: smoke-test only, off the curated install path. +`aidd-ui` is alpha: it owns interface experience decisions and remains off the curated install path. - **Knowledge vs execution is a firewall.** Knowledge plugins produce artifacts you *read* and never write or run application source. `aidd-context`'s bootstrap deliberately creates no `package.json`. Real code belongs to `aidd-dev` or an orchestrator's own setup actions. - **Concern decides placement, not existence.** A missing capability goes in the plugin whose concern owns it, then the caller delegates. Never reimplement it in the calling plugin because the right home lacks it today. +- **The UI seam is an experience contract, not application code.** Product intent and durable project knowledge feed UI decisions; code transformation consumes those decisions for implementation. Current code wins when project memory drifts, and only the knowledge concern updates memory. - **Orchestration = sequencing across concerns** with little domain logic. Delegating a sub-step once does not make a skill an orchestrator. The orchestrator owns only glue and hands off through a seam artifact, for example an `INSTALL.md` one plugin produces and another consumes. - `aidd-orchestrator:02-backlog` owns the cross-artifact flow. Each artifact's contract stays in its `aidd-pm` skill, so a direct PM call follows the same rules as an orchestrated one. diff --git a/docs/CATALOG.md b/docs/CATALOG.md index d08bf4696..41f4de9f5 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -8,7 +8,7 @@ The exhaustive list of AIDD plugins, skills, and actions. Skills are invoked thr - [aidd-refine](#-aidd-refine) - meta-cognition - [aidd-vcs](#-aidd-vcs) - version control workflows - [aidd-orchestrator](#-aidd-orchestrator) - async orchestration (optional) -- [aidd-ui](#-aidd-ui) - UI / UX (🚧 alpha, not ready) +- [aidd-ui](#-aidd-ui) - UI / UX decisions (🚧 alpha) --- @@ -38,10 +38,10 @@ Code transformation: plan, implement, assert, audit, review, test, refactor, deb | Skill | Role | Actions | | --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -| `01-plan` | Turn a request, ticket, or file into a phased implementation plan: gather, explore, wireframe, plan | `01-gather`, `02-explore`, `03-wireframe`, `04-plan` | +| `01-plan` | Turn a request, ticket, or file into a phased implementation plan and resolve ready UI decisions | `01-gather`, `02-explore`, `03-experience`, `04-plan` | | `02-implement` | Execute a plan phase by phase until 100% complete | `01-implement` | | `03-assert` | Assert features work - general, architecture, frontend UI | `01-assert`, `02-assert-architecture`, `03-assert-frontend` | -| `04-audit` | Read-only codebase audit across quality pillars | `01-code-quality`, `02-architecture`, `03-security`, `04-dependencies`, `05-performance`, `06-tests`, `07-ui` | +| `04-audit` | Read-only codebase audit; UI experience is delegated to its owning concern | `01-code-quality`, `02-architecture`, `03-security`, `04-dependencies`, `05-performance`, `06-tests`, `07-ui` | | `05-review` | Read-only review of a diff - code quality and feature behavior | `01-review-code`, `02-review-functional` | | `06-test` | Write and iterate tests, validate user journeys in the browser | `01-test`, `02-test-journey` | | `07-refactor` | Improve code without changing behavior across four axes | `01-performance`, `02-security`, `03-cleanup`, `04-architecture` | @@ -102,8 +102,12 @@ Runs synchronous feature delivery, optional async issue automation, and the prod ## 🎨 aidd-ui -🚧 **Alpha — not ready for use.** UI / UX: design, review, and improve frontend interfaces. Currently a smoke-test only. +🚧 **Alpha.** Shared UI systems and feature experience decisions. Off the curated install path. -| Skill | Role | Actions | -| ---------- | ----------------------------------------- | ---------- | -| `01-hello` | Smoke-test that confirms the plugin loads | `01-greet` | +| Skill | Role | Actions | +| --- | --- | --- | +| `01-system` | Manage shared UI system contracts and deltas | `inspect`, `map`, `specialize`, `adopt`, `establish`, `extend`, `retire`, `reconcile`, `promote` | +| `02-design` | Create or revise a feature UI contract | `frame`, `inspect`, `specialize`, `structure`, `compose`, `write`, `verify` | +| `03-review` | Diagnose and prioritize experience defects | `inspect`, `specialize`, `assess`, `write` | +| `04-accessibility` | Own accessibility requirements and verdicts | `inspect`, `specify`, `evaluate` | +| `05-adapt` | Own space, input, and platform transformations | `inspect`, `specify`, `evaluate` | diff --git a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md index 9c18e9dd9..009a59f1a 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md @@ -1,25 +1,23 @@ # Design -The visual language: the design system, tokens, and UI conventions. What it looks like, not how it is coded. +Compact pointers to stable UI knowledge. Current code remains implementation truth; an active UI system contract remains decision authority. -## System +## UI System Authority -- -- +- -## Tokens +## Current Implementation -- +- +- -## Components +## Stable Context -- - -## Accessibility - -- +- +- diff --git a/plugins/aidd-context/skills/02-project-memory/references/reading-sources.md b/plugins/aidd-context/skills/02-project-memory/references/reading-sources.md index dbc39a760..bd3256ca5 100644 --- a/plugins/aidd-context/skills/02-project-memory/references/reading-sources.md +++ b/plugins/aidd-context/skills/02-project-memory/references/reading-sources.md @@ -10,6 +10,7 @@ opening it again. | -------------------------------------------- | -------------------------------------------- | | the manifest, and a lockfile beside it | the stack, the workspaces, the published name | | the root README, then any `docs/` | what it does, for whom, its domain words | +| current contracts under `aidd_docs/ui/systems/` | accepted shared UI authority, ids, and scopes | | the top-level directories | the shape, and which areas own what | | the entry points the manifest declares | where execution starts | | every file under the VCS platform's own directory | how it ships, and what runs on its own schedule | @@ -38,6 +39,8 @@ wrote stays whatever the verdicts below say. | a work item, a live value, a technical id | drop | | a plan, a wish, a thing not shipped | drop | +For a current UI system contract, keep only its path, immutable id, and normalized scope. The path resolves the current revision; do not copy its decisions or retain the revision number in memory. + ## Depth - Every workspace of a monorepo, never the root manifest alone. diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 671f54194..b1cc57ac2 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -44,7 +44,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-gather.md](skills/01-plan/actions/01-gather.md) | - | | `actions` | [02-explore.md](skills/01-plan/actions/02-explore.md) | - | -| `actions` | [03-wireframe.md](skills/01-plan/actions/03-wireframe.md) | - | +| `actions` | [03-experience.md](skills/01-plan/actions/03-experience.md) | - | | `actions` | [04-plan.md](skills/01-plan/actions/04-plan.md) | - | | `assets` | [phase-template.md](skills/01-plan/assets/phase-template.md) | - | | `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | - | @@ -84,7 +84,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [06-tests.md](skills/04-audit/actions/06-tests.md) | - | | `actions` | [07-ui.md](skills/04-audit/actions/07-ui.md) | - | | `assets` | [audit-template.md](skills/04-audit/assets/audit-template.md) | `Codebase audit report template` | -| `-` | [SKILL.md](skills/04-audit/SKILL.md) | `Audit a codebase read-only across seven quality pillars into one ranked report. Use when the user wants to assess, health-check, or audit a codebase or one pillar. Not for fixing findings, reviewing a change, or checking a feature works.` | +| `-` | [SKILL.md](skills/04-audit/SKILL.md) | `Audit a codebase read-only across six engineering pillars plus delegated UI experience review. Use when the user wants to assess, health-check, or audit a codebase or one pillar. Not for fixing findings, reviewing a change, or checking a feature works.` | #### `skills/05-review` diff --git a/plugins/aidd-dev/README.md b/plugins/aidd-dev/README.md index a23bc830b..e7632a00e 100644 --- a/plugins/aidd-dev/README.md +++ b/plugins/aidd-dev/README.md @@ -14,7 +14,7 @@ Covers code transformation: planning, implementation, assertions, audits, code r | Bracket ID | Skill | Description | |---|---|---| -| [2.1] | [plan](skills/01-plan/SKILL.md) | Turn a request, ticket, or file into a phased implementation plan, gathering the source first and optionally wireframing a screen before planning. | +| [2.1] | [plan](skills/01-plan/SKILL.md) | Turn a request, ticket, or file into a phased implementation plan, resolving a ready UI contract for frontend work with a bounded compatibility fallback while the UI provider is optional. | | [2.2] | [implement](skills/02-implement/SKILL.md) | Execute an implementation plan phase by phase, recipe-style, iterating until 100% completeness. | | [2.3] | [assert](skills/03-assert/SKILL.md) | Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. | | [2.4] | [audit](skills/04-audit/SKILL.md) | Perform deep codebase analysis to identify technical debt, dead code, and improvement opportunities. | diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index e8649e4a6..972982a1e 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/plugins/aidd-dev/skills/01-plan/SKILL.md @@ -10,19 +10,19 @@ Turn a gathered source into an implementation plan and its phase files. Never wr ## Actions -| # | Action | Role | Input | -| --- | ----------- | ---------------------------------------------------- | -------------------------- | -| 01 | `gather` | Collect and restate the source | user request | -| 02 | `explore` | Read the codebase for projection, rules, feasibility | gathered source | -| 03 | `wireframe` | Sketch a screen at low fidelity, frontend only | source + explore context | -| 04 | `plan` | Break into phases, write the plan and phase files | explore output + wireframe | +| # | Action | Role | Input | +| --- | ------------ | ---------------------------------------------------- | ---------------------------- | +| 01 | `gather` | Collect and restate the source | user request | +| 02 | `explore` | Read the codebase for projection, rules, feasibility | gathered source | +| 03 | `experience` | Resolve UI decisions, frontend only | source + explore context | +| 04 | `plan` | Break into phases, write the plan and phase files | explore output + UI contract | Run them in order, `01 → 04`. The plan is the culmination. Skip `03` when there is no UI. Before running an action, read its file in `actions/`, not only the table or assets. ## References -- `references/wireframe-conventions.md`: how to draw the ASCII wireframe a screen needs. +- `references/wireframe-conventions.md`: bounded compatibility fallback while the UI provider remains optional. - `references/plan-status.md`: the plan lifecycle `status` values and who writes each. ## Assets diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-experience.md b/plugins/aidd-dev/skills/01-plan/actions/03-experience.md new file mode 100644 index 000000000..6e84ec429 --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/03-experience.md @@ -0,0 +1,29 @@ +# 03 - Experience + +Resolve implementation-ready UI decisions for frontend work. Skip when the feature has no interface. + +## Input + +The gathered source, explore context, and optional feature `ui.md`. + +## Output + +Prefer one verified current `ui.md` reference with revision, pinned systems, and required deltas. When the alpha UI provider is unavailable, return a compatibility-only low-fidelity wireframe. + +## Process + +1. **Find.** Inspect the feature's current `ui.md` and reject it while `.ui.lock` exists. +2. **Discover.** Resolve a provider from runtime capability metadata without naming a sibling. +3. **Resolve.** Invoke `create` or `revise` when available, then accept only a current ready contract whose systems and approved or verified deltas resolve at their current bases. + - Route satisfied approved deltas to system reconciliation and promoted deltas to UI revision. +4. **Fallback.** Draw a structure-only wireframe from [wireframe-conventions.md](../references/wireframe-conventions.md) only when no contract and no provider exist. + - Stop with `UI revision needed` when a contract exists but no provider can revise it. +5. **Return.** Reference a resolved contract and dependencies without copying decisions, or return the bounded fallback wireframe. + +## Test + +- Non-UI work skips this action. +- UI work yields one current ready contract with resolvable dependencies. +- A draft, stale, or promoted graph routes to its owning UI operation. +- Provider absence preserves only the compatibility wireframe and creates no UI artifact. +- Provider absence never bypasses an existing draft or stale contract. diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md deleted file mode 100644 index 928b9cb95..000000000 --- a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md +++ /dev/null @@ -1,20 +0,0 @@ -# 03 - Wireframe - -Sketch a low-fidelity ASCII wireframe of a screen, to fix its layout before the plan. Frontend only, skip it when the feature has no UI. - -## Input - -The screens to sketch, from the gathered source and the `02-explore` context (the existing screens and components). - -## Output - -A low-fidelity ASCII wireframe of each screen, its regions and key elements in place, with a numbered note per region. Structure only, no behavior, no styling, no final copy. - -## Process - -1. **Pick.** List the screens the feature needs. Skip the action entirely when there is no UI. -2. **Draw.** Sketch each screen per [wireframe-conventions.md](../references/wireframe-conventions.md). The wireframe feeds the plan. - -## Test - -- The output is a box-drawing wireframe of each screen with numbered regions and a one-line note each, carrying no behavior, styling, or final copy. diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md index e6f0677ce..685c1526c 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md +++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md @@ -4,7 +4,7 @@ Turn the explored source into a plan and its phases, save them, then review the ## Input -The explore output from `02-explore` (projection, rules, feasibility, risks), plus any confirmed wireframe from `03-wireframe`. +The explore output from `02-explore` (projection, rules, feasibility, risks), plus the verified UI contract reference or compatibility wireframe from `03-experience` for frontend work. ## Output @@ -14,9 +14,13 @@ A feature folder, always at `aidd_docs/tasks//_/_ {baseline restored}: 5: {channel} ``` -## Wireframe +## UI Contract +- Contract: `{project-relative ui.md path}@{revision}` +- Systems: {system ids and revisions} +- Implement deltas: {approved delta paths owned by this phase or none} +- Consume deltas: {verified delta paths and approved delta paths owned by an earlier phase, or none} +- Depends on phases: {owners of consumed approved deltas or none} + +## Wireframe + + + ```txt -{the confirmed wireframe} +{structure-only wireframe} ``` ## Tasks to do diff --git a/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md b/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md index 1dfb23947..14a9c4331 100644 --- a/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md +++ b/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md @@ -1,28 +1,8 @@ # Wireframe conventions -A wireframe is a low-fidelity ASCII sketch of a screen. Structure only: no behavior, no styling, no final copy. +Compatibility fallback used only when no UI decision provider is installed. -## Drawing - -- One box per screen, drawn with `┌ ─ ┐ │ └ ┘`. -- Place the regions (header, nav, main, aside, footer) and the key elements (lists, forms, cards, buttons, inputs) where they sit. -- Number each region. -- Under the sketch, one line per number on what it holds and why. - -## Example - -``` -┌─────────────────────────────────────┐ -│ (1) Header: logo · search · account │ -├──────────┬──────────────────────────┤ -│ (2) Nav │ (3) Results list │ -│ filters │ ┌──────────────────────┐ │ -│ by type │ │ (4) Result card │ │ -│ │ └──────────────────────┘ │ -└──────────┴──────────────────────────┘ -``` - -1. Header: brand, global search, account menu. -2. Nav: filters that narrow the list. -3. Results: the matched items, paginated. -4. Card: one result, title and summary. +- Draw one ASCII box per screen with numbered regions. +- Show regions and key elements in place. +- Add one line per number explaining its structural role. +- Include no behavior, state, styling, final copy, accessibility verdict, adaptation rule, or shared-system decision. diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md index 7e99042de..63c209fe5 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md +++ b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md @@ -13,11 +13,25 @@ The resolved plan on a feature branch with its frontmatter `status: in-progress` ## Process 1. **Resolve.** Resolve the plan from the arguments. A path must exist and be readable. With neither a readable file nor inline content, stop with `plan not found at `. Never fabricate a plan. -2. **Branch.** On the default branch, create a feature branch and announce it. On a non-default branch, keep it. -3. **Mark.** Set the plan frontmatter `status: in-progress` as a runtime marker. No separate commit: it rides into the first phase commit, or into the `implemented` commit if there is no phase to code. +2. **Revalidate UI.** Validate every referenced UI contract, system revision, and delta before mutation. + - Stop when the UI contract's feature folder contains `.ui.lock`. + - Require a current ready contract and current active system revisions. + - Permit a no-base establishment only without a current matching id or equal or unorderable active scope overlap. + - Permit `systems: []` when the contract proves no shared system decision applies. + - Require each approved delta in one `Implement deltas` owner phase. + - Require verified deltas only under `Consume deltas`. + - Permit an already-satisfied approved delta only when its owner phase is done in this plan. + - Stop with `replan needed` for any stale, invalid, changed, competing, or misowned reference. +3. **Branch.** On the default branch, create a feature branch and announce it. On a non-default branch, keep it. +4. **Mark.** Set the plan frontmatter `status: in-progress` as a runtime marker. No separate commit: it rides into the first phase commit, or into the `implemented` commit if there is no phase to code. ## Test - A missing or unreadable plan with no inline content stops with `plan not found at `, and no plan is fabricated. +- Stale UI references stop with `replan needed` before branch or status mutation. +- Delta ownership is complete and unique before branch or status mutation. +- A no-base establishment delta fails when a current matching id or equal or unorderable active scope overlap appears. +- An in-flight UI contract fails while `.ui.lock` exists. +- A contract without a shared system passes only when no shared system decision applies. - The current branch is not the default branch. - The plan frontmatter reads `status: in-progress`. diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md index 2c531ffb4..019f01387 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -12,10 +12,11 @@ Every phase coded, asserted, and its frontmatter marked `status: done`, with the ## Process -1. **Open.** Walk the phases in order. In a feature folder each is a `phase-.md` next to `plan.md`. Set its `status: in-progress` as a runtime marker; no commit yet. -2. **Code.** Build the phase scope against its acceptance criteria. -3. **Assert.** Assert the phase against its acceptance criteria. On failure, repair and repeat. The gate is the assertion passing, not a self-report. Once it passes, set `status: done` and commit the phase as one unit, its code and its status together. -4. **Guard.** Stop the loop on either condition: +1. **Open.** Walk the phases in order. In a feature folder each is a `phase-.md` next to `plan.md`. Open every referenced UI contract, exact system revision, and required delta before setting the phase `status: in-progress`. +2. **Revalidate.** Apply the prepare gate again immediately before each phase, including absence of a competing active contract for establishment. Any changed status, base, revision, body, scope ownership, or missing dependency returns `replan needed` without editing the phase. +3. **Code.** Build the phase scope against its acceptance criteria and the complete referenced UI contract. Implement only approved deltas listed under `Implement deltas`; each must be owned by exactly this phase. Treat verified deltas and approved deltas owned by completed phases as read-only dependencies. Missing or duplicate ownership returns `replan needed`. +4. **Assert.** Assert the phase against its acceptance criteria, UI contract behaviors, and delta verification conditions. On failure, repair and repeat. The gate is the assertion passing, not a self-report. Once it passes, set `status: done` and commit the phase as one unit, its code and its status together. Delta verification remains an explicit `01-system reconcile` operation; do not edit delta status locally. +5. **Guard.** Stop the loop on either condition: - **Blocked** (see [blocked.md](../references/blocked.md)): set the plan `status: blocked`, commit, stop. - **Drift**: any mismatch with the plan, trivial or substantive, stop and report `replan needed: `. Never rewrite the plan; replanning is the caller's job. @@ -24,3 +25,5 @@ Every phase coded, asserted, and its frontmatter marked `status: done`, with the - A phase reaches `status: done` only after assert passes against its acceptance criteria, in one commit with its code (`git status --short` shows no dangling phase edits). - The branch holds one commit per phase; there are no separate `in-progress` status commits. - A blocker leaves the plan `status: blocked` with no later phase run. +- UI contracts and deltas are opened and asserted, not treated as metadata only. +- An approved delta is implemented by one phase; a verified delta is never reimplemented. diff --git a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md index 2943bc426..80b62ef04 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md +++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md @@ -12,10 +12,12 @@ The feature validated green with the plan frontmatter `status: implemented`. ## Process -1. **Verify.** Run the plan's validation commands and tests. Never format code, never run dev mode. -2. **Mark.** Every phase done and validation green, set the plan `status: implemented` and commit it. +1. **Revalidate UI.** Apply the prepare UI graph gate once more, including no competing active contract for an establishment delta. Drift returns `replan needed` before final status mutation. +2. **Verify.** Run the plan's validation commands and tests. Never format code, never run dev mode. +3. **Mark.** Every phase done and validation green, set the plan `status: implemented` and commit it. ## Test - The validation commands exit zero. - The plan reads `status: implemented`, committed (`git status --short` shows it clean). +- An implemented establishment remains an approved delta until explicit system reconciliation verifies it. diff --git a/plugins/aidd-dev/skills/04-audit/SKILL.md b/plugins/aidd-dev/skills/04-audit/SKILL.md index 768ba5ec8..0e6d9d81a 100644 --- a/plugins/aidd-dev/skills/04-audit/SKILL.md +++ b/plugins/aidd-dev/skills/04-audit/SKILL.md @@ -1,6 +1,6 @@ --- name: 04-audit -description: Audit a codebase read-only across seven quality pillars into one ranked report. Use when the user wants to assess, health-check, or audit a codebase or one pillar. Not for fixing findings, reviewing a change, or checking a feature works. +description: Audit a codebase read-only across six engineering pillars plus delegated UI experience review. Use when the user wants to assess, health-check, or audit a codebase or one pillar. Not for fixing findings, reviewing a change, or checking a feature works. argument-hint: scope | pillar model: opus --- @@ -19,7 +19,7 @@ Diagnose a codebase against quality pillars and emit one ranked findings report. | 04 | `dependencies` | dependencies | CVEs, licenses, outdated and unused deps, supply chain | | 05 | `performance` | performance | N+1 queries, hot paths, bundle size, heavy operations | | 06 | `tests` | tests | Critical-path coverage, flakiness, test pyramid balance | -| 07 | `ui` | ui | Loading/error/empty states, visual hierarchy, design-system drift, responsive, a11y | +| 07 | `ui` | ui | Delegate experience diagnosis to a discovered UI review capability | Run the one pillar named, or offer all seven when the request is unscoped. Before running an action, read its file in `actions/`, not only the table or assets. @@ -28,9 +28,9 @@ Before running an action, read its file in `actions/`, not only the table or ass - Read-only: diagnose and rank, never edit code. - Scope: run the one named pillar, or for an unscoped request ask once "all seven pillars, or one?" before running. Never silently default to one pillar, never blind-run all without offering the choice. -- One folder per run, `aidd_docs/tasks//_audit/`, like a feature folder. Every pillar that runs always writes its own `.md` there, alone or in a full run. A full run additionally writes a merged `report.md`: one Findings table (category = pillar, severity-first), one Top-actions list, and one Coverage section over all seven pillars. +- One folder per run, `aidd_docs/tasks//_audit/`, like a feature folder. Every engineering pillar that runs writes its own `.md`; delegated UI review keeps its provider-owned report. A full run additionally writes `report.md`: one merged engineering Findings table, one Top-actions list, Coverage over all seven pillars, and a reference to the separate UI report when available. - Unscannable pillar: skip it, record it under `Coverage > Skipped` with the reason, and never invent findings for it. -- Every finding row carries a severity, its pillar, a concrete `file:line`, the issue, a suggested fix, and an effort. +- Every engineering finding row carries a severity, its pillar, a concrete `file:line`, the issue, a suggested fix, and an effort. Delegated UI findings retain the UI provider schema and are never converted into engineering rows. ## Assets diff --git a/plugins/aidd-dev/skills/04-audit/actions/07-ui.md b/plugins/aidd-dev/skills/04-audit/actions/07-ui.md index fa3cdb447..da8e31215 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/07-ui.md +++ b/plugins/aidd-dev/skills/04-audit/actions/07-ui.md @@ -1,31 +1,26 @@ # 07 - UI audit -Read-only audit of the `ui` pillar, missing states, design-system drift, responsive gaps, and accessibility. Reports findings, never edits code. +Compatibility shim that delegates UI experience diagnosis to its owning concern. Contains no UI review logic. ## Input -An optional scope, a directory or file glob, defaulting to the entire codebase. An optional running-frontend URL enables a runtime axe accessibility pass. +An optional interface scope, requirement source, and runtime evidence. ## Output -The `ui` findings, written to `ui.md` in the run's audit folder. +The non-normative UI review report returned by a discovered provider, or explicit skipped coverage when none is installed. ## Process -1. **Scope.** Default to the full codebase when no scope is given. Otherwise restrict scanning to the provided glob or directory. When a URL is given, also run a browser-based accessibility pass against the live frontend. -2. **Scan.** Use static component and markup analysis, plus a runtime axe-style accessibility pass when a URL is given. Stay in this pillar: redesign and implementation fixes are a separate concern. - - **Missing loading, error, and empty states**: flag UI surfaces (lists, forms, async data areas) with no visible feedback for in-progress loading, failed fetches, or zero-result datasets. - - **Visual hierarchy**: flag layouts where primary actions are visually subordinate, or where typographic hierarchy (heading levels, heading-to-body contrast) is broken. - - **Design-token drift**: identify hardcoded colour, spacing, or typography values that deviate from the project's design tokens or component library. - - **Responsive breakpoint gaps**: flag components or layouts that break or overflow at standard breakpoints (mobile, tablet, desktop), detectable from markup or media queries. - - **Accessibility (WCAG)**: contrast-ratio failures, missing keyboard navigation, incorrect or absent aria roles and labels, missing `alt` text. Run axe or equivalent against the URL when given, otherwise inspect markup statically. - - When no URL is given, record "no url provided, runtime a11y pass skipped, static inspection only" in `Coverage > Skipped`. Do not invent runtime findings from static analysis. -3. **Rate.** Give each finding a severity and an effort per the [audit-template.md](../assets/audit-template.md) legend, with a concrete `file:line`. The category is always `ui`. -4. **Write.** Fill [audit-template.md](../assets/audit-template.md) into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. +1. **Discover.** Resolve a capability described as diagnosing and prioritizing experience defects. Never hardcode a sibling provider. +2. **Delegate.** Supply scope and evidence without adding hierarchy, system, accessibility, or adaptation checks locally. +3. **Integrate.** Reference the provider report under `Delegated reports` and mark UI scanned in Coverage. Never merge or translate its findings into the engineering Findings table. +4. **Skip.** When no provider is installed, record `UI review provider unavailable` under Coverage and emit no UI finding. ## Test -- The output file exists at the reported path. -- It has the `## Findings`, `## Top actions`, and `## Coverage` sections. -- Every Findings row carries a severity, category `ui`, a concrete `file:line`, and an effort. -- Coverage lists `ui` as scanned, and no code was changed. +- The action contains no independent UI heuristic or verdict. +- Provider findings and provenance remain unchanged. +- The merged audit references, rather than rewrites, the provider report. +- Provider absence is skipped coverage, not a clean UI result. +- No application source or normative UI artifact changes. diff --git a/plugins/aidd-dev/skills/04-audit/assets/audit-template.md b/plugins/aidd-dev/skills/04-audit/assets/audit-template.md index 6566f8ccc..46c82c6d8 100644 --- a/plugins/aidd-dev/skills/04-audit/assets/audit-template.md +++ b/plugins/aidd-dev/skills/04-audit/assets/audit-template.md @@ -25,7 +25,7 @@ Severity (shared rubric across every audit pillar, so a full audit ranks consist - 🟢 minor - nit or cleanup. Fix when convenient. Effort: `S` (under 1h), `M` (under 1d), `L` (over 1d). -Category (the audit pillar, one of): `code-quality`, `architecture`, `security`, `dependencies`, `performance`, `tests`, `ui`. +Category (the engineering pillar, one of): `code-quality`, `architecture`, `security`, `dependencies`, `performance`, `tests`. UI experience findings remain in their delegated report because they use a different evidence and priority contract. | Sev | Category | Location | Issue | Suggested fix | Effort | | --- | ------------ | ------------------------- | -------------------------------------- | ------------------------------------ | ------ | @@ -35,12 +35,16 @@ Category (the audit pillar, one of): `code-quality`, `architecture`, `security`, ## Top actions -Highest impact first. Each action names the finding rows it resolves and, when a fix is wanted, the act-skill to hand off to (refactor, test, impeccable - the audit itself never edits code). +Highest impact first. Each action names the finding rows it resolves and, when a fix is wanted, the implementation capability to hand off to. The audit itself never edits code. 1. {{action_1}} 2. {{action_2}} 3. {{action_3}} +## Delegated reports + +- UI experience: {{project-relative ui-review.md path, unavailable, or not requested}} + ## Coverage Proves each pillar was examined. A pillar with no findings is still scanned and listed here. A pillar that could not be examined (missing tool or runtime) is listed under Skipped with the reason - never silently dropped. diff --git a/plugins/aidd-ui/.claude-plugin/plugin.json b/plugins/aidd-ui/.claude-plugin/plugin.json index 3bf68df5b..949e51813 100644 --- a/plugins/aidd-ui/.claude-plugin/plugin.json +++ b/plugins/aidd-ui/.claude-plugin/plugin.json @@ -2,13 +2,17 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "aidd-ui", "version": "0.2.1-alpha.0", - "description": "ALPHA, not ready for use. UI and UX concern for the AI-Driven Development framework. Use when the user wants to design, review, or improve a frontend interface. Do NOT use for backend-only or non-UI tasks.", + "description": "ALPHA. Versioned UI systems, feature experience contracts, evidence reviews, accessibility, and interface adaptation.", "author": { "name": "AI-Driven Dev", "url": "https://github.com/ai-driven-dev" }, "skills": [ - "./skills/01-hello" + "./skills/01-system", + "./skills/02-design", + "./skills/03-review", + "./skills/04-accessibility", + "./skills/05-adapt" ], "keywords": [ "ui", diff --git a/plugins/aidd-ui/CATALOG.md b/plugins/aidd-ui/CATALOG.md index 73912f57f..f2d4cd97e 100644 --- a/plugins/aidd-ui/CATALOG.md +++ b/plugins/aidd-ui/CATALOG.md @@ -8,7 +8,11 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai - [`.claude-plugin`](#claude-plugin) - [`skills`](#skills) - - [`skills/01-hello`](#skills01-hello) + - [`skills/01-system`](#skills01-system) + - [`skills/02-design`](#skills02-design) + - [`skills/03-review`](#skills03-review) + - [`skills/04-accessibility`](#skills04-accessibility) + - [`skills/05-adapt`](#skills05-adapt) --- @@ -20,10 +24,74 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai ### `skills` -#### `skills/01-hello` +#### `skills/01-system` | Group | File | Description | |-------|------|---| -| `actions` | [01-greet.md](skills/01-hello/actions/01-greet.md) | - | -| `-` | [SKILL.md](skills/01-hello/SKILL.md) | `Smoke-test that confirms the aidd-ui plugin loads. Use when the user wants to verify the alpha aidd-ui plugin is installed and reachable. Not for real UI or UX design work.` | +| `actions` | [01-inspect.md](skills/01-system/actions/01-inspect.md) | - | +| `actions` | [02-map.md](skills/01-system/actions/02-map.md) | - | +| `actions` | [03-specialize.md](skills/01-system/actions/03-specialize.md) | - | +| `actions` | [04-adopt.md](skills/01-system/actions/04-adopt.md) | - | +| `actions` | [05-establish.md](skills/01-system/actions/05-establish.md) | - | +| `actions` | [06-extend.md](skills/01-system/actions/06-extend.md) | - | +| `actions` | [07-retire.md](skills/01-system/actions/07-retire.md) | - | +| `actions` | [08-reconcile.md](skills/01-system/actions/08-reconcile.md) | - | +| `actions` | [09-promote.md](skills/01-system/actions/09-promote.md) | - | +| `assets` | [system-contract.md](skills/01-system/assets/system-contract.md) | - | +| `assets` | [system-delta.md](skills/01-system/assets/system-delta.md) | - | +| `references` | [authority.md](skills/01-system/references/authority.md) | - | +| `references` | [delta-path.md](skills/01-system/references/delta-path.md) | - | +| `references` | [lifecycle.md](skills/01-system/references/lifecycle.md) | - | +| `references` | [mutation.md](skills/01-system/references/mutation.md) | - | +| `references` | [scope.md](skills/01-system/references/scope.md) | - | +| `-` | [SKILL.md](skills/01-system/SKILL.md) | `Manages versioned shared UI system contracts and change deltas. Use when the user wants to map or govern shared interface conventions as explicit AIDD artifacts. Not for feature decisions, project memory, or source implementation.` | + +#### `skills/02-design` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-frame.md](skills/02-design/actions/01-frame.md) | - | +| `actions` | [02-inspect.md](skills/02-design/actions/02-inspect.md) | - | +| `actions` | [03-specialize.md](skills/02-design/actions/03-specialize.md) | - | +| `actions` | [04-structure.md](skills/02-design/actions/04-structure.md) | - | +| `actions` | [05-compose.md](skills/02-design/actions/05-compose.md) | - | +| `actions` | [06-write.md](skills/02-design/actions/06-write.md) | - | +| `actions` | [07-verify.md](skills/02-design/actions/07-verify.md) | - | +| `assets` | [ui-contract.md](skills/02-design/assets/ui-contract.md) | - | +| `references` | [evidence.md](skills/02-design/references/evidence.md) | - | +| `references` | [specialists.md](skills/02-design/references/specialists.md) | - | +| `-` | [SKILL.md](skills/02-design/SKILL.md) | `Creates or revises an AIDD ui.md experience contract. Use when the user wants implementation ready feature UI decisions versioned from product intent and current evidence. Not for shared system governance, review findings, or source implementation.` | + +#### `skills/03-review` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-inspect.md](skills/03-review/actions/01-inspect.md) | - | +| `actions` | [02-specialize.md](skills/03-review/actions/02-specialize.md) | - | +| `actions` | [03-assess.md](skills/03-review/actions/03-assess.md) | - | +| `actions` | [04-write.md](skills/03-review/actions/04-write.md) | - | +| `assets` | [review-report.md](skills/03-review/assets/review-report.md) | - | +| `references` | [findings.md](skills/03-review/references/findings.md) | - | +| `references` | [fingerprint.md](skills/03-review/references/fingerprint.md) | - | +| `-` | [SKILL.md](skills/03-review/SKILL.md) | `Produces an evidence pinned AIDD experience review report. Use when the user wants to diagnose and prioritize interface or flow defects before acceptance or rework. Not for implementation correctness or normative contract changes.` | + +#### `skills/04-accessibility` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-inspect.md](skills/04-accessibility/actions/01-inspect.md) | - | +| `actions` | [02-specify.md](skills/04-accessibility/actions/02-specify.md) | - | +| `actions` | [03-evaluate.md](skills/04-accessibility/actions/03-evaluate.md) | - | +| `references` | [fragments.md](skills/04-accessibility/references/fragments.md) | - | +| `-` | [SKILL.md](skills/04-accessibility/SKILL.md) | `Returns provider fragments for AIDD UI contracts, system deltas, or reviews. Use when the user wants to define, assess, or confirm accessibility behavior with evidence. Not for overall review priority, artifact composition, or source implementation.` | + +#### `skills/05-adapt` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-inspect.md](skills/05-adapt/actions/01-inspect.md) | - | +| `actions` | [02-specify.md](skills/05-adapt/actions/02-specify.md) | - | +| `actions` | [03-evaluate.md](skills/05-adapt/actions/03-evaluate.md) | - | +| `references` | [fragments.md](skills/05-adapt/references/fragments.md) | - | +| `-` | [SKILL.md](skills/05-adapt/SKILL.md) | `Returns context transformation fragments for AIDD UI artifacts. Use when the user wants to define, assess, or confirm behavior across space, input, or platform contexts. Not for task hierarchy, accessibility, or source implementation.` | diff --git a/plugins/aidd-ui/README.md b/plugins/aidd-ui/README.md index 868d24cb1..a5bbda78f 100644 --- a/plugins/aidd-ui/README.md +++ b/plugins/aidd-ui/README.md @@ -2,27 +2,49 @@ # aidd-ui 🚧 alpha -UI and UX concern for the AI-Driven Development framework. +UI experience and shared interface-system decisions for the AI-Driven Development framework. -> ⚠️ **ALPHA — NOT READY FOR USE.** `0.1.0-alpha.0`. This plugin ships a single smoke-test skill and no real UI/UX capability yet. Do not install it expecting to use it; it exists only to validate the scaffold. APIs, skills, and naming may change or be removed without notice. +> **Alpha.** Contracts may change, and the plugin remains off the curated install path. -> Status: alpha (experimental). +`aidd-ui` owns what an interface and its shared UI system must preserve. It consumes product intent and hands implementation ready decisions to engineering. -This plugin is in alpha (`0.1.0-alpha.0`). It lives on a dedicated branch off `next` and is registered with `recommended: false`, so it stays off the curated install path until it stabilises and graduates to `main`. While it is not in the published marketplace yet, test it from a local checkout of this branch: - -``` -claude --plugin-dir plugins/aidd-ui # zero-marketplace, session-scoped -# or, persistent: -/plugin marketplace add . # register this checkout as a local marketplace -/plugin install aidd-ui@aidd-framework +```text +product intent + current evidence + → shared UI system contract + → feature UI contract + → engineering implementation + → experience review ``` -Then run `aidd-ui:01-hello` to confirm it loads. - -One starter skill today; real UI and UX skills land as the concern stabilises. +Code is current implementation truth. Project memory is a compact stable map. UI contracts are decision authority. ## Skills -| Bracket ID | Skill | Description | -| ---------- | ----- | ----------- | -| [7.1] | [hello](skills/01-hello/SKILL.md) | Smoke-test skill that confirms the plugin loads. | +| Skill | Owns | Produces | +| --- | --- | --- | +| [system](skills/01-system/SKILL.md) | shared UI system lifecycle | system maps, versioned contracts, and lifecycle deltas | +| [design](skills/02-design/SKILL.md) | feature experience decisions | versioned `ui.md` | +| [review](skills/03-review/SKILL.md) | feature experience diagnosis and priority | non-normative `ui-review.md` | +| [accessibility](skills/04-accessibility/SKILL.md) | accessibility requirements and verdicts | typed specialist fragments | +| [adapt](skills/05-adapt/SKILL.md) | space, input, and platform transformations | typed specialist fragments | + +`01-system` stores the current shared contract at `aidd_docs/ui/systems/.md`, immutable prior revisions under `.history/`, and one task local `system-delta--.md` per proposed change. It decides the system. Engineering implements its sources and verification conditions. + +Install explicitly, then invoke the capability matching the decision owner: + +```text +/plugin install aidd-ui@aidd-framework +/aidd-ui:01-system discover +/aidd-ui:02-design create +``` + +## Boundaries + +- Product requirements are consumed, not authored here. +- Project memory is read only. Drift is reported for a separate refresh. +- Shared system and feature experience contracts are owned here, not source code. +- Engineering consumes ready contracts and owns implementation correctness. +- External design documents are evidence until explicitly adopted. +- Existing page patterns, composites, primitives, tokens, and layout conventions are reused before extension or creation. +- Assets may be contracted by role, source, constraints, and acceptance. Binary production remains outside this plugin. +- No design tool integration, image generation, browser automation, visual regression, component library, or token build pipeline is bundled. diff --git a/plugins/aidd-ui/skills/01-hello/SKILL.md b/plugins/aidd-ui/skills/01-hello/SKILL.md deleted file mode 100644 index e3406a95d..000000000 --- a/plugins/aidd-ui/skills/01-hello/SKILL.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: 01-hello -description: Smoke-test that confirms the aidd-ui plugin loads. Use when the user wants to verify the alpha aidd-ui plugin is installed and reachable. Not for real UI or UX design work. ---- - -# Skill: hello - -Confirm the aidd-ui plugin loads and is reachable. - -## Actions - -| # | Action | Role | -| --- | ------- | ------------------------------------------- | -| 01 | `greet` | Greet the user and confirm the skill works | - -Single action skill: run `greet` and return its message. -Before running an action, read its file in `actions/`, not only the table or assets. - -## Prerequisites - -- The plugin loaded locally (`claude --plugin-dir plugins/aidd-ui`, or installed from the marketplace). diff --git a/plugins/aidd-ui/skills/01-hello/actions/01-greet.md b/plugins/aidd-ui/skills/01-hello/actions/01-greet.md deleted file mode 100644 index 57b1aa825..000000000 --- a/plugins/aidd-ui/skills/01-hello/actions/01-greet.md +++ /dev/null @@ -1,15 +0,0 @@ -# 01 - greet - -Greet the caller to confirm the skill is reachable. - -## Output - -A short greeting printed in the chat. - -## Process - -1. **Print.** Print "Hello from aidd-ui (alpha)." - -## Test - -- The chat shows the line "Hello from aidd-ui (alpha)." diff --git a/plugins/aidd-ui/skills/01-system/SKILL.md b/plugins/aidd-ui/skills/01-system/SKILL.md new file mode 100644 index 000000000..9adc1e1a8 --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/SKILL.md @@ -0,0 +1,65 @@ +--- +name: 01-system +description: Manages versioned shared UI system contracts and change deltas. Use when the user wants to map or govern shared interface conventions as explicit AIDD artifacts. Not for feature decisions, project memory, or source implementation. +argument-hint: system request | delta +--- + +# UI System + +```mermaid +flowchart LR + discover([discover]) --> inspect + adopt_request([adopt]) --> inspect + establish_request([establish]) --> inspect + extend_request([extend]) --> inspect + retire_request([retire]) --> inspect + reject_request([reject]) --> inspect + reconcile_request([reconcile]) --> inspect + promote_request([promote]) --> inspect + inspect -->|missing target or scope conflict| stopped([stopped]) + inspect -->|discover| map --> current([system map]) + inspect -->|adopt, establish, extend, or retire| specialize + specialize -->|adopt concern unresolved| unresolved([unresolved]) + specialize -->|adopt| adopt + adopt -->|approval missing| unresolved + adopt -->|lock, id, or scope conflict| stopped + adopt -->|approved| active([active contract]) + specialize -->|establish| establish + establish -->|lock, id, or scope conflict| stopped + establish -->|written| delta([system delta]) + specialize -->|extend| extend + extend -->|reuse sufficient| reused([reuse decision]) + extend -->|lock or base conflict| stopped + extend -->|shared gap| delta + specialize -->|retire| retire + retire -->|lock or base conflict| stopped + retire -->|written| delta + inspect -->|reconcile or reject| reconcile + inspect -->|promote| reconcile + reconcile -->|lock conflict| stopped + reconcile -->|classified, rejected, or not promotable| result([reconciliation result]) + reconcile -->|verified base and promote request| promote + promote -->|lock, evidence, base, or write conflict| stopped + promote -->|success| promoted([promoted contract]) +``` + +## Actions + +Read only the next action file required by the flow above. + +| Action | Does | +| --- | --- | +| inspect | resolve system scope and evidence | +| map | report the current interface system | +| specialize | obtain applicable specialist decisions | +| adopt | record an implemented system | +| establish | authorize a minimum viable system | +| extend | authorize the smallest shared change | +| retire | authorize removal of an active system | +| reconcile | classify contract and implementation drift | +| promote | merge a verified delta into the contract | + +## Transversal rules + +- Own versioned shared UI system contracts and their change deltas. +- Never modify application source or project memory. diff --git a/plugins/aidd-ui/skills/01-system/actions/01-inspect.md b/plugins/aidd-ui/skills/01-system/actions/01-inspect.md new file mode 100644 index 000000000..27268fb06 --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/actions/01-inspect.md @@ -0,0 +1,28 @@ +# 01 - Inspect + +Resolve the target UI system, its scope, and the evidence needed by the requested operation. + +## Input + +The project root, target workspace or surface, and system request. + +## Output + +An evidence map covering matching contracts and deltas, current implementation, project memory, external design documents, conflicts, and missing proof. + +## Process + +1. **Scope.** Resolve zero or one matching current contract with [scope.md](../references/scope.md). +2. **Read.** Inspect the matched contract and deltas, then canonical token, theme, style, component, pattern, breakpoint, and asset sources in the target workspace. +3. **Compare.** Apply [authority.md](../references/authority.md) to project memory and external design documents. +4. **Classify.** Separate evidenced shared conventions, feature choices, conflicts, and gaps. + - When no evidence exists and creation was not requested, report the boundary and stop. + +## Test + +| Case | Pass | +| --- | --- | +| Monorepo | the target resolves zero or one active contract | +| Contract conflict | both sources remain visible and neither wins silently | +| Missing memory | inspection completes from contracts and repository evidence | +| Backend only | no UI artifact is proposed without an explicit creation request | diff --git a/plugins/aidd-ui/skills/01-system/actions/02-map.md b/plugins/aidd-ui/skills/01-system/actions/02-map.md new file mode 100644 index 000000000..25df2a8d1 --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/actions/02-map.md @@ -0,0 +1,27 @@ +# 02 - Map + +Return the current shared UI system without changing it. + +## Input + +The evidence map from [01-inspect.md](01-inspect.md) in discover mode. + +## Output + +A compact system map naming the active contract when present, its revision and scope, canonical implementation sources, confirmed conventions, conflicts, drift, and evidence gaps. + +## Process + +1. **Select.** Keep shared tokens, layouts, components, states, adaptation rules, accessibility rules, and assets that have direct evidence. +2. **Reference.** Name canonical source paths instead of copying implementation catalogs or every value. +3. **Separate.** Keep planned change, drift, stale memory, and unconfirmed evidence outside the map. +4. **Return.** Return only evidenced categories without writing an artifact. + +## Test + +| Case | Pass | +| --- | --- | +| Active contract | id, revision, scope, and implementation sources are named | +| Lightweight project | every reported convention cites a source and categories without evidence are absent | +| External `DESIGN.md` | it is evidence, never adopted automatically | +| Conflicting systems | ambiguity remains explicit when dominance is unsupported | diff --git a/plugins/aidd-ui/skills/01-system/actions/03-specialize.md b/plugins/aidd-ui/skills/01-system/actions/03-specialize.md new file mode 100644 index 000000000..154aabdca --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/actions/03-specialize.md @@ -0,0 +1,31 @@ +# 03 - Specialize + +Obtain applicable shared accessibility and adaptation decisions from their owning capabilities. + +## Input + +The system evidence map and requested adopt, establish, extend, or retire operation. + +## Output + +Provider-owned fragments with provenance, plus unresolved concerns. + +## Process + +1. **Select.** Identify only shared accessibility or context-transformation concerns affected by the requested operation. +2. **Discover.** Resolve providers at runtime by capability description. +3. **Invoke.** Request `confirm` for adoption and `define` for a future delta. + - Supply scope, nullable system revision, and evidence paths. + - Admit only confirmed fragments into an adopted contract. +4. **Resolve.** Return the provider outcome without rewriting its fields or verdict. + - When a required provider cannot run, leave the concern unresolved. + +## Test + +| Case | Pass | +| --- | --- | +| Existing behavior adopted | defective behavior is not canonized as a convention | +| Conforming behavior adopted | a provider-confirmed rule and its provenance enter the contract | +| Future shared behavior | provider requirements are preserved in the delta | +| Provider unavailable | the affected decision stays unresolved | +| Irrelevant concern | no boilerplate provider call is made | diff --git a/plugins/aidd-ui/skills/01-system/actions/04-adopt.md b/plugins/aidd-ui/skills/01-system/actions/04-adopt.md new file mode 100644 index 000000000..b06013583 --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/actions/04-adopt.md @@ -0,0 +1,36 @@ +# 04 - Adopt + +Record an implemented shared UI system as an active revision 1 contract. + +## Input + +An evidence map with no current matching id or ambiguous active scope and implemented shared UI sources. + +## Output + +`aidd_docs/ui/systems/.md` at revision `1`, filled from [system-contract.md](../assets/system-contract.md). + +## Process + +1. **Require.** Require a canonical shared source or two evidenced use sites. + - Stop for a current matching id or equal or unorderable active scope overlap. +2. **Draft.** Capture evidenced decisions, source paths, and confirmed fragments from [03-specialize.md](03-specialize.md). + - Keep defects and evidence gaps outside the contract. +3. **Approve.** Require explicit user approval or an authorized caller mandate for the exact contract. +4. **Lock.** Apply [mutation.md](../references/mutation.md) and repeat the competing-contract check under the lock. +5. **Write.** Fill the asset with `status: active`, `revision: 1`, `supersedes: null`, normalized scope paths, and implementation sources. +6. **Verify.** Read the file back and confirm every decision is supported by current implementation evidence. + +## Test + +| Case | Pass | +| --- | --- | +| Shared implementation | the active contract cites canonical sources or repeated use | +| Partial system | only confirmed shared surfaces are adopted | +| Specialist defect | it remains outside the accepted contract and is reported | +| Specialist fragment integrated | its provider name and verdict are unchanged | +| Competing contract | adoption stops before writing | +| Nested active scope | a strict child or parent scope remains resolvable by specificity | +| First system | the exclusive lock works before the systems directory exists | +| Concurrent mutation | adoption stops without replacing another writer's result | +| No approval | no active contract is created | diff --git a/plugins/aidd-ui/skills/01-system/actions/05-establish.md b/plugins/aidd-ui/skills/01-system/actions/05-establish.md new file mode 100644 index 000000000..cce8d548f --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/actions/05-establish.md @@ -0,0 +1,38 @@ +# 05 - Establish + +Authorize the minimum shared system required when no coherent system exists. + +## Input + +An explicit shared UI need and an evidence map with no current contract for the proposed id or ambiguous active scope. + +## Output + +A delta at [delta-path.md](../references/delta-path.md), filled from [system-delta.md](../assets/system-delta.md) with `mode: establish` and `base_revision: null`. + +## Process + +1. **Lock.** Apply [mutation.md](../references/mutation.md) and rebuild the scope evidence under the lock. + - Stop when a current contract has the proposed id or an active contract has an equal or unorderable scope overlap. +2. **Bound.** Include only conventions required by the stated work. + - Do not create a full token taxonomy or component catalog. +3. **Reuse.** Preserve evidenced local values and patterns before proposing new foundations. +4. **Draft.** Write the delta with normalized scope, expected sources, specialist fragments, acceptance, constraints, and unresolved items. +5. **Finalize.** Set the delta lifecycle state. + - Without exact authorization, keep `status: draft`. + - With exact authorization, record the approval source and set `status: approved`. + +## Test + +| Case | Pass | +| --- | --- | +| No system | every proposed convention cites a requirement and no unrequested foundation category appears | +| Retired id exists | establishment stops without overwriting it | +| Retired different id | its former scope does not block a new system id | +| Nested active scope | a strict child or parent scope remains resolvable by specificity | +| Missing specialist decision | the delta stays draft with an unresolved item | +| Approval | the exact reviewed delta becomes approved | +| Concurrent mutation | the write stops without replacing another writer's result | +| Multiple systems | each change has a distinct system and delta filename | +| First system | the exclusive lock works before the systems directory exists | +| No implementation | no application source or active contract is created | diff --git a/plugins/aidd-ui/skills/01-system/actions/06-extend.md b/plugins/aidd-ui/skills/01-system/actions/06-extend.md new file mode 100644 index 000000000..45e33f9bc --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/actions/06-extend.md @@ -0,0 +1,32 @@ +# 06 - Extend + +Authorize the smallest shared change that satisfies a new UI need. + +## Input + +An active system contract, its implementation evidence, and an explicit unmet shared need. + +## Output + +A delta at [delta-path.md](../references/delta-path.md) with `mode: extend` and `base_revision` equal to the active revision. + +## Process + +1. **Match.** Search existing page patterns, composites, primitives, tokens, and layout conventions in that order. + - When the current system closes the need, return reuse and stop. +2. **Prepare.** Render the smallest extension and any rejected parallel convention in memory. +3. **Lock.** Apply [mutation.md](../references/mutation.md) and recheck the active base under the lock. +4. **Draft.** Record target scope, expected sources, affected states, specialist fragments with exact provider names, acceptance conditions, and `status: draft` without implementation code. +5. **Finalize.** Set the delta lifecycle state. + - Without exact authorization, keep `status: draft`. + - With exact authorization, record the approval source and set `status: approved`. + +## Test + +| Case | Pass | +| --- | --- | +| Existing surface fits | no delta is written | +| Extension | unmet need, affected surface, and states are explicit | +| New primitive | failed reuse and extension options are evidenced | +| Concurrent change | the delta records the exact active base revision | +| Concurrent mutation | the write stops without replacing another writer's result | diff --git a/plugins/aidd-ui/skills/01-system/actions/07-retire.md b/plugins/aidd-ui/skills/01-system/actions/07-retire.md new file mode 100644 index 000000000..87660da42 --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/actions/07-retire.md @@ -0,0 +1,34 @@ +# 07 - Retire + +Authorize removal of an active UI system from scope resolution. + +## Input + +An active system contract and explicit retirement intent. + +## Output + +A delta at [delta-path.md](../references/delta-path.md) with `mode: retire`, the active base, dependencies, and migration acceptance. + +## Process + +1. **Lock.** Apply [mutation.md](../references/mutation.md) and recheck the active base under the lock. +2. **Confirm.** Require explicit intent to remove or replace the system. + - Treat absent usage as evidence, not authorization. +3. **Trace.** Find UI contracts, active deltas, and implementation sources that still reference the system. +4. **Plan.** List active consumers as migration dependencies that block verification but not approval. +5. **Resolve.** Classify the migration outcome. + - While the outcome is ambiguous, keep the delta draft. + - When the authorized outcome is decommissioning, do not require a replacement. +6. **Finalize.** Record the exact authorized retirement without deleting contract history. + +## Test + +| Case | Pass | +| --- | --- | +| Active consumers | an approved delta may name them as required migration work | +| Consumers remain | the delta cannot become verified | +| Approved replacement | the replacement id and migration conditions are present | +| No replacement | explicit decommissioning and consumer removal make the outcome complete | +| Delta written | it contains migration acceptance without changing the contract | +| Concurrent mutation | the write stops without replacing another writer's result | diff --git a/plugins/aidd-ui/skills/01-system/actions/08-reconcile.md b/plugins/aidd-ui/skills/01-system/actions/08-reconcile.md new file mode 100644 index 000000000..d3607f8ca --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/actions/08-reconcile.md @@ -0,0 +1,35 @@ +# 08 - Reconcile + +Classify differences among contracts, deltas, implementation, and memory. + +## Input + +The evidence map, active contract when present, and relevant system deltas. + +## Output + +A reconciliation result classifying each difference, plus an authorized delta status transition when proven. + +## Process + +1. **Classify.** Assign each difference one class from [authority.md](../references/authority.md). + - When a delta status may change, apply [mutation.md](../references/mutation.md) and reclassify under the lock. +2. **Transition.** Apply only a transition allowed by [lifecycle.md](../references/lifecycle.md). + - Mark a stale-base delta `superseded` without rebasing it. + - Mark an exact draft or approved delta `rejected` only from explicit authorization. + - Mark an approved delta `verified` only when every acceptance condition resolves at one implementation commit. +3. **Record.** Store the commit, verified sources, and evidence for verification. + - Leave the delta approved when required runtime proof is unavailable. +4. **Preserve.** Surface unauthorized code drift without choosing a winner. +5. **Stop.** Promotion and memory refresh are separate explicit operations. + +## Test + +| Case | Pass | +| --- | --- | +| Approved, code unchanged | classified as pending, not drift | +| Code matches delta | delta becomes verified with evidence | +| Runtime unavailable | delta remains approved | +| Stale base | delta becomes superseded without contract mutation | +| Explicit rejection | the exact draft or approved delta becomes rejected | +| Concurrent mutation | status transition stops without replacing another writer's result | diff --git a/plugins/aidd-ui/skills/01-system/actions/09-promote.md b/plugins/aidd-ui/skills/01-system/actions/09-promote.md new file mode 100644 index 000000000..0f7ee966a --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/actions/09-promote.md @@ -0,0 +1,45 @@ +# 09 - Promote + +Merge one verified delta into its UI system contract. + +## Input + +A specific verified system delta and its active base contract when one exists. + +## Output + +The updated active or retired system contract and the same delta marked `promoted`. + +## Process + +1. **Lock.** Apply [mutation.md](../references/mutation.md). +2. **Recheck.** Validate the delta and current contract under the lock against [lifecycle.md](../references/lifecycle.md). + - For `establish`, require no current contract with the id and no equal or unorderable active scope overlap. + - For `extend`, require every verified source to prove the change against the active base. + - For `retire`, require migrated consumers and disconnected old sources. + - When retirement declares a replacement, require its implementation sources to resolve. + - Do not require an active replacement contract. +3. **Render.** Prepare the complete contract, archive, and promoted delta bodies in memory. + - Establishment creates revision `1` from target scope and verified sources without an archive or history directory. + - Extension archives and increments the active contract. + - Retirement archives and increments the contract to `retired` while retaining historical source paths. +4. **Write.** Replace the contract and delta with the ordered, recoverable writes in [mutation.md](../references/mutation.md). +5. **Read back.** Confirm the archive, contract revision, and promoted delta before releasing the lock. +6. **Signal.** Report stable-memory drift for a separate refresh. + +## Test + +| Case | Pass | +| --- | --- | +| Verified delta | contract advances exactly one revision | +| Unresolvable commit or source | promotion fails without mutation | +| Stale base | promotion fails without mutation | +| Interrupted write | an exact retry completes promotion and any mismatched state stops for reconciliation | +| Concurrent promotion | the loser stops without replacing another writer's files | +| Stale lock | promotion stops and reports the lock without guessing ownership | +| Retired id establishment | promotion stops without replacing the retired head | +| Retired different id | its former scope permits establishment of a new id | +| First revision | establishment creates no empty history directory | +| Retirement | history remains and status becomes retired | +| Retired source removed | absence may satisfy retirement verification and the historical path remains in the contract | +| Pinned old revision | it resolves from the immutable history file | diff --git a/plugins/aidd-ui/skills/01-system/assets/system-contract.md b/plugins/aidd-ui/skills/01-system/assets/system-contract.md new file mode 100644 index 000000000..787a485b9 --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/assets/system-contract.md @@ -0,0 +1,54 @@ +--- +id: {system-id} +revision: {positive integer} +status: {active | retired} +scope: + - {normalized project-relative UI root} +sources: + - {canonical implementation path} +supersedes: {system-id@revision or null} +--- + + + +# UI System: {name} + +## Intent + +{What this shared system enables and the products or workspaces it serves.} + +## Foundations + +| Decision | Contract | Evidence | +| --- | --- | --- | +| {color, type, spacing, shape, depth, or motion foundation} | {accepted rule} | {canonical source path} | + +## Surfaces + +| Pattern, component, or token | Contract | States | Source | +| --- | --- | --- | --- | +| {shared surface} | {when and how it is used} | {applicable states} | {canonical source path} | + +## Adaptation + +| Provider | Target and scope | Evidence | Required transformation | Acceptance | +| --- | --- | --- | --- | --- | +| {provider provenance} | {space, input, or platform target} | {source} | {shared behavior} | {observable condition} | + +## Accessibility + +| Provider | Target and scope | Evidence | Required behavior | Acceptance | +| --- | --- | --- | --- | --- | +| {provider provenance} | {shared interaction} | {source} | {accessible behavior} | {observable condition} | + +## Assets + +| Asset family | Role | Canonical source | +| --- | --- | --- | +| {icons, imagery, type, or other asset} | {accepted use} | {project path} | + +## Deprecations + +| Surface | Replacement | Removal condition | +| --- | --- | --- | +| {deprecated convention} | {accepted replacement} | {condition} | diff --git a/plugins/aidd-ui/skills/01-system/assets/system-delta.md b/plugins/aidd-ui/skills/01-system/assets/system-delta.md new file mode 100644 index 000000000..1bcdf7810 --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/assets/system-delta.md @@ -0,0 +1,63 @@ +--- +id: {delta-id} +system: {system-id} +base_revision: {positive integer or null} +mode: {establish | extend | retire} +status: {draft | approved | verified | promoted | rejected | superseded} +approval_source: {user confirmation, orchestrator mandate, or null} +verification_commit: {commit id or null} +target_scope: + - {normalized project-relative UI root} +expected_sources: + - {planned canonical implementation path} +verified_sources: + - {implemented canonical path or empty until verified} +--- + + + +# UI System Delta: {title} + +## Need + +{Explicit requirement and why the active system cannot already satisfy it.} + +## Reuse + +| Existing surface | Source | Role | +| --- | --- | --- | +| {pattern, component, token, or convention} | {project path} | {how it is reused} | + +## Change + +| Decision | Evidence | Consequence | Rejected alternative | +| --- | --- | --- | --- | +| {smallest shared change} | {requirement or implementation evidence} | {contract effect} | {optional rejected parallel convention} | + +## States + +| State or context | Required behavior | Acceptance | +| --- | --- | --- | +| {shared component or pattern state} | {behavior} | {observable condition} | + +## Specialist Fragments + +| Provider | Concern and scope | Evidence | Required behavior | Acceptance | System impact | +| --- | --- | --- | --- | --- | --- | +| {provider} | {accessibility or adaptation target and scope} | {evidence} | {behavior} | {condition} | {impact or none} | + +## Dependencies + +- {dependent UI contract, implementation source, or replacement system} + +## Implementation Constraints + +- {constraint without component code or CSS} + +## Verification + +- {evidence required before promotion} + +## Unresolved + +- {decision that keeps the delta draft} diff --git a/plugins/aidd-ui/skills/01-system/references/authority.md b/plugins/aidd-ui/skills/01-system/references/authority.md new file mode 100644 index 000000000..0bae8ff9a --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/references/authority.md @@ -0,0 +1,24 @@ +# UI system authority + +## Evidence priority + +1. explicit user requirement. +2. approved delta for authorized future behavior. +3. active UI system contract for accepted shared decisions. +4. repository code for implemented behavior. +5. project memory as a compact summary. +6. external design documents as supporting evidence. + +Code wins against memory. Contract and code differences remain visible until reconciliation. + +## Difference classes + +| Class | Meaning | +| --- | --- | +| approved pending change | code has not implemented an approved delta | +| conforming implementation | code satisfies the active contract or approved delta | +| unauthorized code drift | code changed shared behavior without authority | +| stale contract | accepted contract no longer represents intended behavior | +| stale memory | memory conflicts with current repository evidence | +| external-document mismatch | supporting design evidence conflicts with authority | +| scope conflict | contracts match the same target without a unique owner | diff --git a/plugins/aidd-ui/skills/01-system/references/delta-path.md b/plugins/aidd-ui/skills/01-system/references/delta-path.md new file mode 100644 index 000000000..0fd449861 --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/references/delta-path.md @@ -0,0 +1,7 @@ +# System delta path + +1. Reuse the task folder containing the supplied requirement or UI contract. +2. Otherwise use an explicit caller supplied task folder. +3. Otherwise create `aidd_docs/tasks//_/`. + +Write the delta there as `system-delta--.md`. diff --git a/plugins/aidd-ui/skills/01-system/references/lifecycle.md b/plugins/aidd-ui/skills/01-system/references/lifecycle.md new file mode 100644 index 000000000..4251cc2a8 --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/references/lifecycle.md @@ -0,0 +1,21 @@ +# UI system lifecycle + +## Delta states + +```text +draft -> approved -> verified -> promoted +draft | approved -> rejected +draft | approved | verified -> superseded +``` + +- Editing an approved delta creates a new draft. +- Verification records one implementation commit and its evidence. +- Promotion requires a verified delta against the current base. +- A promoted delta is historical, not a feature dependency. + +## Revisions + +- The current contract is `aidd_docs/ui/systems/.md`. +- Its prior body is `.history/@.md`. +- Resolve current first, then immutable history. +- Never edit a history file. diff --git a/plugins/aidd-ui/skills/01-system/references/mutation.md b/plugins/aidd-ui/skills/01-system/references/mutation.md new file mode 100644 index 000000000..b42ba478e --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/references/mutation.md @@ -0,0 +1,11 @@ +# System mutation protocol + +1. Acquire `.aidd-ui-systems.lock` at the project root with an atomic directory create before re-reading or writing mutable state. +2. Stop when the lock directory exists. Remove only the lock directory created by this operation. +3. Re-read the current contract and affected delta under the lock, then validate the requested transition. +4. Render changed bodies to sibling temporary files on the same filesystem. +5. Create immutable history with an exclusive create. If the path exists, require its body to match exactly. +6. Replace each current file by atomic rename. Create `.history/` only when a prior revision must be archived. +7. Read back every result before releasing the lock. + +The project-root lock works before the systems directory exists and serializes scope checks across different ids. Promotion writes the contract before the delta. If interrupted between them, a retry may finish only when the current contract exactly matches the revision rendered from that delta. Any other mismatch stops for reconciliation. diff --git a/plugins/aidd-ui/skills/01-system/references/scope.md b/plugins/aidd-ui/skills/01-system/references/scope.md new file mode 100644 index 000000000..ed3e113ac --- /dev/null +++ b/plugins/aidd-ui/skills/01-system/references/scope.md @@ -0,0 +1,11 @@ +# UI system scope + +- Store normalized project-relative UI roots. +- Resolve the most specific active scope. +- Stop on equal or unorderable overlaps. +- Permit strict parent and child scopes because the child is more specific. +- Treat shared packages as sources, not inherited scopes. +- Do not infer contract inheritance. +- Block establishment when the id has an active or retired current contract. +- Block establishment when another active contract has an equal or unorderable overlap. +- A retired contract with another id does not own an active scope. diff --git a/plugins/aidd-ui/skills/02-design/SKILL.md b/plugins/aidd-ui/skills/02-design/SKILL.md new file mode 100644 index 000000000..f118e937b --- /dev/null +++ b/plugins/aidd-ui/skills/02-design/SKILL.md @@ -0,0 +1,45 @@ +--- +name: 02-design +description: Creates or revises an AIDD ui.md experience contract. Use when the user wants implementation ready feature UI decisions versioned from product intent and current evidence. Not for shared system governance, review findings, or source implementation. +argument-hint: create | revise +--- + +# UI Design + +```mermaid +flowchart LR + create([create]) --> frame + revise([revise]) --> frame + frame -->|blocking intent gap| stopped([stopped]) + frame --> inspect + inspect -->|no UI target or scope conflict| stopped + inspect --> specialize --> structure --> compose --> write --> verify + write -->|lock, archive, revision, or recovery conflict| stopped + verify -->|lock, receipt, or revision conflict| stopped + verify -->|ready| ready([ready contract]) + verify -->|unresolved| draft([draft contract]) + verify -->|content defect| compose + verify -->|serialization or version defect| write +``` + +## Actions + +Read only the next action file required by the flow above. + +| Action | Does | +| --- | --- | +| frame | isolate the feature intent | +| inspect | resolve existing UI authority | +| specialize | obtain applicable specialist decisions | +| structure | define feature structure and states | +| compose | decide the feature experience | +| write | record the versioned UI contract | +| verify | prove contract readiness | + +## Transversal rules + +- Own feature-local experience decisions. +- Reference shared system decisions by exact revision. +- In revise mode, preserve information architecture and task flow unless the source explicitly authorizes changing them. +- Preserve factual or legal meaning unless the source explicitly authorizes changing it. +- Never modify application source, UI system contracts, or project memory. diff --git a/plugins/aidd-ui/skills/02-design/actions/01-frame.md b/plugins/aidd-ui/skills/02-design/actions/01-frame.md new file mode 100644 index 000000000..8a3fa4b15 --- /dev/null +++ b/plugins/aidd-ui/skills/02-design/actions/01-frame.md @@ -0,0 +1,28 @@ +# 01 - Frame + +Isolate the feature intent without recreating product requirements. + +## Input + +The user's request or requirements artifact, plus `create` or `revise` mode. + +## Output + +A compact frame naming the contract target, objective, user task, platform, affected surfaces, constraints, sources, and material unknowns. + +## Process + +1. **Locate.** Reuse the supplied artifact folder or create `aidd_docs/tasks//_/`. +2. **Extract.** Keep only facts that constrain the interface experience and retain their sources. +3. **Classify.** Use `create` without a contract and `revise` against an identified revision. + - For one material experience unknown, ask one focused question and stop. + - Keep other unknowns explicit. + +## Test + +| Case | Pass | +| --- | --- | +| Existing requirements | each frame fact is sourced or explicitly derived | +| Revise mode | the existing contract id and revision are named | +| Missing essential fact | design decisions wait for one focused question | +| Complete frame | it contains no new product requirement or implementation choice | diff --git a/plugins/aidd-ui/skills/02-design/actions/02-inspect.md b/plugins/aidd-ui/skills/02-design/actions/02-inspect.md new file mode 100644 index 000000000..abaa219f3 --- /dev/null +++ b/plugins/aidd-ui/skills/02-design/actions/02-inspect.md @@ -0,0 +1,33 @@ +# 02 - Inspect + +Resolve the UI authority and implementation evidence for the feature target. + +## Input + +The frame from [01-frame.md](01-frame.md) and the project root. + +## Output + +An evidence map naming zero or one active UI system contract, implementation sources, relevant feature patterns, drift, and unresolved shared needs. + +## Process + +1. **Scope.** Select the affected frontend workspace before reading monorepo root configuration. +2. **Resolve.** Match the most specific active UI system scope. + - Stop on equal or unorderable overlaps. + - Treat shared packages as sources, not inherited scopes. +3. **Confirm.** Compare available evidence with [evidence.md](../references/evidence.md). + - Cite paths and behavior without copying source syntax. + - When no UI evidence exists and the request does not explicitly create an interface, report the boundary and stop. +4. **Separate.** Record an unmet shared need as a system-delta dependency. + +## Test + +| Case | Pass | +| --- | --- | +| Active system | its id, revision, scope, and canonical sources are named | +| Scope conflict | design stops without arbitrarily selecting a contract | +| Stale memory | repository reality is reported and memory remains unchanged | +| Shared gap | it becomes a system dependency, not a feature-local convention | +| Backend only | no interface is invented without explicit intent | +| Source evidence | it is referenced by path without markup, CSS, or framework excerpts | diff --git a/plugins/aidd-ui/skills/02-design/actions/03-specialize.md b/plugins/aidd-ui/skills/02-design/actions/03-specialize.md new file mode 100644 index 000000000..fc509a7ee --- /dev/null +++ b/plugins/aidd-ui/skills/02-design/actions/03-specialize.md @@ -0,0 +1,28 @@ +# 03 - Specialize + +Obtain applicable accessibility and adaptation decisions from their owning capabilities. + +## Input + +The frame and evidence map. + +## Output + +Specialist fragments conforming to [specialists.md](../references/specialists.md), plus unverified capabilities. + +## Process + +1. **Select.** Identify only accessibility and space, input, or platform concerns that materially affect this feature. +2. **Discover.** Resolve each provider at runtime by capability description. +3. **Resolve.** Invoke each provider with the frame, nullable system revision, evidence paths, and `define` operation. + - Record the exact discovered capability name in every returned fragment. + - When a required provider cannot run, mark its concern unverified. + +## Test + +| Case | Pass | +| --- | --- | +| Provider available | every fragment carries its exact discovered capability name | +| Provider unavailable | the applicable concern is unverified, not inferred | +| Shared impact | the fragment becomes a system-delta dependency | +| Irrelevant concern | no boilerplate fragment is requested | diff --git a/plugins/aidd-ui/skills/02-design/actions/04-structure.md b/plugins/aidd-ui/skills/02-design/actions/04-structure.md new file mode 100644 index 000000000..d8476b19d --- /dev/null +++ b/plugins/aidd-ui/skills/02-design/actions/04-structure.md @@ -0,0 +1,29 @@ +# 04 - Structure + +Define feature information and interaction structure before visual treatment. + +## Input + +The frame, evidence map, and specialist fragments. + +## Output + +A feature structure naming screens, regions, information order, actions, responsibilities, transitions, and applicable states. + +## Process + +1. **Order.** Arrange information and actions around the stated user task. +2. **Assign.** Give each feature region one responsibility. +3. **Model.** Include only applicable default, loading, empty, error, disabled, success, destructive, permission, offline, timeout, localization, and extreme-content states. +4. **Preserve.** Apply specialist required behavior without changing its verdict. +5. **Represent.** Select the minimum structural representation. + - When spatial relationships remain ambiguous, add a low-fidelity view. + +## Test + +| Case | Pass | +| --- | --- | +| Region or action | it traces to the frame, system, or evidence map | +| State included | its trigger and observable outcome are named | +| Specialist behavior | it appears without reinterpretation | +| Low-fidelity view | it contains structure, not arbitrary styling or final copy | diff --git a/plugins/aidd-ui/skills/02-design/actions/05-compose.md b/plugins/aidd-ui/skills/02-design/actions/05-compose.md new file mode 100644 index 000000000..e8a37774e --- /dev/null +++ b/plugins/aidd-ui/skills/02-design/actions/05-compose.md @@ -0,0 +1,39 @@ +# 05 - Compose + +Turn the feature structure into explicit experience decisions. + +## Input + +The structure, evidence map, active UI system, and specialist fragments. + +## Output + +Feature-local interface decisions, reused system surfaces, and required system-delta references. + +## Process + +1. **Reuse.** Apply the reuse order in [evidence.md](../references/evidence.md) to every region and interaction. +2. **Decide.** Record material feature choices with evidence and consequence. + - Include a rejected alternative only when it explains the decision. +3. **Source.** Reuse existing assets by path or record only the role, constraints, and acceptance required for a missing asset. +4. **Express.** Specify only evidenced interface copy, hierarchy, visual emphasis, density, alignment, feedback, and motion that implementation must preserve. +5. **Depend.** Reference an existing delta or leave the shared gap unresolved. +6. **Compare.** Apply the selected contract mode. + - In `revise` mode, record preserved and changed decisions against the prior contract. + - In `create` mode, record no superseded contract. +7. **Bound.** Use system vocabulary without component code, CSS, or framework recipes. + +## Test + +| Case | Pass | +| --- | --- | +| Existing surface fits | it is named at its exact contract revision | +| Shared gap | a system-delta path is referenced, not duplicated | +| Feature choice | it remains local to this contract | +| Interface copy | it traces to intent or system evidence and preserves factual meaning | +| Feature motion | trigger and feedback role are explicit while the applicable accessibility fragment is preserved | +| Existing asset | its project path and role are named | +| Missing asset | role, constraints, and acceptance are explicit without producing a binary | +| Inapplicable expression | no empty checklist or speculative decision is added | +| Revise mode | preserved and changed decisions are explicit | +| Final direction | it contains no production implementation | diff --git a/plugins/aidd-ui/skills/02-design/actions/06-write.md b/plugins/aidd-ui/skills/02-design/actions/06-write.md new file mode 100644 index 000000000..16482ed8e --- /dev/null +++ b/plugins/aidd-ui/skills/02-design/actions/06-write.md @@ -0,0 +1,56 @@ +# 06 - Write + +Record the feature experience as a versioned UI contract. + +## Input + +The frame, feature decisions, specialist fragments, system references, and unresolved items. + +## Output + +`ui.md` in the feature task folder, filled from [ui-contract.md](../assets/ui-contract.md), plus its id, revision, and SHA-256 body digest. + +## Process + +1. **Lock.** Acquire `.ui.lock` with an atomic directory create before reading mutable state. + - Stop when the lock already exists. + - Remove only the lock directory created by this run. +2. **Version.** Start at revision `1` or increment the exact current revision under the lock. + - Set `supersedes` to `@`. + - Archive the prior body at `.ui-history/@.md`. +3. **Pin.** Record each active system revision and required delta path. + - `systems: []` is valid when no shared system decision applies. + - Omit a future system entry for a no-base establishment only when no current matching id or equal or unorderable active scope overlap exists. +4. **Integrate.** Place fragments with [specialists.md](../references/specialists.md). + - Keep an applicable concern unverified when its exact discovered provider name is absent. +5. **Status.** Write `status: draft` until [07-verify.md](07-verify.md) publishes the verified body. + - Record blocking unknowns or draft, rejected, superseded, stale, or promoted dependencies. + - Replace a promoted delta with its new system revision before verification. +6. **Write.** Render sibling temporary files on the same filesystem, then replace the current contract by atomic rename while the lock is held. + - Create an archive with exclusive create only when a prior revision exists. + - Require a matching body when the archive path already exists. + - Remove asset placeholders and empty optional sections. + - Never copy source code or delta bodies into the contract. + - If interrupted after archive creation, retry only when the immutable archive matches. + - Replace the current contract after an exact retry check. +7. **Verify.** Read back the archive when applicable and the current contract before releasing the lock. + - Return the exact id, revision, and SHA-256 digest read from the published draft. + +## Test + +| Case | Pass | +| --- | --- | +| Contract written | id, revision, draft status, systems, and required deltas are valid | +| No shared system | a draft contract may use `systems: []` when no shared decision applies | +| Specialist unavailable | status remains draft and the gap is explicit | +| Specialist provenance missing | the contract stays draft | +| Required delta draft | status remains draft | +| Approved establishment | the draft may omit the not-yet-created system entry | +| Required delta promoted | pin the promoted system revision and remove the delta before verification | +| Revision | the prior revision is traceable and not silently lost | +| Archived revision | its body is immutable and resolves by id and revision | +| Concurrent revision | the write stops without replacing the newer contract | +| Existing lock | the write stops without mutation | +| Interrupted write | an exact retry completes the current write without changing history | +| Write receipt | id, revision, and digest match the published draft body | +| Evidence cited | the contract names paths and behavior without copying source syntax | diff --git a/plugins/aidd-ui/skills/02-design/actions/07-verify.md b/plugins/aidd-ui/skills/02-design/actions/07-verify.md new file mode 100644 index 000000000..9c7c38dd1 --- /dev/null +++ b/plugins/aidd-ui/skills/02-design/actions/07-verify.md @@ -0,0 +1,47 @@ +# 07 - Verify + +Prove the UI contract is internally consistent and publish its readiness atomically. + +## Input + +The draft `ui.md`, its expected id, revision, and SHA-256 digest from [06-write.md](06-write.md), plus referenced systems, deltas, requirements, and specialist fragments. + +## Output + +The verified `ui.md` marked `ready`, or a readiness result with the draft and defects routed back to composition or writing. + +## Process + +1. **Lock.** Acquire `.ui.lock` with an atomic directory create and re-read the current draft. + - Stop when the lock already exists. + - Remove only the lock directory created by this run. + - Stop when id, revision, or SHA-256 body digest differs from the write receipt. +2. **Resolve.** Resolve every pinned revision and required-delta path. + - For a no-base establishment, prove no current contract has its id and no active contract has an equal or unorderable scope overlap. + - Permit `systems: []` only when no shared system decision applies. +3. **Trace.** Confirm each hard requirement maps to a decision or explicit unresolved item and every applicable state has observable behavior. +4. **Compare.** Confirm specialist fragments and exact provider names with [specialists.md](../references/specialists.md), then prove feature decisions do not redefine shared system rules. +5. **Classify.** Return `ready`, `draft`, or a fixable defect. + - Route content defects to `compose`. + - Route serialization or version defects to `write`. +6. **Reject.** Fail any placeholder, unsupported compliance claim, implementation code, CSS, or framework recipe. +7. **Finalize.** Apply exactly one classified outcome. + - For `ready`, replace only the draft status through a sibling temporary file and atomic rename while the lock is held. + - For `ready`, read back the exact verified body and status before releasing the lock. + - For `draft` or a defect, leave the contract byte-identical and return the owning action. + +## Test + +| Case | Pass | +| --- | --- | +| Ready contract | all references resolve and no blocking item remains | +| Ready publication | no `ready` body is visible before all checks pass | +| Stale system revision | status is draft until explicitly reconciled | +| Establishment delta | ready only with `base_revision: null`, no current matching id, and no equal or unorderable active scope overlap | +| No shared system | a ready contract proves its decisions from feature evidence without inventing shared conventions | +| Specialist fragment | provenance and verdict match the provider output | +| Missing provider name | the applicable concern prevents ready publication | +| Final output | only the draft status changes while application source, system contracts, and memory remain unchanged | +| Verification failure | `ui.md` remains byte-identical and the owning action is named | +| Existing lock | verification stops without mutation | +| Concurrent revision | verification stops instead of publishing another run's draft | diff --git a/plugins/aidd-ui/skills/02-design/assets/ui-contract.md b/plugins/aidd-ui/skills/02-design/assets/ui-contract.md new file mode 100644 index 000000000..db757db74 --- /dev/null +++ b/plugins/aidd-ui/skills/02-design/assets/ui-contract.md @@ -0,0 +1,81 @@ +--- +id: {feature-id} +revision: {positive integer} +status: {draft | ready} +systems: + - id: {system-id} + revision: {positive integer} +required_deltas: + - {project-relative system-delta path} +supersedes: {prior contract id and revision or null} +--- + + + +# UI Contract: {feature} + +## Intent + +- User: {target user} +- Task: {primary task} +- Outcome: {observable outcome} + +## User Flow + +{ordered interaction flow} + +## Screens + +| Screen or region | Responsibility | Primary action | +| --- | --- | --- | +| {name} | {one responsibility} | {action} | + +## System Reuse + +| Surface | System revision | Source | Use | +| --- | --- | --- | --- | +| {pattern, composite, primitive, token, or layout} | {system-id@revision} | {project path} | {role} | + +## Interaction States + +| State | Trigger | Feedback | Recovery or next action | +| --- | --- | --- | --- | +| {state} | {trigger} | {observable feedback} | {recovery or next action} | + +## Assets + +| Role | Source or requirement | Constraints | Acceptance | +| --- | --- | --- | --- | +| {feature-local visual role} | {existing source path or required asset} | {content, crop, format, or behavior constraint} | {observable condition} | + +## Adaptation + +| Provider | Target and scope | Evidence | Required behavior | Acceptance | System impact | +| --- | --- | --- | --- | --- | --- | +| {provider} | {target and scope} | {evidence} | {behavior} | {condition} | {impact or none} | + +## Accessibility + +| Provider | Target and scope | Evidence | Required behavior | Acceptance | System impact | +| --- | --- | --- | --- | --- | --- | +| {provider} | {target and scope} | {evidence} | {behavior} | {condition} | {impact or none} | + +## UI Decisions + +| Decision | Evidence | Consequence | Rejected alternative | +| --- | --- | --- | --- | +| {feature choice} | {requirement or convention} | {constraint to preserve} | {optional alternative and reason} | + +## Interface Expression + +| Decision | Evidence | Acceptance | +| --- | --- | --- | +| {applicable copy, hierarchy, emphasis, density, alignment, feedback, or motion decision} | {requirement or system evidence} | {observable condition} | + +## Implementation Constraints + +- {experience constraint without implementation code} + +## Unresolved + +- {missing decision and why it blocks readiness} diff --git a/plugins/aidd-ui/skills/02-design/references/evidence.md b/plugins/aidd-ui/skills/02-design/references/evidence.md new file mode 100644 index 000000000..f617167ce --- /dev/null +++ b/plugins/aidd-ui/skills/02-design/references/evidence.md @@ -0,0 +1,22 @@ +# Feature UI evidence + +## Decision priority + +1. explicit user requirement. +2. approved system delta for authorized future behavior. +3. active UI system contract at the pinned revision. +4. current implementation for present behavior. +5. confirmed project memory as a compact map. +6. minimal feature-local decision. + +Code wins against memory. A system contract and code mismatch remains visible for system reconciliation. Feature design never chooses a silent winner. + +## Reuse order + +1. existing page pattern. +2. existing composite component. +3. existing primitive. +4. existing token. +5. existing layout convention. + +External design documents are supporting evidence. They do not replace an active AIDD UI system contract. diff --git a/plugins/aidd-ui/skills/02-design/references/specialists.md b/plugins/aidd-ui/skills/02-design/references/specialists.md new file mode 100644 index 000000000..8845d7e80 --- /dev/null +++ b/plugins/aidd-ui/skills/02-design/references/specialists.md @@ -0,0 +1,12 @@ +# Specialist integration + +| Field | Integration rule | +| --- | --- | +| provider | keep the exact discovered capability name | +| target and scope | keep unchanged | +| evidence | keep unchanged | +| required behavior | keep unchanged | +| acceptance | keep unchanged | +| system impact | convert only to a delta dependency, never a local rule | + +Place fragments in their owned contract section. Never recalculate a specialist decision. diff --git a/plugins/aidd-ui/skills/03-review/SKILL.md b/plugins/aidd-ui/skills/03-review/SKILL.md new file mode 100644 index 000000000..65dd75d8a --- /dev/null +++ b/plugins/aidd-ui/skills/03-review/SKILL.md @@ -0,0 +1,35 @@ +--- +name: 03-review +description: Produces an evidence pinned AIDD experience review report. Use when the user wants to diagnose and prioritize interface or flow defects before acceptance or rework. Not for implementation correctness or normative contract changes. +argument-hint: interface | flow +--- + +# UI Review + +```mermaid +flowchart LR + interface([interface]) --> inspect + flow([flow]) --> inspect + inspect -->|insufficient evidence| incomplete([incomplete review]) + inspect --> specialize --> assess --> write + write -->|findings| findings([prioritized review]) + write -->|no defect| clean([review with no findings]) +``` + +## Actions + +Read only the next action file required by the flow above. + +| Action | Does | +| --- | --- | +| inspect | pin review targets and evidence | +| specialize | obtain applicable specialist verdicts | +| assess | diagnose feature experience defects | +| write | record the nonnormative review | + +## Transversal rules + +- Own cross-concern task diagnosis and priority. +- Specialists own accessibility and adaptation verdicts. +- Treat findings as nonnormative. +- State assessed and unassessed coverage explicitly. diff --git a/plugins/aidd-ui/skills/03-review/actions/01-inspect.md b/plugins/aidd-ui/skills/03-review/actions/01-inspect.md new file mode 100644 index 000000000..f7905f60e --- /dev/null +++ b/plugins/aidd-ui/skills/03-review/actions/01-inspect.md @@ -0,0 +1,29 @@ +# 01 - Inspect + +Pin the interface and evidence being reviewed. + +## Input + +An existing screen, flow, rendered interface, screenshot, or implementation location. + +## Output + +An evidence inventory naming the target commit, relevant worktree fingerprint, UI contract revision, system revisions, requirements, observations, paths, and gaps. + +## Process + +1. **Locate.** Resolve the relevant workspace, interface entry points, task, and requirement source. +2. **Pin.** Record the current commit, exact artifact revisions, and [fingerprint.md](../references/fingerprint.md) digest. +3. **Observe.** Prefer rendered behavior over implementation evidence. + - Use implementation evidence only for unreachable states. +4. **Compare.** Report contract, implementation, and memory contradictions without resolving them. + - When neither interface nor requirement evidence can be observed, report the missing evidence and stop. + +## Test + +| Case | Pass | +| --- | --- | +| Evidence inventory | each item names a path, revision, commit, or runtime observation | +| Dirty worktree | the report pins a reproducible fingerprint of relevant changes | +| Drift | all conflicting sources remain visible | +| No UI evidence | no experience claim is fabricated | diff --git a/plugins/aidd-ui/skills/03-review/actions/02-specialize.md b/plugins/aidd-ui/skills/03-review/actions/02-specialize.md new file mode 100644 index 000000000..a4f1352ab --- /dev/null +++ b/plugins/aidd-ui/skills/03-review/actions/02-specialize.md @@ -0,0 +1,26 @@ +# 02 - Specialize + +Obtain applicable accessibility and adaptation verdicts. + +## Input + +The pinned evidence inventory. + +## Output + +Typed specialist finding fragments with provider provenance, plus unassessed applicable concerns. + +## Process + +1. **Select.** Identify accessibility and space, input, or platform concerns that apply to observed behavior. +2. **Discover.** Resolve each provider at runtime by capability description. +3. **Resolve.** Invoke each provider with the pinned target, evidence, and requested `assess` operation. + - When a provider cannot run, mark its applicable concern unassessed. + +## Test + +| Case | Pass | +| --- | --- | +| Provider available | its fragment and provenance remain unchanged | +| Provider unavailable | coverage says unassessed and no verdict is invented | +| Specialist finding | review may prioritize it but does not rewrite it | diff --git a/plugins/aidd-ui/skills/03-review/actions/03-assess.md b/plugins/aidd-ui/skills/03-review/actions/03-assess.md new file mode 100644 index 000000000..b45cfde9b --- /dev/null +++ b/plugins/aidd-ui/skills/03-review/actions/03-assess.md @@ -0,0 +1,32 @@ +# 03 - Assess + +Diagnose feature experience defects and prioritize all owned findings. + +## Input + +The evidence inventory and specialist fragments. + +## Output + +A coverage result and findings ordered `blocker`, `important`, then `minor`. + +## Process + +1. **Evaluate.** Compare observable task behavior with requirements, the UI contract, and pinned system decisions. + - Check whether task priority, information order, control affordance, feedback, and required states remain true. + - Assess applicable interface copy, hierarchy, visual emphasis, density, alignment, and motion only against explicit evidence. +2. **Exclude.** Accept accessibility and adaptation findings only from their specialists. +3. **Prioritize.** Assign overall priority using [findings.md](../references/findings.md) without altering specialist verdicts. +4. **Bound.** State required behavior and owner without adding implementation steps. + - Preserve specialist fields unchanged. +5. **Report.** Keep evidence gaps separate from findings. + +## Test + +| Case | Pass | +| --- | --- | +| Feature finding | it includes evidence, impact, outcome, owner, and priority | +| Specialist finding | its content and provenance are unchanged | +| Aesthetic preference | it is absent without requirement or system evidence | +| Expression defect | the violated copy, hierarchy, feedback, or motion decision is cited | +| Technical issue | it appears only through an observable experience consequence | diff --git a/plugins/aidd-ui/skills/03-review/actions/04-write.md b/plugins/aidd-ui/skills/03-review/actions/04-write.md new file mode 100644 index 000000000..b02020e69 --- /dev/null +++ b/plugins/aidd-ui/skills/03-review/actions/04-write.md @@ -0,0 +1,28 @@ +# 04 - Write + +Record the review without changing normative UI artifacts. + +## Input + +The pinned evidence, coverage result, and prioritized findings. + +## Output + +`ui-review.md` beside the supplied task artifact or in `aidd_docs/tasks//_/`, filled from [review-report.md](../assets/review-report.md). + +## Process + +1. **Pin.** Record the target, commit, relevant-worktree fingerprint, UI contract revision, and UI system revisions. +2. **Integrate.** Add only overall priority and owner to specialist findings. +3. **Separate.** List unassessed concerns and unavailable evidence outside findings. +4. **Write.** Remove placeholders and empty optional sections from the nonnormative report. +5. **Verify.** Read back the report and confirm no source, contract, system, or memory file changed. + +## Test + +| Case | Pass | +| --- | --- | +| Report written | its evidence target is reproducible from pinned identifiers | +| Specialist finding | its verdict matches provider output | +| No findings | coverage and evidence gaps remain explicit | +| Read-only review | only `ui-review.md` is created or updated | diff --git a/plugins/aidd-ui/skills/03-review/assets/review-report.md b/plugins/aidd-ui/skills/03-review/assets/review-report.md new file mode 100644 index 000000000..b654942b5 --- /dev/null +++ b/plugins/aidd-ui/skills/03-review/assets/review-report.md @@ -0,0 +1,40 @@ +--- +target: {project-relative interface target} +commit: {commit id} +worktree_fingerprint: {clean or SHA-256 digest from the skill reference} +ui_contract: {project-relative ui.md path or null} +ui_revision: {positive integer or null} +systems: + - id: {system-id} + revision: {positive integer} +reviewed_at: {ISO-8601 timestamp} +normative: false +--- + + + +# UI Review: {target} + +## Coverage + +- Assessed: {domains and evidence} +- Unassessed: {applicable domains and missing evidence or provider} + +## Findings + +### {priority}: {finding} + +- Domain: {feature experience, accessibility, or adaptation} +- Provider: {review capability or exact specialist provider} +- Target: {interface target} +- Scope: {affected state or context} +- Evidence: {observable evidence} +- Impact: {user consequence} +- Required behavior: {behavior that must become true, preserved from specialist when applicable} +- Acceptance: {observable pass condition supplied by a specialist, when applicable} +- System impact: {shared impact supplied by a specialist, when applicable} +- Owner: {capability that owns the correction decision} + +## Open Evidence + +- {missing observation and why it matters} diff --git a/plugins/aidd-ui/skills/03-review/references/findings.md b/plugins/aidd-ui/skills/03-review/references/findings.md new file mode 100644 index 000000000..23774ac53 --- /dev/null +++ b/plugins/aidd-ui/skills/03-review/references/findings.md @@ -0,0 +1,11 @@ +# Review findings + +## Priority + +| Priority | Threshold | +| --- | --- | +| `blocker` | prevents task completion, safe recovery, or essential access | +| `important` | materially increases error, effort, ambiguity, or exclusion | +| `minor` | bounded inconsistency or refinement defect | + +Each finding contains: `domain`, `finding`, `evidence`, `impact`, `required behavior`, `owner`, and `provenance`. Order by user consequence. Keep independent defects separate. diff --git a/plugins/aidd-ui/skills/03-review/references/fingerprint.md b/plugins/aidd-ui/skills/03-review/references/fingerprint.md new file mode 100644 index 000000000..5c64fd678 --- /dev/null +++ b/plugins/aidd-ui/skills/03-review/references/fingerprint.md @@ -0,0 +1,11 @@ +# Relevant worktree fingerprint + +Return `clean` when the target paths have no tracked or untracked changes. + +Otherwise hash these bytes with SHA-256: + +1. `git diff --binary HEAD -- `. +2. each untracked target path in bytewise path order. +3. a null byte, the project-relative path, a null byte, and the file bytes for each path. + +Record the resulting lowercase hexadecimal digest. diff --git a/plugins/aidd-ui/skills/04-accessibility/SKILL.md b/plugins/aidd-ui/skills/04-accessibility/SKILL.md new file mode 100644 index 000000000..dda894835 --- /dev/null +++ b/plugins/aidd-ui/skills/04-accessibility/SKILL.md @@ -0,0 +1,36 @@ +--- +name: 04-accessibility +description: Returns provider fragments for AIDD UI contracts, system deltas, or reviews. Use when the user wants to define, assess, or confirm accessibility behavior with evidence. Not for overall review priority, artifact composition, or source implementation. +argument-hint: define | assess | confirm +--- + +# Accessibility + +```mermaid +flowchart LR + define([define]) --> inspect + assess([assess]) --> inspect + confirm([confirm]) --> inspect + inspect -->|required evidence missing| unverified([unverified]) + inspect -->|define| specify --> requirements([requirement fragments]) + inspect -->|assess or confirm| evaluate + evaluate -->|assess| findings([finding fragments]) + evaluate -->|confirm| rules([confirmed-rule fragments]) + evaluate -->|none supported| none([no supported fragment]) +``` + +## Actions + +Read only the next action file required by the flow above. + +| Action | Does | +| --- | --- | +| inspect | collect applicable accessibility evidence | +| specify | return requirement fragments | +| evaluate | return findings or confirmed rules | + +## Transversal rules + +- Own accessibility requirements and verdicts. +- Do not own overall review priority or artifact composition. +- Never modify application source, UI artifacts, or project memory. diff --git a/plugins/aidd-ui/skills/04-accessibility/actions/01-inspect.md b/plugins/aidd-ui/skills/04-accessibility/actions/01-inspect.md new file mode 100644 index 000000000..2143447d9 --- /dev/null +++ b/plugins/aidd-ui/skills/04-accessibility/actions/01-inspect.md @@ -0,0 +1,32 @@ +# 01 - Inspect + +Collect accessibility evidence for the target interface. + +## Input + +An interface proposal or existing interface, its UI system revision when one exists, and the relevant project area. + +## Output + +The confirmed accessibility bar, interaction model, semantic and state evidence, runtime observations, and evidence gaps. + +## Process + +1. **Read.** Inspect requirements, shared components, implementation, project-memory pointers, and the pinned UI system when one exists. +2. **Select.** Keep only semantics, keyboard, focus, naming, contrast, errors, labels, target size, announcements, or reduced motion that apply. +3. **Observe.** Use runtime evidence when assessing existing behavior that cannot be proven statically. +4. **Bound.** Classify evidence by the requested mode. + - `define`: use requirements and repository evidence when no system exists. + - `assess` or `confirm`: mark unavailable runtime evidence unverified. + - Any mode: report contract or memory drift without resolving it. + +## Test + +| Case | Pass | +| --- | --- | +| Existing accessibility bar | its exact system revision and sources are named | +| Runtime unavailable in assess mode | runtime-only behavior is unverified | +| Prospective behavior in define mode | an observable acceptance condition can resolve it without current runtime proof | +| No active system | requirements and repository evidence remain usable | +| Concern irrelevant | it is omitted rather than emitted as boilerplate | +| Drift | conflicting evidence remains explicit and no artifact changes | diff --git a/plugins/aidd-ui/skills/04-accessibility/actions/02-specify.md b/plugins/aidd-ui/skills/04-accessibility/actions/02-specify.md new file mode 100644 index 000000000..c024fdccc --- /dev/null +++ b/plugins/aidd-ui/skills/04-accessibility/actions/02-specify.md @@ -0,0 +1,27 @@ +# 02 - Specify + +Define observable accessibility behavior for a proposed interface. + +## Input + +The proposal and evidence from [01-inspect.md](01-inspect.md). + +## Output + +Requirement fragments conforming to [fragments.md](../references/fragments.md). + +## Process + +1. **Align.** Reuse the pinned accessibility bar and existing interaction patterns. +2. **Specify.** State the user interaction, required behavior, and observable acceptance condition. +3. **Classify.** Set system impact only for a shared convention change. +4. **Defer.** List missing evidence or a missing shared system decision outside the fragment. + +## Test + +| Case | Pass | +| --- | --- | +| Fragment produced | every required field is present and evidence is cited | +| Existing convention fits | no system extension is claimed | +| Shared behavior changes | system impact names the exact gap, not its solution | +| Unsupported compliance claim | it is absent | diff --git a/plugins/aidd-ui/skills/04-accessibility/actions/03-evaluate.md b/plugins/aidd-ui/skills/04-accessibility/actions/03-evaluate.md new file mode 100644 index 000000000..69d9adb1f --- /dev/null +++ b/plugins/aidd-ui/skills/04-accessibility/actions/03-evaluate.md @@ -0,0 +1,32 @@ +# 03 - Evaluate + +Return accessibility findings or confirmed shared rules from observable evidence. + +## Input + +The requested `assess` or `confirm` mode and evidence from [01-inspect.md](01-inspect.md). + +## Output + +Fragments conforming to [fragments.md](../references/fragments.md), plus unverified concerns. + +## Process + +1. **Compare.** Evaluate observed behavior against requirements, pinned conventions, and relevant platform semantics. +2. **Classify.** Return only the fragment type requested by the mode. + - `assess`: emit each defect with its impact and required behavior. + - `confirm`: emit a rule only when a canonical shared source or repeated use proves its behavior and scope. +3. **Exclude.** Keep defects out of confirmed rules and missing evidence outside all fragments. +4. **Return.** Return the selected outcome. + - When no finding or confirmed rule is supported, state that outcome explicitly. + +## Test + +| Case | Pass | +| --- | --- | +| Finding produced | every required field and observable evidence is present | +| Confirmed shared behavior | a sourced rule and its shared scope are returned | +| Canonical shared component | its owned behavior may be confirmed before repeated use | +| Unsupported claim | it is unverified, not a finding | +| Keyboard or focus defect | the exact control and behavior are named | +| Wrong mode output | a finding never appears as a confirmed rule | diff --git a/plugins/aidd-ui/skills/04-accessibility/references/fragments.md b/plugins/aidd-ui/skills/04-accessibility/references/fragments.md new file mode 100644 index 000000000..bb492c0ae --- /dev/null +++ b/plugins/aidd-ui/skills/04-accessibility/references/fragments.md @@ -0,0 +1,9 @@ +# Accessibility fragments + +| Output | Required fields | +| --- | --- | +| requirement | provider, target, scope, evidence, required behavior, acceptance, system impact | +| finding | provider, target, scope, evidence, finding, impact, required behavior, acceptance, system impact | +| confirmed rule | provider, target, scope, evidence, required behavior, acceptance, system impact | + +List missing evidence separately. Never emit an unresolved item as a verdict. diff --git a/plugins/aidd-ui/skills/05-adapt/SKILL.md b/plugins/aidd-ui/skills/05-adapt/SKILL.md new file mode 100644 index 000000000..2f306c907 --- /dev/null +++ b/plugins/aidd-ui/skills/05-adapt/SKILL.md @@ -0,0 +1,38 @@ +--- +name: 05-adapt +description: Returns context transformation fragments for AIDD UI artifacts. Use when the user wants to define, assess, or confirm behavior across space, input, or platform contexts. Not for task hierarchy, accessibility, or source implementation. +argument-hint: define | assess | confirm +--- + +# UI Adaptation + +```mermaid +flowchart LR + define([define]) --> inspect + assess([assess]) --> inspect + confirm([confirm]) --> inspect + inspect -->|required evidence missing| unverified([unverified]) + inspect -->|define| specify --> requirements([requirement fragments]) + inspect -->|assess or confirm| evaluate + evaluate -->|assess| findings([finding fragments]) + evaluate -->|confirm| rules([confirmed-rule fragments]) + evaluate -->|none supported| none([no supported fragment]) +``` + +## Actions + +Read only the next action file required by the flow above. + +| Action | Does | +| --- | --- | +| inspect | collect adaptation evidence | +| specify | return requirement fragments | +| evaluate | return findings or confirmed rules | + +## Transversal rules + +- Own transformations across context. +- Feature design owns invariant task hierarchy. +- Exclude keyboard operability, focus, minimum target size, and accessibility zoom. +- Accessibility owns excluded concerns. +- Never modify application source, UI artifacts, or project memory. diff --git a/plugins/aidd-ui/skills/05-adapt/actions/01-inspect.md b/plugins/aidd-ui/skills/05-adapt/actions/01-inspect.md new file mode 100644 index 000000000..f7f578942 --- /dev/null +++ b/plugins/aidd-ui/skills/05-adapt/actions/01-inspect.md @@ -0,0 +1,31 @@ +# 01 - Inspect + +Collect evidence for interface behavior across space, input, and platform contexts. + +## Input + +An interface proposal or existing interface, its UI system revision when one exists, and the relevant workspace. + +## Output + +Confirmed breakpoints, layout primitives, navigation changes, density, overlays, overflow, input behavior, content pressures, runtime observations, and evidence gaps. + +## Process + +1. **Scope.** Select the affected frontend workspace and interface regions. +2. **Read.** Inspect configuration, layout primitives, shared patterns, implementation, project-memory pointers, and the pinned UI system when one exists. +3. **Observe.** Collect space, orientation, pointer, and platform evidence required by the requested mode. + - `define`: use requirements and repository evidence when no system exists. + - `assess` or `confirm`: mark unobserved contexts unverified. +4. **Pressure.** Keep only evidenced long-content, localization, and density constraints. +5. **Bound.** Report drift without resolving it. + +## Test + +| Case | Pass | +| --- | --- | +| Breakpoint named | its system revision and repository source are cited | +| Runtime observation | context and resulting behavior are named | +| Monorepo | evidence comes from the affected frontend workspace | +| No active system | requirements and repository evidence remain usable | +| Untested context | no behavior is inferred from absence of evidence | diff --git a/plugins/aidd-ui/skills/05-adapt/actions/02-specify.md b/plugins/aidd-ui/skills/05-adapt/actions/02-specify.md new file mode 100644 index 000000000..0a06c96ff --- /dev/null +++ b/plugins/aidd-ui/skills/05-adapt/actions/02-specify.md @@ -0,0 +1,27 @@ +# 02 - Specify + +Define required interface transformations across contexts. + +## Input + +The proposal, invariant task hierarchy, and evidence from [01-inspect.md](01-inspect.md). + +## Output + +Requirement fragments conforming to [fragments.md](../references/fragments.md). + +## Process + +1. **Preserve.** Keep the feature's primary task and required information available. +2. **Transform.** Define applicable stacking, collapse, wrapping, persistence, density, overflow, overlay, and input changes. +3. **Reuse.** Apply pinned breakpoints and layout primitives before reporting system impact. +4. **Describe.** Use available space and input capability, not arbitrary device models. + +## Test + +| Case | Pass | +| --- | --- | +| Fragment produced | every required field and observable acceptance condition is present | +| Existing breakpoint fits | no system impact is claimed | +| New breakpoint needed | an evidenced failure at existing breakpoints is named | +| Overflow adapts | content access and interaction remain explicit | diff --git a/plugins/aidd-ui/skills/05-adapt/actions/03-evaluate.md b/plugins/aidd-ui/skills/05-adapt/actions/03-evaluate.md new file mode 100644 index 000000000..40e149507 --- /dev/null +++ b/plugins/aidd-ui/skills/05-adapt/actions/03-evaluate.md @@ -0,0 +1,32 @@ +# 03 - Evaluate + +Return adaptation findings or confirmed shared rules from observed behavior. + +## Input + +The requested `assess` or `confirm` mode and evidence from [01-inspect.md](01-inspect.md). + +## Output + +Fragments conforming to [fragments.md](../references/fragments.md), plus unverified contexts. + +## Process + +1. **Compare.** Evaluate observed transformations against requirements, task priority, and pinned conventions. +2. **Classify.** Return only the fragment type requested by the mode. + - `assess`: emit each defect with its impact and required behavior. + - `confirm`: emit a rule only when a canonical shared source or repeated use proves its trigger, transformation, and scope. +3. **Exclude.** Keep defects out of confirmed rules and untested contexts outside all fragments. +4. **Return.** Return the selected outcome. + - When no finding or confirmed rule is supported, state that outcome explicitly. + +## Test + +| Case | Pass | +| --- | --- | +| Finding produced | every required field and observable evidence is present | +| Confirmed transformation | its trigger, behavior, scope, and source are returned | +| Canonical shared layout | its owned transformation may be confirmed before repeated use | +| Existing primitive solves it | the acceptance condition references that primitive | +| Context untested | no defect is claimed | +| Wrong mode output | a finding never appears as a confirmed rule | diff --git a/plugins/aidd-ui/skills/05-adapt/references/fragments.md b/plugins/aidd-ui/skills/05-adapt/references/fragments.md new file mode 100644 index 000000000..e3a56a043 --- /dev/null +++ b/plugins/aidd-ui/skills/05-adapt/references/fragments.md @@ -0,0 +1,9 @@ +# Adaptation fragments + +| Output | Required fields | +| --- | --- | +| requirement | provider, target, scope, evidence, required behavior, acceptance, system impact | +| finding | provider, target, scope, evidence, finding, impact, required behavior, acceptance, system impact | +| confirmed rule | provider, target, scope, evidence, required behavior, acceptance, system impact | + +List untested contexts separately. Never emit an unobserved context as a verdict. diff --git a/scripts/skill-eval.mjs b/scripts/skill-eval.mjs index fc04ea823..d864afb5f 100644 --- a/scripts/skill-eval.mjs +++ b/scripts/skill-eval.mjs @@ -19,10 +19,10 @@ // Local / opt-in only: needs an authenticated `claude` CLI and spends tokens. // Not a CI gate. -import { mkdtempSync, mkdirSync, writeFileSync, cpSync, rmSync, readFileSync, existsSync } from "node:fs"; +import { mkdtempSync, mkdirSync, writeFileSync, cpSync, rmSync, readFileSync, existsSync, readdirSync } from "node:fs"; import { tmpdir } from "node:os"; import { join, dirname, resolve } from "node:path"; -import { spawn } from "node:child_process"; +import { execFileSync, spawn } from "node:child_process"; import { fileURLToPath } from "node:url"; const HERE = dirname(fileURLToPath(import.meta.url)); @@ -62,7 +62,11 @@ function runClaude(prompt, cwd) { child.stdout.on("data", (d) => (out += d)); child.stderr.on("data", (d) => (out += d)); child.on("error", ko); - child.on("close", () => ok(out)); + child.on("close", (code, signal) => { + if (code === 0 && !signal) return ok(out); + const cause = signal ? `signal ${signal}` : `exit ${code}`; + ko(new Error(`claude failed with ${cause}\n${out.slice(-2000)}`)); + }); child.stdin.end(); }); } @@ -71,6 +75,23 @@ function has(haystack, needle) { return haystack.toLowerCase().includes(String(needle).toLowerCase()); } +function snapshotFiles(root) { + const files = {}; + const walk = (rel = "") => { + for (const entry of readdirSync(join(root, rel), { withFileTypes: true })) { + const next = join(rel, entry.name); + if (!rel && [".claude", ".git"].includes(entry.name)) continue; + if (entry.isDirectory()) { + files[`${next}/`] = ""; + walk(next); + } + else if (entry.isFile()) files[next] = readFileSync(join(root, next)).toString("base64"); + } + }; + walk(); + return files; +} + // One assertion = { ok: boolean, label: string } async function evaluate(expect, ctx) { const checks = []; @@ -110,6 +131,20 @@ async function evaluate(expect, ctx) { checks.push({ ok: new RegExp(re, "i").test(ctx.stdout), label: `stdout matches /${re}/` }); } + const after = snapshotFiles(ctx.tmp); + const allowed = new Set([ + ...(expect.filesExist || []), + ...Object.keys(expect.fileContains || {}), + ...Object.keys(expect.fileNotContains || {}), + ...(expect.allowMutations || []), + ]); + for (const name of new Set([...Object.keys(ctx.snapshot), ...Object.keys(after)])) { + const allowedDirectory = name.endsWith("/") && [...allowed].some((file) => file.startsWith(name)); + if (ctx.snapshot[name] !== after[name] && !allowed.has(name) && !allowedDirectory) { + checks.push({ ok: false, label: `unexpected mutation: ${name}` }); + } + } + if (expect.judge) { if (!JUDGE) { checks.push({ ok: true, skipped: true, label: `judge (skipped, pass --judge): ${expect.judge}` }); @@ -128,23 +163,50 @@ async function evaluate(expect, ctx) { function setupCase(c) { const tmp = mkdtempSync(join(tmpdir(), "skilleval-")); - const skillDst = join(tmp, ".claude", "skills", c.evalName); - mkdirSync(skillDst, { recursive: true }); - cpSync(join(skillsDir(c), c.skill), skillDst, { recursive: true }); - // A skill may run a script its plugin bundles. Stage it next to the skill so - // the sandbox matches an installed plugin rather than a skill copied alone. - const hooks = join(ROOT, "plugins", c.plugin || "aidd-refine", "hooks"); - if (existsSync(hooks)) cpSync(hooks, join(skillDst, "hooks"), { recursive: true }); - // Rewrite the frontmatter name so it matches the unique eval folder. - const skillMd = join(skillDst, "SKILL.md"); - const rewritten = readFileSync(skillMd, "utf8").replace(/^name:.*$/m, `name: ${c.evalName}`); - writeFileSync(skillMd, rewritten); + const setup = { ...(c.setup?.files || {}) }; + const stageSkill = (spec) => { + const plugin = spec.plugin || c.plugin || "aidd-refine"; + const skillDst = join(tmp, ".claude", "skills", spec.evalName); + mkdirSync(skillDst, { recursive: true }); + cpSync(join(ROOT, "plugins", plugin, "skills", spec.skill), skillDst, { recursive: true }); + // A skill may run a script its plugin bundles. Stage it next to the skill so + // the sandbox matches an installed plugin rather than a skill copied alone. + const hooks = join(ROOT, "plugins", plugin, "hooks"); + if (existsSync(hooks)) cpSync(hooks, join(skillDst, "hooks"), { recursive: true }); + // Rewrite frontmatter so each staged capability has a unique project name. + const skillMd = join(skillDst, "SKILL.md"); + const rewritten = readFileSync(skillMd, "utf8").replace(/^name:.*$/m, `name: ${spec.evalName}`); + writeFileSync(skillMd, rewritten); + }; + stageSkill(c); + for (const provider of c.providers || []) stageSkill(provider); for (const [rel, content] of Object.entries(c.setup?.files || {})) { const dst = join(tmp, rel); mkdirSync(dirname(dst), { recursive: true }); writeFileSync(dst, content); } - return tmp; + if (c.setup?.git) { + execFileSync("git", ["init", "-q", "-b", "main"], { cwd: tmp }); + execFileSync("git", ["config", "user.name", "Skill Eval"], { cwd: tmp }); + execFileSync("git", ["config", "user.email", "skill-eval@example.invalid"], { cwd: tmp }); + execFileSync("git", ["add", "."], { cwd: tmp }); + execFileSync("git", ["commit", "-qm", "fixture"], { cwd: tmp }); + const commit = execFileSync("git", ["rev-parse", "HEAD"], { cwd: tmp, encoding: "utf8" }).trim(); + for (const rel of Object.keys(c.setup?.files || {})) { + const dst = join(tmp, rel); + const content = readFileSync(dst, "utf8"); + if (content.includes("{{COMMIT}}")) { + const resolved = content.replaceAll("{{COMMIT}}", commit); + writeFileSync(dst, resolved); + setup[rel] = resolved; + } + } + if (execFileSync("git", ["status", "--short"], { cwd: tmp, encoding: "utf8" }).trim()) { + execFileSync("git", ["add", "."], { cwd: tmp }); + execFileSync("git", ["commit", "-qm", "fixture metadata"], { cwd: tmp }); + } + } + return { tmp, setup, snapshot: snapshotFiles(tmp) }; } async function runCase(c) { @@ -154,10 +216,11 @@ async function runCase(c) { let checks; let stdout = ""; try { - tmp = setupCase(c); + const fixture = setupCase(c); + tmp = fixture.tmp; const prompt = c.prompt.replaceAll("{{SKILL}}", c.evalName); stdout = await runClaude(prompt, tmp); - checks = await evaluate(c.expect, { tmp, stdout, setup: c.setup?.files || {} }); + checks = await evaluate(c.expect, { tmp, stdout, setup: fixture.setup, snapshot: fixture.snapshot }); } catch (err) { checks = [{ ok: false, label: `run error: ${err.message}` }]; } diff --git a/scripts/skill-eval/cases.json b/scripts/skill-eval/cases.json index 90aacca46..5d775e93b 100644 --- a/scripts/skill-eval/cases.json +++ b/scripts/skill-eval/cases.json @@ -317,5 +317,1568 @@ ] } } + }, + { + "plugin": "aidd-dev", + "skill": "01-plan", + "evalName": "xeval-dev-plan-ui-contract", + "name": "plans frontend work from a ready versioned UI contract", + "setup": { + "files": { + "src/Checkout.jsx": "export function Checkout() { return
Current checkout
; }\n", + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 1\nstatus: active\nscope:\n - src\nsources:\n - src/Checkout.jsx\nsupersedes: null\n---\n\n# UI System: App\n", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/requirement.md": "# Checkout\n\nImplement the approved checkout interface contract.\n", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/ui.md": "---\nid: checkout\nrevision: 2\nstatus: ready\nsystems:\n - id: app\n revision: 1\nrequired_deltas: []\nsupersedes: checkout@1\n---\n\n# UI Contract: Checkout\n\n## Intent\n\n- Task: submit payment and recover from errors\n\n## Interaction States\n\n| State | Trigger | Feedback | Recovery or next action |\n| --- | --- | --- | --- |\n| pending | submit | Processing | wait |\n| error | payment fails | inline error | retry |\n" + } + }, + "prompt": "Use the {{SKILL}} skill to plan aidd_docs/tasks/2026_08/2026_08_23_checkout/requirement.md. This is frontend work and its current ready UI contract is beside the requirement. Run headlessly, consume that contract without redesigning it, and write the plan and phases in the same task folder.", + "expect": { + "filesExist": [ + "aidd_docs/tasks/2026_08/2026_08_23_checkout/plan.md", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/phase-1.md" + ], + "filesUnchanged": [ + "src/Checkout.jsx", + "aidd_docs/ui/systems/app.md", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/requirement.md", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/ui.md" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_23_checkout/phase-1.md": [ + "## UI Contract", + "ui.md@2", + "app@1" + ] + }, + "fileNotContains": { + "aidd_docs/tasks/2026_08/2026_08_23_checkout/phase-1.md": [ + "## Wireframe" + ] + }, + "judgeFiles": [ + "aidd_docs/tasks/2026_08/2026_08_23_checkout/plan.md", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/phase-1.md" + ], + "judge": "The implementation plan consumes checkout ui.md revision 2 and app system revision 1, preserves the experience decisions by reference, and does not invent a wireframe or modify normative UI artifacts." + } + }, + { + "plugin": "aidd-dev", + "skill": "02-implement", + "evalName": "xeval-dev-implement-ui-drift", + "name": "stops before implementation when a UI dependency drifts", + "setup": { + "files": { + "src/Checkout.jsx": "export function Checkout() { return
unchanged
; }\n", + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 2\nstatus: active\nscope:\n - src\nsources:\n - src/Checkout.jsx\nsupersedes: app@1\n---\n\n# UI System: App\n", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/ui.md": "---\nid: checkout\nrevision: 3\nstatus: ready\nsystems:\n - id: app\n revision: 2\nrequired_deltas:\n - aidd_docs/tasks/2026_08/2026_08_23_checkout/system-delta-app-errors.md\nsupersedes: checkout@2\n---\n\n# UI Contract: Checkout\n", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/system-delta-app-errors.md": "---\nid: errors\nsystem: app\nbase_revision: 1\nmode: extend\nstatus: superseded\napproval_source: user\nverification_commit: null\ntarget_scope:\n - src\nexpected_sources:\n - src/Checkout.jsx\nverified_sources: []\n---\n\n# UI System Delta: Errors\n", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/plan.md": "---\nobjective: Implement checkout\nstatus: pending\n---\n\n# Plan: Checkout\n\n## Phases\n\n| # | Phase | File |\n| --- | --- | --- |\n| 1 | checkout | [phase-1.md](./phase-1.md) |\n", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/phase-1.md": "---\nstatus: pending\n---\n\n# Instruction: Checkout\n\n## UI Contract\n\n- Contract: `aidd_docs/tasks/2026_08/2026_08_23_checkout/ui.md@3`\n- Systems: app@2\n- Implement deltas: aidd_docs/tasks/2026_08/2026_08_23_checkout/system-delta-app-errors.md\n- Consume deltas: none\n- Depends on phases: none\n" + } + }, + "prompt": "Use the {{SKILL}} skill on aidd_docs/tasks/2026_08/2026_08_23_checkout/plan.md. Revalidate the referenced UI graph before any implementation and stop deterministically on drift.", + "expect": { + "filesUnchanged": [ + "src/Checkout.jsx", + "aidd_docs/ui/systems/app.md", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/ui.md", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/system-delta-app-errors.md", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/plan.md", + "aidd_docs/tasks/2026_08/2026_08_23_checkout/phase-1.md" + ], + "stdoutContains": [ + "replan needed", + "superseded" + ], + "judge": "Implementation stops before branch, status, phase, or source mutation because a required UI system delta is superseded." + } + }, + { + "plugin": "aidd-ui", + "skill": "02-design", + "evalName": "xeval-ui-design", + "name": "designs from a lightweight UI and explicit visual direction", + "providers": [ + { + "plugin": "aidd-ui", + "skill": "04-accessibility", + "evalName": "xeval-ui-a11y-provider" + }, + { + "plugin": "aidd-ui", + "skill": "05-adapt", + "evalName": "xeval-ui-adapt-provider" + } + ], + "setup": { + "files": { + "package.json": "{ \"name\": \"orders\", \"dependencies\": { \"react\": \"^19.0.0\" } }\n", + "public/warehouse-mark.png": "existing-asset-fixture\n", + "src/App.jsx": "export function App() { return

Orders

; }\n", + "src/styles.css": ".page { max-width: 60rem; margin: 0 auto; padding: 1rem; }\nbutton { min-height: 44px; }\nbutton:focus-visible { outline: 2px solid currentColor; }\n@media (min-width: 48rem) { .page { padding: 2rem; } }\n", + "aidd_docs/tasks/2026_08/2026_08_23_order_search/requirements.md": "# Order search\n\nWarehouse operators use a keyboard, not a scanner, to repeatedly search by order ID. Search stays primary. Results show order ID, status, destination, and Review. Use exact result status copy `Ready to review`. Cover loading, empty, recoverable error, and result states. Reveal fresh results with a motion cue as feedback, but remove that cue under the reduced-motion preference. Long IDs remain fully accessible. Below the existing 48rem breakpoint, stack result metadata while keeping Review adjacent to its order. Every field has a persistent label and status feedback is announced. Reuse `public/warehouse-mark.png` in the header. The empty state requires a feature-local illustration that depicts an empty sorting tray, remains legible at constrained widths, and has an acceptance requirement, but no binary asset is supplied or requested from this capability. Use a brutalist visual direction.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in create mode with aidd_docs/tasks/2026_08/2026_08_23_order_search/requirements.md. Discover and use the installed accessibility and adaptation providers. Write aidd_docs/tasks/2026_08/2026_08_23_order_search/ui.md. You are running headless: do not ask questions or implement code.", + "expect": { + "filesExist": [ + "aidd_docs/tasks/2026_08/2026_08_23_order_search/ui.md" + ], + "filesUnchanged": [ + "package.json", + "public/warehouse-mark.png", + "src/App.jsx", + "src/styles.css", + "aidd_docs/tasks/2026_08/2026_08_23_order_search/requirements.md" + ], + "filesAbsent": [ + "aidd_docs/memory/design.md", + "public/order-empty.png" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_23_order_search/ui.md": [ + "status: ready", + "brutalist", + "loading", + "empty", + "error", + "Ready to review", + "public/warehouse-mark.png", + "empty sorting tray", + "fresh results", + "feedback", + "reduced-motion", + "Accessibility", + "Adaptation", + "xeval-ui-a11y-provider", + "xeval-ui-adapt-provider" + ] + }, + "fileNotContains": { + "aidd_docs/tasks/2026_08/2026_08_23_order_search/ui.md": [ + "{feature-id}", + "

Invoices

; }\n", + "src/styles.css": "main { max-width: 50rem; margin: auto; }\nbutton { padding: 0.5rem 1rem; }\n", + "aidd_docs/tasks/2026_08/2026_08_23_invoice/requirement.md": "# Invoice list\n\nThe invoice list and create form need one shared action style, field treatment, spacing rhythm, and visible focus behavior. No design system exists.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in establish mode for aidd_docs/tasks/2026_08/2026_08_23_invoice/requirement.md. Reuse coherent current CSS and write only the minimum draft system to aidd_docs/tasks/2026_08/2026_08_23_invoice/system-delta-invoices-foundation.md. Do not approve it or modify source.", + "expect": { + "filesExist": [ + "aidd_docs/tasks/2026_08/2026_08_23_invoice/system-delta-invoices-foundation.md" + ], + "filesUnchanged": [ + "src/App.jsx", + "src/styles.css" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_23_invoice/system-delta-invoices-foundation.md": [ + "mode: establish", + "base_revision: null", + "status: draft", + "target_scope", + "expected_sources", + "src/styles.css" + ] + }, + "fileNotContains": { + "aidd_docs/tasks/2026_08/2026_08_23_invoice/system-delta-invoices-foundation.md": [ + "status: approved", + "enterprise", + "complete token taxonomy" + ] + }, + "judgeFiles": [ + "aidd_docs/tasks/2026_08/2026_08_23_invoice/system-delta-invoices-foundation.md" + ], + "judge": "The draft establishes only conventions needed by the invoice work, reuses coherent current CSS, leaves specialist gaps unresolved, and does not invent a broad design system or implementation code." + } + }, + { + "plugin": "aidd-ui", + "skill": "02-design", + "evalName": "xeval-ui-provider-missing", + "name": "keeps a feature draft when a required specialist is unavailable", + "setup": { + "files": { + "src/ResetPassword.jsx": "export function ResetPassword() { return
; }\n", + "aidd_docs/tasks/2026_08/2026_08_23_reset/requirements.md": "# Reset password\n\nA user enters a new password, submits it, and sees validation errors or success. Keyboard and accessible error behavior are required.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in create mode from aidd_docs/tasks/2026_08/2026_08_23_reset/requirements.md. Write aidd_docs/tasks/2026_08/2026_08_23_reset/ui.md. No specialist provider is installed: do not invent its verdict and do not implement code.", + "expect": { + "filesExist": [ + "aidd_docs/tasks/2026_08/2026_08_23_reset/ui.md" + ], + "filesUnchanged": [ + "src/ResetPassword.jsx", + "aidd_docs/tasks/2026_08/2026_08_23_reset/requirements.md" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_23_reset/ui.md": [ + "status: draft" + ] + }, + "fileMatches": { + "aidd_docs/tasks/2026_08/2026_08_23_reset/ui.md": "status: draft[\\s\\S]*(unverified|unresolved)" + }, + "fileNotContains": { + "aidd_docs/tasks/2026_08/2026_08_23_reset/ui.md": [ + "status: ready", + "WCAG compliant" + ] + }, + "judgeFiles": [ + "aidd_docs/tasks/2026_08/2026_08_23_reset/ui.md" + ], + "judge": "The UI contract remains draft because accessibility is applicable but its provider is unavailable. It identifies the gap without generating a substitute accessibility verdict or implementation code." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-system", + "name": "discovers the target workspace system and confirms matching memory", + "setup": { + "files": { + "package.json": "{ \"private\": true, \"workspaces\": [\"apps/*\"] }\n", + "apps/admin/package.json": "{ \"name\": \"admin\", \"dependencies\": { \"react\": \"^19.0.0\" } }\n", + "apps/admin/src/ui/tokens.css": ":root { --space-2: 0.5rem; --color-action: #075985; }\n@media (min-width: 48rem) { :root { --content-columns: 12; } }\n", + "apps/admin/src/ui/Button.jsx": "export function Button({ children, disabled }) { return ; }\n", + "apps/admin/src/ui/Input.jsx": "export function Input(props) { return ; }\n", + "apps/admin/src/screens/Users.jsx": "import { Button } from '../ui/Button';\nimport { Input } from '../ui/Input';\nexport function Users() { return
; }\n", + "apps/marketing/src/theme.css": ":root { --MARKETING_ONLY-purple: rebeccapurple; }\n", + "aidd_docs/memory/design.md": "# Design\n\n- The admin workspace owns tokens in `apps/admin/src/ui/tokens.css`.\n- Admin actions reuse `apps/admin/src/ui/Button.jsx`.\n- Admin layouts change at 48rem.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in discover mode to map the interface system for the admin Users screen only. This is a monorepo. Confirm memory against implementation, keep other frontend systems separate, modify nothing, and do not wait for input.", + "expect": { + "filesUnchanged": [ + "apps/admin/src/ui/tokens.css", + "apps/admin/src/ui/Button.jsx", + "apps/admin/src/ui/Input.jsx", + "aidd_docs/memory/design.md" + ], + "stdoutContains": [ + "apps/admin/src/ui/tokens.css", + "apps/admin/src/ui/Button.jsx", + "aidd_docs/memory/design.md", + "48rem" + ], + "judge": "The system map is scoped to apps/admin, confirms the matching memory with repository paths, and does not treat the marketing workspace's MARKETING_ONLY token as part of the admin system." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-system", + "name": "reports stale design memory and uses current repository evidence", + "setup": { + "files": { + "package.json": "{ \"name\": \"dashboard\", \"dependencies\": { \"tailwindcss\": \"^4.0.0\" } }\n", + "tailwind.config.js": "export default { content: ['./src/**/*.{js,jsx}'], theme: { extend: {} } };\n", + "src/App.jsx": "export function App() { return
Dashboard
; }\n", + "aidd_docs/memory/design.md": "# Design\n\n- Styling uses styled-components from `src/theme.js`.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in discover mode. Map the current interface system, explicitly report any project-memory contradiction, treat repository evidence as current truth, and modify nothing.", + "expect": { + "filesUnchanged": [ + "tailwind.config.js", + "src/App.jsx", + "aidd_docs/memory/design.md" + ], + "stdoutContains": [ + "tailwind.config.js", + "styled-components", + "aidd_docs/memory/design.md" + ], + "judge": "The output says Tailwind is current reality, identifies the styled-components memory claim as stale or contradicted, and directs any memory correction to a separate project-memory refresh rather than changing memory." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-system", + "name": "extends the dominant button system and flags a stable convention", + "setup": { + "files": { + "src/ui/Button.jsx": "export function Button({ variant = 'primary', children }) { return ; }\n", + "src/legacy/LegacyButton.jsx": "export function LegacyButton({ children }) { return ; }\n", + "src/screens/Orders.jsx": "import { Button } from '../ui/Button';\nexport function Orders() { return <>; }\n", + "src/screens/Users.jsx": "import { Button } from '../ui/Button';\nexport function Users() { return ; }\n", + "src/screens/Archive.jsx": "import { LegacyButton } from '../legacy/LegacyButton';\nexport function Archive() { return Restore; }\n", + "aidd_docs/memory/design.md": "# Design\n\n- Active UI system: `aidd_docs/ui/systems/app.md`, revision 2.\n", + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 2\nstatus: active\nscope:\n - src\nsources:\n - src/ui/Button.jsx\nsupersedes: app@1\n---\n\n# UI System: App\n\n## Surfaces\n\n| Pattern, component, or token | Contract | States | Source |\n| --- | --- | --- | --- |\n| Button | Shared actions use Button variants | default, hover, focus, disabled | src/ui/Button.jsx |\n", + "aidd_docs/tasks/2026_08/2026_08_23_bulk_delete/requirement.md": "# Bulk delete\n\nOrders needs a destructive bulk-delete action with default, hover, focus, disabled, and pending states.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in extend mode from aidd_docs/tasks/2026_08/2026_08_23_bulk_delete/requirement.md. Resolve the active system, account for both button implementations, and write the draft to aidd_docs/tasks/2026_08/2026_08_23_bulk_delete/system-delta-app-button-destructive.md. Do not approve it, modify code, or change memory.", + "expect": { + "filesExist": [ + "aidd_docs/tasks/2026_08/2026_08_23_bulk_delete/system-delta-app-button-destructive.md" + ], + "filesUnchanged": [ + "src/ui/Button.jsx", + "src/legacy/LegacyButton.jsx", + "aidd_docs/memory/design.md", + "aidd_docs/ui/systems/app.md" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_23_bulk_delete/system-delta-app-button-destructive.md": [ + "system: app", + "base_revision: 2", + "mode: extend", + "status: draft", + "target_scope", + "expected_sources", + "src/ui/Button.jsx", + "src/legacy/LegacyButton.jsx", + "destructive", + "pending" + ] + }, + "judgeFiles": [ + "aidd_docs/tasks/2026_08/2026_08_23_bulk_delete/system-delta-app-button-destructive.md" + ], + "judge": "The draft recognizes both button systems, extends the active Button instead of creating a parallel control, records the exact base revision, remains unapproved, and contains no production code." + } + }, + { + "plugin": "aidd-ui", + "skill": "03-review", + "evalName": "xeval-ui-review", + "name": "reports prioritized experience findings from observable evidence", + "providers": [ + { + "plugin": "aidd-ui", + "skill": "04-accessibility", + "evalName": "xeval-review-a11y-provider" + }, + { + "plugin": "aidd-ui", + "skill": "05-adapt", + "evalName": "xeval-review-adapt-provider" + } + ], + "setup": { + "files": { + "aidd_docs/tasks/2026_08/2026_08_23_checkout/requirements.md": "# Checkout\n\nA shopper must see a recoverable payment error and know when submission is pending.\n", + "src/Checkout.jsx": "import { useState } from 'react';\nexport function Checkout() { const [pending, setPending] = useState(false); const [error, setError] = useState(''); return
setPending(true)}>{error ? null : null}
; }\n" + } + }, + "prompt": "Use the {{SKILL}} skill to review src/Checkout.jsx against aidd_docs/tasks/2026_08/2026_08_23_checkout/requirements.md. Discover the installed accessibility and adaptation providers. No browser is available. Write aidd_docs/tasks/2026_08/2026_08_23_checkout/ui-review.md without changing source or normative UI artifacts.", + "expect": { + "filesExist": [ + "aidd_docs/tasks/2026_08/2026_08_23_checkout/ui-review.md" + ], + "filesUnchanged": [ + "aidd_docs/tasks/2026_08/2026_08_23_checkout/requirements.md", + "src/Checkout.jsx" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_23_checkout/ui-review.md": [ + "normative: false", + "src/Checkout.jsx", + "error", + "pending", + "xeval-review-a11y-provider", + "xeval-review-adapt-provider" + ] + }, + "judgeFiles": [ + "aidd_docs/tasks/2026_08/2026_08_23_checkout/ui-review.md" + ], + "judge": "The non-normative review catches the hidden payment error and ambiguous pending feedback, preserves specialist provenance, prioritizes user impact, separates unverified browser behavior, and contains no implementation refactor advice." + } + }, + { + "plugin": "aidd-ui", + "skill": "05-adapt", + "evalName": "xeval-ui-adapt", + "name": "defines constrained behavior using existing breakpoints", + "setup": { + "files": { + "tailwind.config.js": "export default { theme: { screens: { sm: '40rem', md: '48rem', lg: '64rem' } } };\n", + "src/ui/TableShell.jsx": "export function TableShell({ children }) { return
{children}
; }\n", + "requirements.md": "# Orders\n\nThe order ID, status, and primary Review action must remain available. Notes and timestamps are secondary. Long order IDs must remain accessible.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in define mode for an Orders table using requirements.md. Return typed adaptation fragments for constrained space and overflow. Reuse existing breakpoints and TableShell, introduce no breakpoint unless evidence proves a gap, and modify nothing.", + "expect": { + "filesUnchanged": [ + "tailwind.config.js", + "src/ui/TableShell.jsx", + "requirements.md" + ], + "stdoutContains": [ + "tailwind.config.js", + "src/ui/TableShell.jsx", + "48rem", + "overflow", + "Review" + ], + "judge": "Each adaptation fragment has the required typed fields, preserves task priority, reuses an existing breakpoint and TableShell, covers overflow, and invents no device width or accessibility verdict." + } + }, + { + "plugin": "aidd-ui", + "skill": "04-accessibility", + "evalName": "xeval-ui-accessibility", + "name": "finds evidenced keyboard and naming defects without claiming runtime compliance", + "setup": { + "files": { + "src/Search.jsx": "export function Search({ openFilters }) { return
Filters
; }\n", + "src/styles.css": ".filter-trigger { color: #666; }\n", + "aidd_docs/memory/design.md": "# Design\n\n- Interactive controls require visible focus indication and accessible names.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in assess mode for Search. Return typed accessibility finding fragments for semantics, accessible naming, keyboard reachability, and focus evidence. A browser and computed contrast values are unavailable: keep runtime-only claims unverified, cite exact controls, and modify nothing.", + "expect": { + "filesUnchanged": [ + "src/Search.jsx", + "src/styles.css", + "aidd_docs/memory/design.md" + ], + "stdoutContains": [ + "accessibility", + "src/Search.jsx", + "Filters", + "keyboard", + "accessible name", + "unverified" + ], + "judge": "Typed accessibility fragments identify the clickable Filters div and placeholder-only field defects, include observable acceptance behavior and system impact, separate runtime evidence gaps, and assign no overall review priority." + } + }, + { + "plugin": "aidd-ui", + "skill": "02-design", + "evalName": "xeval-ui-revise", + "name": "revises expression without taking a second polish domain", + "providers": [ + { + "plugin": "aidd-ui", + "skill": "04-accessibility", + "evalName": "xeval-revise-a11y-provider" + }, + { + "plugin": "aidd-ui", + "skill": "05-adapt", + "evalName": "xeval-revise-adapt-provider" + } + ], + "setup": { + "files": { + "aidd_docs/tasks/2026_08/2026_08_23_profile/requirements.md": "# Profile summary\n\nStructure is approved: title, account facts, then Edit profile as the primary action. Adaptation and accessibility behavior are settled. Do not change region order or task flow.\n", + "aidd_docs/tasks/2026_08/2026_08_23_profile/ui.md": "---\nid: profile-summary\nrevision: 1\nstatus: ready\nsystems: []\nrequired_deltas: []\nsupersedes: null\n---\n\n# UI Contract: Profile summary\n\n## Intent\n\n- User: account holder\n- Task: inspect account facts and edit the profile\n- Outcome: facts remain readable and Edit profile starts editing\n\n## Screens\n\n| Screen or region | Responsibility | Primary action |\n| --- | --- | --- |\n| Profile | title, account facts, then Edit profile | Edit profile |\n\n## Adaptation\n\n- Preserve the region order at constrained widths.\n\n## Accessibility\n\n- Preserve semantic heading and description-list structure with visible button focus.\n", + "src/Profile.jsx": "export function Profile() { return

Profile

Email
a@example.com
; }\n", + "src/tokens.css": ":root { --space-2: 0.5rem; --space-4: 1rem; --font-heading: 1.5rem; --focus-ring: 2px solid #075985; }\n" + } + }, + "prompt": "Use the {{SKILL}} skill in revise mode for aidd_docs/tasks/2026_08/2026_08_23_profile/ui.md. Improve spacing, typography, alignment, and affordance with existing tokens while preserving intent, hierarchy, and flow. Discover the installed specialists, archive revision 1, and write revision 2. Do not implement code.", + "expect": { + "filesExist": [ + "aidd_docs/tasks/2026_08/2026_08_23_profile/.ui-history/profile-summary@1.md" + ], + "filesUnchanged": [ + "aidd_docs/tasks/2026_08/2026_08_23_profile/requirements.md", + "src/Profile.jsx", + "src/tokens.css" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_23_profile/ui.md": [ + "revision: 2", + "supersedes: profile-summary@1", + "space-2", + "space-4", + "Edit profile", + "xeval-revise-a11y-provider", + "xeval-revise-adapt-provider" + ], + "aidd_docs/tasks/2026_08/2026_08_23_profile/.ui-history/profile-summary@1.md": [ + "revision: 1", + "title, account facts, then Edit profile" + ] + }, + "judgeFiles": [ + "aidd_docs/tasks/2026_08/2026_08_23_profile/ui.md" + ], + "judge": "Revision 2 performs bounded polish inside design, preserves title-account facts-action order and task flow, uses existing tokens, preserves specialist authority, and archives the exact prior contract." + } + }, + { + "plugin": "aidd-ui", + "skill": "02-design", + "evalName": "xeval-ui-contract", + "name": "owns its implementation-ready contract without a handoff skill", + "providers": [ + { + "plugin": "aidd-ui", + "skill": "04-accessibility", + "evalName": "xeval-contract-a11y-provider" + }, + { + "plugin": "aidd-ui", + "skill": "05-adapt", + "evalName": "xeval-contract-adapt-provider" + } + ], + "setup": { + "files": { + "src/ui/Button.jsx": "import './button.css';\nexport function Button({ children, disabled }) { return ; }\n", + "src/ui/button.css": ".button { min-height: 44px; color: #fff; background: #075985; }\n.button:focus-visible { outline: 2px solid #000; outline-offset: 2px; }\n", + "src/ui/input.css": ".field input { min-height: 44px; }\n.field input:focus-visible { outline: 2px solid #000; outline-offset: 2px; }\n", + "tailwind.config.js": "export default { theme: { screens: { md: '48rem' } } };\n", + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 1\nstatus: active\nscope:\n - src\nsources:\n - src/ui/Button.jsx\n - src/ui/button.css\n - src/ui/input.css\n - tailwind.config.js\nsupersedes: null\n---\n\n# UI System: App\n\n## Surfaces\n\n| Pattern, component, or token | Contract | States | Source |\n| --- | --- | --- | --- |\n| Button | shared actions | default, focus, disabled | src/ui/Button.jsx |\n| Field | shared labeled inputs | default, focus, invalid | src/ui/input.css |\n\n## Adaptation\n\n| Provider | Target and scope | Evidence | Required transformation | Acceptance |\n| --- | --- | --- | --- | --- |\n| existing system | checkout form below md | tailwind.config.js | stack fields in source order | source order remains unchanged |\n\n## Accessibility\n\n| Provider | Target and scope | Evidence | Required behavior | Acceptance |\n| --- | --- | --- | --- | --- |\n| existing system | form controls | src/ui/button.css; src/ui/input.css | persistent label, visible focus, and 44px minimum target | label and focus remain visible; computed height is at least 44px |\n| existing system | status feedback | active convention | announce state changes once | screen reader receives one status update |\n", + "aidd_docs/memory/design.md": "# Design\n\n- Active UI system: `aidd_docs/ui/systems/app.md`, revision 1.\n", + "aidd_docs/tasks/2026_08/2026_08_22_checkout/decisions.md": "# Confirmed checkout decisions\n\nIntent: shoppers submit payment and receive an order confirmation.\nFlow: enter cardholder name, card number, expiry, and security code; submit; then confirmation.\nReuse `Button` from `src/ui/Button.jsx` for Pay.\nPending: submission disables Pay, changes its accessible name to Processing, and announces progress once.\nError: show one inline payment error associated with the invalid field, move focus to the error summary, then allow retry.\nAdaptation: below the existing `md` breakpoint from `tailwind.config.js`, stack fields in source order and keep Pay after the last field; at and above `md`, use two columns while preserving the same order.\nAccessibility: every field has a persistent label and described error; the error summary is announced once and receives focus; reuse the active system focus and target-size behavior.\nNo new primitive or system delta is required.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in create mode from ./aidd_docs/tasks/2026_08/2026_08_22_checkout/decisions.md. Discover the installed accessibility and adaptation providers. Write and verify ./aidd_docs/tasks/2026_08/2026_08_22_checkout/ui.md. Do not ask questions, invent decisions, write production code, or modify source and project memory.", + "expect": { + "filesExist": [ + "aidd_docs/tasks/2026_08/2026_08_22_checkout/ui.md" + ], + "filesUnchanged": [ + "src/ui/Button.jsx", + "src/ui/button.css", + "src/ui/input.css", + "tailwind.config.js", + "aidd_docs/ui/systems/app.md", + "aidd_docs/memory/design.md", + "aidd_docs/tasks/2026_08/2026_08_22_checkout/decisions.md" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_22_checkout/ui.md": [ + "# UI Contract", + "status: ready", + "src/ui/Button.jsx", + "Processing", + "error", + "md", + "xeval-contract-a11y-provider", + "xeval-contract-adapt-provider" + ] + }, + "fileNotContains": { + "aidd_docs/tasks/2026_08/2026_08_22_checkout/ui.md": [ + "Fill applicable sections", + "{feature}", + "{children}; }\n", + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 2\nstatus: active\nscope:\n - src\nsources:\n - src/ui/Button.jsx\nsupersedes: app@1\n---\n\n# UI System: App\n\n## Surfaces\n\n| Pattern, component, or token | Contract | States | Source |\n| --- | --- | --- | --- |\n| Button | primary and secondary shared actions | default, hover, focus, disabled | src/ui/Button.jsx |\n", + "aidd_docs/tasks/2026_08/2026_08_23_button/system-delta-app-button-destructive.md": "---\nid: button-destructive\nsystem: app\nbase_revision: 2\nmode: extend\nstatus: verified\napproval_source: user approval recorded in requirement.md\nverification_commit: {{COMMIT}}\ntarget_scope:\n - src\nexpected_sources:\n - src/ui/Button.jsx\nverified_sources:\n - src/ui/Button.jsx\n---\n\n# UI System Delta: Destructive Button\n\n## Need\n\nShared destructive actions need an explicit Button variant.\n\n## Change\n\n| Decision | Evidence | Consequence |\n| --- | --- | --- |\n| Add destructive Button variant | approved requirement and src/ui/Button.jsx at {{COMMIT}} | Button contract includes destructive intent |\n\n## Verification\n\n- src/ui/Button.jsx at {{COMMIT}} implements the approved variant.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in promote mode for aidd_docs/tasks/2026_08/2026_08_23_button/system-delta-app-button-destructive.md. Resolve its real verification commit and current implementation, promote it into the app contract, archive revision 2, and preserve code and memory. Do not reinterpret the approved decision.", + "expect": { + "filesExist": [ + "aidd_docs/ui/systems/.history/app@2.md" + ], + "filesUnchanged": [ + "src/ui/Button.jsx" + ], + "fileContains": { + "aidd_docs/ui/systems/app.md": [ + "revision: 3", + "supersedes: app@2", + "destructive" + ], + "aidd_docs/ui/systems/.history/app@2.md": [ + "revision: 2", + "primary and secondary shared actions" + ], + "aidd_docs/tasks/2026_08/2026_08_23_button/system-delta-app-button-destructive.md": [ + "status: promoted", + "base_revision: 2" + ] + }, + "judgeFiles": [ + "aidd_docs/ui/systems/app.md", + "aidd_docs/tasks/2026_08/2026_08_23_button/system-delta-app-button-destructive.md" + ], + "judge": "Promotion advances the active contract exactly once, preserves the prior revision immutably, marks the same verified delta promoted, and does not modify implementation or memory." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-system", + "name": "adopts a mature implemented system with specialist provenance", + "providers": [ + { + "plugin": "aidd-ui", + "skill": "04-accessibility", + "evalName": "xeval-adopt-a11y-provider" + }, + { + "plugin": "aidd-ui", + "skill": "05-adapt", + "evalName": "xeval-adopt-adapt-provider" + } + ], + "setup": { + "files": { + "apps/admin/src/ui/tokens.css": ":root { --space-2: 0.5rem; --action: #075985; }\n@media (min-width: 48rem) { .shell { grid-template-columns: 14rem 1fr; } }\n", + "apps/admin/src/ui/Button.jsx": "export function Button({ children, disabled }) { return ; }\n", + "apps/admin/src/ui/Input.jsx": "export function Input({ label, ...props }) { return ; }\n", + "apps/admin/src/Users.jsx": "import { Button } from './ui/Button';\nimport { Input } from './ui/Input';\nexport function Users() { return
; }\n" + } + }, + "prompt": "Use the {{SKILL}} skill in adopt mode for apps/admin. This prompt explicitly authorizes adoption as system id admin. Discover the installed accessibility and adaptation providers, record only confirmed implemented conventions, and write aidd_docs/ui/systems/admin.md at revision 1. Do not modify source or memory.", + "expect": { + "filesExist": [ + "aidd_docs/ui/systems/admin.md" + ], + "filesUnchanged": [ + "apps/admin/src/ui/tokens.css", + "apps/admin/src/ui/Button.jsx", + "apps/admin/src/ui/Input.jsx", + "apps/admin/src/Users.jsx" + ], + "fileContains": { + "aidd_docs/ui/systems/admin.md": [ + "id: admin", + "revision: 1", + "status: active", + "apps/admin", + "xeval-adopt-a11y-provider", + "xeval-adopt-adapt-provider" + ] + }, + "judgeFiles": [ + "aidd_docs/ui/systems/admin.md" + ], + "judge": "The adopted contract contains only implemented shared conventions, records exact sources and specialist provenance, excludes unsupported claims, and does not modify implementation or memory." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-adopt-nested", + "name": "adopts a strictly nested workspace system", + "providers": [ + { + "plugin": "aidd-ui", + "skill": "04-accessibility", + "evalName": "xeval-nested-a11y-provider" + }, + { + "plugin": "aidd-ui", + "skill": "05-adapt", + "evalName": "xeval-nested-adapt-provider" + } + ], + "setup": { + "files": { + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 2\nstatus: active\nscope:\n - apps\nsources:\n - apps/shared.css\nsupersedes: app@1\n---\n\n# UI System: App\n", + "apps/shared.css": ":root { --space-2: 0.5rem; }\n", + "apps/admin/ui.css": ":root { --admin-accent: #075985; }\n.admin-action:focus-visible { outline: 2px solid currentColor; }\n", + "apps/admin/Button.jsx": "export function Button({ children }) { return ; }\n" + } + }, + "prompt": "Use the {{SKILL}} skill in adopt mode for implemented system id admin scoped to apps/admin. The active app system owns parent scope apps, so admin is an unambiguous more-specific system. This prompt authorizes the exact evidenced revision 1 contract. Discover the installed specialists, write aidd_docs/ui/systems/admin.md, and modify no source or parent contract.", + "expect": { + "filesExist": [ + "aidd_docs/ui/systems/admin.md" + ], + "filesUnchanged": [ + "aidd_docs/ui/systems/app.md", + "apps/shared.css", + "apps/admin/ui.css", + "apps/admin/Button.jsx" + ], + "fileContains": { + "aidd_docs/ui/systems/admin.md": [ + "id: admin", + "revision: 1", + "status: active", + "apps/admin", + "apps/admin/ui.css" + ] + }, + "judge": "A strictly nested implemented system is adopted at revision 1 because most-specific scope resolution is unambiguous, while the active parent contract and all implementation sources remain unchanged." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-reconcile", + "name": "supersedes a delta whose base revision is stale", + "setup": { + "files": { + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 3\nstatus: active\nscope:\n - src\nsources:\n - src/ui/Button.jsx\nsupersedes: app@2\n---\n\n# UI System: App\n", + "aidd_docs/tasks/2026_08/2026_08_23_stale/system-delta-app-spacing.md": "---\nid: spacing\nsystem: app\nbase_revision: 2\nmode: extend\nstatus: approved\napproval_source: user\nverification_commit: null\ntarget_scope:\n - src\nexpected_sources:\n - src/ui/tokens.css\nverified_sources: []\n---\n\n# UI System Delta: Spacing\n" + } + }, + "prompt": "Use the {{SKILL}} skill in reconcile mode for aidd_docs/tasks/2026_08/2026_08_23_stale/system-delta-app-spacing.md against the current app contract. Classify the stale base deterministically and modify no other file.", + "expect": { + "filesUnchanged": [ + "aidd_docs/ui/systems/app.md" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_23_stale/system-delta-app-spacing.md": [ + "base_revision: 2", + "status: superseded" + ] + }, + "judge": "The approved delta is marked superseded because app revision 3 is active, is never rebased or promoted, and the active contract remains unchanged." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-retire", + "name": "approves retirement with consumers as migration dependencies", + "setup": { + "files": { + "apps/legacy/App.jsx": "export function App() { return
Legacy checkout
; }\n", + "aidd_docs/ui/systems/legacy.md": "---\nid: legacy\nrevision: 4\nstatus: active\nscope:\n - apps/legacy\nsources:\n - apps/legacy/App.jsx\nsupersedes: legacy@3\n---\n\n# UI System: Legacy\n", + "aidd_docs/tasks/2026_08/2026_08_23_retire/ui.md": "---\nid: legacy-checkout\nrevision: 1\nstatus: ready\nsystems:\n - id: legacy\n revision: 4\nrequired_deltas: []\nsupersedes: null\n---\n\n# UI Contract: Legacy checkout\n", + "aidd_docs/tasks/2026_08/2026_08_23_retire/requirement.md": "# Retire legacy UI\n\nUser approval: retire the legacy system after migrating legacy-checkout to apps/new. The existing consumer is required migration work, not a reason to delay approval.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in retire mode from aidd_docs/tasks/2026_08/2026_08_23_retire/requirement.md. The user explicitly approves the retirement. Write aidd_docs/tasks/2026_08/2026_08_23_retire/system-delta-legacy-retire.md, list the current UI contract as a migration dependency, leave verification blocked until migration, and modify no source or active contract.", + "expect": { + "filesExist": [ + "aidd_docs/tasks/2026_08/2026_08_23_retire/system-delta-legacy-retire.md" + ], + "filesUnchanged": [ + "apps/legacy/App.jsx", + "aidd_docs/ui/systems/legacy.md", + "aidd_docs/tasks/2026_08/2026_08_23_retire/ui.md" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_23_retire/system-delta-legacy-retire.md": [ + "mode: retire", + "status: approved", + "base_revision: 4", + "ui.md", + "apps/new" + ] + }, + "fileNotContains": { + "aidd_docs/tasks/2026_08/2026_08_23_retire/system-delta-legacy-retire.md": [ + "status: verified", + "status: promoted" + ] + }, + "judgeFiles": [ + "aidd_docs/tasks/2026_08/2026_08_23_retire/system-delta-legacy-retire.md" + ], + "judge": "The retirement delta is approved despite an active consumer, names that consumer as required migration work, remains unverified until migration, and leaves source and the active contract unchanged." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-system", + "name": "stops at the backend-only interface boundary", + "setup": { + "files": { + "package.json": "{ \"name\": \"orders-api\", \"dependencies\": { \"express\": \"^5.0.0\" } }\n", + "src/server.js": "const express = require('express');\nconst app = express();\napp.get('/orders', (_req, res) => res.json([]));\nmodule.exports = app;\n", + "openapi.yaml": "openapi: 3.1.0\ninfo:\n title: Orders API\n version: 1.0.0\n" + } + }, + "prompt": "Use the {{SKILL}} skill in discover mode to inspect this repository. The request is only to discover what interface system already exists, not to create a UI. Report the boundary from evidence, invent nothing, and modify nothing.", + "expect": { + "filesUnchanged": [ + "package.json", + "src/server.js", + "openapi.yaml" + ], + "filesAbsent": [ + "aidd_docs/memory/design.md", + "src/ui", + "tailwind.config.js" + ], + "stdoutMatches": [ + "(no (ui|interface) system|backend-only)" + ], + "judge": "The output recognizes a backend-only repository, reports that no interface system can be discovered, and does not invent UI conventions, recommend a design system, or propose frontend implementation." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-retire-promote", + "name": "promotes a verified retirement after sources are removed", + "setup": { + "git": true, + "files": { + "apps/new/App.jsx": "export function App() { return
Current checkout
; }\n", + "aidd_docs/ui/systems/legacy.md": "---\nid: legacy\nrevision: 4\nstatus: active\nscope:\n - apps/legacy\nsources:\n - apps/legacy/App.jsx\nsupersedes: legacy@3\n---\n\n# UI System: Legacy\n\n## Surfaces\n\n| Pattern, component, or token | Contract | States | Source |\n| --- | --- | --- | --- |\n| Legacy shell | checkout layout | default | apps/legacy/App.jsx |\n", + "aidd_docs/ui/systems/new.md": "---\nid: new\nrevision: 1\nstatus: active\nscope:\n - apps/new\nsources:\n - apps/new/App.jsx\nsupersedes: null\n---\n\n# UI System: New\n", + "aidd_docs/tasks/2026_08/2026_08_23_retire/system-delta-legacy-retire.md": "---\nid: retire\nsystem: legacy\nbase_revision: 4\nmode: retire\nstatus: verified\napproval_source: user\nverification_commit: {{COMMIT}}\ntarget_scope:\n - apps/legacy\nexpected_sources:\n - apps/new/App.jsx\nverified_sources:\n - apps/new/App.jsx\n---\n\n# UI System Delta: Retire Legacy\n\n## Dependencies\n\n- Replacement system new@1\n\n## Verification\n\n- No current UI contract consumes legacy@4.\n- apps/legacy/App.jsx is absent.\n- apps/new/App.jsx at {{COMMIT}} is the replacement.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in promote mode for aidd_docs/tasks/2026_08/2026_08_23_retire/system-delta-legacy-retire.md. Promote the verified retirement, retain historical source provenance, and do not recreate the removed legacy source.", + "expect": { + "filesExist": [ + "aidd_docs/ui/systems/.history/legacy@4.md" + ], + "filesAbsent": [ + "apps/legacy/App.jsx" + ], + "filesUnchanged": [ + "apps/new/App.jsx", + "aidd_docs/ui/systems/new.md" + ], + "fileContains": { + "aidd_docs/ui/systems/legacy.md": [ + "revision: 5", + "status: retired", + "apps/legacy/App.jsx" + ], + "aidd_docs/tasks/2026_08/2026_08_23_retire/system-delta-legacy-retire.md": [ + "status: promoted" + ] + }, + "judge": "Retirement promotion succeeds although the retired source is absent, archives revision 4, retains its path as historical provenance, and leaves the replacement implementation unchanged." + } + }, + { + "plugin": "aidd-dev", + "skill": "01-plan", + "evalName": "xeval-dev-plan-recover-ui", + "name": "recovers a draft UI contract through capability discovery", + "providers": [ + { + "plugin": "aidd-ui", + "skill": "02-design", + "evalName": "xeval-ui-contract-provider" + }, + { + "plugin": "aidd-ui", + "skill": "04-accessibility", + "evalName": "xeval-ui-a11y-recovery" + }, + { + "plugin": "aidd-ui", + "skill": "05-adapt", + "evalName": "xeval-ui-adapt-recovery" + } + ], + "setup": { + "files": { + "src/Status.jsx": "export function Status() { return

Service status

; }\n", + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 1\nstatus: active\nscope:\n - src\nsources:\n - src/Status.jsx\nsupersedes: null\n---\n\n# UI System: App\n", + "aidd_docs/tasks/2026_08/2026_08_23_status/requirement.md": "# Service status\n\nOperators must see current service health and a loading, available, or unavailable state. Status changes are announced. The same information remains visible in constrained space using the existing app system.\n", + "aidd_docs/tasks/2026_08/2026_08_23_status/ui.md": "---\nid: status\nrevision: 1\nstatus: draft\nsystems:\n - id: app\n revision: 1\nrequired_deltas: []\nsupersedes: null\n---\n\n# UI Contract: Status\n\n## Unresolved\n\n- States and specialist behavior not yet defined.\n" + } + }, + "prompt": "Use the {{SKILL}} skill to plan aidd_docs/tasks/2026_08/2026_08_23_status/requirement.md. The adjacent UI contract is draft. Discover the UI contract provider, revise it, then plan only if it becomes ready. Run headlessly and do not implement source.", + "expect": { + "filesExist": [ + "aidd_docs/tasks/2026_08/2026_08_23_status/plan.md", + "aidd_docs/tasks/2026_08/2026_08_23_status/phase-1.md", + "aidd_docs/tasks/2026_08/2026_08_23_status/.ui-history/status@1.md" + ], + "filesUnchanged": [ + "src/Status.jsx", + "aidd_docs/ui/systems/app.md", + "aidd_docs/tasks/2026_08/2026_08_23_status/requirement.md" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_23_status/ui.md": [ + "revision: 2", + "status: ready", + "xeval-ui-a11y-recovery", + "xeval-ui-adapt-recovery" + ], + "aidd_docs/tasks/2026_08/2026_08_23_status/phase-1.md": [ + "ui.md@2", + "app@1" + ] + }, + "fileNotContains": { + "aidd_docs/tasks/2026_08/2026_08_23_status/phase-1.md": [ + "## Wireframe" + ] + }, + "judge": "Planning recovers the draft through the discovered UI capability, consumes the new ready revision by reference, and does not redesign or implement the source itself." + } + }, + { + "plugin": "aidd-dev", + "skill": "01-plan", + "evalName": "xeval-dev-plan-fallback", + "name": "uses the bounded wireframe fallback without a UI provider", + "setup": { + "files": { + "src/Profile.jsx": "export function Profile() { return
Profile
; }\n", + "requirement.md": "# Profile\n\nAdd an account profile form with Save as the primary action.\n" + } + }, + "prompt": "Use the {{SKILL}} skill to plan requirement.md in aidd_docs/tasks/2026_08/2026_08_23_profile. This is frontend work and no UI capability provider is installed. Preserve the compatibility behavior without creating a normative UI contract or implementing source.", + "expect": { + "filesExist": [ + "aidd_docs/tasks/2026_08/2026_08_23_profile/plan.md", + "aidd_docs/tasks/2026_08/2026_08_23_profile/phase-1.md" + ], + "filesUnchanged": [ + "src/Profile.jsx", + "requirement.md" + ], + "filesAbsent": [ + "aidd_docs/ui/systems/app.md" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_23_profile/phase-1.md": [ + "## Wireframe", + "compatibility" + ] + }, + "fileNotContains": { + "aidd_docs/tasks/2026_08/2026_08_23_profile/phase-1.md": [ + "## UI Contract" + ] + }, + "judge": "With no UI provider, planning emits only a structure wireframe explicitly marked as compatibility fallback, creates no UI contract, and leaves source unchanged." + } + }, + { + "plugin": "aidd-dev", + "skill": "02-implement", + "evalName": "xeval-dev-implement-establish", + "name": "implements one approved establishment delta in its owning phase", + "setup": { + "git": true, + "files": { + "package.json": "{\"scripts\":{\"test\":\"node --test\"}}\n", + "test/button.test.js": "const test = require('node:test');\nconst assert = require('node:assert/strict');\ntest('destructive is a supported button intent', () => {\n const { buttonIntent } = require('../src/ui/Button.js');\n assert.equal(buttonIntent('destructive'), 'button button--destructive');\n});\n", + "aidd_docs/tasks/2026_08/2026_08_23_button/ui.md": "---\nid: button\nrevision: 1\nstatus: ready\nsystems: []\nrequired_deltas:\n - aidd_docs/tasks/2026_08/2026_08_23_button/system-delta-app-establish.md\nsupersedes: null\n---\n\n# UI Contract: Button\n\n## Intent\n\n- Task: render a destructive action with an explicit shared intent\n", + "aidd_docs/tasks/2026_08/2026_08_23_button/system-delta-app-establish.md": "---\nid: establish\nsystem: app\nbase_revision: null\nmode: establish\nstatus: approved\napproval_source: user\nverification_commit: null\ntarget_scope:\n - src\nexpected_sources:\n - src/ui/Button.js\nverified_sources: []\n---\n\n# UI System Delta: Establish App\n\n## Change\n\n| Decision | Evidence | Consequence | Rejected alternative |\n| --- | --- | --- | --- |\n| Export buttonIntent with primary and destructive intents | approved requirement | shared Button intent naming | one-off class names |\n\n## Verification\n\n- npm test passes.\n", + "aidd_docs/tasks/2026_08/2026_08_23_button/plan.md": "---\nobjective: Establish the minimum shared Button intent\nstatus: pending\n---\n\n# Plan: Button\n\n## Phases\n\n| # | Phase | File |\n| --- | --- | --- |\n| 1 | button | [phase-1.md](./phase-1.md) |\n", + "aidd_docs/tasks/2026_08/2026_08_23_button/phase-1.md": "---\nstatus: pending\n---\n\n# Instruction: Establish Button intent\n\n## Architecture projection\n\n```txt\nsrc/ui/Button.js create\n```\n\n## UI Contract\n\n- Contract: `aidd_docs/tasks/2026_08/2026_08_23_button/ui.md@1`\n- Systems: none\n- Implement deltas: aidd_docs/tasks/2026_08/2026_08_23_button/system-delta-app-establish.md\n- Consume deltas: none\n- Depends on phases: none\n\n## Tasks to do\n\n### `1)` Establish Button intent\n\n1. Create src/ui/Button.js with buttonIntent for primary and destructive.\n2. Run npm test.\n\n## Test acceptance criteria\n\n| Task | Acceptance criteria |\n| --- | --- |\n| 1 | npm test proves destructive resolves to button button--destructive |\n" + } + }, + "prompt": "Use the {{SKILL}} skill on aidd_docs/tasks/2026_08/2026_08_23_button/plan.md. Implement the approved establishment delta only in its owning phase, run the stated test, and leave UI artifacts and delta lifecycle status unchanged.", + "expect": { + "filesExist": [ + "src/ui/Button.js" + ], + "filesUnchanged": [ + "aidd_docs/tasks/2026_08/2026_08_23_button/ui.md", + "aidd_docs/tasks/2026_08/2026_08_23_button/system-delta-app-establish.md", + "test/button.test.js" + ], + "fileContains": { + "src/ui/Button.js": [ + "destructive" + ], + "aidd_docs/tasks/2026_08/2026_08_23_button/plan.md": [ + "status: implemented" + ], + "aidd_docs/tasks/2026_08/2026_08_23_button/phase-1.md": [ + "status: done" + ] + }, + "fileNotContains": { + "aidd_docs/tasks/2026_08/2026_08_23_button/system-delta-app-establish.md": [ + "status: verified" + ] + }, + "judge": "Implementation creates the approved minimum system source in exactly one owning phase, passes the test, and leaves verification and promotion to the UI system lifecycle." + } + }, + { + "plugin": "aidd-dev", + "skill": "02-implement", + "evalName": "xeval-dev-implement-verified", + "name": "consumes a verified delta without reimplementing it", + "setup": { + "git": true, + "files": { + "package.json": "{\"scripts\":{\"test\":\"node --test\"}}\n", + "src/ui/Button.js": "function buttonIntent(intent) { return `button button--${intent}`; }\nmodule.exports = { buttonIntent };\n", + "test/button.test.js": "const test = require('node:test');\nconst assert = require('node:assert/strict');\nconst { buttonIntent } = require('../src/ui/Button.js');\ntest('destructive', () => assert.equal(buttonIntent('destructive'), 'button button--destructive'));\n", + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 1\nstatus: active\nscope:\n - src\nsources:\n - src/ui/Button.js\nsupersedes: null\n---\n\n# UI System: App\n", + "aidd_docs/tasks/2026_08/2026_08_23_button/ui.md": "---\nid: button\nrevision: 1\nstatus: ready\nsystems:\n - id: app\n revision: 1\nrequired_deltas:\n - aidd_docs/tasks/2026_08/2026_08_23_button/system-delta-app-destructive.md\nsupersedes: null\n---\n\n# UI Contract: Button\n", + "aidd_docs/tasks/2026_08/2026_08_23_button/system-delta-app-destructive.md": "---\nid: destructive\nsystem: app\nbase_revision: 1\nmode: extend\nstatus: verified\napproval_source: user\nverification_commit: {{COMMIT}}\ntarget_scope:\n - src\nexpected_sources:\n - src/ui/Button.js\nverified_sources:\n - src/ui/Button.js\n---\n\n# UI System Delta: Destructive\n\n## Verification\n\n- src/ui/Button.js at {{COMMIT}} implements destructive.\n", + "aidd_docs/tasks/2026_08/2026_08_23_button/plan.md": "---\nobjective: Consume the verified Button behavior\nstatus: pending\n---\n\n# Plan: Button\n\n## Phases\n\n| # | Phase | File |\n| --- | --- | --- |\n| 1 | verify | [phase-1.md](./phase-1.md) |\n", + "aidd_docs/tasks/2026_08/2026_08_23_button/phase-1.md": "---\nstatus: pending\n---\n\n# Instruction: Verify Button behavior\n\n## UI Contract\n\n- Contract: `aidd_docs/tasks/2026_08/2026_08_23_button/ui.md@1`\n- Systems: app@1\n- Implement deltas: none\n- Consume deltas: aidd_docs/tasks/2026_08/2026_08_23_button/system-delta-app-destructive.md\n- Depends on phases: none\n\n## Tasks to do\n\n### `1)` Verify\n\n1. Run npm test without changing the implemented Button.\n\n## Test acceptance criteria\n\n| Task | Acceptance criteria |\n| --- | --- |\n| 1 | npm test passes |\n" + } + }, + "prompt": "Use the {{SKILL}} skill on aidd_docs/tasks/2026_08/2026_08_23_button/plan.md. Consume and assert the verified delta without reimplementing it.", + "expect": { + "filesUnchanged": [ + "src/ui/Button.js", + "test/button.test.js", + "aidd_docs/ui/systems/app.md", + "aidd_docs/tasks/2026_08/2026_08_23_button/ui.md", + "aidd_docs/tasks/2026_08/2026_08_23_button/system-delta-app-destructive.md" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_23_button/plan.md": [ + "status: implemented" + ], + "aidd_docs/tasks/2026_08/2026_08_23_button/phase-1.md": [ + "status: done" + ] + }, + "judge": "The verified delta is treated as a read-only dependency: source and lifecycle artifact remain byte-identical while its acceptance test is run." + } + }, + { + "plugin": "aidd-dev", + "skill": "02-implement", + "evalName": "xeval-dev-implement-historical", + "name": "rejects a historical system revision before mutation", + "setup": { + "git": true, + "files": { + "src/App.jsx": "export function App() { return
unchanged
; }\n", + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 2\nstatus: active\nscope:\n - src\nsources:\n - src/App.jsx\nsupersedes: app@1\n---\n\n# UI System: App\n", + "aidd_docs/ui/systems/.history/app@1.md": "---\nid: app\nrevision: 1\nstatus: active\nscope:\n - src\nsources:\n - src/App.jsx\nsupersedes: null\n---\n\n# UI System: App\n", + "aidd_docs/tasks/2026_08/2026_08_23_app/ui.md": "---\nid: app-feature\nrevision: 1\nstatus: ready\nsystems:\n - id: app\n revision: 1\nrequired_deltas: []\nsupersedes: null\n---\n\n# UI Contract: App feature\n", + "aidd_docs/tasks/2026_08/2026_08_23_app/plan.md": "---\nobjective: Implement app feature\nstatus: pending\n---\n\n# Plan: App\n\n## Phases\n\n| # | Phase | File |\n| --- | --- | --- |\n| 1 | app | [phase-1.md](./phase-1.md) |\n", + "aidd_docs/tasks/2026_08/2026_08_23_app/phase-1.md": "---\nstatus: pending\n---\n\n# Instruction: App\n\n## UI Contract\n\n- Contract: `aidd_docs/tasks/2026_08/2026_08_23_app/ui.md@1`\n- Systems: app@1\n- Implement deltas: none\n- Consume deltas: none\n- Depends on phases: none\n" + } + }, + "prompt": "Use the {{SKILL}} skill on aidd_docs/tasks/2026_08/2026_08_23_app/plan.md. Revalidate the UI graph and stop before mutation because the contract pins a historical system revision.", + "expect": { + "filesUnchanged": [ + "src/App.jsx", + "aidd_docs/ui/systems/app.md", + "aidd_docs/ui/systems/.history/app@1.md", + "aidd_docs/tasks/2026_08/2026_08_23_app/ui.md", + "aidd_docs/tasks/2026_08/2026_08_23_app/plan.md", + "aidd_docs/tasks/2026_08/2026_08_23_app/phase-1.md" + ], + "stdoutContains": [ + "replan needed", + "app@1" + ], + "judge": "Implementation rejects the resolvable but historical app revision before branch, status, phase, or source mutation." + } + }, + { + "plugin": "aidd-ui", + "skill": "04-accessibility", + "evalName": "xeval-ui-a11y-define", + "name": "defines accessibility requirements without an active UI system", + "setup": { + "files": { + "src/Profile.jsx": "export function Profile() { return
; }\n", + "requirement.md": "# Profile form\n\nEmail has a persistent label. Save remains keyboard reachable. Validation identifies the field and recovery. Status feedback is announced.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in define mode for requirement.md and src/Profile.jsx. No UI system contract exists. Return only sourced accessibility requirement fragments and modify nothing.", + "expect": { + "filesUnchanged": [ + "src/Profile.jsx", + "requirement.md" + ], + "stdoutContains": [ + "persistent label", + "acceptance" + ], + "judge": "The output defines observable accessibility requirements from the requirement and repository evidence without requiring or inventing a UI system revision." + } + }, + { + "plugin": "aidd-ui", + "skill": "04-accessibility", + "evalName": "xeval-ui-a11y-confirm", + "name": "confirms only implemented shared accessibility behavior", + "setup": { + "files": { + "src/ui/Input.jsx": "export function Input({ label, error, ...props }) { return ; }\n", + "src/Profile.jsx": "import { Input } from './ui/Input'; export function Profile() { return ; }\n" + } + }, + "prompt": "Use the {{SKILL}} skill in confirm mode for the shared Input in src/ui/Input.jsx. Return only shared behavior proven by canonical source evidence, keep gaps separate, and modify nothing.", + "expect": { + "filesUnchanged": [ + "src/ui/Input.jsx", + "src/Profile.jsx" + ], + "stdoutContains": [ + "src/ui/Input.jsx", + "label", + "confirmed" + ], + "judge": "The output confirms only accessibility behavior directly implemented by the canonical shared Input and does not convert unsupported runtime behavior into a rule." + } + }, + { + "plugin": "aidd-ui", + "skill": "05-adapt", + "evalName": "xeval-ui-adapt-assess", + "name": "finds an evidenced constrained-space adaptation defect", + "setup": { + "files": { + "src/Orders.jsx": "export function Orders() { return
A-VERY-LONG-ORDER-ID Review
; }\n", + "src/styles.css": ".orders { width: 900px; } .row { white-space: nowrap; }\n", + "requirement.md": "# Orders\n\nAt 320px wide, every order ID and its Review action remain accessible without page-level horizontal scrolling.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in assess mode for the Orders interface using the supplied 320px requirement and implementation evidence. Return an adaptation finding only when supported and modify nothing.", + "expect": { + "filesUnchanged": [ + "src/Orders.jsx", + "src/styles.css", + "requirement.md" + ], + "stdoutContains": [ + "320px", + "horizontal", + "impact" + ], + "judge": "The output identifies the fixed width and nowrap behavior as evidence for constrained-space failure, names user impact and required behavior, and makes no accessibility verdict." + } + }, + { + "plugin": "aidd-ui", + "skill": "05-adapt", + "evalName": "xeval-ui-adapt-confirm", + "name": "confirms a canonical shared adaptation rule", + "setup": { + "files": { + "src/ui/shell.css": ".shell { display: grid; grid-template-columns: 1fr; } @media (min-width: 48rem) { .shell { grid-template-columns: 14rem 1fr; } }\n", + "src/Users.jsx": "export function Users() { return
Users
; }\n", + "src/Orders.jsx": "export function Orders() { return
Orders
; }\n" + } + }, + "prompt": "Use the {{SKILL}} skill in confirm mode for the canonical shell rule in src/ui/shell.css. Confirm only the implemented shared transformation and modify nothing.", + "expect": { + "filesUnchanged": [ + "src/ui/shell.css", + "src/Users.jsx", + "src/Orders.jsx" + ], + "stdoutContains": [ + "48rem", + "src/ui/shell.css", + "confirmed" + ], + "judge": "The output confirms the sourced one-column to two-column shared transformation and does not add device dimensions or unrelated accessibility rules." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-reconcile-verified", + "name": "verifies an approved delta from committed implementation evidence", + "setup": { + "git": true, + "files": { + "src/ui/Button.jsx": "export function Button({ intent = 'primary', children }) { return ; }\n", + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 1\nstatus: active\nscope:\n - src\nsources:\n - src/ui/Button.jsx\nsupersedes: null\n---\n\n# UI System: App\n", + "aidd_docs/tasks/2026_08/2026_08_24_button/system-delta-app-intent.md": "---\nid: intent\nsystem: app\nbase_revision: 1\nmode: extend\nstatus: approved\napproval_source: user\nverification_commit: null\ntarget_scope:\n - src\nexpected_sources:\n - src/ui/Button.jsx\nverified_sources: []\n---\n\n# UI System Delta: Button Intent\n\n## Change\n\n| Decision | Evidence | Consequence | Rejected alternative |\n| --- | --- | --- | --- |\n| Add a shared intent property | approved requirement | Button exposes intent | one-off classes |\n\n## Verification\n\n- src/ui/Button.jsx exposes intent and npm-free static inspection proves it.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in reconcile mode for aidd_docs/tasks/2026_08/2026_08_24_button/system-delta-app-intent.md. Verify it only from the current committed implementation evidence and modify no other file.", + "expect": { + "filesUnchanged": [ + "src/ui/Button.jsx", + "aidd_docs/ui/systems/app.md" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_24_button/system-delta-app-intent.md": [ + "status: verified", + "src/ui/Button.jsx" + ] + }, + "fileNotContains": { + "aidd_docs/tasks/2026_08/2026_08_24_button/system-delta-app-intent.md": [ + "verification_commit: null" + ] + }, + "judge": "Reconciliation moves the exact approved delta to verified only because its acceptance is proven at a real commit, recording the commit and source without changing the contract or code." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-promote-establish", + "name": "promotes a verified establishment into revision one", + "setup": { + "git": true, + "files": { + "src/ui/Button.js": "function buttonIntent(intent) { return `button button--${intent}`; } module.exports = { buttonIntent };\n", + "aidd_docs/tasks/2026_08/2026_08_24_system/system-delta-app-establish.md": "---\nid: establish\nsystem: app\nbase_revision: null\nmode: establish\nstatus: verified\napproval_source: user\nverification_commit: {{COMMIT}}\ntarget_scope:\n - src\nexpected_sources:\n - src/ui/Button.js\nverified_sources:\n - src/ui/Button.js\n---\n\n# UI System Delta: Establish App\n\n## Change\n\n| Decision | Evidence | Consequence | Rejected alternative |\n| --- | --- | --- | --- |\n| Share Button intents | requirement and src/ui/Button.js at {{COMMIT}} | app system owns Button intent | one-off classes |\n\n## Verification\n\n- src/ui/Button.js at {{COMMIT}} proves the rule.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in promote mode for aidd_docs/tasks/2026_08/2026_08_24_system/system-delta-app-establish.md. Create app revision 1 from the verified establishment and release the operation lock.", + "expect": { + "filesExist": [ + "aidd_docs/ui/systems/app.md" + ], + "filesAbsent": [ + ".aidd-ui-systems.lock" + ], + "filesUnchanged": [ + "src/ui/Button.js" + ], + "fileContains": { + "aidd_docs/ui/systems/app.md": [ + "id: app", + "revision: 1", + "status: active", + "src/ui/Button.js" + ], + "aidd_docs/tasks/2026_08/2026_08_24_system/system-delta-app-establish.md": [ + "status: promoted" + ] + }, + "judge": "Promotion creates exactly revision 1 from the verified no-base delta, marks that delta promoted, leaves implementation unchanged, and leaves no operation lock." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-reject", + "name": "rejects an exact approved delta only from explicit authorization", + "setup": { + "files": { + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 1\nstatus: active\nscope:\n - src\nsources:\n - src/styles.css\nsupersedes: null\n---\n\n# UI System: App\n", + "aidd_docs/tasks/2026_08/2026_08_24_color/system-delta-app-accent.md": "---\nid: accent\nsystem: app\nbase_revision: 1\nmode: extend\nstatus: approved\napproval_source: prior user approval\nverification_commit: null\ntarget_scope:\n - src\nexpected_sources:\n - src/styles.css\nverified_sources: []\n---\n\n# UI System Delta: Accent\n" + } + }, + "prompt": "Use the {{SKILL}} skill to reject aidd_docs/tasks/2026_08/2026_08_24_color/system-delta-app-accent.md. This prompt explicitly authorizes rejection of that exact delta. Modify no other artifact.", + "expect": { + "filesUnchanged": [ + "aidd_docs/ui/systems/app.md" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_24_color/system-delta-app-accent.md": [ + "status: rejected", + "base_revision: 1" + ] + }, + "judge": "The exact approved delta becomes rejected from explicit authorization without changing its base, the active contract, or implementation." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-retired-id", + "name": "blocks establishment over a retired system id", + "setup": { + "files": { + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 3\nstatus: retired\nscope:\n - src\nsources:\n - src/legacy.css\nsupersedes: app@2\n---\n\n# UI System: Retired App\n", + "requirement.md": "# New app system\n\nEstablish a minimal shared Button system under id app for src.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in establish mode for requirement.md with proposed system id app and scope src. Stop because that current id is retired, do not reactivate or overwrite it, and modify nothing.", + "expect": { + "filesUnchanged": [ + "aidd_docs/ui/systems/app.md", + "requirement.md" + ], + "filesAbsent": [ + "aidd_docs/tasks/2026_08/2026_08_24_new-app-system/system-delta-app-establish.md" + ], + "stdoutContains": [ + "retired", + "app" + ], + "judge": "Establishment is blocked because a retired current head already owns the id, preserving its revision history and proposing no silent revision 1 replacement." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-replace-retired-scope", + "name": "establishes a new id after the prior scoped system is retired", + "setup": { + "files": { + "aidd_docs/ui/systems/legacy.md": "---\nid: legacy\nrevision: 4\nstatus: retired\nscope:\n - src\nsources:\n - src/legacy.css\nsupersedes: legacy@3\n---\n\n# UI System: Legacy\n", + "aidd_docs/tasks/2026_08/2026_08_24_replacement/requirement.md": "# Replacement system\n\nEstablish only a shared Button intent convention under new system id app for src. Reuse the existing button naming.\n", + "src/button.css": ".button-primary { font: inherit; }\n" + } + }, + "prompt": "Use the {{SKILL}} skill in establish mode for aidd_docs/tasks/2026_08/2026_08_24_replacement/requirement.md. Draft system delta id establish for new system id app and scope src. The legacy system on that scope is retired, so it must remain immutable and must not block this new id. Do not implement or promote the delta.", + "expect": { + "filesUnchanged": [ + "aidd_docs/ui/systems/legacy.md", + "src/button.css" + ], + "filesExist": [ + "aidd_docs/tasks/2026_08/2026_08_24_replacement/system-delta-app-establish.md" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_24_replacement/system-delta-app-establish.md": [ + "system: app", + "base_revision: null", + "mode: establish", + "src" + ] + }, + "judge": "A retired contract keeps its immutable head but no longer owns active scope resolution, so a different system id can draft a minimal establishment delta without implementation or promotion." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-adopt-lock", + "name": "stops adoption when the systems lock is held", + "setup": { + "files": { + ".aidd-ui-systems.lock/owner": "other-operation\n", + "src/ui/Button.jsx": "export function Button({ children }) { return ; }\n" + } + }, + "prompt": "Use the {{SKILL}} skill in adopt mode for system id app and scope src. I authorize the exact evidenced revision 1 contract, but the systems mutation lock is held. Stop without changing the lock or creating a contract.", + "expect": { + "filesUnchanged": [ + ".aidd-ui-systems.lock/owner", + "src/ui/Button.jsx" + ], + "filesAbsent": [ + "aidd_docs/ui/systems/app.md" + ], + "stdoutContains": [ + "lock" + ], + "judge": "Adoption obeys the shared systems mutation lock and creates no competing revision while another system operation owns it." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-reconcile-lock", + "name": "stops delta reconciliation when the systems lock is held", + "setup": { + "git": true, + "files": { + ".aidd-ui-systems.lock/owner": "other-operation\n", + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 1\nstatus: active\nscope:\n - src\nsources:\n - src/ui/Button.jsx\nsupersedes: null\n---\n\n# UI System: App\n", + "aidd_docs/tasks/2026_08/2026_08_24_button/system-delta-app-intent.md": "---\nid: intent\nsystem: app\nbase_revision: 1\nmode: extend\nstatus: approved\napproval_source: user\nverification_commit: null\ntarget_scope:\n - src\nexpected_sources:\n - src/ui/Button.jsx\nverified_sources: []\n---\n\n# UI System Delta: Intent\n\n## Verification\n\n- Button intent is implemented at one commit.\n", + "src/ui/Button.jsx": "export function Button({ intent, children }) { return ; }\n" + } + }, + "prompt": "Use the {{SKILL}} skill in reconcile mode for aidd_docs/tasks/2026_08/2026_08_24_button/system-delta-app-intent.md. The implementation matches, but the systems mutation lock is held. Stop without changing the delta, contract, source, or lock.", + "expect": { + "filesUnchanged": [ + ".aidd-ui-systems.lock/owner", + "aidd_docs/ui/systems/app.md", + "aidd_docs/tasks/2026_08/2026_08_24_button/system-delta-app-intent.md", + "src/ui/Button.jsx" + ], + "stdoutContains": [ + "lock" + ], + "judge": "Reconciliation cannot transition delta state while another system operation owns the shared mutation lock." + } + }, + { + "plugin": "aidd-ui", + "skill": "01-system", + "evalName": "xeval-ui-promote-lock", + "name": "stops promotion when the system lock is held", + "setup": { + "git": true, + "files": { + "src/ui/Button.jsx": "export function Button({ intent, children }) { return ; }\n", + ".aidd-ui-systems.lock/owner": "other-operation\n", + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 1\nstatus: active\nscope:\n - src\nsources:\n - src/ui/Button.jsx\nsupersedes: null\n---\n\n# UI System: App\n", + "aidd_docs/tasks/2026_08/2026_08_24_lock/system-delta-app-intent.md": "---\nid: intent\nsystem: app\nbase_revision: 1\nmode: extend\nstatus: verified\napproval_source: user\nverification_commit: {{COMMIT}}\ntarget_scope:\n - src\nexpected_sources:\n - src/ui/Button.jsx\nverified_sources:\n - src/ui/Button.jsx\n---\n\n# UI System Delta: Intent\n\n## Verification\n\n- src/ui/Button.jsx at {{COMMIT}} proves intent.\n" + } + }, + "prompt": "Use the {{SKILL}} skill in promote mode for aidd_docs/tasks/2026_08/2026_08_24_lock/system-delta-app-intent.md. Respect the existing systems mutation lock and stop without mutation.", + "expect": { + "filesUnchanged": [ + "src/ui/Button.jsx", + ".aidd-ui-systems.lock/owner", + "aidd_docs/ui/systems/app.md", + "aidd_docs/tasks/2026_08/2026_08_24_lock/system-delta-app-intent.md" + ], + "filesAbsent": [ + "aidd_docs/ui/systems/.history/app@1.md" + ], + "stdoutContains": [ + "lock" + ], + "judge": "Promotion observes the preexisting exclusive lock, changes no contract, delta, archive, source, or lock owner, and reports contention." + } + }, + { + "plugin": "aidd-ui", + "skill": "02-design", + "evalName": "xeval-ui-write-lock", + "name": "stops UI revision when the feature lock is held", + "setup": { + "files": { + "src/Profile.jsx": "export function Profile() { return
Profile
; }\n", + "aidd_docs/tasks/2026_08/2026_08_24_profile/.ui.lock/owner": "other-operation\n", + "aidd_docs/tasks/2026_08/2026_08_24_profile/requirement.md": "# Profile\n\nClarify the current profile status copy without changing flow.\n", + "aidd_docs/tasks/2026_08/2026_08_24_profile/ui.md": "---\nid: profile\nrevision: 1\nstatus: ready\nsystems: []\nrequired_deltas: []\nsupersedes: null\n---\n\n# UI Contract: Profile\n\n## Intent\n\n- Task: view profile status\n" + } + }, + "prompt": "Use the {{SKILL}} skill in revise mode for aidd_docs/tasks/2026_08/2026_08_24_profile/ui.md from its adjacent requirement. Respect the existing feature lock and stop without mutation.", + "expect": { + "filesUnchanged": [ + "src/Profile.jsx", + "aidd_docs/tasks/2026_08/2026_08_24_profile/.ui.lock/owner", + "aidd_docs/tasks/2026_08/2026_08_24_profile/requirement.md", + "aidd_docs/tasks/2026_08/2026_08_24_profile/ui.md" + ], + "filesAbsent": [ + "aidd_docs/tasks/2026_08/2026_08_24_profile/.ui-history/profile@1.md" + ], + "stdoutContains": [ + "lock" + ], + "judge": "UI revision stops at the exclusive feature lock without changing source, requirement, current contract, history, or lock owner." + } + }, + { + "plugin": "aidd-dev", + "skill": "01-plan", + "evalName": "xeval-dev-plan-stale-no-provider", + "name": "does not bypass an invalid UI contract without a provider", + "setup": { + "files": { + "src/Profile.jsx": "export function Profile() { return
Profile
; }\n", + "aidd_docs/tasks/2026_08/2026_08_24_profile/requirement.md": "# Profile\n\nImplement the profile UI only from a ready contract.\n", + "aidd_docs/tasks/2026_08/2026_08_24_profile/ui.md": "---\nid: profile\nrevision: 1\nstatus: draft\nsystems: []\nrequired_deltas: []\nsupersedes: null\n---\n\n# UI Contract: Profile\n\n## Unresolved\n\n- Required states are missing.\n" + } + }, + "prompt": "Use the {{SKILL}} skill to plan aidd_docs/tasks/2026_08/2026_08_24_profile/requirement.md. No UI provider is installed and the adjacent UI contract is draft. Stop instead of replacing it with a compatibility wireframe.", + "expect": { + "filesUnchanged": [ + "src/Profile.jsx", + "aidd_docs/tasks/2026_08/2026_08_24_profile/requirement.md", + "aidd_docs/tasks/2026_08/2026_08_24_profile/ui.md" + ], + "filesAbsent": [ + "aidd_docs/tasks/2026_08/2026_08_24_profile/plan.md", + "aidd_docs/tasks/2026_08/2026_08_24_profile/phase-1.md" + ], + "stdoutContains": [ + "UI revision needed" + ], + "judge": "Planning refuses to bypass an existing draft UI contract when no provider can revise it, preserving the normative graph and producing no fallback plan." + } + }, + { + "plugin": "aidd-dev", + "skill": "01-plan", + "evalName": "xeval-dev-plan-reconcile-first", + "name": "requires reconciliation before planning an already implemented approved delta", + "setup": { + "files": { + "src/ui/Button.jsx": "export function Button({ intent, children }) { return ; }\n", + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 1\nstatus: active\nscope:\n - src\nsources:\n - src/ui/Button.jsx\nsupersedes: null\n---\n\n# UI System: App\n", + "aidd_docs/tasks/2026_08/2026_08_24_button/requirement.md": "# Button\n\nUse the approved shared intent behavior.\n", + "aidd_docs/tasks/2026_08/2026_08_24_button/ui.md": "---\nid: button\nrevision: 1\nstatus: ready\nsystems:\n - id: app\n revision: 1\nrequired_deltas:\n - aidd_docs/tasks/2026_08/2026_08_24_button/system-delta-app-intent.md\nsupersedes: null\n---\n\n# UI Contract: Button\n", + "aidd_docs/tasks/2026_08/2026_08_24_button/system-delta-app-intent.md": "---\nid: intent\nsystem: app\nbase_revision: 1\nmode: extend\nstatus: approved\napproval_source: user\nverification_commit: null\ntarget_scope:\n - src\nexpected_sources:\n - src/ui/Button.jsx\nverified_sources: []\n---\n\n# UI System Delta: Intent\n\n## Verification\n\n- Button exposes the intent property.\n" + } + }, + "prompt": "Use the {{SKILL}} skill to plan aidd_docs/tasks/2026_08/2026_08_24_button/requirement.md. Repository evidence already satisfies the approved delta. Stop for UI system reconciliation instead of assigning implementation again.", + "expect": { + "filesUnchanged": [ + "src/ui/Button.jsx", + "aidd_docs/ui/systems/app.md", + "aidd_docs/tasks/2026_08/2026_08_24_button/requirement.md", + "aidd_docs/tasks/2026_08/2026_08_24_button/ui.md", + "aidd_docs/tasks/2026_08/2026_08_24_button/system-delta-app-intent.md" + ], + "filesAbsent": [ + "aidd_docs/tasks/2026_08/2026_08_24_button/plan.md" + ], + "stdoutContains": [ + "reconciliation" + ], + "judge": "Planning recognizes that code already satisfies the approved delta, requests system reconciliation, and does not schedule duplicate implementation or mutate lifecycle state." + } + }, + { + "plugin": "aidd-ui", + "skill": "03-review", + "evalName": "xeval-ui-review-flow", + "name": "records an evidence-pinned flow review with no invented findings", + "providers": [ + { + "plugin": "aidd-ui", + "skill": "04-accessibility", + "evalName": "xeval-review-flow-a11y" + }, + { + "plugin": "aidd-ui", + "skill": "05-adapt", + "evalName": "xeval-review-flow-adapt" + } + ], + "setup": { + "git": true, + "files": { + "src/Search.jsx": "export function Search() { return

Orders

Ready

; }\n", + "aidd_docs/ui/systems/app.md": "---\nid: app\nrevision: 1\nstatus: active\nscope:\n - src\nsources:\n - src/Search.jsx\nsupersedes: null\n---\n\n# UI System: App\n", + "aidd_docs/tasks/2026_08/2026_08_24_search/requirement.md": "# Search flow\n\nAn operator enters an order ID, activates Search, and receives announced status. The form remains usable in constrained space.\n", + "aidd_docs/tasks/2026_08/2026_08_24_search/ui.md": "---\nid: search\nrevision: 1\nstatus: ready\nsystems:\n - id: app\n revision: 1\nrequired_deltas: []\nsupersedes: null\n---\n\n# UI Contract: Search\n\n## User Flow\n\n1. Enter order ID.\n2. Activate Search.\n3. Receive status feedback.\n", + "aidd_docs/tasks/2026_08/2026_08_24_search/runtime-observations.md": "# Runtime observations\n\nAt 1280px and 320px, the form remains visible without horizontal overflow. Keyboard order is heading, input, Search. Activating Search updates the role=status region. No failure was observed in the required flow.\n" + } + }, + "prompt": "Use the {{SKILL}} skill to review the complete search flow against its requirement, UI contract, source, and runtime-observations.md. Discover both specialist providers. Write ui-review.md, preserve a no-findings result when evidence supports it, and modify nothing else.", + "expect": { + "filesExist": [ + "aidd_docs/tasks/2026_08/2026_08_24_search/ui-review.md" + ], + "filesUnchanged": [ + "src/Search.jsx", + "aidd_docs/ui/systems/app.md", + "aidd_docs/tasks/2026_08/2026_08_24_search/requirement.md", + "aidd_docs/tasks/2026_08/2026_08_24_search/ui.md", + "aidd_docs/tasks/2026_08/2026_08_24_search/runtime-observations.md" + ], + "fileContains": { + "aidd_docs/tasks/2026_08/2026_08_24_search/ui-review.md": [ + "normative: false", + "worktree_fingerprint: clean", + "## Findings", + "xeval-review-flow-a11y", + "xeval-review-flow-adapt" + ] + }, + "fileNotContains": { + "aidd_docs/tasks/2026_08/2026_08_24_search/ui-review.md": [ + "### blocker", + "### important", + "### minor" + ] + }, + "judge": "The review pins the clean commit and exact UI revisions, preserves specialist provenance, records assessed runtime contexts, and invents no defect when the supplied flow evidence satisfies the contract." + } } ]