@harness-engineering/cli 1.6.2 → 1.8.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 (180) hide show
  1. package/dist/agents/personas/documentation-maintainer.yaml +3 -1
  2. package/dist/agents/personas/performance-guardian.yaml +23 -0
  3. package/dist/agents/personas/planner.yaml +27 -0
  4. package/dist/agents/personas/verifier.yaml +30 -0
  5. package/dist/agents/skills/claude-code/align-documentation/SKILL.md +13 -0
  6. package/dist/agents/skills/claude-code/cleanup-dead-code/SKILL.md +25 -1
  7. package/dist/agents/skills/claude-code/cleanup-dead-code/skill.yaml +5 -2
  8. package/dist/agents/skills/claude-code/detect-doc-drift/SKILL.md +12 -0
  9. package/dist/agents/skills/claude-code/enforce-architecture/SKILL.md +67 -1
  10. package/dist/agents/skills/claude-code/enforce-architecture/skill.yaml +5 -2
  11. package/dist/agents/skills/claude-code/harness-accessibility/SKILL.md +281 -0
  12. package/dist/agents/skills/claude-code/harness-accessibility/skill.yaml +51 -0
  13. package/dist/agents/skills/claude-code/harness-autopilot/SKILL.md +119 -72
  14. package/dist/agents/skills/claude-code/harness-autopilot/skill.yaml +4 -2
  15. package/dist/agents/skills/claude-code/harness-brainstorming/SKILL.md +76 -4
  16. package/dist/agents/skills/claude-code/harness-brainstorming/skill.yaml +2 -0
  17. package/dist/agents/skills/claude-code/harness-code-review/SKILL.md +487 -234
  18. package/dist/agents/skills/claude-code/harness-code-review/skill.yaml +15 -2
  19. package/dist/agents/skills/claude-code/harness-codebase-cleanup/SKILL.md +226 -0
  20. package/dist/agents/skills/claude-code/harness-codebase-cleanup/skill.yaml +64 -0
  21. package/dist/agents/skills/claude-code/harness-dependency-health/SKILL.md +35 -6
  22. package/dist/agents/skills/claude-code/harness-dependency-health/skill.yaml +1 -1
  23. package/dist/agents/skills/claude-code/harness-design/SKILL.md +265 -0
  24. package/dist/agents/skills/claude-code/harness-design/skill.yaml +53 -0
  25. package/dist/agents/skills/claude-code/harness-design-mobile/SKILL.md +336 -0
  26. package/dist/agents/skills/claude-code/harness-design-mobile/skill.yaml +49 -0
  27. package/dist/agents/skills/claude-code/harness-design-system/SKILL.md +282 -0
  28. package/dist/agents/skills/claude-code/harness-design-system/skill.yaml +50 -0
  29. package/dist/agents/skills/claude-code/harness-design-web/SKILL.md +360 -0
  30. package/dist/agents/skills/claude-code/harness-design-web/skill.yaml +52 -0
  31. package/dist/agents/skills/claude-code/harness-docs-pipeline/SKILL.md +460 -0
  32. package/dist/agents/skills/claude-code/harness-docs-pipeline/skill.yaml +69 -0
  33. package/dist/agents/skills/claude-code/harness-execution/SKILL.md +73 -8
  34. package/dist/agents/skills/claude-code/harness-execution/skill.yaml +1 -0
  35. package/dist/agents/skills/claude-code/harness-hotspot-detector/SKILL.md +32 -6
  36. package/dist/agents/skills/claude-code/harness-hotspot-detector/skill.yaml +1 -1
  37. package/dist/agents/skills/claude-code/harness-i18n/SKILL.md +484 -0
  38. package/dist/agents/skills/claude-code/harness-i18n/skill.yaml +54 -0
  39. package/dist/agents/skills/claude-code/harness-i18n-process/SKILL.md +388 -0
  40. package/dist/agents/skills/claude-code/harness-i18n-process/skill.yaml +43 -0
  41. package/dist/agents/skills/claude-code/harness-i18n-workflow/SKILL.md +512 -0
  42. package/dist/agents/skills/claude-code/harness-i18n-workflow/skill.yaml +53 -0
  43. package/dist/agents/skills/claude-code/harness-impact-analysis/SKILL.md +51 -6
  44. package/dist/agents/skills/claude-code/harness-integrity/SKILL.md +35 -1
  45. package/dist/agents/skills/claude-code/harness-knowledge-mapper/SKILL.md +46 -5
  46. package/dist/agents/skills/claude-code/harness-knowledge-mapper/skill.yaml +1 -1
  47. package/dist/agents/skills/claude-code/harness-onboarding/SKILL.md +19 -1
  48. package/dist/agents/skills/claude-code/harness-perf/SKILL.md +37 -8
  49. package/dist/agents/skills/claude-code/harness-perf/skill.yaml +3 -0
  50. package/dist/agents/skills/claude-code/harness-perf-tdd/SKILL.md +17 -4
  51. package/dist/agents/skills/claude-code/harness-planning/SKILL.md +57 -3
  52. package/dist/agents/skills/claude-code/harness-planning/skill.yaml +2 -0
  53. package/dist/agents/skills/claude-code/harness-release-readiness/SKILL.md +29 -9
  54. package/dist/agents/skills/claude-code/harness-roadmap/SKILL.md +562 -0
  55. package/dist/agents/skills/claude-code/harness-roadmap/skill.yaml +43 -0
  56. package/dist/agents/skills/claude-code/harness-security-review/SKILL.md +36 -2
  57. package/dist/agents/skills/claude-code/harness-security-review/skill.yaml +8 -6
  58. package/dist/agents/skills/claude-code/harness-security-scan/skill.yaml +1 -1
  59. package/dist/agents/skills/claude-code/harness-soundness-review/SKILL.md +1267 -0
  60. package/dist/agents/skills/claude-code/harness-soundness-review/skill.yaml +48 -0
  61. package/dist/agents/skills/claude-code/harness-test-advisor/SKILL.md +35 -6
  62. package/dist/agents/skills/claude-code/harness-verification/SKILL.md +66 -0
  63. package/dist/agents/skills/claude-code/harness-verification/skill.yaml +1 -0
  64. package/dist/agents/skills/claude-code/harness-verify/SKILL.md +37 -0
  65. package/dist/agents/skills/claude-code/initialize-harness-project/SKILL.md +15 -1
  66. package/dist/agents/skills/claude-code/validate-context-engineering/SKILL.md +12 -0
  67. package/dist/agents/skills/gemini-cli/harness-accessibility/SKILL.md +281 -0
  68. package/dist/agents/skills/gemini-cli/harness-accessibility/skill.yaml +51 -0
  69. package/dist/agents/skills/gemini-cli/harness-autopilot/SKILL.md +119 -72
  70. package/dist/agents/skills/gemini-cli/harness-autopilot/skill.yaml +4 -2
  71. package/dist/agents/skills/gemini-cli/harness-codebase-cleanup/SKILL.md +226 -0
  72. package/dist/agents/skills/gemini-cli/harness-codebase-cleanup/skill.yaml +64 -0
  73. package/dist/agents/skills/gemini-cli/harness-dependency-health/SKILL.md +35 -6
  74. package/dist/agents/skills/gemini-cli/harness-dependency-health/skill.yaml +1 -1
  75. package/dist/agents/skills/gemini-cli/harness-design/SKILL.md +265 -0
  76. package/dist/agents/skills/gemini-cli/harness-design/skill.yaml +53 -0
  77. package/dist/agents/skills/gemini-cli/harness-design-mobile/SKILL.md +336 -0
  78. package/dist/agents/skills/gemini-cli/harness-design-mobile/skill.yaml +49 -0
  79. package/dist/agents/skills/gemini-cli/harness-design-system/SKILL.md +282 -0
  80. package/dist/agents/skills/gemini-cli/harness-design-system/skill.yaml +50 -0
  81. package/dist/agents/skills/gemini-cli/harness-design-web/SKILL.md +360 -0
  82. package/dist/agents/skills/gemini-cli/harness-design-web/skill.yaml +52 -0
  83. package/dist/agents/skills/gemini-cli/harness-docs-pipeline/SKILL.md +460 -0
  84. package/dist/agents/skills/gemini-cli/harness-docs-pipeline/skill.yaml +69 -0
  85. package/dist/agents/skills/gemini-cli/harness-hotspot-detector/SKILL.md +32 -6
  86. package/dist/agents/skills/gemini-cli/harness-hotspot-detector/skill.yaml +1 -1
  87. package/dist/agents/skills/gemini-cli/harness-i18n/SKILL.md +484 -0
  88. package/dist/agents/skills/gemini-cli/harness-i18n/skill.yaml +54 -0
  89. package/dist/agents/skills/gemini-cli/harness-i18n-process/SKILL.md +388 -0
  90. package/dist/agents/skills/gemini-cli/harness-i18n-process/skill.yaml +43 -0
  91. package/dist/agents/skills/gemini-cli/harness-i18n-workflow/SKILL.md +512 -0
  92. package/dist/agents/skills/gemini-cli/harness-i18n-workflow/skill.yaml +53 -0
  93. package/dist/agents/skills/gemini-cli/harness-impact-analysis/SKILL.md +51 -6
  94. package/dist/agents/skills/gemini-cli/harness-knowledge-mapper/SKILL.md +46 -5
  95. package/dist/agents/skills/gemini-cli/harness-knowledge-mapper/skill.yaml +1 -1
  96. package/dist/agents/skills/gemini-cli/harness-perf/SKILL.md +37 -8
  97. package/dist/agents/skills/gemini-cli/harness-perf/skill.yaml +3 -0
  98. package/dist/agents/skills/gemini-cli/harness-perf-tdd/SKILL.md +17 -4
  99. package/dist/agents/skills/gemini-cli/harness-release-readiness/SKILL.md +29 -9
  100. package/dist/agents/skills/gemini-cli/harness-roadmap/SKILL.md +562 -0
  101. package/dist/agents/skills/gemini-cli/harness-roadmap/skill.yaml +43 -0
  102. package/dist/agents/skills/gemini-cli/harness-security-review/skill.yaml +8 -6
  103. package/dist/agents/skills/gemini-cli/harness-security-scan/skill.yaml +1 -1
  104. package/dist/agents/skills/gemini-cli/harness-soundness-review/SKILL.md +1267 -0
  105. package/dist/agents/skills/gemini-cli/harness-soundness-review/skill.yaml +48 -0
  106. package/dist/agents/skills/gemini-cli/harness-test-advisor/SKILL.md +35 -6
  107. package/dist/agents/skills/node_modules/.bin/vitest +2 -2
  108. package/dist/agents/skills/shared/design-knowledge/anti-patterns/color.yaml +106 -0
  109. package/dist/agents/skills/shared/design-knowledge/anti-patterns/layout.yaml +109 -0
  110. package/dist/agents/skills/shared/design-knowledge/anti-patterns/motion.yaml +109 -0
  111. package/dist/agents/skills/shared/design-knowledge/anti-patterns/typography.yaml +112 -0
  112. package/dist/agents/skills/shared/design-knowledge/industries/creative.yaml +80 -0
  113. package/dist/agents/skills/shared/design-knowledge/industries/ecommerce.yaml +80 -0
  114. package/dist/agents/skills/shared/design-knowledge/industries/emerging-tech.yaml +83 -0
  115. package/dist/agents/skills/shared/design-knowledge/industries/fintech.yaml +80 -0
  116. package/dist/agents/skills/shared/design-knowledge/industries/healthcare.yaml +80 -0
  117. package/dist/agents/skills/shared/design-knowledge/industries/lifestyle.yaml +80 -0
  118. package/dist/agents/skills/shared/design-knowledge/industries/saas.yaml +80 -0
  119. package/dist/agents/skills/shared/design-knowledge/industries/services.yaml +80 -0
  120. package/dist/agents/skills/shared/design-knowledge/palettes/curated.yaml +234 -0
  121. package/dist/agents/skills/shared/design-knowledge/platform-rules/android.yaml +125 -0
  122. package/dist/agents/skills/shared/design-knowledge/platform-rules/flutter.yaml +144 -0
  123. package/dist/agents/skills/shared/design-knowledge/platform-rules/ios.yaml +106 -0
  124. package/dist/agents/skills/shared/design-knowledge/platform-rules/web.yaml +102 -0
  125. package/dist/agents/skills/shared/design-knowledge/typography/pairings.yaml +274 -0
  126. package/dist/agents/skills/shared/i18n-knowledge/accessibility/intersection.yaml +142 -0
  127. package/dist/agents/skills/shared/i18n-knowledge/anti-patterns/encoding.yaml +67 -0
  128. package/dist/agents/skills/shared/i18n-knowledge/anti-patterns/formatting.yaml +106 -0
  129. package/dist/agents/skills/shared/i18n-knowledge/anti-patterns/layout.yaml +80 -0
  130. package/dist/agents/skills/shared/i18n-knowledge/anti-patterns/pluralization.yaml +80 -0
  131. package/dist/agents/skills/shared/i18n-knowledge/anti-patterns/string-handling.yaml +106 -0
  132. package/dist/agents/skills/shared/i18n-knowledge/frameworks/android-resources.yaml +47 -0
  133. package/dist/agents/skills/shared/i18n-knowledge/frameworks/apple-strings.yaml +47 -0
  134. package/dist/agents/skills/shared/i18n-knowledge/frameworks/backend-patterns.yaml +50 -0
  135. package/dist/agents/skills/shared/i18n-knowledge/frameworks/flutter-intl.yaml +47 -0
  136. package/dist/agents/skills/shared/i18n-knowledge/frameworks/i18next.yaml +47 -0
  137. package/dist/agents/skills/shared/i18n-knowledge/frameworks/react-intl.yaml +47 -0
  138. package/dist/agents/skills/shared/i18n-knowledge/frameworks/vue-i18n.yaml +47 -0
  139. package/dist/agents/skills/shared/i18n-knowledge/industries/ecommerce.yaml +66 -0
  140. package/dist/agents/skills/shared/i18n-knowledge/industries/fintech.yaml +66 -0
  141. package/dist/agents/skills/shared/i18n-knowledge/industries/gaming.yaml +69 -0
  142. package/dist/agents/skills/shared/i18n-knowledge/industries/healthcare.yaml +66 -0
  143. package/dist/agents/skills/shared/i18n-knowledge/industries/legal.yaml +66 -0
  144. package/dist/agents/skills/shared/i18n-knowledge/locales/ar.yaml +41 -0
  145. package/dist/agents/skills/shared/i18n-knowledge/locales/de.yaml +35 -0
  146. package/dist/agents/skills/shared/i18n-knowledge/locales/en.yaml +32 -0
  147. package/dist/agents/skills/shared/i18n-knowledge/locales/es.yaml +35 -0
  148. package/dist/agents/skills/shared/i18n-knowledge/locales/fi.yaml +35 -0
  149. package/dist/agents/skills/shared/i18n-knowledge/locales/fr.yaml +35 -0
  150. package/dist/agents/skills/shared/i18n-knowledge/locales/he.yaml +41 -0
  151. package/dist/agents/skills/shared/i18n-knowledge/locales/hi.yaml +35 -0
  152. package/dist/agents/skills/shared/i18n-knowledge/locales/it.yaml +32 -0
  153. package/dist/agents/skills/shared/i18n-knowledge/locales/ja.yaml +38 -0
  154. package/dist/agents/skills/shared/i18n-knowledge/locales/ko.yaml +38 -0
  155. package/dist/agents/skills/shared/i18n-knowledge/locales/nl.yaml +32 -0
  156. package/dist/agents/skills/shared/i18n-knowledge/locales/pl.yaml +35 -0
  157. package/dist/agents/skills/shared/i18n-knowledge/locales/pt.yaml +32 -0
  158. package/dist/agents/skills/shared/i18n-knowledge/locales/ru.yaml +35 -0
  159. package/dist/agents/skills/shared/i18n-knowledge/locales/sv.yaml +32 -0
  160. package/dist/agents/skills/shared/i18n-knowledge/locales/th.yaml +35 -0
  161. package/dist/agents/skills/shared/i18n-knowledge/locales/tr.yaml +35 -0
  162. package/dist/agents/skills/shared/i18n-knowledge/locales/zh-Hans.yaml +38 -0
  163. package/dist/agents/skills/shared/i18n-knowledge/locales/zh-Hant.yaml +35 -0
  164. package/dist/agents/skills/shared/i18n-knowledge/mcp-interop/i18next-mcp.yaml +56 -0
  165. package/dist/agents/skills/shared/i18n-knowledge/mcp-interop/lingo-dev.yaml +56 -0
  166. package/dist/agents/skills/shared/i18n-knowledge/mcp-interop/lokalise.yaml +60 -0
  167. package/dist/agents/skills/shared/i18n-knowledge/mcp-interop/tolgee.yaml +60 -0
  168. package/dist/agents/skills/shared/i18n-knowledge/testing/locale-testing.yaml +107 -0
  169. package/dist/agents/skills/shared/i18n-knowledge/testing/pseudo-localization.yaml +86 -0
  170. package/dist/bin/harness.js +64 -4
  171. package/dist/{chunk-UDWGSL3T.js → chunk-3JWCBVUZ.js} +3 -3
  172. package/dist/{chunk-IUFFBBYV.js → chunk-LNI4T7R6.js} +179 -61
  173. package/dist/{chunk-USEYPS7F.js → chunk-SJECMKSS.js} +2250 -40
  174. package/dist/{dist-4MYPT3OE.js → dist-BDO5GFEM.js} +295 -14
  175. package/dist/{dist-RBZXXJHG.js → dist-NT3GXHQZ.js} +95 -1
  176. package/dist/index.d.ts +266 -7
  177. package/dist/index.js +7 -3
  178. package/dist/validate-cross-check-2OPGCGGU.js +7 -0
  179. package/package.json +7 -7
  180. package/dist/validate-cross-check-CPEPNLOD.js +0 -7
