@paths.design/caws-cli 7.0.2 → 8.0.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 (217) hide show
  1. package/dist/budget-derivation.js +5 -4
  2. package/dist/commands/diagnose.js +24 -19
  3. package/dist/commands/init.js +51 -4
  4. package/dist/commands/quality-gates.js +147 -9
  5. package/dist/commands/specs.js +148 -14
  6. package/dist/commands/status.js +2 -2
  7. package/dist/commands/tool.js +2 -4
  8. package/dist/config/index.js +17 -8
  9. package/dist/generators/working-spec.js +19 -6
  10. package/dist/scaffold/git-hooks.js +245 -46
  11. package/dist/scaffold/index.js +53 -7
  12. package/dist/templates/.caws/tools/README.md +21 -0
  13. package/dist/templates/.cursor/README.md +311 -0
  14. package/dist/templates/.cursor/hooks/audit.sh +55 -0
  15. package/dist/templates/.cursor/hooks/block-dangerous.sh +83 -0
  16. package/dist/templates/.cursor/hooks/caws-quality-check.sh +52 -0
  17. package/dist/templates/.cursor/hooks/caws-scope-guard.sh +130 -0
  18. package/dist/templates/.cursor/hooks/caws-tool-validation.sh +121 -0
  19. package/dist/templates/.cursor/hooks/format.sh +38 -0
  20. package/dist/templates/.cursor/hooks/naming-check.sh +64 -0
  21. package/dist/templates/.cursor/hooks/scan-secrets.sh +46 -0
  22. package/dist/templates/.cursor/hooks/scope-guard.sh +52 -0
  23. package/dist/templates/.cursor/hooks/validate-spec.sh +83 -0
  24. package/dist/templates/.cursor/hooks.json +59 -0
  25. package/dist/templates/.cursor/rules/00-claims-verification.mdc +144 -0
  26. package/dist/templates/.cursor/rules/01-working-style.mdc +50 -0
  27. package/dist/templates/.cursor/rules/02-quality-gates.mdc +370 -0
  28. package/dist/templates/.cursor/rules/03-naming-and-refactor.mdc +33 -0
  29. package/dist/templates/.cursor/rules/04-logging-language-style.mdc +23 -0
  30. package/dist/templates/.cursor/rules/05-safe-defaults-guards.mdc +23 -0
  31. package/dist/templates/.cursor/rules/06-typescript-conventions.mdc +36 -0
  32. package/dist/templates/.cursor/rules/07-process-ops.mdc +20 -0
  33. package/dist/templates/.cursor/rules/08-solid-and-architecture.mdc +16 -0
  34. package/dist/templates/.cursor/rules/09-docstrings.mdc +89 -0
  35. package/dist/templates/.cursor/rules/10-documentation-quality-standards.mdc +390 -0
  36. package/dist/templates/.cursor/rules/11-scope-management-waivers.mdc +385 -0
  37. package/dist/templates/.cursor/rules/12-implementation-completeness.mdc +516 -0
  38. package/dist/templates/.cursor/rules/13-language-agnostic-standards.mdc +588 -0
  39. package/dist/templates/.cursor/rules/README.md +148 -0
  40. package/dist/templates/.github/copilot/instructions.md +311 -0
  41. package/dist/templates/.idea/runConfigurations/CAWS_Evaluate.xml +5 -0
  42. package/dist/templates/.idea/runConfigurations/CAWS_Validate.xml +5 -0
  43. package/dist/templates/.vscode/launch.json +56 -0
  44. package/dist/templates/.vscode/settings.json +93 -0
  45. package/dist/templates/.windsurf/workflows/caws-guided-development.md +92 -0
  46. package/dist/templates/COMMIT_CONVENTIONS.md +86 -0
  47. package/dist/templates/OIDC_SETUP.md +300 -0
  48. package/dist/templates/agents.md +1047 -0
  49. package/dist/templates/codemod/README.md +1 -0
  50. package/dist/templates/codemod/test.js +93 -0
  51. package/dist/templates/docs/README.md +150 -0
  52. package/dist/templates/scripts/quality-gates/check-god-objects.js +146 -0
  53. package/dist/templates/scripts/quality-gates/run-quality-gates.js +50 -0
  54. package/dist/templates/scripts/v3/analysis/todo_analyzer.py +1997 -0
  55. package/dist/tool-loader.js +6 -1
  56. package/dist/tool-validator.js +8 -2
  57. package/dist/utils/detection.js +4 -3
  58. package/dist/utils/git-lock.js +119 -0
  59. package/dist/utils/gitignore-updater.js +148 -0
  60. package/dist/utils/project-analysis.js +176 -16
  61. package/dist/utils/quality-gates.js +48 -7
  62. package/dist/utils/spec-resolver.js +27 -3
  63. package/dist/utils/yaml-validation.js +156 -0
  64. package/dist/validation/spec-validation.js +81 -2
  65. package/package.json +2 -2
  66. package/templates/.caws/schemas/waivers.schema.json +30 -0
  67. package/templates/.caws/schemas/working-spec.schema.json +133 -0
  68. package/templates/.caws/templates/working-spec.template.yml +74 -0
  69. package/templates/.caws/tools/README.md +21 -0
  70. package/templates/.caws/tools/scope-guard.js +208 -0
  71. package/templates/.caws/tools-allow.json +331 -0
  72. package/templates/.caws/waivers.yml +19 -0
  73. package/templates/.cursor/hooks/scope-guard.sh +2 -2
  74. package/templates/.cursor/hooks/validate-spec.sh +42 -7
  75. package/dist/budget-derivation.d.ts +0 -74
  76. package/dist/budget-derivation.d.ts.map +0 -1
  77. package/dist/cicd-optimizer.d.ts +0 -142
  78. package/dist/cicd-optimizer.d.ts.map +0 -1
  79. package/dist/commands/archive.d.ts +0 -50
  80. package/dist/commands/archive.d.ts.map +0 -1
  81. package/dist/commands/burnup.d.ts +0 -6
  82. package/dist/commands/burnup.d.ts.map +0 -1
  83. package/dist/commands/diagnose.d.ts +0 -52
  84. package/dist/commands/diagnose.d.ts.map +0 -1
  85. package/dist/commands/evaluate.d.ts +0 -8
  86. package/dist/commands/evaluate.d.ts.map +0 -1
  87. package/dist/commands/init.d.ts +0 -5
  88. package/dist/commands/init.d.ts.map +0 -1
  89. package/dist/commands/iterate.d.ts +0 -8
  90. package/dist/commands/iterate.d.ts.map +0 -1
  91. package/dist/commands/mode.d.ts +0 -24
  92. package/dist/commands/mode.d.ts.map +0 -1
  93. package/dist/commands/plan.d.ts +0 -49
  94. package/dist/commands/plan.d.ts.map +0 -1
  95. package/dist/commands/provenance.d.ts +0 -32
  96. package/dist/commands/provenance.d.ts.map +0 -1
  97. package/dist/commands/quality-gates.d.ts +0 -52
  98. package/dist/commands/quality-gates.d.ts.map +0 -1
  99. package/dist/commands/quality-monitor.d.ts +0 -17
  100. package/dist/commands/quality-monitor.d.ts.map +0 -1
  101. package/dist/commands/specs.d.ts +0 -71
  102. package/dist/commands/specs.d.ts.map +0 -1
  103. package/dist/commands/status.d.ts +0 -44
  104. package/dist/commands/status.d.ts.map +0 -1
  105. package/dist/commands/templates.d.ts +0 -74
  106. package/dist/commands/templates.d.ts.map +0 -1
  107. package/dist/commands/tool.d.ts +0 -13
  108. package/dist/commands/tool.d.ts.map +0 -1
  109. package/dist/commands/troubleshoot.d.ts +0 -8
  110. package/dist/commands/troubleshoot.d.ts.map +0 -1
  111. package/dist/commands/tutorial.d.ts +0 -55
  112. package/dist/commands/tutorial.d.ts.map +0 -1
  113. package/dist/commands/validate.d.ts +0 -15
  114. package/dist/commands/validate.d.ts.map +0 -1
  115. package/dist/commands/waivers.d.ts +0 -8
  116. package/dist/commands/waivers.d.ts.map +0 -1
  117. package/dist/commands/workflow.d.ts +0 -85
  118. package/dist/commands/workflow.d.ts.map +0 -1
  119. package/dist/config/index.d.ts +0 -29
  120. package/dist/config/index.d.ts.map +0 -1
  121. package/dist/config/modes.d.ts +0 -225
  122. package/dist/config/modes.d.ts.map +0 -1
  123. package/dist/constants/spec-types.d.ts +0 -41
  124. package/dist/constants/spec-types.d.ts.map +0 -1
  125. package/dist/error-handler.d.ts +0 -164
  126. package/dist/error-handler.d.ts.map +0 -1
  127. package/dist/generators/jest-config.d.ts +0 -32
  128. package/dist/generators/jest-config.d.ts.map +0 -1
  129. package/dist/generators/working-spec.d.ts +0 -13
  130. package/dist/generators/working-spec.d.ts.map +0 -1
  131. package/dist/index-new.d.ts +0 -5
  132. package/dist/index-new.d.ts.map +0 -1
  133. package/dist/index-new.js +0 -317
  134. package/dist/index.d.ts +0 -5
  135. package/dist/index.d.ts.map +0 -1
  136. package/dist/index.js.backup +0 -4711
  137. package/dist/minimal-cli.d.ts +0 -3
  138. package/dist/minimal-cli.d.ts.map +0 -1
  139. package/dist/policy/PolicyManager.d.ts +0 -104
  140. package/dist/policy/PolicyManager.d.ts.map +0 -1
  141. package/dist/scaffold/cursor-hooks.d.ts +0 -7
  142. package/dist/scaffold/cursor-hooks.d.ts.map +0 -1
  143. package/dist/scaffold/git-hooks.d.ts +0 -20
  144. package/dist/scaffold/git-hooks.d.ts.map +0 -1
  145. package/dist/scaffold/index.d.ts +0 -20
  146. package/dist/scaffold/index.d.ts.map +0 -1
  147. package/dist/spec/SpecFileManager.d.ts +0 -146
  148. package/dist/spec/SpecFileManager.d.ts.map +0 -1
  149. package/dist/test-analysis.d.ts +0 -182
  150. package/dist/test-analysis.d.ts.map +0 -1
  151. package/dist/tool-interface.d.ts +0 -236
  152. package/dist/tool-interface.d.ts.map +0 -1
  153. package/dist/tool-loader.d.ts +0 -77
  154. package/dist/tool-loader.d.ts.map +0 -1
  155. package/dist/tool-validator.d.ts +0 -72
  156. package/dist/tool-validator.d.ts.map +0 -1
  157. package/dist/utils/detection.d.ts +0 -7
  158. package/dist/utils/detection.d.ts.map +0 -1
  159. package/dist/utils/finalization.d.ts +0 -17
  160. package/dist/utils/finalization.d.ts.map +0 -1
  161. package/dist/utils/project-analysis.d.ts +0 -14
  162. package/dist/utils/project-analysis.d.ts.map +0 -1
  163. package/dist/utils/quality-gates.d.ts +0 -49
  164. package/dist/utils/quality-gates.d.ts.map +0 -1
  165. package/dist/utils/spec-resolver.d.ts +0 -88
  166. package/dist/utils/spec-resolver.d.ts.map +0 -1
  167. package/dist/utils/typescript-detector.d.ts +0 -63
  168. package/dist/utils/typescript-detector.d.ts.map +0 -1
  169. package/dist/validation/spec-validation.d.ts +0 -43
  170. package/dist/validation/spec-validation.d.ts.map +0 -1
  171. package/dist/waivers-manager.d.ts +0 -167
  172. package/dist/waivers-manager.d.ts.map +0 -1
  173. package/templates/apps/tools/caws/COMPLETION_REPORT.md +0 -331
  174. package/templates/apps/tools/caws/MIGRATION_SUMMARY.md +0 -360
  175. package/templates/apps/tools/caws/README.md +0 -463
  176. package/templates/apps/tools/caws/TEST_STATUS.md +0 -365
  177. package/templates/apps/tools/caws/attest.js +0 -357
  178. package/templates/apps/tools/caws/ci-optimizer.js +0 -642
  179. package/templates/apps/tools/caws/config.ts +0 -245
  180. package/templates/apps/tools/caws/cross-functional.js +0 -876
  181. package/templates/apps/tools/caws/dashboard.js +0 -1112
  182. package/templates/apps/tools/caws/flake-detector.ts +0 -362
  183. package/templates/apps/tools/caws/gates.js +0 -198
  184. package/templates/apps/tools/caws/gates.ts +0 -271
  185. package/templates/apps/tools/caws/language-adapters.ts +0 -381
  186. package/templates/apps/tools/caws/language-support.d.ts +0 -367
  187. package/templates/apps/tools/caws/language-support.d.ts.map +0 -1
  188. package/templates/apps/tools/caws/language-support.js +0 -585
  189. package/templates/apps/tools/caws/legacy-assessment.ts +0 -408
  190. package/templates/apps/tools/caws/legacy-assessor.js +0 -764
  191. package/templates/apps/tools/caws/mutant-analyzer.js +0 -734
  192. package/templates/apps/tools/caws/perf-budgets.ts +0 -349
  193. package/templates/apps/tools/caws/prompt-lint.js.backup +0 -274
  194. package/templates/apps/tools/caws/property-testing.js +0 -707
  195. package/templates/apps/tools/caws/provenance.d.ts +0 -14
  196. package/templates/apps/tools/caws/provenance.d.ts.map +0 -1
  197. package/templates/apps/tools/caws/provenance.js +0 -132
  198. package/templates/apps/tools/caws/provenance.js.backup +0 -73
  199. package/templates/apps/tools/caws/provenance.ts +0 -211
  200. package/templates/apps/tools/caws/security-provenance.ts +0 -483
  201. package/templates/apps/tools/caws/shared/base-tool.ts +0 -281
  202. package/templates/apps/tools/caws/shared/config-manager.ts +0 -366
  203. package/templates/apps/tools/caws/shared/gate-checker.ts +0 -849
  204. package/templates/apps/tools/caws/shared/types.ts +0 -444
  205. package/templates/apps/tools/caws/shared/validator.ts +0 -305
  206. package/templates/apps/tools/caws/shared/waivers-manager.ts +0 -174
  207. package/templates/apps/tools/caws/spec-test-mapper.ts +0 -391
  208. package/templates/apps/tools/caws/test-quality.js +0 -578
  209. package/templates/apps/tools/caws/validate.js +0 -76
  210. package/templates/apps/tools/caws/validate.ts +0 -228
  211. package/templates/apps/tools/caws/waivers.js +0 -344
  212. /package/{templates/apps/tools/caws → dist/templates/.caws}/schemas/waivers.schema.json +0 -0
  213. /package/{templates/apps/tools/caws → dist/templates/.caws}/schemas/working-spec.schema.json +0 -0
  214. /package/{templates/apps/tools/caws → dist/templates/.caws}/templates/working-spec.template.yml +0 -0
  215. /package/{templates/apps/tools/caws → dist/templates/.caws/tools}/scope-guard.js +0 -0
  216. /package/{templates/apps/tools/caws → dist/templates/.caws}/tools-allow.json +0 -0
  217. /package/{templates/apps/tools/caws → dist/templates/.caws}/waivers.yml +0 -0
