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.46 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: component-conformance-review description: 'Checks every component in the AST-derived inventory against its spec in components.md, flagging undocumented variants, !important, inline style= and unwrapped primitives. Use when a design-test run has finished token-conformance-review.' metadata: model_tier: reasoning cacheable: 'false' output_format: markdown paqad-meta: skill.meta.yaml --- ## What It Does Audits the project's UI components against `components.md`. The AST-derived component inventory is the subject; the contract is the standard. Every component used in source must appear in `components.md` with declared variants, states, and permitted compositions. Override sprawl (`!important`, inline `style=`, undocumented Tailwind combinations, shadcn primitives wrapped without spec) is a finding. ## Use This When For every design-test run, after `token-conformance-review`. The two together form the "is the contract followed at the source level" pair. ## Inputs - Read `docs/instructions/design-system/components.md`. - Read the contract-summary from `design-system-coverage` (declared component clauses). - Read `references/component-conformance-checklist.md` before scanning. ## Procedure The set difference between source and contract is deterministic, drive it with the scripts. Reserve LLM judgment for severity and the "is this primitive correctly wrapped" question. 1. Run `scripts/derive-inventory.sh [components-dir]` → `<name>\t<source-file>` TSV. The script already excludes tests, stories, type decls, barrels, and lower-case helpers. 2. Run `scripts/parse-components-md.sh <components.md>` → `<name>\t<variants-csv>\t<states-csv>` TSV. Empty CSV slots are `-`. 3. Run `scripts/diff-inventories.sh --source <derived> --declared <parsed>`. Each row is a deterministic gap: - `in-source-not-declared\tName\t<file>` → `documentation-drift` finding, **medium**. - `declared-not-in-source\tName\t-` → `documentation-drift` finding (contract references a non-existent component), **medium** to **high** depending on whether the contract is what the team intends to build. 4. Run `runtime/scripts/design/scan-overrides.sh` to enumerate `!important`, inline `style=`, arbitrary Tailwind brackets, undocumented utility combos. The LLM decides whether each hit is a missing prop on a declared component or genuine code smell. 5. For each declared component, verify its declared variants are implemented in the source file. Missing variant → `component` finding, **high**. ## Output Contract - Match `assets/output.template.md`. `contract_ref` is `components.md → <ComponentName>` or `patterns.md → override budget`. - Default severity `high` for missing-variant findings, `medium` for override sprawl, `low` for cosmetic deviations. - Output must pass `scripts/lint-findings.sh` (exit 0). ## Escalate / Stop Conditions - Ask when `components.md` has no entries: defer to `design-system-coverage` (tier likely `bare`). - Warn when the inventory exceeds 100 components: the audit may need to be chunked. ## Resources - `references/component-conformance-checklist.md` - `scripts/derive-inventory.sh`: AST-ish inventory of `src/components/**`. - `scripts/parse-components-md.sh`: declared inventory + variants/states from `components.md`. - `scripts/diff-inventories.sh`: set difference between source and declared. - `scripts/lint-findings.sh` - `assets/output.template.md` - `agents/openai.yaml`