@@ -0,0 +1,64 @@
1
+ name: harness-codebase-cleanup
2
+ version: "1.0.0"
3
+ description: Orchestrate dead code removal and architecture violation fixes with shared convergence loop
4
+ cognitive_mode: systematic-orchestrator
5
+ triggers:
6
+ - manual
7
+ platforms:
8
+ - claude-code
9
+ - gemini-cli
10
+ tools:
11
+ - Bash
12
+ - Read
13
+ - Glob
14
+ - Grep
15
+ cli:
16
+ command: harness skill run harness-codebase-cleanup
17
+ args:
18
+ - name: path
19
+ description: Project root path
20
+ required: false
21
+ - name: fix
22
+ description: Enable convergence-based auto-fix (default detect+report only)
23
+ required: false
24
+ - name: dead-code-only
25
+ description: Skip architecture checks
26
+ required: false
27
+ - name: architecture-only
28
+ description: Skip dead code checks
29
+ required: false
30
+ - name: dry-run
31
+ description: Show what would be fixed without applying
32
+ required: false
33
+ - name: ci
34
+ description: Non-interactive mode (safe fixes only, report everything else)
35
+ required: false
36
+ mcp:
37
+ tool: run_skill
38
+ input:
39
+ skill: harness-codebase-cleanup
40
+ path: string
41
+ type: flexible
42
+ phases:
43
+ - name: context
44
+ description: Run hotspot detection, build churn map
45
+ required: true
46
+ - name: detect
47
+ description: Run dead code and architecture detection in parallel
48
+ required: true
49
+ - name: classify
50
+ description: Classify findings, apply hotspot downgrade, cross-concern dedup
51
+ required: true
52
+ - name: fix
53
+ description: Convergence loop - apply safe fixes, verify, re-detect
54
+ required: false
55
+ - name: report
56
+ description: Generate actionable report of fixes applied and remaining findings
57
+ required: true
58
+ state:
59
+ persistent: false
60
+ files: []
61
+ depends_on:
62
+ - cleanup-dead-code
63
+ - enforce-architecture
64
+ - harness-hotspot-detector
@@ -12,8 +12,23 @@
12
12
 