@@ -1,876 +0,0 @@
1
- #!/usr/bin/env node
2
-
3
- /**
4
- * @fileoverview CAWS Cross-Functional Integration Workflows
5
- * Facilitates collaboration between development, accessibility, UX, and product teams
6
- * @author @darianrosebrook
7
- */
8
-
9
- const fs = require('fs');
10
- const path = require('path');
11
-
12
- /**
13
- * Cross-functional stakeholder roles and responsibilities
14
- */
15
- const STAKEHOLDER_ROLES = {
16
- ACCESSIBILITY: {
17
- name: 'Accessibility Advocate',
18
- description: 'Ensures compliance with accessibility standards and guidelines',
19
- responsibilities: [
20
- 'Review accessibility requirements in working spec',
21
- 'Validate a11y test results and recommendations',
22
- 'Approve changes affecting user interface accessibility',
23
- 'Ensure WCAG compliance for Tier 1 features',
24
- ],
25
- sign_off_required: true,
26
- tier_requirement: [1, 2], // Required for Tier 1 and 2
27
- },
28
-
29
- UX_DESIGN: {
30
- name: 'UX Designer',
31
- description: 'Ensures user experience quality and design consistency',
32
- responsibilities: [
33
- 'Review UX requirements and user journey impact',
34
- 'Validate design system compliance',
35
- 'Approve UI/UX changes for Tier 1 features',
36
- 'Ensure responsive design across devices',
37
- ],
38
- sign_off_required: true,
39
- tier_requirement: [1], // Required for Tier 1 only
40
- },
41
-
42
- PRODUCT_MANAGER: {
43
- name: 'Product Manager',
44
- description: 'Ensures changes align with product strategy and user needs',
45
- responsibilities: [
46
- 'Review business requirements and user stories',
47
- 'Validate acceptance criteria alignment',
48
- 'Approve changes affecting core user workflows',
49
- 'Ensure feature completeness before release',
50
- ],
51
- sign_off_required: true,
52
- tier_requirement: [1, 2], // Required for Tier 1 and 2
53
- },
54
-
55
- SECURITY: {
56
- name: 'Security Engineer',
57
- description: 'Ensures security compliance and vulnerability mitigation',
58
- responsibilities: [
59
- 'Review security requirements and threat model',
60
- 'Validate security test results',
61
- 'Approve changes affecting authentication or data',
62
- 'Ensure compliance with security standards',
63
- ],
64
- sign_off_required: true,
65
- tier_requirement: [1], // Required for Tier 1 only
66
- },
67
-
68
- QA_LEAD: {
69
- name: 'QA Lead',
70
- description: 'Ensures comprehensive testing and quality standards',
71
- responsibilities: [
72
- 'Review test coverage and quality metrics',
73
- 'Validate testing strategy and edge case coverage',
74
- 'Approve release readiness for Tier 1 features',
75
- 'Ensure regression testing completeness',
76
- ],
77
- sign_off_required: false,
78
- tier_requirement: [1], // Optional for Tier 1, recommended
79
- },
80
-
81
- TECH_LEAD: {
82
- name: 'Technical Lead',
83
- description: 'Ensures technical excellence and architecture consistency',
84
- responsibilities: [
85
- 'Review technical implementation approach',
86
- 'Validate architecture and code quality',
87
- 'Approve complex refactoring or system changes',
88
- 'Ensure performance and scalability requirements',
89
- ],
90
- sign_off_required: false,
91
- tier_requirement: [1, 2], // Recommended for Tier 1 and 2
92
- },
93
- };
94
-
95
- /**
96
- * Generate cross-functional review checklist
97
- * @param {string} workingSpecPath - Path to working spec file
98
- * @param {number} tier - Risk tier (1, 2, or 3)
99
- * @returns {Object} Review checklist
100
- */
101
- function generateReviewChecklist(workingSpecPath, tier) {
102
- console.log(`šŸ“‹ Generating cross-functional review checklist for Tier ${tier}...`);
103
-
104
- let spec = null;
105
- try {
106
- const yaml = require('js-yaml');
107
- spec = yaml.load(fs.readFileSync(workingSpecPath, 'utf8'));
108
- } catch (error) {
109
- console.warn('āš ļø Could not load working spec for review checklist');
110
- }
111
-
112
- const checklist = {
113
- metadata: {
114
- generated_at: new Date().toISOString(),
115
- tier,
116
- project_id: spec?.id || 'unknown',
117
- project_title: spec?.title || 'unknown',
118
- },
119
-
120
- required_stakeholders: [],
121
- optional_stakeholders: [],
122
- review_items: {},
123
- sign_offs: {},
124
- status: 'pending',
125
- };
126
-
127
- // Determine required stakeholders based on tier
128
- Object.keys(STAKEHOLDER_ROLES).forEach((role) => {
129
- const roleInfo = STAKEHOLDER_ROLES[role];
130
-
131
- if (roleInfo.tier_requirement.includes(tier)) {
132
- checklist.required_stakeholders.push({
133
- role: roleInfo.name,
134
- description: roleInfo.description,
135
- required: roleInfo.sign_off_required,
136
- status: 'pending',
137
- assignee: null,
138
- comments: [],
139
- });
140
- } else {
141
- checklist.optional_stakeholders.push({
142
- role: roleInfo.name,
143
- description: roleInfo.description,
144
- required: false,
145
- status: 'not_required',
146
- assignee: null,
147
- comments: [],
148
- });
149
- }
150
- });
151
-
152
- // Generate review items based on working spec
153
- checklist.review_items = generateReviewItems(spec, tier);
154
-
155
- return checklist;
156
- }
157
-
158
- /**
159
- * Generate specific review items based on working spec content
160
- */
161
- function generateReviewItems(spec, tier) {
162
- const items = {};
163
-
164
- if (!spec) {
165
- return items;
166
- }
167
-
168
- // Accessibility review items
169
- items.accessibility = {
170
- title: 'Accessibility Compliance',
171
- category: 'ACCESSIBILITY',
172
- priority: 'high',
173
- items: [
174
- {
175
- id: 'a11y_requirements',
176
- question:
177
- 'Do the accessibility requirements in the working spec align with WCAG guidelines?',
178
- required: tier <= 2,
179
- status: 'pending',
180
- assignee: null,
181
- comments: [],
182
- },
183
- {
184
- id: 'a11y_testing',
185
- question: 'Are accessibility tests included and passing?',
186
- required: tier <= 2,
187
- status: 'pending',
188
- assignee: null,
189
- comments: [],
190
- },
191
- {
192
- id: 'keyboard_navigation',
193
- question: 'Does the change maintain keyboard navigation support?',
194
- required: tier <= 2,
195
- status: 'pending',
196
- assignee: null,
197
- comments: [],
198
- },
199
- ],
200
- };
201
-
202
- // UX design review items
203
- items.ux_design = {
204
- title: 'User Experience Quality',
205
- category: 'UX_DESIGN',
206
- priority: 'high',
207
- items: [
208
- {
209
- id: 'design_consistency',
210
- question: 'Does the change maintain design system consistency?',
211
- required: tier === 1,
212
- status: 'pending',
213
- assignee: null,
214
- comments: [],
215
- },
216
- {
217
- id: 'user_journey',
218
- question: 'Does the change preserve expected user workflows?',
219
- required: tier <= 2,
220
- status: 'pending',
221
- assignee: null,
222
- comments: [],
223
- },
224
- {
225
- id: 'responsive_design',
226
- question: 'Is the change responsive across all device sizes?',
227
- required: tier <= 2,
228
- status: 'pending',
229
- assignee: null,
230
- comments: [],
231
- },
232
- ],
233
- };
234
-
235
- // Product management review items
236
- items.product_management = {
237
- title: 'Product Alignment',
238
- category: 'PRODUCT_MANAGER',
239
- priority: 'high',
240
- items: [
241
- {
242
- id: 'business_requirements',
243
- question: 'Does the change fulfill the stated business requirements?',
244
- required: tier <= 2,
245
- status: 'pending',
246
- assignee: null,
247
- comments: [],
248
- },
249
- {
250
- id: 'acceptance_criteria',
251
- question: 'Do the acceptance criteria match the product requirements?',
252
- required: tier <= 2,
253
- status: 'pending',
254
- assignee: null,
255
- comments: [],
256
- },
257
- {
258
- id: 'user_impact',
259
- question: 'Has the user impact been properly assessed?',
260
- required: tier <= 2,
261
- status: 'pending',
262
- assignee: null,
263
- comments: [],
264
- },
265
- ],
266
- };
267
-
268
- // Security review items
269
- items.security = {
270
- title: 'Security Compliance',
271
- category: 'SECURITY',
272
- priority: 'critical',
273
- items: [
274
- {
275
- id: 'threat_model',
276
- question: 'Has the threat model been updated for this change?',
277
- required: tier === 1,
278
- status: 'pending',
279
- assignee: null,
280
- comments: [],
281
- },
282
- {
283
- id: 'security_tests',
284
- question: 'Are security tests passing and comprehensive?',
285
- required: tier === 1,
286
- status: 'pending',
287
- assignee: null,
288
- comments: [],
289
- },
290
- {
291
- id: 'data_handling',
292
- question: 'Does the change handle sensitive data appropriately?',
293
- required: tier <= 2,
294
- status: 'pending',
295
- assignee: null,
296
- comments: [],
297
- },
298
- ],
299
- };
300
-
301
- // Technical review items
302
- items.technical = {
303
- title: 'Technical Excellence',
304
- category: 'TECH_LEAD',
305
- priority: 'medium',
306
- items: [
307
- {
308
- id: 'architecture_impact',
309
- question: 'Does the change maintain architectural integrity?',
310
- required: tier <= 2,
311
- status: 'pending',
312
- assignee: null,
313
- comments: [],
314
- },
315
- {
316
- id: 'performance_impact',
317
- question: 'Has performance impact been assessed and is within budget?',
318
- required: tier <= 2,
319
- status: 'pending',
320
- assignee: null,
321
- comments: [],
322
- },
323
- {
324
- id: 'code_quality',
325
- question: 'Does the code meet quality standards (tests, documentation, style)?',
326
- required: true,
327
- status: 'pending',
328
- assignee: null,
329
- comments: [],
330
- },
331
- ],
332
- };
333
-
334
- // QA review items
335
- items.qa = {
336
- title: 'Quality Assurance',
337
- category: 'QA_LEAD',
338
- priority: 'medium',
339
- items: [
340
- {
341
- id: 'test_coverage',
342
- question: 'Is test coverage adequate for the risk level?',
343
- required: tier === 1,
344
- status: 'pending',
345
- assignee: null,
346
- comments: [],
347
- },
348
- {
349
- id: 'edge_cases',
350
- question: 'Have edge cases and error conditions been tested?',
351
- required: tier <= 2,
352
- status: 'pending',
353
- assignee: null,
354
- comments: [],
355
- },
356
- {
357
- id: 'regression_testing',
358
- question: 'Has regression testing been planned and executed?',
359
- required: tier <= 2,
360
- status: 'pending',
361
- assignee: null,
362
- comments: [],
363
- },
364
- ],
365
- };
366
-
367
- return items;
368
- }
369
-
370
- /**
371
- * Generate stakeholder notification templates
372
- * @param {Object} checklist - Review checklist
373
- * @returns {Object} Notification templates
374
- */
375
- function generateNotificationTemplates(checklist) {
376
- const templates = {};
377
-
378
- // Generate notification for each required stakeholder
379
- checklist.required_stakeholders.forEach((stakeholder) => {
380
- const role = stakeholder.role.toLowerCase().replace(/\s+/g, '_');
381
-
382
- templates[role] = {
383
- subject: `CAWS Review Request: ${checklist.metadata.project_title} (Tier ${checklist.metadata.tier})`,
384
- body: `Dear ${stakeholder.role},
385
-
386
- A new change requires your review as part of the CAWS (Coding Agent Workflow System) process.
387
-
388
- **Project Details:**
389
- - Project ID: ${checklist.metadata.project_id}
390
- - Title: ${checklist.metadata.project_title}
391
- - Risk Tier: ${checklist.metadata.tier}
392
- - Generated: ${new Date(checklist.metadata.generated_at).toLocaleString()}
393
-
394
- **Your Responsibilities:**
395
- ${STAKEHOLDER_ROLES[stakeholder.role.toUpperCase().replace(/\s+/g, '_')]?.responsibilities.map((resp) => `- ${resp}`).join('\n') || 'Review the proposed changes for compliance with your area of expertise.'}
396
-
397
- **Review Items:**
398
- ${
399
- Object.values(checklist.review_items)
400
- .filter((item) => item.category === stakeholder.role.toUpperCase().replace(/\s+/g, '_'))
401
- .flatMap((item) => item.items)
402
- .map((reviewItem) => `- ${reviewItem.question}`)
403
- .join('\n') || 'Please review the change for general compliance.'
404
- }
405
-
406
- **Next Steps:**
407
- 1. Review the working spec and implementation
408
- 2. Provide feedback or approval in the PR comments
409
- 3. Update your review status in the checklist
410
-
411
- **Timeline:**
412
- Please complete your review within 2 business days for Tier ${checklist.metadata.tier} changes.
413
-
414
- **Resources:**
415
- - Working Spec: .caws/working-spec.yaml
416
- - CAWS Documentation: [Link to CAWS docs]
417
- - Dashboard: [Link to CAWS dashboard]
418
-
419
- Thank you for your expertise in ensuring the quality and safety of our codebase.
420
-
421
- Best regards,
422
- CAWS Automation System`,
423
- };
424
- });
425
-
426
- return templates;
427
- }
428
-
429
- /**
430
- * Generate integration workflow configuration
431
- * @param {Object} checklist - Review checklist
432
- * @param {string} outputDir - Output directory for workflow files
433
- */
434
- function generateIntegrationWorkflow(checklist, outputDir = '.github/workflows') {
435
- const workflow = {
436
- name: 'CAWS Cross-Functional Review',
437
- on: {
438
- pull_request: {
439
- types: ['opened', 'synchronize', 'reopened'],
440
- paths: ['.caws/working-spec.yaml'],
441
- },
442
- },
443
- jobs: {
444
- cross_functional_review: {
445
- 'runs-on': 'ubuntu-latest',
446
- steps: [
447
- {
448
- name: 'Checkout code',
449
- uses: 'actions/checkout@v4',
450
- },
451
- {
452
- name: 'Generate review checklist',
453
- run: 'node apps/tools/caws/cross-functional.js generate-checklist .caws/working-spec.yaml',
454
- },
455
- {
456
- name: 'Notify stakeholders',
457
- run: generateNotificationScript(checklist),
458
- },
459
- {
460
- name: 'Wait for approvals',
461
- run: generateApprovalWaitScript(checklist),
462
- timeout: '2d',
463
- },
464
- ],
465
- },
466
- },
467
- };
468
-
469
- // Ensure output directory exists
470
- if (!fs.existsSync(outputDir)) {
471
- fs.mkdirSync(outputDir, { recursive: true });
472
- }
473
-
474
- const workflowPath = path.join(outputDir, 'caws-cross-functional-review.yml');
475
- fs.writeFileSync(
476
- workflowPath,
477
- `# Generated by CAWS Cross-Functional Tool\n${JSON.stringify(workflow, null, 2)}`
478
- );
479
-
480
- console.log(`āœ… Generated cross-functional review workflow: ${workflowPath}`);
481
- }
482
-
483
- /**
484
- * Generate notification script for workflow
485
- */
486
- function generateNotificationScript(_checklist) {
487
- return `
488
- # Generate and send notifications to required stakeholders
489
- node apps/tools/caws/cross-functional.js notify-stakeholders review-checklist.json
490
- `;
491
- }
492
-
493
- /**
494
- * Generate approval wait script for workflow
495
- */
496
- function generateApprovalWaitScript(_checklist) {
497
- return `
498
- # Wait for all required stakeholders to approve
499
- node apps/tools/caws/cross-functional.js wait-for-approvals review-checklist.json
500
- `;
501
- }
502
-
503
- /**
504
- * Create stakeholder onboarding guide
505
- * @param {string} outputPath - Output path for guide
506
- */
507
- function generateStakeholderGuide(outputPath = 'CAWS_STAKEHOLDER_GUIDE.md') {
508
- const guide = `# CAWS Cross-Functional Stakeholder Guide
509
-
510
- This guide explains how different roles participate in the CAWS (Coding Agent Workflow System) process.
511
-
512
- ## Overview
513
-
514
- CAWS ensures that AI-assisted development meets senior-engineer-level quality standards through structured review processes involving multiple stakeholders.
515
-
516
- ## Stakeholder Roles and Responsibilities
517
-
518
- ### Accessibility Advocate
519
- **When Involved:** Tier 1 and 2 changes affecting user interfaces
520
-
521
- **Responsibilities:**
522
- - Review accessibility requirements in working spec
523
- - Validate a11y test results and axe-core reports
524
- - Ensure WCAG 2.1 AA compliance
525
- - Approve keyboard navigation and screen reader support
526
-
527
- **Review Focus:**
528
- - Color contrast ratios
529
- - Keyboard navigation paths
530
- - Screen reader compatibility
531
- - Focus management
532
- - Alternative text for images
533
-
534
- ### UX Designer
535
- **When Involved:** Tier 1 changes with UI/UX impact
536
-
537
- **Responsibilities:**
538
- - Review design system compliance
539
- - Validate user journey preservation
540
- - Ensure responsive design across devices
541
- - Approve visual consistency
542
-
543
- **Review Focus:**
544
- - Design system component usage
545
- - User flow consistency
546
- - Responsive breakpoints
547
- - Visual hierarchy
548
- - Brand consistency
549
-
550
- ### Product Manager
551
- **When Involved:** Tier 1 and 2 changes with business impact
552
-
553
- **Responsibilities:**
554
- - Review business requirement alignment
555
- - Validate acceptance criteria completeness
556
- - Ensure feature meets user needs
557
- - Approve release readiness
558
-
559
- **Review Focus:**
560
- - Business requirement fulfillment
561
- - Acceptance criteria accuracy
562
- - User story completeness
563
- - Impact on user workflows
564
-
565
- ### Security Engineer
566
- **When Involved:** Tier 1 changes affecting security
567
-
568
- **Responsibilities:**
569
- - Review threat model updates
570
- - Validate security test results
571
- - Ensure secure coding practices
572
- - Approve authentication/authorization changes
573
-
574
- **Review Focus:**
575
- - Authentication mechanisms
576
- - Data protection measures
577
- - Input validation
578
- - Security test coverage
579
-
580
- ### Technical Lead
581
- **When Involved:** Tier 1 and 2 changes with architectural impact
582
-
583
- **Responsibilities:**
584
- - Review technical implementation approach
585
- - Validate architecture consistency
586
- - Ensure performance requirements
587
- - Approve complex refactoring
588
-
589
- **Review Focus:**
590
- - Code architecture patterns
591
- - Performance implications
592
- - Scalability considerations
593
- - Technical debt impact
594
-
595
- ### QA Lead
596
- **When Involved:** Tier 1 changes requiring comprehensive testing
597
-
598
- **Responsibilities:**
599
- - Review test coverage adequacy
600
- - Validate testing strategy
601
- - Ensure edge case coverage
602
- - Approve release testing
603
-
604
- **Review Focus:**
605
- - Test coverage metrics
606
- - Edge case testing
607
- - Regression test strategy
608
- - Test automation quality
609
-
610
- ## Review Process
611
-
612
- ### 1. Notification
613
- When a PR is created or updated with a working spec, stakeholders are automatically notified based on:
614
- - Risk tier of the change
615
- - Areas affected by the change
616
- - Stakeholder expertise areas
617
-
618
- ### 2. Review
619
- Stakeholders review the change against their area of expertise:
620
- - Read the working spec requirements
621
- - Examine the implementation
622
- - Run relevant tests or checks
623
- - Provide feedback or approval
624
-
625
- ### 3. Sign-off
626
- Required stakeholders must provide explicit approval:
627
- - Comment with approval status
628
- - Include rationale for decisions
629
- - Suggest improvements if needed
630
-
631
- ### 4. Escalation
632
- If stakeholders cannot reach consensus:
633
- - Tech lead arbitration for technical issues
634
- - Product manager decision for business issues
635
- - Security team override for security concerns
636
-
637
- ## Tools and Resources
638
-
639
- ### CAWS Dashboard
640
- Access the CAWS dashboard to view:
641
- - Current trust scores and metrics
642
- - Historical trends and insights
643
- - Actionable recommendations
644
- - Risk distribution across tiers
645
-
646
- ### Review Checklist
647
- Each review includes a structured checklist covering:
648
- - Specific questions for your area of expertise
649
- - Required vs optional review items
650
- - Status tracking and comments
651
-
652
- ### Working Spec
653
- The working spec contains:
654
- - Detailed requirements and constraints
655
- - Risk assessment and mitigation
656
- - Test plans and acceptance criteria
657
- - Rollback and migration strategies
658
-
659
- ## Best Practices
660
-
661
- ### For Reviewers
662
- 1. **Review early and often** - Catch issues before they become problems
663
- 2. **Be specific** - Provide concrete feedback and suggestions
664
- 3. **Test your assumptions** - Verify that requirements are testable
665
- 4. **Consider edge cases** - Think about error conditions and unusual scenarios
666
- 5. **Document decisions** - Explain why you approve or reject changes
667
-
668
- ### For Developers
669
- 1. **Involve stakeholders early** - Get input during planning phase
670
- 2. **Provide context** - Explain the "why" behind changes
671
- 3. **Respond to feedback** - Address concerns promptly and thoroughly
672
- 4. **Update documentation** - Keep working specs current
673
- 5. **Test thoroughly** - Ensure changes work as expected
674
-
675
- ## Emergency Procedures
676
-
677
- ### Hotfixes and Urgent Changes
678
- For critical issues requiring immediate deployment:
679
- 1. Create minimal working spec with \`human_override\` section
680
- 2. Notify stakeholders after deployment if time-critical
681
- 3. Complete full review process post-deployment
682
- 4. Address any identified issues in follow-up PR
683
-
684
- ### Rollback Situations
685
- If a deployment causes issues:
686
- 1. Follow the rollback plan in the working spec
687
- 2. Notify all stakeholders immediately
688
- 3. Conduct root cause analysis
689
- 4. Update working spec for future prevention
690
-
691
- ## Support and Training
692
-
693
- ### Getting Help
694
- - CAWS Documentation: [Link to full CAWS docs]
695
- - Stakeholder Slack Channel: #caws-stakeholders
696
- - Office Hours: Weekly Q&A sessions with CAWS team
697
-
698
- ### Training Resources
699
- - CAWS Overview Presentation
700
- - Role-specific training modules
701
- - Hands-on workshops and examples
702
- - Best practices and anti-patterns guide
703
-
704
- ## Continuous Improvement
705
-
706
- CAWS evolves based on stakeholder feedback:
707
- - Regular retrospectives on review process
708
- - Metric tracking for review effectiveness
709
- - Process improvements based on lessons learned
710
- - Tool enhancements for better collaboration
711
-
712
- ---
713
-
714
- *This guide is automatically generated and maintained by the CAWS Cross-Functional Integration Tool.*
715
- `;
716
-
717
- fs.writeFileSync(outputPath, guide);
718
- console.log(`āœ… Generated stakeholder guide: ${outputPath}`);
719
- }
720
-
721
- /**
722
- * Validate stakeholder assignments and notify if needed
723
- * @param {Object} checklist - Review checklist
724
- */
725
- function validateStakeholderAssignments(checklist) {
726
- console.log('šŸ” Validating stakeholder assignments...');
727
-
728
- const issues = [];
729
- const missingAssignments = [];
730
-
731
- // Check required stakeholders
732
- checklist.required_stakeholders.forEach((stakeholder) => {
733
- if (!stakeholder.assignee) {
734
- missingAssignments.push(stakeholder.role);
735
- issues.push(`Missing assignee for ${stakeholder.role}`);
736
- }
737
- });
738
-
739
- // Check for overdue reviews
740
- const now = new Date();
741
- const twoDaysAgo = new Date(now.getTime() - 2 * 24 * 60 * 60 * 1000);
742
-
743
- checklist.required_stakeholders.forEach((stakeholder) => {
744
- if (stakeholder.status === 'pending' && stakeholder.assigned_at) {
745
- const assignedAt = new Date(stakeholder.assigned_at);
746
- if (assignedAt < twoDaysAgo) {
747
- issues.push(
748
- `${stakeholder.role} review is overdue (assigned ${assignedAt.toLocaleDateString()})`
749
- );
750
- }
751
- }
752
- });
753
-
754
- if (issues.length > 0) {
755
- console.warn('\nāš ļø Review Issues Found:');
756
- issues.forEach((issue) => console.warn(` - ${issue}`));
757
-
758
- if (missingAssignments.length > 0) {
759
- console.log('\nšŸ“§ To assign reviewers:');
760
- missingAssignments.forEach((role) => {
761
- console.log(` - Assign ${role} via PR comment or GitHub assignment`);
762
- });
763
- }
764
-
765
- return false;
766
- }
767
-
768
- console.log('āœ… All stakeholder assignments are valid');
769
- return true;
770
- }
771
-
772
- // CLI interface
773
- if (require.main === module) {
774
- const command = process.argv[2];
775
-
776
- switch (command) {
777
- case 'generate-checklist':
778
- const specPath = process.argv[3] || '.caws/working-spec.yaml';
779
- const tier = parseInt(process.argv[4]) || 2;
780
-
781
- if (!fs.existsSync(specPath)) {
782
- console.error(`āŒ Working spec not found: ${specPath}`);
783
- process.exit(1);
784
- }
785
-
786
- try {
787
- const checklist = generateReviewChecklist(specPath, tier);
788
-
789
- console.log('\nšŸ“‹ Generated Cross-Functional Review Checklist:');
790
- console.log(` Project: ${checklist.metadata.project_title}`);
791
- console.log(` Tier: ${tier}`);
792
- console.log(` Required Stakeholders: ${checklist.required_stakeholders.length}`);
793
- console.log(` Optional Stakeholders: ${checklist.optional_stakeholders.length}`);
794
-
795
- // Save checklist
796
- const checklistPath = 'review-checklist.json';
797
- fs.writeFileSync(checklistPath, JSON.stringify(checklist, null, 2));
798
- console.log(`āœ… Checklist saved: ${checklistPath}`);
799
-
800
- // Generate workflow
801
- generateIntegrationWorkflow(checklist);
802
- } catch (error) {
803
- console.error(`āŒ Error generating checklist: ${error.message}`);
804
- process.exit(1);
805
- }
806
- break;
807
-
808
- case 'generate-guide':
809
- const guidePath = process.argv[3] || 'CAWS_STAKEHOLDER_GUIDE.md';
810
-
811
- try {
812
- generateStakeholderGuide(guidePath);
813
- console.log('\nšŸ“– Generated comprehensive stakeholder guide');
814
- console.log(' Guide includes:');
815
- console.log(' - Role definitions and responsibilities');
816
- console.log(' - Review process and best practices');
817
- console.log(' - Tools and resources');
818
- console.log(' - Emergency procedures');
819
- } catch (error) {
820
- console.error(`āŒ Error generating guide: ${error.message}`);
821
- process.exit(1);
822
- }
823
- break;
824
-
825
- case 'validate-assignments':
826
- const checklistPath = process.argv[3] || 'review-checklist.json';
827
-
828
- if (!fs.existsSync(checklistPath)) {
829
- console.error(`āŒ Checklist not found: ${checklistPath}`);
830
- process.exit(1);
831
- }
832
-
833
- try {
834
- const checklist = JSON.parse(fs.readFileSync(checklistPath, 'utf8'));
835
- const isValid = validateStakeholderAssignments(checklist);
836
-
837
- if (isValid) {
838
- console.log('āœ… All stakeholder assignments are complete and current');
839
- } else {
840
- console.error('āŒ Stakeholder assignment issues found');
841
- process.exit(1);
842
- }
843
- } catch (error) {
844
- console.error(`āŒ Error validating assignments: ${error.message}`);
845
- process.exit(1);
846
- }
847
- break;
848
-
849
- default:
850
- console.log('CAWS Cross-Functional Integration Tool');
851
- console.log('Usage:');
852
- console.log(' node cross-functional.js generate-checklist [spec-path] [tier]');
853
- console.log(' node cross-functional.js generate-guide [output-path]');
854
- console.log(' node cross-functional.js validate-assignments [checklist-path]');
855
- console.log('');
856
- console.log('Stakeholder Roles:');
857
- Object.values(STAKEHOLDER_ROLES).forEach((role) => {
858
- console.log(` - ${role.name}: ${role.description}`);
859
- });
860
- console.log('');
861
- console.log('Examples:');
862
- console.log(' node cross-functional.js generate-checklist .caws/working-spec.yaml 1');
863
- console.log(' node cross-functional.js generate-guide docs/CAWS_STAKEHOLDER_GUIDE.md');
864
- console.log(' node cross-functional.js validate-assignments review-checklist.json');
865
- process.exit(1);
866
- }
867
- }
868
-
869
- module.exports = {
870
- generateReviewChecklist,
871
- generateNotificationTemplates,
872
- generateIntegrationWorkflow,
873
- generateStakeholderGuide,
874
- validateStakeholderAssignments,
875
- STAKEHOLDER_ROLES,
876
- };