@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.
Files changed (140) hide show
  1. package/.claude-plugin/marketplace.json +9 -1
  2. package/CHANGELOG.md +117 -0
  3. package/README.md +4 -2
  4. package/dist/agent-src/commands/council/default.md +28 -20
  5. package/dist/agent-src/commands/evals/fix.json +5 -1
  6. package/dist/agent-src/commands/fix/comments.md +101 -0
  7. package/dist/agent-src/commands/fix.md +5 -2
  8. package/dist/agent-src/contexts/execution/auto-dispatch-classification.md +65 -0
  9. package/dist/agent-src/contexts/execution/auto-orchestration-activation.md +68 -0
  10. package/dist/agent-src/contexts/execution/host-capability-manifest.md +68 -0
  11. package/dist/agent-src/contexts/execution/orchestration-benchmark-gate.md +62 -0
  12. package/dist/agent-src/contexts/execution/orchestration-telemetry.md +59 -0
  13. package/dist/agent-src/contexts/execution/roadmap-process-loop.md +8 -3
  14. package/dist/agent-src/contexts/execution/subagent-response-contract.md +56 -0
  15. package/dist/agent-src/contexts/execution/subagent-routing.md +57 -0
  16. package/dist/agent-src/contexts/execution/subagent-spawn-contract.md +54 -0
  17. package/dist/agent-src/contexts/execution/subagent-steering.md +71 -0
  18. package/dist/agent-src/contexts/execution/verify-budget.md +50 -0
  19. package/dist/agent-src/rules/brand-source-of-truth.md +10 -0
  20. package/dist/agent-src/rules/delegation-policy.md +85 -0
  21. package/dist/agent-src/rules/design-fidelity.md +98 -0
  22. package/dist/agent-src/rules/domain-safety-pii.md +22 -0
  23. package/dist/agent-src/rules/legal-safety-floor.md +182 -0
  24. package/dist/agent-src/rules/lethal-trifecta-guard.md +25 -22
  25. package/dist/agent-src/rules/output-discipline.md +85 -0
  26. package/dist/agent-src/rules/telegraph-speak.md +4 -1
  27. package/dist/agent-src/rules/token-budget-discipline.md +94 -0
  28. package/dist/agent-src/scripts/archive_completed_roadmaps.ts +102 -15
  29. package/dist/agent-src/scripts/update_roadmap_progress.ts +30 -3
  30. package/dist/agent-src/skills/accessibility-auditor/SKILL.md +20 -5
  31. package/dist/agent-src/skills/ai-council/SKILL.md +28 -1
  32. package/dist/agent-src/skills/blade-ui/SKILL.md +9 -0
  33. package/dist/agent-src/skills/contract-review/SKILL.md +125 -0
  34. package/dist/agent-src/skills/contract-review/evals/triggers.json +17 -0
  35. package/dist/agent-src/skills/dashboard-design/SKILL.md +21 -5
  36. package/dist/agent-src/skills/design-intelligence/SKILL.md +96 -0
  37. package/dist/agent-src/skills/design-review/SKILL.md +83 -0
  38. package/dist/agent-src/skills/design-system-capture/SKILL.md +234 -0
  39. package/dist/agent-src/skills/design-tokens/SKILL.md +1 -0
  40. package/dist/agent-src/skills/dpa-review/SKILL.md +130 -0
  41. package/dist/agent-src/skills/dpa-review/evals/triggers.json +17 -0
  42. package/dist/agent-src/skills/existing-ui-audit/SKILL.md +15 -4
  43. package/dist/agent-src/skills/fe-design/SKILL.md +98 -16
  44. package/dist/agent-src/skills/flux/SKILL.md +8 -0
  45. package/dist/agent-src/skills/iconography/SKILL.md +1 -0
  46. package/dist/agent-src/skills/laravel/SKILL.md +1 -0
  47. package/dist/agent-src/skills/legal-intake-triage/SKILL.md +128 -0
  48. package/dist/agent-src/skills/legal-intake-triage/evals/triggers.json +17 -0
  49. package/dist/agent-src/skills/legal-practice-profile/SKILL.md +101 -0
  50. package/dist/agent-src/skills/legal-practice-profile/evals/triggers.json +17 -0
  51. package/dist/agent-src/skills/livewire/SKILL.md +8 -0
  52. package/dist/agent-src/skills/nda-triage/SKILL.md +114 -0
  53. package/dist/agent-src/skills/nda-triage/evals/triggers.json +17 -0
  54. package/dist/agent-src/skills/react-shadcn-ui/SKILL.md +21 -9
  55. package/dist/agent-src/skills/reasoning-orchestrator/SKILL.md +3 -1
  56. package/dist/agent-src/skills/recursive-verification/SKILL.md +186 -0
  57. package/dist/agent-src/skills/roadmap-management/SKILL.md +17 -0
  58. package/dist/agent-src/skills/skill-writing/SKILL.md +18 -0
  59. package/dist/agent-src/skills/subagent-orchestration/SKILL.md +11 -0
  60. package/dist/agent-src/skills/tailwind-engineer/SKILL.md +17 -7
  61. package/dist/agent-src/skills/typography-system/SKILL.md +14 -0
  62. package/dist/agent-src/skills/ui-component-architect/SKILL.md +9 -0
  63. package/dist/agent-src/templates/agent-settings.md +64 -19
  64. package/dist/discovery/deprecation-report.md +1 -1
  65. package/dist/discovery/discovery-manifest.json +362 -43
  66. package/dist/discovery/discovery-manifest.json.sha256 +1 -1
  67. package/dist/discovery/discovery-manifest.summary.md +13 -5
  68. package/dist/discovery/orphan-report.md +1 -1
  69. package/dist/discovery/packs.json +56 -11
  70. package/dist/discovery/trust-report.md +7 -5
  71. package/dist/discovery/workspaces.json +38 -7
  72. package/dist/mcp/registry-manifest.json +3 -3
  73. package/dist/router.json +1 -1
  74. package/dist/server/routes/wizard.js +4 -3
  75. package/dist/server/routes/wizard.js.map +1 -1
  76. package/dist/server/schemas/settings.js +23 -0
  77. package/dist/server/schemas/settings.js.map +1 -1
  78. package/dist/ui/assets/{index-CoQo90sz.js → index-UjcTG_9O.js} +2 -2
  79. package/dist/ui/assets/index-UjcTG_9O.js.map +1 -0
  80. package/dist/ui/index.html +1 -1
  81. package/docs/RELEASE_STORY_TEMPLATE.md +37 -0
  82. package/docs/architecture.md +4 -4
  83. package/docs/benchmark.md +46 -0
  84. package/docs/catalog.md +18 -6
  85. package/docs/command-flows.md +7 -1
  86. package/docs/contracts/ai-council-config.md +17 -10
  87. package/docs/contracts/audit-log-v1.md +7 -0
  88. package/docs/contracts/auto-orchestration-v1.md +70 -0
  89. package/docs/contracts/capability-boundary.md +64 -0
  90. package/docs/contracts/command-clusters.md +1 -1
  91. package/docs/contracts/discovery-manifest.schema.json +2 -2
  92. package/docs/contracts/package-self-orientation.md +3 -0
  93. package/docs/contracts/subagent-boundary.md +54 -0
  94. package/docs/decisions/ADR-013-discovery-frontmatter-contract.md +32 -0
  95. package/docs/decisions/ADR-020-global-only-consumer-scope.md +13 -6
  96. package/docs/decisions/ADR-049-configuration-trust-boundary.md +11 -1
  97. package/docs/decisions/ADR-093-ai-council-config-user-global.md +10 -4
  98. package/docs/decisions/ADR-104-ai-council-config-global-only.md +119 -0
  99. package/docs/decisions/ADR-105-automatic-subagent-orchestration.md +102 -0
  100. package/docs/decisions/ADR-106-recursive-verification-benchmark-gate.md +126 -0
  101. package/docs/decisions/ADR-107-legal-domain-pack-adoption.md +70 -0
  102. package/docs/decisions/ADR-108-open-source-forever-no-commercial-tier.md +46 -0
  103. package/docs/decisions/INDEX.md +5 -0
  104. package/docs/getting-started.md +2 -2
  105. package/docs/guidelines/agent-infra/domain-eval-anti-pattern.md +53 -0
  106. package/docs/guidelines/agent-infra/domain-pack-architecture.md +56 -0
  107. package/docs/guidelines/design-antipatterns-triggers.json +17 -0
  108. package/docs/guidelines/design-antipatterns.md +170 -0
  109. package/docs/guidelines/design-modes.md +97 -0
  110. package/package.json +1 -1
  111. package/src/config/agent-settings.template.yml +103 -3
  112. package/src/config/discovery/packs.yml +24 -0
  113. package/src/config/discovery/workspaces.yml +7 -0
  114. package/src/scripts/_lib/auto_dispatch.ts +95 -0
  115. package/src/scripts/_lib/host_capability.ts +59 -0
  116. package/src/scripts/_lib/orchestration_gate.ts +98 -0
  117. package/src/scripts/_lib/subagent_bundle.ts +154 -0
  118. package/src/scripts/_lib/subagent_response.ts +82 -0
  119. package/src/scripts/_lib/subagent_routing.ts +81 -0
  120. package/src/scripts/_lib/subagent_spawn.ts +97 -0
  121. package/src/scripts/_lib/subagent_steering.ts +64 -0
  122. package/src/scripts/_lib/verify_budget.ts +54 -0
  123. package/src/scripts/ai_council/advisors.ts +4 -2
  124. package/src/scripts/ai_council/clients.ts +7 -1
  125. package/src/scripts/ai_council/config.ts +22 -17
  126. package/src/scripts/bench_ab_v2_run.ts +127 -0
  127. package/src/scripts/bench_ab_v2_stats.ts +39 -0
  128. package/src/scripts/check_council_config_location.ts +6 -5
  129. package/src/scripts/check_trunk_drift.ts +67 -0
  130. package/src/scripts/lint_design_quality.ts +321 -0
  131. package/src/scripts/lint_discovery_vocabulary.ts +6 -0
  132. package/src/scripts/lint_framework_leakage_allowlist.json +21 -0
  133. package/src/scripts/lint_legal_pack.ts +197 -0
  134. package/src/scripts/lint_output_slop.ts +223 -0
  135. package/src/scripts/lint_pack_risk_class.ts +79 -0
  136. package/src/scripts/probe_projection_fidelity.ts +7 -1
  137. package/src/scripts/schemas/agent-settings.schema.json +23 -0
  138. package/src/scripts/schemas/skill.schema.json +5 -0
  139. package/src/scripts/skill_linter.ts +3 -0
  140. 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; its reuse findings outrank corpus suggestions — never
21
- > let a grounded recommendation introduce a component the inventory
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.