13
13
  ## Prerequisites
14
14
 
15
- A knowledge graph must exist at `.harness/graph/`. Run `harness scan` if no graph is available.
16
- If the graph exists but code has changed since the last scan, re-run `harness scan` first — stale graph data leads to inaccurate results.
15
+ A knowledge graph at `.harness/graph/` enables full analysis. If no graph exists,
16
+ the skill uses static analysis fallbacks (see Graph Availability section).
17
+ Run `harness scan` to enable graph-enhanced analysis.
18
+
19
+ ### Graph Availability
20
+
21
+ Before starting, check if `.harness/graph/graph.json` exists.
22
+
23
+ **If graph exists:** Check staleness — compare `.harness/graph/metadata.json`
24
+ scanTimestamp against `git log -1 --format=%ct` (latest commit timestamp).
25
+ If graph is more than 2 commits behind (`git log --oneline <scanTimestamp>..HEAD | wc -l`),
26
+ run `harness scan` to refresh before proceeding. (Staleness sensitivity: **High**)
27
+
28
+ **If graph exists and is fresh (or refreshed):** Use graph tools as primary strategy.
29
+
30
+ **If no graph exists:** Output "Running without graph (run `harness scan` to
31
+ enable full analysis)" and use fallback strategies for all subsequent steps.
17
32
 
