@event4u/agent-config 7.0.2 → 7.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +9 -1
- package/CHANGELOG.md +117 -0
- package/README.md +4 -2
- package/dist/agent-src/commands/council/default.md +28 -20
- package/dist/agent-src/commands/evals/fix.json +5 -1
- package/dist/agent-src/commands/fix/comments.md +101 -0
- package/dist/agent-src/commands/fix.md +5 -2
- package/dist/agent-src/contexts/execution/auto-dispatch-classification.md +65 -0
- package/dist/agent-src/contexts/execution/auto-orchestration-activation.md +68 -0
- package/dist/agent-src/contexts/execution/host-capability-manifest.md +68 -0
- package/dist/agent-src/contexts/execution/orchestration-benchmark-gate.md +62 -0
- package/dist/agent-src/contexts/execution/orchestration-telemetry.md +59 -0
- package/dist/agent-src/contexts/execution/roadmap-process-loop.md +8 -3
- package/dist/agent-src/contexts/execution/subagent-response-contract.md +56 -0
- package/dist/agent-src/contexts/execution/subagent-routing.md +57 -0
- package/dist/agent-src/contexts/execution/subagent-spawn-contract.md +54 -0
- package/dist/agent-src/contexts/execution/subagent-steering.md +71 -0
- package/dist/agent-src/contexts/execution/verify-budget.md +50 -0
- package/dist/agent-src/rules/brand-source-of-truth.md +10 -0
- package/dist/agent-src/rules/delegation-policy.md +85 -0
- package/dist/agent-src/rules/design-fidelity.md +98 -0
- package/dist/agent-src/rules/domain-safety-pii.md +22 -0
- package/dist/agent-src/rules/legal-safety-floor.md +182 -0
- package/dist/agent-src/rules/lethal-trifecta-guard.md +25 -22
- package/dist/agent-src/rules/output-discipline.md +85 -0
- package/dist/agent-src/rules/telegraph-speak.md +4 -1
- package/dist/agent-src/rules/token-budget-discipline.md +94 -0
- package/dist/agent-src/scripts/archive_completed_roadmaps.ts +102 -15
- package/dist/agent-src/scripts/update_roadmap_progress.ts +30 -3
- package/dist/agent-src/skills/accessibility-auditor/SKILL.md +20 -5
- package/dist/agent-src/skills/ai-council/SKILL.md +28 -1
- package/dist/agent-src/skills/blade-ui/SKILL.md +9 -0
- package/dist/agent-src/skills/contract-review/SKILL.md +125 -0
- package/dist/agent-src/skills/contract-review/evals/triggers.json +17 -0
- package/dist/agent-src/skills/dashboard-design/SKILL.md +21 -5
- package/dist/agent-src/skills/design-intelligence/SKILL.md +96 -0
- package/dist/agent-src/skills/design-review/SKILL.md +83 -0
- package/dist/agent-src/skills/design-system-capture/SKILL.md +234 -0
- package/dist/agent-src/skills/design-tokens/SKILL.md +1 -0
- package/dist/agent-src/skills/dpa-review/SKILL.md +130 -0
- package/dist/agent-src/skills/dpa-review/evals/triggers.json +17 -0
- package/dist/agent-src/skills/existing-ui-audit/SKILL.md +15 -4
- package/dist/agent-src/skills/fe-design/SKILL.md +98 -16
- package/dist/agent-src/skills/flux/SKILL.md +8 -0
- package/dist/agent-src/skills/iconography/SKILL.md +1 -0
- package/dist/agent-src/skills/laravel/SKILL.md +1 -0
- package/dist/agent-src/skills/legal-intake-triage/SKILL.md +128 -0
- package/dist/agent-src/skills/legal-intake-triage/evals/triggers.json +17 -0
- package/dist/agent-src/skills/legal-practice-profile/SKILL.md +101 -0
- package/dist/agent-src/skills/legal-practice-profile/evals/triggers.json +17 -0
- package/dist/agent-src/skills/livewire/SKILL.md +8 -0
- package/dist/agent-src/skills/nda-triage/SKILL.md +114 -0
- package/dist/agent-src/skills/nda-triage/evals/triggers.json +17 -0
- package/dist/agent-src/skills/react-shadcn-ui/SKILL.md +21 -9
- package/dist/agent-src/skills/reasoning-orchestrator/SKILL.md +3 -1
- package/dist/agent-src/skills/recursive-verification/SKILL.md +186 -0
- package/dist/agent-src/skills/roadmap-management/SKILL.md +17 -0
- package/dist/agent-src/skills/skill-writing/SKILL.md +18 -0
- package/dist/agent-src/skills/subagent-orchestration/SKILL.md +11 -0
- package/dist/agent-src/skills/tailwind-engineer/SKILL.md +17 -7
- package/dist/agent-src/skills/typography-system/SKILL.md +14 -0
- package/dist/agent-src/skills/ui-component-architect/SKILL.md +9 -0
- package/dist/agent-src/templates/agent-settings.md +64 -19
- package/dist/discovery/deprecation-report.md +1 -1
- package/dist/discovery/discovery-manifest.json +362 -43
- package/dist/discovery/discovery-manifest.json.sha256 +1 -1
- package/dist/discovery/discovery-manifest.summary.md +13 -5
- package/dist/discovery/orphan-report.md +1 -1
- package/dist/discovery/packs.json +56 -11
- package/dist/discovery/trust-report.md +7 -5
- package/dist/discovery/workspaces.json +38 -7
- package/dist/mcp/registry-manifest.json +3 -3
- package/dist/router.json +1 -1
- package/dist/server/routes/wizard.js +4 -3
- package/dist/server/routes/wizard.js.map +1 -1
- package/dist/server/schemas/settings.js +23 -0
- package/dist/server/schemas/settings.js.map +1 -1
- package/dist/ui/assets/{index-CoQo90sz.js → index-UjcTG_9O.js} +2 -2
- package/dist/ui/assets/index-UjcTG_9O.js.map +1 -0
- package/dist/ui/index.html +1 -1
- package/docs/RELEASE_STORY_TEMPLATE.md +37 -0
- package/docs/architecture.md +4 -4
- package/docs/benchmark.md +46 -0
- package/docs/catalog.md +18 -6
- package/docs/command-flows.md +7 -1
- package/docs/contracts/ai-council-config.md +17 -10
- package/docs/contracts/audit-log-v1.md +7 -0
- package/docs/contracts/auto-orchestration-v1.md +70 -0
- package/docs/contracts/capability-boundary.md +64 -0
- package/docs/contracts/command-clusters.md +1 -1
- package/docs/contracts/discovery-manifest.schema.json +2 -2
- package/docs/contracts/package-self-orientation.md +3 -0
- package/docs/contracts/subagent-boundary.md +54 -0
- package/docs/decisions/ADR-013-discovery-frontmatter-contract.md +32 -0
- package/docs/decisions/ADR-020-global-only-consumer-scope.md +13 -6
- package/docs/decisions/ADR-049-configuration-trust-boundary.md +11 -1
- package/docs/decisions/ADR-093-ai-council-config-user-global.md +10 -4
- package/docs/decisions/ADR-104-ai-council-config-global-only.md +119 -0
- package/docs/decisions/ADR-105-automatic-subagent-orchestration.md +102 -0
- package/docs/decisions/ADR-106-recursive-verification-benchmark-gate.md +126 -0
- package/docs/decisions/ADR-107-legal-domain-pack-adoption.md +70 -0
- package/docs/decisions/ADR-108-open-source-forever-no-commercial-tier.md +46 -0
- package/docs/decisions/INDEX.md +5 -0
- package/docs/getting-started.md +2 -2
- package/docs/guidelines/agent-infra/domain-eval-anti-pattern.md +53 -0
- package/docs/guidelines/agent-infra/domain-pack-architecture.md +56 -0
- package/docs/guidelines/design-antipatterns-triggers.json +17 -0
- package/docs/guidelines/design-antipatterns.md +170 -0
- package/docs/guidelines/design-modes.md +97 -0
- package/package.json +1 -1
- package/src/config/agent-settings.template.yml +103 -3
- package/src/config/discovery/packs.yml +24 -0
- package/src/config/discovery/workspaces.yml +7 -0
- package/src/scripts/_lib/auto_dispatch.ts +95 -0
- package/src/scripts/_lib/host_capability.ts +59 -0
- package/src/scripts/_lib/orchestration_gate.ts +98 -0
- package/src/scripts/_lib/subagent_bundle.ts +154 -0
- package/src/scripts/_lib/subagent_response.ts +82 -0
- package/src/scripts/_lib/subagent_routing.ts +81 -0
- package/src/scripts/_lib/subagent_spawn.ts +97 -0
- package/src/scripts/_lib/subagent_steering.ts +64 -0
- package/src/scripts/_lib/verify_budget.ts +54 -0
- package/src/scripts/ai_council/advisors.ts +4 -2
- package/src/scripts/ai_council/clients.ts +7 -1
- package/src/scripts/ai_council/config.ts +22 -17
- package/src/scripts/bench_ab_v2_run.ts +127 -0
- package/src/scripts/bench_ab_v2_stats.ts +39 -0
- package/src/scripts/check_council_config_location.ts +6 -5
- package/src/scripts/check_trunk_drift.ts +67 -0
- package/src/scripts/lint_design_quality.ts +321 -0
- package/src/scripts/lint_discovery_vocabulary.ts +6 -0
- package/src/scripts/lint_framework_leakage_allowlist.json +21 -0
- package/src/scripts/lint_legal_pack.ts +197 -0
- package/src/scripts/lint_output_slop.ts +223 -0
- package/src/scripts/lint_pack_risk_class.ts +79 -0
- package/src/scripts/probe_projection_fidelity.ts +7 -1
- package/src/scripts/schemas/agent-settings.schema.json +23 -0
- package/src/scripts/schemas/skill.schema.json +5 -0
- package/src/scripts/skill_linter.ts +3 -0
- package/dist/ui/assets/index-CoQo90sz.js.map +0 -1
|
@@ -36,6 +36,12 @@ A **live preview URL** is required for testing.
|
|
|
36
36
|
|
|
37
37
|
## Procedure: Design review
|
|
38
38
|
|
|
39
|
+
1. **Inspect the PR and preview** — Read the PR description, diff, and identify changed components/pages; capture a baseline screenshot of the preview URL.
|
|
40
|
+
2. **Walk the interactions** — Run Phase 1; cover hover/focus/active/disabled, keyboard, loading, and form error states.
|
|
41
|
+
3. **Cover responsiveness, polish, a11y, robustness** — Run Phases 2–5 in order; record findings per phase.
|
|
42
|
+
4. **Audit code-health and content** — Run Phases 6–7; check tokens, dead styles, copy, console warnings.
|
|
43
|
+
5. **Verify and report** — Consolidate findings in the report structure; classify each as Blocker / High / Medium / Nit before posting.
|
|
44
|
+
|
|
39
45
|
### Phase 0: Preparation
|
|
40
46
|
|
|
41
47
|
- Read PR description and git diff.
|
|
@@ -110,6 +116,61 @@ Test at three viewports:
|
|
|
110
116
|
- No placeholder text left in production.
|
|
111
117
|
- Check browser console for JavaScript errors or warnings.
|
|
112
118
|
|
|
119
|
+
## Reviewer posture
|
|
120
|
+
|
|
121
|
+
**Approval is earned, not assumed. Default to flagging.**
|
|
122
|
+
|
|
123
|
+
A design review is a skeptic's pass. The default verdict for every element
|
|
124
|
+
is "this needs to justify itself" — not "this is probably fine." Approve
|
|
125
|
+
explicitly when you have examined the evidence and found it sound.
|
|
126
|
+
|
|
127
|
+
This posture prevents the failure of "nothing to report" reviews that miss
|
|
128
|
+
real issues because the reviewer defaulted to charitable assumptions.
|
|
129
|
+
|
|
130
|
+
## Subtraction-first remedial hierarchy
|
|
131
|
+
|
|
132
|
+
When a finding warrants a remediation recommendation, prefer in this order:
|
|
133
|
+
|
|
134
|
+
1. **Delete** — remove the element, animation, pattern, or copy entirely
|
|
135
|
+
2. **Reduce** — make it smaller, shorter, subtler, less frequent
|
|
136
|
+
3. **Fix the specific issue** — change easing, origin, duration, contrast, font
|
|
137
|
+
4. **Make it interruptible** (for motion) — switch to transition/spring
|
|
138
|
+
5. **Move to GPU** (for motion) — animate only transform/opacity
|
|
139
|
+
6. **Polish** — the lowest-leverage fix; only if the above don't apply
|
|
140
|
+
|
|
141
|
+
*"Delete the animation" is always the first option to consider, even before
|
|
142
|
+
suggesting a different easing curve.* The same applies to decorative elements,
|
|
143
|
+
excessive copy, and redundant UI chrome.
|
|
144
|
+
|
|
145
|
+
## Before / After / Why output format
|
|
146
|
+
|
|
147
|
+
When reporting a finding with a specific remediation, use this table format:
|
|
148
|
+
|
|
149
|
+
| Field | Content |
|
|
150
|
+
|---|---|
|
|
151
|
+
| **Before** | The current state (quote the code, value, or describe the pattern) |
|
|
152
|
+
| **After** | The corrected state (specific value or alternative) |
|
|
153
|
+
| **Why** | The mechanism: why is Before wrong and After better? (one sentence, states the principle) |
|
|
154
|
+
|
|
155
|
+
**Wrong format** (do not use):
|
|
156
|
+
```
|
|
157
|
+
Before:
|
|
158
|
+
button { transition: all 0.3s ease; }
|
|
159
|
+
After:
|
|
160
|
+
button { transition: transform 0.2s ease-out, opacity 0.2s ease-out; }
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
**Right format:**
|
|
164
|
+
|
|
165
|
+
| | |
|
|
166
|
+
|---|---|
|
|
167
|
+
| **Before** | `transition: all 0.3s ease` |
|
|
168
|
+
| **After** | `transition: transform 0.2s ease-out, opacity 0.2s ease-out` |
|
|
169
|
+
| **Why** | `transition: all` animates layout properties on every state change, causing browser reflow; enumerate only the properties that move. |
|
|
170
|
+
|
|
171
|
+
The Why column carries the reasoning — it's the part that teaches the developer
|
|
172
|
+
and prevents the same finding from recurring.
|
|
173
|
+
|
|
113
174
|
## Communication principles
|
|
114
175
|
|
|
115
176
|
### Problems over prescriptions
|
|
@@ -224,6 +285,28 @@ This is especially useful when the user provides a screenshot or Figma export as
|
|
|
224
285
|
- The model tends to suggest accessibility improvements that break the existing design system.
|
|
225
286
|
- "Best practice" is not always the right choice — sometimes "good enough" ships faster.
|
|
226
287
|
|
|
288
|
+
## Anti-slop scan
|
|
289
|
+
|
|
290
|
+
During any design review, load
|
|
291
|
+
[`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md)
|
|
292
|
+
as a reference. After the structured review phases, add an explicit
|
|
293
|
+
**Anti-Slop Check** section to the review output:
|
|
294
|
+
|
|
295
|
+
1. List any patterns from the catalog that appear in the reviewed UI (cite by
|
|
296
|
+
entry ID, e.g. V1, T2, C1).
|
|
297
|
+
2. For each finding: note whether an override condition is in effect (if yes,
|
|
298
|
+
verify it is stated in the design brief; if not, flag as a finding).
|
|
299
|
+
3. Run the AI-slop originality self-test on the overall aesthetic direction.
|
|
300
|
+
Report the result (pass / flag / fail) with one sentence of evidence.
|
|
301
|
+
|
|
302
|
+
For the **objective quality floors** (WCAG contrast, font-size, line-length,
|
|
303
|
+
reduced-motion, heading hierarchy, focus indicator), do NOT eyeball them —
|
|
304
|
+
cite [`lint_design_quality`](../../../src/scripts/lint_design_quality.ts)
|
|
305
|
+
output for the consumer project (Q1–Q6 in the catalog). The review owns the
|
|
306
|
+
*subjective* anti-slop judgment (Visual / Typography / Color / Layout taste);
|
|
307
|
+
the linter owns the *objective* floors; `accessibility-auditor` owns the WCAG
|
|
308
|
+
*audit method*. Cite, don't re-derive.
|
|
309
|
+
|
|
227
310
|
## Do NOT
|
|
228
311
|
|
|
229
312
|
- Do NOT skip accessibility testing — it's not optional.
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
---
|
|
2
|
+
model_tier: inherit
|
|
3
|
+
name: design-system-capture
|
|
4
|
+
description: "Write and maintain DESIGN.md + PRODUCT.md — captures visual decisions and interaction patterns so design tasks stay consistent across sessions without re-scanning past work."
|
|
5
|
+
domain: engineering
|
|
6
|
+
personas:
|
|
7
|
+
- frontend-engineer
|
|
8
|
+
workspaces:
|
|
9
|
+
- engineering
|
|
10
|
+
packs:
|
|
11
|
+
- frontend-design
|
|
12
|
+
token_budget_class: rich
|
|
13
|
+
execution:
|
|
14
|
+
type: manual
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
# design-system-capture
|
|
18
|
+
|
|
19
|
+
> Solves "design amnesia" — the failure mode where every AI design task
|
|
20
|
+
> re-invents visual patterns (radius, shadows, motion, spacing) and
|
|
21
|
+
> interaction patterns (destructive-action handling, optimistic UI, filter
|
|
22
|
+
> persistence) because the agent has no cross-task memory of decisions
|
|
23
|
+
> already made.
|
|
24
|
+
>
|
|
25
|
+
> **Boundary:** `brand-to-tokens` extracts *primitives* (colors, font
|
|
26
|
+
> families → DTCG tokens). `existing-ui-audit` inventories *what exists*.
|
|
27
|
+
> **This skill captures *usage decisions*:** "we use 8px radius for
|
|
28
|
+
> elevated surfaces", "all destructive actions require typed confirmation".
|
|
29
|
+
> They are complementary, not redundant.
|
|
30
|
+
>
|
|
31
|
+
> Gated by `tokens.rich_skills` in `.agent-settings.yml` (default `on`).
|
|
32
|
+
> If `off`, skip rich context loading and work from brief alone.
|
|
33
|
+
|
|
34
|
+
## Why this skill is rich
|
|
35
|
+
|
|
36
|
+
DESIGN.md and PRODUCT.md serve as the project's design memory. To write
|
|
37
|
+
useful capture documents and to read/apply them effectively, the agent
|
|
38
|
+
needs full templates with worked examples showing what a well-structured
|
|
39
|
+
DESIGN.md and PRODUCT.md look like in practice. A condensed version that
|
|
40
|
+
says "write down your design decisions" produces documents too vague to
|
|
41
|
+
be useful. The worked examples teach agents both the *vocabulary*
|
|
42
|
+
(elevation, motion strategy, destructive-action policy) and the
|
|
43
|
+
*specificity level* that makes these documents actionable across tasks.
|
|
44
|
+
|
|
45
|
+
## When to use
|
|
46
|
+
|
|
47
|
+
- Starting a new consumer project (initial capture, run once early)
|
|
48
|
+
- After 2+ design tasks in the same project (update to capture what was decided)
|
|
49
|
+
- When a subsequent design task produces inconsistent results (audit and reconcile)
|
|
50
|
+
- Explicitly asked: "capture the design system", "write a DESIGN.md", "document our patterns"
|
|
51
|
+
|
|
52
|
+
## The two documents
|
|
53
|
+
|
|
54
|
+
### `DESIGN.md` — visual-system decisions
|
|
55
|
+
|
|
56
|
+
Captures the *visual usage decisions* (not token primitives) that agents
|
|
57
|
+
should apply consistently across all UI tasks in this project. Unlike
|
|
58
|
+
`.tokens.json` (which records what a color value IS), DESIGN.md records
|
|
59
|
+
*how and when to use it*.
|
|
60
|
+
|
|
61
|
+
**Format:**
|
|
62
|
+
|
|
63
|
+
```markdown
|
|
64
|
+
# DESIGN.md — [Project name] visual system
|
|
65
|
+
|
|
66
|
+
> AI-readable project design memory. Update after each design decision.
|
|
67
|
+
> Last updated: [date]
|
|
68
|
+
|
|
69
|
+
## Design philosophy
|
|
70
|
+
One sentence: [density/formality/complexity philosophy]
|
|
71
|
+
Example: "Information-dense dashboard; optimize for power users, not casual exploration."
|
|
72
|
+
|
|
73
|
+
## Visual system
|
|
74
|
+
|
|
75
|
+
### Elevation and radius
|
|
76
|
+
- Elevated surfaces (modals, sheets, dropdowns): [X]px radius, [shadow-spec]
|
|
77
|
+
- Inline elements (cards, chips): [X]px radius
|
|
78
|
+
- Buttons: [X]px radius
|
|
79
|
+
|
|
80
|
+
### Shadows
|
|
81
|
+
- Elevated: [box-shadow value]
|
|
82
|
+
- Floating (tooltips, popovers): [box-shadow value]
|
|
83
|
+
- None (flat cards): [confirm]
|
|
84
|
+
|
|
85
|
+
### Motion
|
|
86
|
+
- Overlays and modals: [spring / easing spec + duration]
|
|
87
|
+
- Micro-interactions (button feedback, toggles): [duration + easing]
|
|
88
|
+
- Page transitions: [strategy or "none"]
|
|
89
|
+
|
|
90
|
+
### Spacing
|
|
91
|
+
- Base unit: [X]px
|
|
92
|
+
- Card padding: [spec]
|
|
93
|
+
- Section gap: [spec]
|
|
94
|
+
- Tight grouping: [spec]
|
|
95
|
+
|
|
96
|
+
### Color usage
|
|
97
|
+
- Primary action: [token name]
|
|
98
|
+
- Destructive: [token name]
|
|
99
|
+
- Surface hierarchy: [primary bg → secondary bg → elevated bg]
|
|
100
|
+
|
|
101
|
+
## Stack and conventions
|
|
102
|
+
- CSS approach: [Tailwind / CSS modules / styled-components / etc.]
|
|
103
|
+
- Component primitives: [shadcn / Radix / Headless UI / custom]
|
|
104
|
+
- Icon system: [Phosphor / Heroicons / Lucide / etc.]
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### `PRODUCT.md` — cross-feature interaction patterns
|
|
108
|
+
|
|
109
|
+
Captures *interaction decisions* that should be consistent across features.
|
|
110
|
+
Unlike a feature spec (which describes one feature), PRODUCT.md captures
|
|
111
|
+
patterns that apply everywhere.
|
|
112
|
+
|
|
113
|
+
**Format:**
|
|
114
|
+
|
|
115
|
+
```markdown
|
|
116
|
+
# PRODUCT.md — [Project name] interaction patterns
|
|
117
|
+
|
|
118
|
+
> AI-readable cross-feature pattern memory. Update when a new pattern is established.
|
|
119
|
+
> Last updated: [date]
|
|
120
|
+
|
|
121
|
+
## Destructive actions
|
|
122
|
+
Policy: [typed confirmation ("DELETE") / dialog with verb button / undo toast / etc.]
|
|
123
|
+
Example: "All destructive actions require the user to type 'DELETE' or the resource name."
|
|
124
|
+
|
|
125
|
+
## Mutation feedback
|
|
126
|
+
Policy: [optimistic UI + inline undo / loading spinner / success toast / etc.]
|
|
127
|
+
Undo window: [N seconds, or "not applicable"]
|
|
128
|
+
Example: "Optimistic UI for all mutations; inline undo toast for 5 seconds, then commit."
|
|
129
|
+
|
|
130
|
+
## Filter and sort persistence
|
|
131
|
+
Policy: [URL params / localStorage / session / not persisted]
|
|
132
|
+
Restore on load: [yes / no]
|
|
133
|
+
|
|
134
|
+
## Empty states
|
|
135
|
+
Approach: [illustration + CTA / text only / skeleton / etc.]
|
|
136
|
+
Example: "Illustration + primary CTA for empty lists; text-only for zero-search-results."
|
|
137
|
+
|
|
138
|
+
## Error handling
|
|
139
|
+
Approach: [inline field errors / toast / error boundary / etc.]
|
|
140
|
+
Network errors: [retry + message / fail fast / etc.]
|
|
141
|
+
|
|
142
|
+
## Navigation and routing
|
|
143
|
+
Pattern: [SPA / MPA / hybrid / etc.]
|
|
144
|
+
Active state: [how active nav items are marked]
|
|
145
|
+
|
|
146
|
+
## Mental model
|
|
147
|
+
One sentence: [how the product conceptualizes itself to the user]
|
|
148
|
+
Example: "Dashboard = control panel for power users, not an exploration space."
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Procedure
|
|
152
|
+
|
|
153
|
+
### Step 1 — Assess what exists
|
|
154
|
+
|
|
155
|
+
1. Check if `DESIGN.md` and `PRODUCT.md` already exist in the project root.
|
|
156
|
+
2. If they exist: read both → skip to Step 3 (Update).
|
|
157
|
+
3. If they don't exist: run `existing-ui-audit` (if not already done for this session) to inventory existing components, tokens, and conventions → proceed to Step 2.
|
|
158
|
+
|
|
159
|
+
### Step 2 — Create (first run)
|
|
160
|
+
|
|
161
|
+
1. **Extract visual decisions from the audit** (`state.ui_audit`): dominant
|
|
162
|
+
radius values, shadow patterns, spacing conventions, motion patterns.
|
|
163
|
+
Fill the DESIGN.md template above with the observed values. Mark
|
|
164
|
+
un-observed sections as `TBD`.
|
|
165
|
+
2. **Extract interaction decisions from the codebase**: scan for delete
|
|
166
|
+
confirmation patterns, toast/feedback patterns, filter/URL persistence.
|
|
167
|
+
Fill the PRODUCT.md template. Mark un-observed sections as `TBD`.
|
|
168
|
+
3. Write `DESIGN.md` and `PRODUCT.md` to the project root.
|
|
169
|
+
4. Surface a one-paragraph summary: what was captured, what is still TBD,
|
|
170
|
+
and what action the user should take (review and correct the TBDs).
|
|
171
|
+
|
|
172
|
+
### Step 3 — Update (subsequent runs)
|
|
173
|
+
|
|
174
|
+
1. Read existing `DESIGN.md` and `PRODUCT.md`.
|
|
175
|
+
2. Identify any decisions made in recent tasks that aren't yet captured
|
|
176
|
+
(e.g., a modal was built with 12px radius — add that to DESIGN.md).
|
|
177
|
+
3. Correct any TBDs that are now resolved.
|
|
178
|
+
4. Update the "Last updated" date.
|
|
179
|
+
5. Output a diff summary: what changed and why.
|
|
180
|
+
|
|
181
|
+
## How the design skills consume these documents
|
|
182
|
+
|
|
183
|
+
When `DESIGN.md` or `PRODUCT.md` is present in the project root:
|
|
184
|
+
|
|
185
|
+
- **`design-intelligence`** and **`fe-design`**: read DESIGN.md at the
|
|
186
|
+
start of any design task — use the captured decisions as project
|
|
187
|
+
constraints that override corpus suggestions.
|
|
188
|
+
- **`ui-component-architect`**: read DESIGN.md for radius/shadow/motion
|
|
189
|
+
conventions before proposing any new component.
|
|
190
|
+
- **`existing-ui-audit`**: when a full audit is impractical (large project),
|
|
191
|
+
read DESIGN.md as a proxy for "what this project's conventions are".
|
|
192
|
+
|
|
193
|
+
The boundary from `brand-to-tokens`:
|
|
194
|
+
- `.tokens.json` carries primitive values (gray-700 = #374151)
|
|
195
|
+
- DESIGN.md carries usage decisions (elevated surfaces use 8px radius,
|
|
196
|
+
not 4px or 12px)
|
|
197
|
+
Both are consumed together; DESIGN.md takes precedence for usage questions.
|
|
198
|
+
|
|
199
|
+
## Gotcha
|
|
200
|
+
|
|
201
|
+
- **Over-writing instead of diff-updating** — the most common failure.
|
|
202
|
+
Always read existing `DESIGN.md`/`PRODUCT.md` before writing; carry
|
|
203
|
+
all existing decisions forward and only add/correct. Losing prior
|
|
204
|
+
captured history is worse than capturing nothing.
|
|
205
|
+
- **Copying tokens into DESIGN.md** — DESIGN.md is NOT a copy of
|
|
206
|
+
`.tokens.json`. It captures *usage decisions* ("8px radius on elevated
|
|
207
|
+
surfaces"), not primitive values ("gray-700 = #374151"). The
|
|
208
|
+
distinction is what makes DESIGN.md actionable.
|
|
209
|
+
- **Capturing feature-specific behavior** — PRODUCT.md is for patterns
|
|
210
|
+
that repeat across 2+ features. A delete-confirmation pattern in one
|
|
211
|
+
form does NOT belong in PRODUCT.md until it appears in at least two
|
|
212
|
+
independent features.
|
|
213
|
+
|
|
214
|
+
## Do NOT
|
|
215
|
+
|
|
216
|
+
- Do NOT overwrite DESIGN.md/PRODUCT.md without first reading and diffing
|
|
217
|
+
the existing content — accumulated history is the value.
|
|
218
|
+
- Do NOT make DESIGN.md a copy of `.tokens.json` — it captures decisions,
|
|
219
|
+
not token definitions.
|
|
220
|
+
- Do NOT capture feature-specific behavior in PRODUCT.md — only patterns
|
|
221
|
+
that repeat across multiple features.
|
|
222
|
+
- Do NOT mark a decision as captured without evidence from the actual codebase.
|
|
223
|
+
|
|
224
|
+
## Output format
|
|
225
|
+
|
|
226
|
+
On create:
|
|
227
|
+
1. Write `DESIGN.md` to the project root with the extracted visual decisions.
|
|
228
|
+
2. Write `PRODUCT.md` to the project root with the extracted interaction patterns.
|
|
229
|
+
3. Surface a one-paragraph summary of what was captured and what is TBD.
|
|
230
|
+
4. List any questions where the existing code is ambiguous.
|
|
231
|
+
|
|
232
|
+
On update:
|
|
233
|
+
1. Update both files with new decisions.
|
|
234
|
+
2. Output a short diff: "Added: destructive-action policy. Updated: motion strategy (was TBD, now spring)."
|
|
@@ -132,4 +132,5 @@ four-operation split assigns to *rules/linters*, not the corpus).
|
|
|
132
132
|
- [`design-intelligence`](../design-intelligence/SKILL.md) — grounded value selection.
|
|
133
133
|
- [`tailwind-engineer`](../tailwind-engineer/SKILL.md) — utility-discipline consumer.
|
|
134
134
|
- [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) — shadcn token conventions.
|
|
135
|
+
- [`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md) — when authoring the colour layer, avoid the C5 cream/sand default palette (OKLCH L 0.84–0.97, C < 0.06) and C1 purple/violet primaries unless the brand explicitly defines them; the `brand-consistency` rule validates emitted tokens against the active brand profile.
|
|
135
136
|
- Tests: `tests/test_design_tokens_toolchain.py`.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
---
|
|
2
|
+
model_tier: inherit
|
|
3
|
+
name: dpa-review
|
|
4
|
+
description: "Use when reviewing a DPA as controller or processor against GDPR Art. 28 — GREEN/YELLOW/RED gap frame, never a final call. Triggers on \"review this DPA\", \"check this DPA\"."
|
|
5
|
+
status: active
|
|
6
|
+
tier: senior
|
|
7
|
+
council_depth: deep
|
|
8
|
+
domain: process
|
|
9
|
+
recommended_for_user_types: [legal]
|
|
10
|
+
workspaces:
|
|
11
|
+
- legal-review-prep
|
|
12
|
+
packs:
|
|
13
|
+
- legal-review-prep
|
|
14
|
+
trust:
|
|
15
|
+
level: advisory
|
|
16
|
+
install:
|
|
17
|
+
removable: true
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
# dpa-review
|
|
21
|
+
|
|
22
|
+
## When to use
|
|
23
|
+
|
|
24
|
+
- A counterparty sends a DPA (their paper or yours) and the question is *where the GDPR Art. 28 obligations are met, partial, or missing* — before an attorney spends time on it.
|
|
25
|
+
- An existing processing relationship is being re-papered (new sub-processor chain, new transfer route, new scope) and the Art. 28 surface must be re-walked.
|
|
26
|
+
- You need a structured gap frame and the open questions an attorney must resolve — not a redline and not a verdict.
|
|
27
|
+
|
|
28
|
+
Do NOT use for clause-level redlining of a general contract (route to `contract-review`), for the regulatory-regime delta read in isolation (route to [`privacy-review`](../privacy-review/SKILL.md)), or for the classification / retention / transfer-mechanism operational surface (route to [`data-handling-judgment`](../data-handling-judgment/SKILL.md)). This skill walks the Art. 28 *agreement*; those skills produce the inputs it cites.
|
|
29
|
+
|
|
30
|
+
## Procedure
|
|
31
|
+
|
|
32
|
+
### Step 0: Establish jurisdiction and refuse if out of scope
|
|
33
|
+
|
|
34
|
+
1. Read the DPA's governing-law / jurisdiction clause. Tag the output `Jurisdiction: EU` or `Jurisdiction: DE`.
|
|
35
|
+
2. If the DPA is governed by a non-EU/DE regime with no GDPR nexus (e.g. a pure US state-privacy regime), **refuse the gap review**: say "consult licensed local counsel". Note as an open question that GDPR may still apply extraterritorially under Art. 3 (EU-established controller/processor, or offering to / monitoring EU data subjects) — for the attorney to confirm.
|
|
36
|
+
3. No default positions ship. Read acceptable values (sub-processor notice window, audit frequency, liability cap, breach-notice deadline) from `legal-practice-profile`. Until configured, every such value is a `[configure]` placeholder in the output, not a guess.
|
|
37
|
+
|
|
38
|
+
### Step 1: Fix the role — controller or processor
|
|
39
|
+
|
|
40
|
+
The Art. 28 reading forks on which side you are.
|
|
41
|
+
|
|
42
|
+
- **You are the controller** → you instruct. Read whether the agreement binds the *processor* to your instructions, confidentiality, security, sub-processor flow-down, assistance, deletion, and audit *rights for you*.
|
|
43
|
+
- **You are the processor** → you are bound. Read whether the obligations imposed are deliverable as written (audit cadence you can sustain, deletion you can actually perform, sub-processor flow-down you can pass down).
|
|
44
|
+
- **Joint / unclear** → flag it as the first open question; Art. 26 joint-controllership changes the frame.
|
|
45
|
+
|
|
46
|
+
### Step 2: Walk the Art. 28(3) requirements as a checklist FLOOR (not ceiling)
|
|
47
|
+
|
|
48
|
+
For each, assign GREEN (present + adequate) / YELLOW (present but weak/ambiguous) / RED (missing or contradicts Art. 28):
|
|
49
|
+
|
|
50
|
+
1. **(a) Documented instructions** — processing only on the controller's documented instructions, incl. for transfers.
|
|
51
|
+
2. **(b) Confidentiality** — persons authorised to process are under a confidentiality commitment.
|
|
52
|
+
3. **(c) Security — Art. 32** — appropriate technical and organisational measures named (not "industry-standard" alone).
|
|
53
|
+
4. **(d) Sub-processors** — prior authorisation (general or specific), notice of changes + objection right, and **flow-down** of equivalent Art. 28 terms.
|
|
54
|
+
5. **(e) Data-subject-rights assistance** — processor assists the controller in responding to DSR requests.
|
|
55
|
+
6. **(f) Breach + DPIA assistance — Art. 33/34/35/36** — breach-notification assistance with a deadline, plus assistance with DPIAs and prior consultation.
|
|
56
|
+
7. **(g) Deletion / return** — at end of provision, delete or return all personal data + copies, at the controller's choice.
|
|
57
|
+
8. **(h) Audit / inspection** — make available the information needed to demonstrate compliance + allow and contribute to audits/inspections.
|
|
58
|
+
9. **International transfer — Chapter V** — any transfer outside the EEA has a valid mechanism (adequacy / SCCs with module + version / BCR) and, where required, supplementary measures. Schrems-II transfer-impact assessment is an open question, not a checkbox.
|
|
59
|
+
|
|
60
|
+
The nine are the floor; flag anything beyond them that materially shifts risk (liability cap, indemnity, deletion-vs-legal-hold conflict).
|
|
61
|
+
|
|
62
|
+
### Step 3: Frame the gaps and the open questions
|
|
63
|
+
|
|
64
|
+
1. Produce the GREEN/YELLOW/RED frame, one line per Art. 28(3) item + transfers.
|
|
65
|
+
2. For every YELLOW/RED, write the **open question an attorney must resolve** — not a redline. ("(d) names no objection window — is `[configure]` acceptable, or must a specific window be negotiated?")
|
|
66
|
+
3. Surface any `[configure]` placeholder that blocked a GREEN/YELLOW/RED call.
|
|
67
|
+
|
|
68
|
+
### Step 4: Emit the artifacts
|
|
69
|
+
|
|
70
|
+
Produce `dpa-gap-frame.md` and `open-questions.md`. Each carries the `Jurisdiction:` tag and the attorney-review line. This skill does not opine; it prepares the attorney's review.
|
|
71
|
+
|
|
72
|
+
## Related Skills
|
|
73
|
+
|
|
74
|
+
**WHEN to use this**
|
|
75
|
+
|
|
76
|
+
- Reviewing a DPA against the GDPR Art. 28 surface, as controller or processor.
|
|
77
|
+
- Producing a gap frame + attorney open-questions before counsel review.
|
|
78
|
+
|
|
79
|
+
**WHEN NOT to use this**
|
|
80
|
+
|
|
81
|
+
- General contract clause redlines (liability, IP, term, termination) — route to `contract-review`.
|
|
82
|
+
- Which regime applies / regime delta read — route to [`privacy-review`](../privacy-review/SKILL.md).
|
|
83
|
+
- Data classification, retention windows, transfer-mechanism + supplementary-measures operational shape — route to [`data-handling-judgment`](../data-handling-judgment/SKILL.md).
|
|
84
|
+
- A binding legal conclusion — route to a licensed attorney; this skill never issues one.
|
|
85
|
+
|
|
86
|
+
## When the agent should load this
|
|
87
|
+
|
|
88
|
+
- "Kannst Du diese AVV / DPA gegen Art. 28 prüfen?"
|
|
89
|
+
- "Ein Kunde hat seinen Auftragsverarbeitungsvertrag geschickt — wo sind die Lücken?"
|
|
90
|
+
|
|
91
|
+
## Output
|
|
92
|
+
|
|
93
|
+
1. **`dpa-gap-frame.md`** — `Jurisdiction:` tag; role (controller/processor); one GREEN/YELLOW/RED line per Art. 28(3)(a)–(h) + Chapter V transfers; the attorney-review line.
|
|
94
|
+
2. **`open-questions.md`** — `Jurisdiction:` tag; one attorney-resolvable question per YELLOW/RED, plus every `[configure]` placeholder that blocked a call; the attorney-review line.
|
|
95
|
+
|
|
96
|
+
## Gotcha
|
|
97
|
+
|
|
98
|
+
- "Industry-standard security" satisfies neither Art. 28(3)(c) nor Art. 32 — the TOMs must be named; an unnamed measures clause is YELLOW at best, often RED.
|
|
99
|
+
- Sub-processor flow-down is the silent RED: the agreement names sub-processors but never binds them to equivalent Art. 28 terms, so the chain leaks obligations.
|
|
100
|
+
- The role fork is load-bearing — a processor-side review that reads the controller-side rights as if they were yours mis-frames every deliverability gap.
|
|
101
|
+
- "Delete OR return" at the controller's choice is the requirement; a clause that hard-codes deletion (ignoring legal-hold) or hard-codes return is a gap, not a convenience.
|
|
102
|
+
- A non-EU governing-law clause does not end the question — GDPR can still bite under Art. 3; refuse the gap review but hand the Art. 3 question to the attorney, never silently drop it.
|
|
103
|
+
|
|
104
|
+
## Do NOT
|
|
105
|
+
|
|
106
|
+
- Do NOT ship default values for notice windows, audit cadence, liability caps, or breach deadlines; read `legal-practice-profile` or emit `[configure]`.
|
|
107
|
+
- Do NOT issue a final legal call, a clearance, or a "this DPA is fine" — GREEN is a triage signal, not a sign-off. Cite `legal-safety-floor`.
|
|
108
|
+
- Do NOT review a DPA outside EU/DE scope as if it were in scope; refuse to gap-review and route to local counsel.
|
|
109
|
+
- Do NOT drop the `Jurisdiction:` tag or the attorney-review line from any output.
|
|
110
|
+
|
|
111
|
+
## Runnable example
|
|
112
|
+
|
|
113
|
+
Processor-side review of a customer's DPA, governed by German law.
|
|
114
|
+
|
|
115
|
+
- Step 0 — `Jurisdiction: DE`. In scope. `legal-practice-profile` not configured → notice window, audit cadence, breach deadline are `[configure]`.
|
|
116
|
+
- Step 1 — Role = **processor** (we host the customer's SaaS data). Frame reads deliverability, not rights.
|
|
117
|
+
- Step 2 — Art. 28(3) walk:
|
|
118
|
+
- (a) documented instructions — GREEN.
|
|
119
|
+
- (b) confidentiality — GREEN.
|
|
120
|
+
- (c) security / Art. 32 — YELLOW ("appropriate measures per industry standard"; no TOMs annex named).
|
|
121
|
+
- (d) sub-processors — RED (general authorisation granted, but **no flow-down** clause binding our sub-processors to equivalent terms, and objection window left blank = `[configure]`).
|
|
122
|
+
- (e) DSR assistance — GREEN.
|
|
123
|
+
- (f) breach assistance / Art. 33 — YELLOW (assistance promised, deadline blank = `[configure]`; can we meet the controller's own 72h clock?).
|
|
124
|
+
- (g) deletion / return — YELLOW (hard-codes deletion; no return option, no legal-hold carve-out).
|
|
125
|
+
- (h) audit — RED for us as processor (on-site audit "at any time, without notice" — not sustainable; cadence = `[configure]`).
|
|
126
|
+
- Chapter V transfers — RED (our logging sub-processor is US-based; no SCC module/version named; Schrems-II TIA = open question).
|
|
127
|
+
- Step 3 — open questions, e.g.: *"(d) — add a flow-down clause and a `[configure]` objection window?"*; *"(h) — negotiate audit to `[configure]` cadence with notice?"*; *"Chapter V — which SCC module/version covers the US logging sub-processor, and is a TIA required?"*
|
|
128
|
+
- Step 4 — emit `dpa-gap-frame.md` + `open-questions.md`, both tagged `Jurisdiction: DE` and carrying:
|
|
129
|
+
|
|
130
|
+
> ⚠️ Attorney review required on material use. This is a draft for a licensed attorney, not legal advice and not a legal conclusion.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"skill": "dpa-review",
|
|
3
|
+
"last_eval": "2026-06-24",
|
|
4
|
+
"description": "5 should-trigger + 5 should-not-trigger. Should-trigger covers DE+EN phrasings for reviewing a Data Processing Agreement against GDPR Art. 28 (controller or processor). Should-not-trigger covers near-miss neighbours: NDA triage, generic contract review, privacy-regime read (privacy-review), legal triage.",
|
|
5
|
+
"queries": [
|
|
6
|
+
{ "q": "review this DPA as processor against GDPR Art. 28", "trigger": true },
|
|
7
|
+
{ "q": "check this data processing agreement, we're the controller", "trigger": true },
|
|
8
|
+
{ "q": "der Kunde hat seine AVV geschickt — prüf die Art-28-Lücken", "trigger": true },
|
|
9
|
+
{ "q": "gap-frame this processor agreement for sub-processor and audit clauses", "trigger": true },
|
|
10
|
+
{ "q": "erfüllt dieser Auftragsverarbeitungsvertrag Art. 28 DSGVO?", "trigger": true },
|
|
11
|
+
{ "q": "check this NDA — standard or not?", "trigger": false },
|
|
12
|
+
{ "q": "review this vendor MSA clause-by-clause", "trigger": false },
|
|
13
|
+
{ "q": "which privacy regime applies to us, GDPR or CCPA?", "trigger": false },
|
|
14
|
+
{ "q": "is this a legal problem at all?", "trigger": false },
|
|
15
|
+
{ "q": "set up our legal practice profile", "trigger": false }
|
|
16
|
+
]
|
|
17
|
+
}
|
|
@@ -16,10 +16,10 @@ packs:
|
|
|
16
16
|
> **Interplay:** this audit answers *what exists* (components, tokens,
|
|
17
17
|
> primitives → `state.ui_audit`);
|
|
18
18
|
> [`design-intelligence`](../design-intelligence/SKILL.md) answers *what to
|
|
19
|
-
> build* (corpus-grounded style/token/typography/pattern selection
|
|
20
|
-
> Audit runs first
|
|
21
|
-
> let a grounded recommendation introduce a
|
|
22
|
-
> already covers.
|
|
19
|
+
> build* (corpus-grounded style/token/typography/pattern selection for the
|
|
20
|
+
> brief). Audit runs first, and its reuse findings outrank corpus
|
|
21
|
+
> suggestions — never let a grounded recommendation introduce a new
|
|
22
|
+
> component the inventory already covers.
|
|
23
23
|
|
|
24
24
|
## When to use
|
|
25
25
|
|
|
@@ -208,6 +208,17 @@ violations will surface as new findings on every run.
|
|
|
208
208
|
- Greenfield is detected, not assumed — a project with one Blade layout and no components is still greenfield only if tokens AND design system markers AND components are all empty.
|
|
209
209
|
- Re-running the skill on a stale state-file: cache by `(composer.json mtime, package.json mtime)`; if either changed, re-audit and overwrite.
|
|
210
210
|
|
|
211
|
+
## Anti-slop cross-reference
|
|
212
|
+
|
|
213
|
+
When the audit inventory reveals an existing aesthetic direction (dominant color
|
|
214
|
+
scheme, border-radius convention, motion patterns), cross-check the findings
|
|
215
|
+
against
|
|
216
|
+
[`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md).
|
|
217
|
+
If the existing UI already uses a listed anti-pattern, surface it as a design-debt
|
|
218
|
+
finding (separate from the reuse inventory) — flag by entry ID and severity. The
|
|
219
|
+
next design step can then decide whether to continue the existing pattern (for
|
|
220
|
+
consistency) or introduce a corrective direction change.
|
|
221
|
+
|
|
211
222
|
## Do NOT
|
|
212
223
|
|
|
213
224
|
- Do NOT advance to `directives/ui/design.py` or `apply.py` if `state.ui_audit` is empty.
|