UNPKG

paqad-ai

Version:

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

github.com/Eliyce/paqad-ai

Eliyce/paqad-ai

58 lines (42 loc) • 3.75 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
--- name: design-system-coverage description: 'Grades the design-system contract for completeness and writes the coverage inventory every later design-test skill reads. Use when a design-test run starts; it always runs first and its tier gates the run.' metadata: model_tier: reasoning cacheable: 'false' output_format: json paqad-meta: skill.meta.yaml --- ## What It Does Grades `docs/instructions/design-system/` for completeness, produces a coverage inventory, and emits the **tier** (`missing | bare | adequate | strong`) the rest of the workflow uses to decide whether to stop, warn, or proceed in strict mode. Runs as Step 0 (readiness gate) and as the first skill in Step 1: every downstream skill consumes this inventory. ## Use This When As the **first skill in every design-test run**. The tier it emits gates the entire workflow. Never skip it; never run other design-test skills without it. ## Inputs - Read every file under `docs/instructions/design-system/` (typically `tokens.md`, `components.md`, `accessibility.md`, `motion.md`, `patterns.md`, `responsive.md`). - Read `references/contract-clauses.md` before grading. ## Procedure The decisions in steps 1–3 are deterministic: drive them with the scripts in `scripts/` rather than re-deriving the logic from prose each run. 1. Run `scripts/list-contract-files.sh` to enumerate which contract files exist and which are empty/stub. 2. For each file, run `scripts/count-clauses.sh <file>` to count contract clauses (the file emits `<path>\t<count>` and skips headings, blank lines, frontmatter delimiters, and lines inside fenced code blocks). Concatenate the rows. 3. Pipe the concatenated counts into `scripts/derive-tier.sh`: it emits a single `tier=<missing|bare|adequate|strong>` line. This is the gate decision: don't second-guess it. 4. Emit the coverage inventory per `assets/output.template.json` to `.paqad/design-test/runs/<run_id>/artifacts/contract-summary.json`. 5. Validate with `scripts/validate-contract.sh`: enforces required fields, allowed tier vocabulary, and rejects empty clause arrays when the tier is `adequate` or `strong`. 6. If tier is `missing`, raise a Decision Pause Contract packet asking the user whether to invoke the `documentation-update` workflow inline for `design-system` before resuming. If tier is `bare`, additionally run `scripts/gap-report.sh` and emit each row as a `DT-DS-XXXX` `documentation-drift` finding (the script's id sequence is stable across runs so retests preserve ids). ## Output Contract - Match `assets/output.template.json`: `{ tier, files: [{ path, present, empty, clause_count }], clauses: { tokens: [...], components: [...], accessibility: [...], responsive: [...], motion: [...], patterns: [...] } }`. - `tier` ∈ `missing | bare | adequate | strong`. - Output must pass `scripts/validate-contract.sh` (exit 0). ## Escalate / Stop Conditions - Stop and prompt when tier is `missing`. Offer inline invocation of the `documentation-update` workflow for the design-system. - Warn when tier is `bare`. Run downstream skills in exploratory mode and tag findings `confidence: low`. - Do not auto-engage `design_test.strict` when tier is `strong`: strict mode is explicit opt-in only. ## Resources - `references/contract-clauses.md` - `scripts/list-contract-files.sh`: enumerate contract files (present/empty/non-empty). - `scripts/count-clauses.sh`: count clauses in one contract file. - `scripts/derive-tier.sh`: derive the tier from per-file counts (pure function of counts). - `scripts/gap-report.sh`: enumerate contract gaps as `DT-DS-XXXX` rows with stable ids. - `scripts/validate-contract.sh`: schema-check the emitted coverage inventory. - `assets/output.template.json` - `agents/openai.yaml`