18
33
  ## Process
19
34
 
@@ -50,6 +65,20 @@ Query the graph for five key structural indicators:
50
65
 
51
66
  5. **Module cohesion**: For each module (directory), count internal vs external edges. Low internal cohesion (many external edges, few internal) suggests misplaced code.
52
67
 
68
+ #### Fallback (without graph)
69
+
70
+ When no graph is available, use static analysis to approximate structural metrics:
71
+
72
+ 1. **Build adjacency list**: Grep all source files for `import`/`require` statements. Parse each to extract the imported path. Build an adjacency list mapping each file to its imports.
73
+ 2. **Hub detection**: From the adjacency list, count inbound edges per file. Files with >10 importers are hubs.
74
+ 3. **Orphan detection**: Files with zero inbound edges that are not entry points (not `index.*`, not in `package.json` main/exports). Use glob to find all source files, then subtract those that appear as import targets.
75
+ 4. **Cycle detection**: Run DFS on the adjacency list. When a back-edge is found, report the cycle path.
76
+ 5. **Deep chain detection**: From entry points, DFS to find the longest import chain. Report chains exceeding 7 hops.
77
+ 6. **Module cohesion (approximate)**: For each directory, count imports that stay within the directory (internal) vs imports that leave it (external). Cohesion = internal / (internal + external).
78
+ 7. **Run `check_dependencies` CLI** — this works without a graph and can detect layer violations.
79
+
80
+ > Fallback completeness: ~60% — cannot compute transitive depth beyond what import parsing reveals; coupling metrics are approximate.
81
+
53
82
  ### Phase 2: SCORE — Calculate Health Score
