UNPKG

paqad-ai

Version:

Spec-driven development framework — AI agents that think before they type

github.com/Eliyce/paqad-ai

Eliyce/paqad-ai

59 lines (43 loc) • 3.37 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
--- name: state-coverage-review description: 'Checks that every component in the AST inventory implements its declared states (default, hover, focus, disabled, loading, error, empty) and that Playwright tests exercise them. Use when a design-test run has finished component-conformance-review.' metadata: model_tier: reasoning cacheable: 'false' output_format: markdown paqad-meta: skill.meta.yaml --- ## What It Does Cross-checks the declared state machine of each component against (1) what the source code implements and (2) what Playwright tests actually exercise. A declared state that's neither implemented nor tested is a finding; an implemented state that's never tested is a coverage finding. ## Use This When For every design-test run after `component-conformance-review`. It depends on the AST inventory that skill produced. ## Inputs - Read `docs/instructions/design-system/components.md` for declared states. - Read Playwright test files (`tests/**`, `e2e/**`) for what's exercised. - Read `references/state-coverage-checklist.md` before grading. ## Procedure The set arithmetic across declared / implemented / tested is deterministic, drive it with the scripts. LLM picks severity per missing state (focus and error are elevated to **high** per the checklist). 1. For each component, run `scripts/extract-source-states.sh <component-file>` → TSV of `<state>\t<signal>` (signals: `:hover`, Tailwind `hover:` utility, `disabled` prop, `aria-disabled`, framer-motion hooks, etc.). `default` is always emitted. 2. Run `scripts/extract-tested-states.sh --component <Name> --tests <dir>` → TSV of `<state>\t<test-file>`. The tests directory should contain Playwright specs only (the script greps for component name + state driver pattern; mixing the component's source with the tests dir would self-pollute the result). 3. Take the declared states from `components.md` (the CSV from `parse-components-md.sh` works directly). 4. Run `scripts/cross-reference-states.sh --declared <csv> --implemented <impl.tsv> --tested <tested.tsv>`. Each row is a deterministic gap: - `declared-not-implemented\t<state>` → `state` finding. - `implemented-not-tested\t<state>` → `state` finding (regression risk). - `tested-not-implemented\t<state>` → `documentation-drift` finding (test asserts something the component can't reach). ## Output Contract - Match `assets/output.template.md`. `contract_ref` is `components.md → <ComponentName> > <state>`. - Default severity `medium`. Use `high` when the missing state is `focus` (a11y blocker) or `error` (silently fails for users). - Output must pass `scripts/lint-findings.sh` (exit 0). ## Escalate / Stop Conditions - Ask when Playwright is not configured: coverage cross-check can't run; emit all state findings as `confidence: low`. - Warn when a component has no declared states in `components.md`: defer the check, emit a `documentation-drift` finding instead. ## Resources - `references/state-coverage-checklist.md` - `scripts/extract-source-states.sh`: implemented-states detector for one component file. - `scripts/extract-tested-states.sh`: tested-states detector across a Playwright tests dir. - `scripts/cross-reference-states.sh`: declared/implemented/tested set-difference gap emitter. - `scripts/lint-findings.sh` - `assets/output.template.md` - `agents/openai.yaml`