54
83
 
55
84
  Compute a weighted health score (0-100):
@@ -104,7 +133,7 @@ For each problem found, generate a specific, actionable recommendation:
104
133
 
105
134
  ## Harness Integration
106
135
 
107
- - **`harness scan`** — Must run before this skill to ensure graph is current.
136
+ - **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses static analysis fallbacks.
108
137
  - **`harness validate`** — Run after acting on findings to verify project health.
109
138
  - **Graph tools** — This skill uses `query_graph`, `get_relationships`, and `check_dependencies` MCP tools.
110
139
 
@@ -114,7 +143,7 @@ For each problem found, generate a specific, actionable recommendation:
114
143
  - All five structural metrics gathered (hubs, orphans, cycles, deep chains, cohesion)
115
144
  - Recommendations are specific and actionable (name files, suggest concrete fixes)
116
145
  - Report follows the structured output format
117
- - All findings are backed by graph query evidence, not heuristics
146
+ - All findings are backed by graph query evidence (with graph) or systematic static analysis (without graph)
118
147
 
119
148
  ## Examples
120
149
 
@@ -141,8 +170,8 @@ Output:
141
170
 
142
171
  ## Gates
143
172
 
144
- - **No analysis without graph.** If no graph exists, stop and instruct to run `harness scan`.
145
- - **No guessing.** All metrics must come from graph queries, not heuristics.
173
+ - **Graph preferred, fallback available.** If no graph exists, use fallback strategies (import parsing, DFS cycle detection, hub/orphan identification). Do not stop produce the best analysis possible.
174
+ - **Systematic analysis required.** All metrics must come from graph queries (with graph) or systematic import parsing (without graph). Do not guess — parse actual import statements.
146
175
 
147
176
  ## Escalation
148
177
 
@@ -4,7 +4,7 @@ description: Analyze structural health of the codebase using graph metrics
4
4
  cognitive_mode: analytical-reporter
5
5
  triggers:
6
6
  - manual
7
- - scheduled
7
+ - on_milestone
8
8
  platforms:
9
9
  - claude-code
10
10
  - gemini-cli
@@ -0,0 +1,265 @@
1
+ # Harness Design
2
+
3
+ > Aesthetic direction workflow. Capture design intent, generate DESIGN.md with anti-patterns and platform notes, review components against aesthetic guidelines, and enforce design constraints at configurable strictness levels.
4
+
5
+ ## When to Use
6
+
7
+ - Establishing aesthetic direction for a new or existing project (style, tone, differentiator)
8
+ - When `on_new_feature` triggers fire and the feature has design scope requiring aesthetic guidance
9
+ - Reviewing existing components against declared design intent and anti-patterns
10
+ - Enforcing design constraints via the knowledge graph with configurable strictness
11
+ - Generating or updating `design-system/DESIGN.md` with aesthetic direction, anti-patterns, and platform notes
12
+ - NOT for design token generation or palette selection (use harness-design-system)
13
+ - NOT for accessibility auditing or WCAG compliance (use harness-accessibility)
14
+ - NOT for platform-specific token implementation into CSS/Tailwind/etc. (use harness-design-web/mobile, Phase 5)
15
+
16
+ ## Process
17
+
18
+ ### Phase 1: INTENT -- Capture Aesthetic Intent
19
+
20
+ 1. **Read existing design artifacts.** Search for:
21
+ - `design-system/DESIGN.md` -- existing aesthetic direction documentation (from harness-design-system output)
22
+ - `design-system/tokens.json` -- existing W3C DTCG tokens (palette, typography, spacing defined by harness-design-system)
23
+ - `harness.config.json` -- project configuration for design settings
24
+
25
+ 2. **Check harness configuration.** Read `harness.config.json` for:
26
+ - `design.strictness` -- enforcement level (`strict`, `standard`, `permissive`). If not set, default to `standard`.
27
+ - `design.platforms` -- which platforms are enabled (web, mobile)
28
+ - `design.aestheticIntent` -- path to design intent doc (default: `design-system/DESIGN.md`)
29
+
30
+ 3. **Load industry profile.** If an industry is specified (via CLI `--industry` arg or config), read the industry profile from `agents/skills/shared/design-knowledge/industries/{industry}.yaml`. Available industries include: `saas`, `fintech`, `healthcare`, `ecommerce`, `creative`, `emerging-tech`, `lifestyle`, `services`. The profile provides sector-specific guidance on:
31
+ - Recommended visual style and tone
32
+ - Industry conventions and user expectations
33
+ - Regulatory or cultural considerations
34
+ - Common anti-patterns for the sector
35
+
36
+ 4. **Capture user intent.** Ask the user to define:
37
+ - **Style:** minimal, expressive, corporate, playful, editorial, or custom
38
+ - **Tone:** warm, cool, neutral, bold, muted, or custom
39
+ - **Key differentiator:** what makes this product's visual identity unique
40
+ - **Anti-patterns:** specific design choices to explicitly avoid (e.g., "no gradients on data elements," "no decorative borders on cards")
41
+
42
+ 5. **Load shared design knowledge.** Read anti-pattern awareness from `agents/skills/shared/design-knowledge/`:
43
+ - `palettes/curated.yaml` -- curated palettes to understand which aesthetic families are available
44
+ - `typography/pairings.yaml` -- typography pairings to understand which font combinations are recommended
45
+ - Industry-specific anti-pattern guidance from the loaded industry profile
46
+
47
+ 6. **Confirm intent before proceeding.** Present a summary of the captured aesthetic intent to the user. This is a hard gate -- no DESIGN.md generation without the user confirming their aesthetic intent.
48
+
49
+ ### Phase 2: DIRECTION -- Generate DESIGN.md
50
+
51
+ 1. **Generate or update `design-system/DESIGN.md`.** The document must contain the following sections:
52
+
53
+ **Aesthetic Direction:**
54
+ - Style declaration (the chosen style and what it means for this project)
55
+ - Tone description (how the tone manifests in color usage, typography weight, spacing density)
56
+ - Key differentiator (the unique visual identity aspect and how it is expressed)
57
+
58
+ **Anti-Patterns:**
59
+ - Project-specific anti-patterns (from user input in Phase 1)
60
+ - Industry-informed anti-patterns (from the loaded industry profile)
61
+ - Each anti-pattern includes: name, description, example of what NOT to do, and why it conflicts with the declared intent
62
+
63
+ **Platform Notes:**
64
+ - Web-specific guidance (CSS strategy, responsive behavior, animation preferences)
65
+ - Mobile-specific guidance (touch targets, native component usage, platform conventions)
66
+ - Cross-platform consistency rules (which elements must be identical vs. platform-adapted)
67
+
68
+ **Strictness Override:**
69
+ - Current `designStrictness` level and what it means
70
+ - Instructions for changing strictness in `harness.config.json`
71
+ - Behavior differences per level:
72
+ - `permissive` -- all design violations reported as `info` (nothing blocks)
73
+ - `standard` -- anti-pattern and accessibility violations are `warn`, critical violations are `error` (default)
74
+ - `strict` -- accessibility violations are `error` (blocks CI/PR merge), anti-pattern violations are `warn`
75
+
76
+ 2. **Populate the knowledge graph.** If a graph exists at `.harness/graph/`:
77
+ - Create an `AestheticIntent` node with properties: style, tone, differentiator, strictness level. Use `DesignIngestor` from `packages/graph/src/ingest/DesignIngestor.ts` for graph ingestion.
78
+ - Create a `DECLARES_INTENT` edge from the project node to the `AestheticIntent` node.
79
+ - This enables downstream skills (harness-accessibility, harness-impact-analysis) to query the declared design intent.
80
+
81
+ 3. **Run harness validate.** After generating DESIGN.md, verify the project still passes all constraints. The new file must not break existing validations.
82
+
83
+ ### Phase 3: REVIEW -- Review Components Against Design Intent
84
+
85
+ 1. **Scan for anti-pattern violations.** Use Grep to search the codebase for patterns that match declared anti-patterns:
86
+ - Hardcoded color values not present in `design-system/tokens.json` (suggests off-brand color usage)
87
+ - Font families flagged as anti-patterns in the design intent (e.g., decorative fonts in a minimal project)
88
+ - Layout patterns on the forbidden list (e.g., excessive drop shadows in a flat design, gradients on data elements)
89
+ - CSS properties or values that contradict the declared style (e.g., rounded corners in a sharp-edge design)
90
+
91
+ 2. **Load detection rules from shared design knowledge.** Read from `agents/skills/shared/design-knowledge/`:
92
+ - `anti-patterns/typography.yaml` — font combinations, size, weight, and line-height issues that clash with the declared style
93
+ - `anti-patterns/color.yaml` — hardcoded colors, insufficient contrast, color-only indicators that undermine the declared tone
94
+ - `anti-patterns/layout.yaml` — spacing inconsistencies, missing touch targets, fixed-width containers
95
+ - `anti-patterns/motion.yaml` — missing prefers-reduced-motion, long animations, scroll-jacking
96
+ - `industries/{industry}.yaml` — industry-specific rules from the loaded industry profile
97
+
98
+ 3. **Cross-reference with graph constraints.** If a graph exists at `.harness/graph/`:
99
+ - Query for existing `VIOLATES_DESIGN` edges using `DesignConstraintAdapter` from `packages/graph/src/constraints/DesignConstraintAdapter.ts`
100
+ - Compare current findings against previously recorded violations
101
+ - Identify new violations and resolved violations
102
+
103
+ 4. **Assign severity based on `designStrictness`:**
104
+ - `permissive` -- all findings are `info` severity
105
+ - `standard` -- anti-pattern violations and accessibility-related findings are `warn`, critical design constraint violations are `error`
106
+ - `strict` -- accessibility violations are `error` (blocks), anti-pattern violations are `warn`
107
+
108
+ 5. **Report findings.** Present each finding with:
109
+ - File path and line number
110
+ - Violation description and which anti-pattern or design constraint it violates
111
+ - Severity level (based on current strictness)
112
+ - Suggested remediation
113
+
114
+ ### Phase 4: ENFORCE -- Surface and Record Violations
115
+
116
+ 1. **Create constraint nodes in the graph.** For each violated design rule, if a graph exists at `.harness/graph/`:
117
+ - Create a `DesignConstraint` node for the rule being violated (if one does not already exist)
118
+ - Create a `VIOLATES_DESIGN` edge from the violating component to the `DesignConstraint` node
119
+ - Use `DesignConstraintAdapter` from `packages/graph/src/constraints/DesignConstraintAdapter.ts` to manage constraint creation and violation recording
120
+
121
+ 2. **Format violation output.** Each violation follows a numbered format:
122
+
123
+ ```
124
+ DESIGN-001 [warn] Anti-pattern: gradient used on data visualization element
125
+ File: src/components/Chart.tsx
126
+ Line: 42
127
+ Constraint: No gradients on data elements
128
+ Intent: Style "minimal" prohibits decorative effects on informational components
129
+ Fix: Replace linear-gradient with solid color from token "neutral.100"
130
+
131
+ DESIGN-002 [error] Off-brand color: hardcoded #ff6b35 not in token set
132
+ File: src/components/Alert.tsx
133
+ Line: 18
134
+ Constraint: All colors must reference design tokens
135
+ Intent: Tone "cool" conflicts with warm orange accent
136
+ Fix: Use token "semantic.warning" (#f59e0b) or add color to tokens.json via harness-design-system
137
+
138
+ DESIGN-003 [info] Typography: decorative font "Playfair Display" used in component
139
+ File: src/components/Hero.tsx
140
+ Line: 8
141
+ Constraint: Heading font must match declared typography pairing
142
+ Intent: Style "minimal" uses Inter for all headings
143
+ Fix: Replace with token "typography.heading.fontFamily"
144
+ ```
145
+
146
+ 3. **Control severity by `designStrictness`:**
147
+ - `permissive` -- all violations output as `info` (DESIGN-001 [info], DESIGN-002 [info], etc.)
148
+ - `standard` -- anti-patterns and a11y = `warn`, off-brand tokens = `error` (default)
149
+ - `strict` -- a11y violations = `error` (blocks CI), anti-patterns = `warn`, off-brand tokens = `error`
150
+
151
+ 4. **Run harness validate.** After recording violations in the graph, run validation to ensure the enforcement pass is consistent with the project state.
152
+
153
+ ## Harness Integration
154
+
155
+ - **`harness validate`** -- Run after generating DESIGN.md and after enforcement passes. Design violations surface as constraint violations at the configured strictness level.
156
+ - **`harness scan`** -- Run after changes to refresh the knowledge graph. Updated graph enables accurate violation detection and impact analysis.
157
+ - **`DesignIngestor`** (`packages/graph/src/ingest/DesignIngestor.ts`) -- Parses `tokens.json` and `DESIGN.md` to create graph nodes representing the design system. Creates `AestheticIntent` nodes and `DECLARES_INTENT` edges during the DIRECTION phase.
158
+ - **`DesignConstraintAdapter`** (`packages/graph/src/constraints/DesignConstraintAdapter.ts`) -- Manages `DesignConstraint` nodes and `VIOLATES_DESIGN` edges in the graph. Reads `design.strictness` to control violation severity. Used during REVIEW and ENFORCE phases.
159
+
160
+ **Graph naming convention:** This skill uses PascalCase for node types (`AestheticIntent`, `DesignToken`, `DesignConstraint`) and UPPER_SNAKE for edge types (`DECLARES_INTENT`, `VIOLATES_DESIGN`, `USES_TOKEN`, `PLATFORM_BINDING`) as conceptual labels. The graph schema registers these as snake_case identifiers (`aesthetic_intent`, `design_token`, `design_constraint`, `declares_intent`, `violates_design`, `uses_token`, `platform_binding`). The adapter classes (`DesignIngestor`, `DesignConstraintAdapter`) handle the mapping — always use the adapters rather than constructing graph queries with raw type names.
161
+
162
+ - **`harness-design-system`** -- Dependency. This skill reads tokens and design intent generated by harness-design-system. Token-level issues (palette changes, new colors) are resolved by running harness-design-system, not this skill.
163
+ - **`harness-impact-analysis`** -- When design tokens change, impact analysis traces which components consume affected tokens. Use this to determine which components need re-review after token updates.
164
+
165
+ ## Success Criteria
166
+
167
+ - `design-system/DESIGN.md` exists with all required sections: Aesthetic Direction, Anti-Patterns, Platform Notes, Strictness Override
168
+ - Anti-patterns are detected in the codebase and reported with file paths, line numbers, and severity
169
+ - `designStrictness` configuration is read from `harness.config.json` and respected in all severity assignments
170
+ - `AestheticIntent` node created in the knowledge graph with style, tone, differentiator, and strictness properties
171
+ - `DECLARES_INTENT` edge connects the project to the aesthetic intent node
172
+ - `DesignConstraint` nodes created for each violated design rule
173
+ - `VIOLATES_DESIGN` edges connect violating components to their constraint nodes
174
+ - Violations output in numbered format (DESIGN-001, DESIGN-002, etc.) with severity matching strictness level
175
+ - `harness validate` passes after DESIGN.md generation and enforcement
176
+ - User confirmed aesthetic intent before DESIGN.md generation (hard gate)
177
+
178
+ ## Examples
179
+
180
+ ### Example: SaaS Analytics Dashboard Aesthetic Direction
181
+
182
+ **Context:** A SaaS analytics dashboard project. Industry: `saas`. Design tokens already generated by harness-design-system. No existing DESIGN.md aesthetic direction.
183
+
184
+ **INTENT capture:**
185
+
186
+ ```
187
+ Industry profile: Loaded (saas) -- recommends professional, data-focused aesthetic
188
+ Style: Minimal
189
+ Tone: Cool, professional
190
+ Differentiator: Dense information display with generous whitespace between sections
191
+ Anti-patterns: No gradients on data elements, no decorative borders on cards,
192
+ no more than 2 font weights per component
193
+ Strictness: standard (from harness.config.json)
194
+ ```
195
+
196
+ **DIRECTION output (DESIGN.md excerpt):**
197
+
198
+ ```markdown
199
+ ## Aesthetic Direction
200
+
201
+ **Style:** Minimal -- clean lines, flat surfaces, no decorative elements that do not serve
202
+ an informational purpose. Every visual element must earn its place by conveying data or
203
+ guiding the user's eye.
204
+
205
+ **Tone:** Cool, professional -- slate and blue palette dominates. Warm colors reserved
206
+ exclusively for semantic states (warning, error). No warm accents in neutral UI.
207
+
208
+ **Differentiator:** Dense information display with generous whitespace between sections.
209
+ Components are compact internally but breathe externally. Card padding is tight (12px),
210
+ but gaps between cards are generous (24px+).
211
+
212
+ ## Anti-Patterns
213
+
214
+ | Pattern | Description | Why It Conflicts |
215
+ | -------------------------- | -------------------------------------------- | ------------------------------------------ |
216
+ | Gradients on data elements | linear-gradient on charts, tables, cards | Minimal style: flat surfaces only |
217
+ | Decorative card borders | border with color on .card elements | Minimal style: borders are structural only |
218
+ | Excess font weights | More than 2 font-weight values per component | Minimal style: typographic restraint |
219
+
220
+ ## Strictness Override
221
+
222
+ Current level: **standard**
223
+
224
+ To change, update `harness.config.json`:
225
+ "design": { "strictness": "strict" | "standard" | "permissive" }
226
+ ```
227
+
228
+ **REVIEW findings:**
229
+
230
+ ```
231
+ Found 3 anti-pattern violations in 2 files:
232
+
233
+ DESIGN-001 [warn] Gradient on data element
234
+ File: src/components/RevenueChart.tsx:42
235
+ Constraint: No gradients on data elements
236
+ Fix: Replace linear-gradient(#3b82f6, #1d4ed8) with solid token "primary.500"
237
+
238
+ DESIGN-002 [warn] Decorative border on card
239
+ File: src/components/MetricCard.tsx:15
240
+ Constraint: No decorative borders on cards
241
+ Fix: Remove border-color: #3b82f6, use border-color: transparent or remove border
242
+
243
+ DESIGN-003 [info] Three font weights in one component
244
+ File: src/components/MetricCard.tsx:8
245
+ Constraint: Max 2 font weights per component
246
+ Fix: Consolidate font-weight values to 400 (body) and 600 (heading) only
247
+ ```
248
+
249
+ ## Gates
250
+
251
+ These are hard stops. Violating any gate means the process has broken down.
252
+
253
+ - **No DESIGN.md generated without the user confirming aesthetic intent.** The INTENT phase must end with explicit user confirmation of style, tone, differentiator, and anti-patterns. Do not generate based on assumptions.
254
+ - **No enforcement without reading tokens from harness-design-system.** The REVIEW and ENFORCE phases require `design-system/tokens.json` to exist. If tokens have not been generated, instruct the user to run harness-design-system first.
255
+ - **Strictness must be read from configuration, not assumed.** Read `design.strictness` from `harness.config.json`. If the key does not exist, default to `standard` and report the default to the user. Never hardcode a strictness level.
256
+ - **No anti-pattern detection without a declared intent.** The REVIEW phase requires an existing DESIGN.md with declared anti-patterns. If no intent has been captured, run the INTENT and DIRECTION phases first.
257
+ - **No graph mutations without validating node types.** When creating `AestheticIntent`, `DesignConstraint`, or `VIOLATES_DESIGN` edges, verify the node and edge types are registered in the graph schema before writing.
258
+
259
+ ## Escalation
260
+
261
+ - **When the user cannot articulate a style or tone:** Suggest industry-based defaults from the loaded industry profile. Present 2-3 options with examples: "Based on the saas industry profile, common styles are: (1) Minimal -- clean, data-focused, (2) Corporate -- structured, trustworthy, (3) Expressive -- colorful, engaging. Which resonates most?"
262
+ - **When declared anti-patterns conflict with existing code:** Present a migration path rather than flagging every instance as a violation. Report: "Found 47 instances of gradients on data elements. Recommend a phased migration: (1) Update new components immediately, (2) Schedule legacy component updates over 3 sprints. Set strictness to 'permissive' during migration to avoid blocking CI."
263
+ - **When tokens do not exist yet:** Do not attempt to infer a token set. Instruct the user: "Design tokens have not been generated. Run harness-design-system first to create `design-system/tokens.json`, then re-run harness-design for aesthetic direction."
264
+ - **When strictness level conflicts with team velocity:** Explain the tradeoffs: "Strict mode blocks PRs on any design violation. If this is slowing the team, consider 'standard' mode which blocks only on critical violations (off-brand colors, accessibility) and warns on anti-patterns."
265
+ - **When the knowledge graph is unavailable:** Skip graph operations in DIRECTION and ENFORCE phases. Log: "Graph not available at `.harness/graph/` -- skipping AestheticIntent node creation and violation recording. Run `harness scan` later to populate." Continue with file-based operations.
@@ -0,0 +1,53 @@
1
+ name: harness-design
2
+ version: "1.0.0"
3
+ description: Aesthetic direction workflow, anti-pattern enforcement, DESIGN.md generation, and strictness configuration
4
+ cognitive_mode: advisory-guide
5
+ triggers:
6
+ - manual
7
+ - on_new_feature
8
+ platforms:
9
+ - claude-code
10
+ - gemini-cli
11
+ tools:
12
+ - Bash
13
+ - Read
14
+ - Write
15
+ - Edit
16
+ - Glob
17
+ - Grep
18
+ cli:
19
+ command: harness skill run harness-design
20
+ args:
21
+ - name: path
22
+ description: Project root path
23
+ required: false
24
+ - name: strictness
25
+ description: Override strictness level (strict, standard, permissive)
26
+ required: false
27
+ - name: industry
28
+ description: Industry vertical for aesthetic recommendations
29
+ required: false
30
+ mcp:
31
+ tool: run_skill
32
+ input:
33
+ skill: harness-design
34
+ path: string
35
+ type: flexible
36
+ phases:
37
+ - name: intent
38
+ description: Capture aesthetic intent, style, tone, and differentiator
39
+ required: true
40
+ - name: direction
41
+ description: Generate DESIGN.md with aesthetic direction, anti-patterns, and platform notes
42
+ required: true
43
+ - name: review
44
+ description: Review existing components against design intent and anti-patterns
45
+ required: false
46
+ - name: enforce
47
+ description: Enforce design constraints via graph, surface violations by strictness level
48
+ required: false
49
+ state:
50
+ persistent: false
51
+ files: []
52
+ depends_on:
53
+ - harness-design-system