codymaster 4.1.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 (193) hide show
  1. package/CHANGELOG.md +50 -0
  2. package/README.md +285 -0
  3. package/adapters/antigravity.js +15 -0
  4. package/adapters/claude-code.js +17 -0
  5. package/adapters/cursor.js +16 -0
  6. package/commands/bootstrap.md +49 -0
  7. package/commands/build.md +48 -0
  8. package/commands/content.md +48 -0
  9. package/commands/continuity.md +60 -0
  10. package/commands/debug.md +51 -0
  11. package/commands/demo.md +96 -0
  12. package/commands/deploy.md +51 -0
  13. package/commands/plan.md +42 -0
  14. package/commands/review.md +55 -0
  15. package/commands/track.md +46 -0
  16. package/commands/ux.md +46 -0
  17. package/dist/agent-dispatch.js +161 -0
  18. package/dist/chains/builtin.js +85 -0
  19. package/dist/continuity.js +385 -0
  20. package/dist/dashboard.js +926 -0
  21. package/dist/data.js +122 -0
  22. package/dist/index.js +2434 -0
  23. package/dist/judge.js +252 -0
  24. package/dist/parallel-dispatch.js +359 -0
  25. package/dist/parallel-quality.js +172 -0
  26. package/dist/skill-chain.js +258 -0
  27. package/install.sh +513 -0
  28. package/package.json +79 -0
  29. package/skills/.content-factory-state.json +132 -0
  30. package/skills/.git 2/logs/refs/heads/main +1 -0
  31. package/skills/.git 2/logs/refs/remotes/origin/main +1 -0
  32. package/skills/.git 2/objects/02/fb0956734b5f8ba3f918b7defd04a89cfe0076 +0 -0
  33. package/skills/.git 2/objects/08/1e129d75dc6feac6c02037272e6bd1a04e3324 +0 -0
  34. package/skills/.git 2/objects/0c/5393416f3c5e01c9a655a802bff0dd52f76f0a +0 -0
  35. package/skills/.git 2/objects/10/0b9be46978a946a77188f68be725098a122001 +0 -0
  36. package/skills/.git 2/objects/10/cf041167fc9843610eb3d90259ef3396315fdc +0 -0
  37. package/skills/.git 2/objects/12/5e19538dd6e1338ffe74f6c4c165b00435bf48 +0 -0
  38. package/skills/.git 2/objects/16/a9b9d0088d5c1347628b45a2620b479d8ad57c +0 -0
  39. package/skills/.git 2/objects/17/8c2a9ef93c33ae4eec9d58e82321f9229843a1 +0 -0
  40. package/skills/.git 2/objects/25/397ae41d09104d763bdcac2695209d85cdea89 +0 -0
  41. package/skills/.git 2/objects/2f/a836b7947f2d458e1f639788bf4bb0983a3305 +0 -0
  42. package/skills/.git 2/objects/3a/baaaf0a1c0909c0828335791557125fba911e0 +0 -0
  43. package/skills/.git 2/objects/42/2924221b81f5ce3c4e4daac9a64a24f9b01f9a +0 -0
  44. package/skills/.git 2/objects/42/ec0ce707447dc11446a34c9995fb8533801731 +0 -0
  45. package/skills/.git 2/objects/46/e43ce92866d56ce74b1d750db307cfe6154a15 +0 -0
  46. package/skills/.git 2/objects/48/5e41b633c63f55b8277bcc59f44f67681f671a +0 -0
  47. package/skills/.git 2/objects/49/49c596a3a89fa240642acd95dd3258e261eb09 +0 -0
  48. package/skills/.git 2/objects/50/9d42d8412ef8eaf7f7e138476bac2e4d10ce60 +0 -0
  49. package/skills/.git 2/objects/55/0c8c389d981b463ef849aeb792d8be3ccb6ec8 +0 -0
  50. package/skills/.git 2/objects/5d/82d3b18410cdda3ace3677436f0cb599dbe2d2 +0 -0
  51. package/skills/.git 2/objects/60/0617c58e871a38b33bf29e282d132bb3c381ad +0 -0
  52. package/skills/.git 2/objects/6a/8369a99c687b7245c92ffaf0e0f0dab9014504 +0 -0
  53. package/skills/.git 2/objects/79/bea435d40ab531c1aaf6be0432c6a5b7aaed21 +0 -0
  54. package/skills/.git 2/objects/7e/5ebd79251c2f14e4aceb86c74b6b6daae6b500 +0 -0
  55. package/skills/.git 2/objects/81/98a822a60178d6d5023ddb3e222cddf048742e +0 -0
  56. package/skills/.git 2/objects/86/0a0e1943dfe53411d2e499a1f16f46a96ef758 +0 -0
  57. package/skills/.git 2/objects/86/971fb55fdc081fdbae52376f0f13e57a4e9b04 +0 -0
  58. package/skills/.git 2/objects/88/b89dd609a0a03f8d4fe8bfde20d5b8fc1d326d +0 -0
  59. package/skills/.git 2/objects/90/8737edb6b7809e32cc01590b4e08ba42a9d40d +0 -0
  60. package/skills/.git 2/objects/93/d5a8a9a7d4fb7f11491cb596a6880528725118 +0 -0
  61. package/skills/.git 2/objects/98/46a2ab81d0c3b3eb00ef88fc56989aa7e9f316 +0 -0
  62. package/skills/.git 2/objects/9b/d8dd1e49cf274eaf9c555f3ab39dce7af5715e +0 -0
  63. package/skills/.git 2/objects/a1/13329fb0cec96ae78b222d33a24c3b5bc7fa1f +0 -0
  64. package/skills/.git 2/objects/a9/e6effe626e8a3aea3a8fc3364b492191c6e7d0 +0 -0
  65. package/skills/.git 2/objects/ad/6de7e48d9782cca9353d1ff0aa1aab7fe1df85 +0 -0
  66. package/skills/.git 2/objects/af/54ae316f771ff692e299ffcd8bf2f06b413b59 +0 -0
  67. package/skills/.git 2/objects/b0/4cb8b0b00dad633e731c1472161419e738d674 +0 -0
  68. package/skills/.git 2/objects/b3/094abb0b9ed46419b269e4a4e36a459690e3b0 +0 -0
  69. package/skills/.git 2/objects/b9/435c5d4baac2cfc5c83009ddd27b46b60db5f1 +0 -0
  70. package/skills/.git 2/objects/ba/5da17dbaec5ec2dcfdfd126aead518d1171d5c +0 -0
  71. package/skills/.git 2/objects/c0/bf58703aa258ba5dd63083bebaec8f223d844c +0 -0
  72. package/skills/.git 2/objects/c4/701a34edf1fc1bad58ccc57bd03f9426acb59a +0 -0
  73. package/skills/.git 2/objects/c7/5ccce9a4e5cc74d9b3174550cf6d993ca43638 +0 -0
  74. package/skills/.git 2/objects/c7/710d59b5a35b0f1f0a0399386643a0bd94c929 +0 -0
  75. package/skills/.git 2/objects/d1/fe58237112e953e5fec52da22cf38e08be3df9 +5 -0
  76. package/skills/.git 2/objects/d2/2bbe9fd2f74c95bc5583e803f5e435f1e2cd86 +0 -0
  77. package/skills/.git 2/objects/d7/e72852ea2bff74581dbf247d400120086229f4 +0 -0
  78. package/skills/.git 2/objects/d8/d4c3b5553e4fd72807e1d4b49ef07d9ef3ac35 +0 -0
  79. package/skills/.git 2/objects/dc/75050c2876f6a02ae2a53a3c886f395b622977 +0 -0
  80. package/skills/.git 2/objects/ee/e8546f95acec500187c08a28a8b9ee02db0dec +0 -0
  81. package/skills/.git 2/objects/ef/263c059208b416c2146434f10cb2b9fabcba16 +0 -0
  82. package/skills/.git 2/objects/f3/ae597e84d9a59b88acd21c99bde2eaf686d785 +0 -0
  83. package/skills/.git 2/objects/f3/f6f5673c821d3d8e76fa267a9e882e7a5387ea +0 -0
  84. package/skills/.git 2/objects/f9/6e6d0ad02624dd11d5848594d056caef7a5e8b +0 -0
  85. package/skills/.git 2/objects/ff/278988fc1edf0db3abcf18de795f4cc0b4f3e1 +0 -0
  86. package/skills/.git 2/refs/heads/main +1 -0
  87. package/skills/.git 2/refs/remotes/origin/main +1 -0
  88. package/skills/.pytest_cache 2/v/cache/nodeids +76 -0
  89. package/skills/.pytest_cache 2/v/cache/stepwise +1 -0
  90. package/skills/_shared/helpers.md +123 -0
  91. package/skills/_shared/outputs-convention.md +24 -0
  92. package/skills/cm-ads-tracker/SKILL.md +109 -0
  93. package/skills/cm-ads-tracker/evals/evals.json +55 -0
  94. package/skills/cm-ads-tracker/references/gtm-architecture.md +321 -0
  95. package/skills/cm-ads-tracker/references/industry-events.md +294 -0
  96. package/skills/cm-ads-tracker/references/platforms-api.md +238 -0
  97. package/skills/cm-ads-tracker/templates/capi-payload.md +79 -0
  98. package/skills/cm-ads-tracker/templates/datalayer-push.js +104 -0
  99. package/skills/cm-ads-tracker/templates/gtm-variables.js +56 -0
  100. package/skills/cm-brainstorm-idea/SKILL.md +423 -0
  101. package/skills/cm-code-review/SKILL.md +151 -0
  102. package/skills/cm-content-factory/SKILL.md +416 -0
  103. package/skills/cm-continuity/SKILL.md +399 -0
  104. package/skills/cm-dashboard/SKILL.md +533 -0
  105. package/skills/cm-dashboard/ui/app.js +1270 -0
  106. package/skills/cm-dashboard/ui/index.html +206 -0
  107. package/skills/cm-dashboard/ui/style.css +440 -0
  108. package/skills/cm-debugging/SKILL.md +412 -0
  109. package/skills/cm-deep-search/SKILL.md +242 -0
  110. package/skills/cm-design-system/SKILL.md +97 -0
  111. package/skills/cm-design-system/resources/halo-modern.md +40 -0
  112. package/skills/cm-design-system/resources/lunaris-advanced.md +40 -0
  113. package/skills/cm-design-system/resources/nitro-enterprise.md +39 -0
  114. package/skills/cm-design-system/resources/shadcn-default.md +37 -0
  115. package/skills/cm-dockit/README.md +100 -0
  116. package/skills/cm-dockit/SKILL.md +302 -0
  117. package/skills/cm-dockit/index.html +443 -0
  118. package/skills/cm-dockit/package-lock.json +1850 -0
  119. package/skills/cm-dockit/package.json +14 -0
  120. package/skills/cm-dockit/prompts/analysis.md +34 -0
  121. package/skills/cm-dockit/prompts/api-reference.md +24 -0
  122. package/skills/cm-dockit/prompts/architecture.md +21 -0
  123. package/skills/cm-dockit/prompts/data-flow.md +20 -0
  124. package/skills/cm-dockit/prompts/database.md +21 -0
  125. package/skills/cm-dockit/prompts/deployment.md +22 -0
  126. package/skills/cm-dockit/prompts/flows.md +21 -0
  127. package/skills/cm-dockit/prompts/jtbd.md +20 -0
  128. package/skills/cm-dockit/prompts/personas.md +24 -0
  129. package/skills/cm-dockit/prompts/sop-modules.md +40 -0
  130. package/skills/cm-dockit/scripts/doc-gen.sh +121 -0
  131. package/skills/cm-dockit/scripts/dockit-dashboard.sh +142 -0
  132. package/skills/cm-dockit/scripts/dockit-runner.sh +607 -0
  133. package/skills/cm-dockit/scripts/dockit-task.sh +166 -0
  134. package/skills/cm-dockit/skills/analyze-codebase.md +174 -0
  135. package/skills/cm-dockit/skills/api-reference.md +237 -0
  136. package/skills/cm-dockit/skills/changelog-guide.md +195 -0
  137. package/skills/cm-dockit/skills/content-guidelines.md +190 -0
  138. package/skills/cm-dockit/skills/sop-guide.md +184 -0
  139. package/skills/cm-dockit/skills/tech-docs.md +287 -0
  140. package/skills/cm-dockit/templates/markdown/structure.md +60 -0
  141. package/skills/cm-dockit/templates/vitepress-premium/.vitepress/config.mts +110 -0
  142. package/skills/cm-dockit/templates/vitepress-premium/.vitepress/theme/custom.css +189 -0
  143. package/skills/cm-dockit/templates/vitepress-premium/.vitepress/theme/index.ts +4 -0
  144. package/skills/cm-dockit/templates/vitepress-premium/package.json +19 -0
  145. package/skills/cm-dockit/templates/vitepress-premium/tests/frontend.test.ts +45 -0
  146. package/skills/cm-dockit/tests/runner.test.ts +66 -0
  147. package/skills/cm-dockit/workflows/export-markdown.md +82 -0
  148. package/skills/cm-dockit/workflows/generate-docs.md +68 -0
  149. package/skills/cm-dockit/workflows/setup-vitepress.md +181 -0
  150. package/skills/cm-example/SKILL.md +26 -0
  151. package/skills/cm-execution/SKILL.md +268 -0
  152. package/skills/cm-git-worktrees/SKILL.md +164 -0
  153. package/skills/cm-how-it-work/SKILL.md +189 -0
  154. package/skills/cm-identity-guard/SKILL.md +412 -0
  155. package/skills/cm-jtbd/SKILL.md +98 -0
  156. package/skills/cm-planning/SKILL.md +130 -0
  157. package/skills/cm-project-bootstrap/SKILL.md +161 -0
  158. package/skills/cm-project-bootstrap/templates/AGENTS.md +42 -0
  159. package/skills/cm-project-bootstrap/templates/frontend-safety.test.js +51 -0
  160. package/skills/cm-project-bootstrap/templates/i18n-sync.test.js +38 -0
  161. package/skills/cm-project-bootstrap/templates/pr-template.md +12 -0
  162. package/skills/cm-project-bootstrap/templates/project-identity.json +29 -0
  163. package/skills/cm-project-bootstrap/templates/vitest.config.js +10 -0
  164. package/skills/cm-quality-gate/SKILL.md +218 -0
  165. package/skills/cm-readit/SKILL.md +289 -0
  166. package/skills/cm-readit/audio-player.md +206 -0
  167. package/skills/cm-readit/examples/blog-reader.js +352 -0
  168. package/skills/cm-readit/examples/voice-cro.js +390 -0
  169. package/skills/cm-readit/tts-engine.md +262 -0
  170. package/skills/cm-readit/ui-patterns.md +362 -0
  171. package/skills/cm-readit/voice-cro.md +223 -0
  172. package/skills/cm-safe-deploy/SKILL.md +120 -0
  173. package/skills/cm-safe-deploy/templates/deploy.sh +89 -0
  174. package/skills/cm-safe-i18n/SKILL.md +473 -0
  175. package/skills/cm-secret-shield/SKILL.md +580 -0
  176. package/skills/cm-skill-chain/SKILL.md +78 -0
  177. package/skills/cm-skill-index/SKILL.md +318 -0
  178. package/skills/cm-skill-mastery/SKILL.md +169 -0
  179. package/skills/cm-start/SKILL.md +65 -0
  180. package/skills/cm-status/SKILL.md +12 -0
  181. package/skills/cm-tdd/SKILL.md +370 -0
  182. package/skills/cm-terminal/SKILL.md +177 -0
  183. package/skills/cm-test-gate/SKILL.md +242 -0
  184. package/skills/cm-ui-preview/SKILL.md +291 -0
  185. package/skills/cm-ux-master/DESIGN_STANDARD_TEMPLATE.md +54 -0
  186. package/skills/cm-ux-master/SKILL.md +114 -0
  187. package/skills/cro-methodology/SKILL.md +98 -0
  188. package/skills/cro-methodology/references/COPYWRITING.md +178 -0
  189. package/skills/cro-methodology/references/OBJECTIONS.md +135 -0
  190. package/skills/cro-methodology/references/PERSUASION.md +158 -0
  191. package/skills/cro-methodology/references/RESEARCH.md +220 -0
  192. package/skills/cro-methodology/references/funnel-analysis.md +365 -0
  193. package/skills/cro-methodology/references/testing-methodology.md +330 -0
@@ -0,0 +1,242 @@
1
+ ---
2
+ name: cm-test-gate
3
+ description: Complete guide to setting up a reliable test gate for any project — covers stack detection, 4 core test files, script wiring, secret hygiene, and Cloudflare Workers/Pages patterns. Use when starting a new project, adding CI to an existing one, or when "tests pass but production breaks." Companion to cm-safe-deploy and cm-project-bootstrap.
4
+ ---
5
+
6
+ # cm-test-gate: Multi-Layer Test Gate Setup
7
+
8
+ ## Overview
9
+
10
+ A deployment process without a test gate is just shipping code and praying. The `test:gate` script is your first line of defense before deployment. A test gate MUST verify four things: frontend component safety, backend API behavior, core business logic, and i18n synchronization.
11
+
12
+ **Core assumption:** The most dangerous errors are syntax flaws, variable shadowing, or import failures that tests often skip if they only check logic.
13
+
14
+ **Violating the letter of this process is violating the spirit of quality engineering.**
15
+
16
+ ## The Protocol
17
+
18
+ When setting up a test gate for a project, follow these 5 phases in order.
19
+
20
+ ### Phase 1: Stack Detection and Environment Setup
21
+
22
+ **Goal:** Identify the framework and install the correct testing dependencies.
23
+
24
+ 1. **Detect Stack:**
25
+ - Check `package.json` for framework (React, Vue, Svelte, static HTML) and build tool (Vite, Next.js).
26
+ - Check for `wrangler.json(c)` (Cloudflare Workers/Pages).
27
+ - Check for Tailwind, PostCSS, or specific UI libraries.
28
+
29
+ 2. **Install Dependencies (Example: Vite/Vitest):**
30
+ ```bash
31
+ # Install vitest and related tools
32
+ npm install -D vitest jsdom @testing-library/react @testing-library/jest-dom
33
+ # (Adjust based on framework: e.g., @testing-library/svelte)
34
+ ```
35
+
36
+ 3. **Configure File:**
37
+ - Create `vitest.config.ts` (or `.js`):
38
+ ```typescript
39
+ import { defineConfig } from 'vitest/config'
40
+ // Import framework plugin (e.g., react(), svelte())
41
+
42
+ export default defineConfig({
43
+ test: {
44
+ environment: 'jsdom',
45
+ globals: true,
46
+ setupFiles: ['./test/setup.ts'], // Optional
47
+ },
48
+ })
49
+ ```
50
+
51
+ ### Phase 2: The 4 Core Test Files
52
+
53
+ A complete `test:gate` must cover four distinct layers. Do not combine these files.
54
+
55
+ #### Layer 1: Frontend Safety (`frontend-safety.test.ts`)
56
+ This layer prevents white screens and catastrophic syntax errors in the browser. Emphasize parsing and template rendering over logical assertions.
57
+
58
+ *Use the exact implementation from `cm-quality-gate` regarding the 4 corruption checks.*
59
+
60
+ ```typescript
61
+ import { test, expect } from 'vitest';
62
+ import fs from 'fs';
63
+ import path from 'path';
64
+
65
+ test('app.js does not contain catastrophic syntax corruption', () => {
66
+ // 1. Read the raw file
67
+ const content = fs.readFileSync(path.resolve(__dirname, '../public/static/app.js'), 'utf-8');
68
+
69
+ // 2. Syntax Validation (Check for broken template literals)
70
+ // ❌ Bug #1: Single-quote wrapping template string
71
+ expect(content).not.toMatch(/=\s*'[^']*\$\{t\(/);
72
+
73
+ // 3. Delimiter consistency
74
+ // ❌ Bug #4: Mismatched delimiters
75
+ expect(content).not.toMatch(/t\('[^']*\`/);
76
+ expect(content).not.toMatch(/t\(\`[^']*'\)/);
77
+
78
+ // 4. HTML structure integrity
79
+ // ❌ Bug #2: Spaces inside tags or broken closers
80
+ expect(content).not.toMatch(/<\s+[a-zA-Z]/); // e.g., "< div"
81
+ expect(content).not.toMatch(/<\/\s+[a-zA-Z]/); // e.g., "</ div"
82
+ expect(content).not.toMatch(/--\s+>/); // e.g., "text-- >"
83
+ });
84
+ ```
85
+
86
+ #### Layer 2: API Routes (`api-routes.test.ts`)
87
+ This layer ensures backend endpoints respond correctly and handle JSON properly.
88
+
89
+ *Example for a generic fetch wrapper or specific Next.js/Worker handler:*
90
+
91
+ ```typescript
92
+ import { test, expect } from 'vitest';
93
+
94
+ test('API mock test', async () => {
95
+ // Test your server handlers directly
96
+ // Ensure 200 OK for valid inputs and 400 for errors
97
+ expect(true).toBe(true);
98
+ });
99
+ ```
100
+
101
+ #### Layer 3: Business Logic (`business-logic.test.ts`)
102
+ This layer tests pure functions: calculations, validations, and data transformations.
103
+
104
+ ```typescript
105
+ import { test, expect } from 'vitest';
106
+
107
+ test('Calculates score correctly', () => {
108
+ // const result = calculateScore(input);
109
+ // expect(result).toBe(expected);
110
+ expect(true).toBe(true);
111
+ });
112
+ ```
113
+
114
+ #### Layer 4: i18n Synchronization (`i18n-sync.test.ts`)
115
+ This layer guarantees that language files are complete and identical in structure.
116
+
117
+ ```typescript
118
+ import { test, expect } from 'vitest';
119
+ import fs from 'fs';
120
+ import path from 'path';
121
+
122
+ test('i18n files have identical key counts', () => {
123
+ const langDir = path.resolve(__dirname, '../public/static/i18n');
124
+ const langs = ['vi.json', 'en.json', 'th.json', 'ph.json'];
125
+
126
+ const countKeys = (obj: any): number => {
127
+ let count = 0;
128
+ for (const k in obj) {
129
+ if (typeof obj[k] === 'object' && obj[k] !== null) {
130
+ count += countKeys(obj[k]);
131
+ } else {
132
+ count++;
133
+ }
134
+ }
135
+ return count;
136
+ };
137
+
138
+ let baseCount = -1;
139
+ for (const file of langs) {
140
+ if (!fs.existsSync(path.join(langDir, file))) continue;
141
+
142
+ const data = JSON.parse(fs.readFileSync(path.join(langDir, file), 'utf-8'));
143
+ const count = countKeys(data);
144
+
145
+ if (baseCount === -1) {
146
+ baseCount = count;
147
+ } else {
148
+ expect(count, `File ${file} has a different key count`).toBe(baseCount);
149
+ }
150
+ }
151
+ });
152
+ ```
153
+
154
+ #### Layer 5: Security Scan (`security-scan.test.ts`)
155
+ This layer prevents secrets from being committed to the repository. Powered by `cm-secret-shield` patterns.
156
+
157
+ ```typescript
158
+ import { test, expect } from 'vitest';
159
+ import fs from 'fs';
160
+ import { execSync } from 'child_process';
161
+
162
+ test('no secret files tracked by git', () => {
163
+ const tracked = execSync('git ls-files', { encoding: 'utf-8' });
164
+ const badFiles = ['.env', '.dev.vars', '.env.local', '.env.production'];
165
+ const found = badFiles.filter(f => tracked.split('\n').includes(f));
166
+ expect(found, `Secret files tracked: ${found.join(', ')}`).toEqual([]);
167
+ });
168
+
169
+ test('.gitignore contains required security patterns', () => {
170
+ const gitignore = fs.readFileSync('.gitignore', 'utf-8');
171
+ expect(gitignore).toContain('.env');
172
+ expect(gitignore).toContain('.dev.vars');
173
+ });
174
+
175
+ test('no hardcoded secrets in source files', () => {
176
+ const dangerousPatterns = [
177
+ /SERVICE_KEY\s*[=:]\s*['"][a-zA-Z0-9/+=]{20,}/g,
178
+ /PRIVATE_KEY\s*[=:]\s*['"][a-zA-Z0-9/+=]{20,}/g,
179
+ /-----BEGIN.*PRIVATE KEY-----/g,
180
+ ];
181
+ const srcDir = 'src';
182
+ if (!fs.existsSync(srcDir)) return;
183
+ const files = fs.readdirSync(srcDir).filter(f => f.endsWith('.ts') || f.endsWith('.js'));
184
+ for (const file of files) {
185
+ const content = fs.readFileSync(`${srcDir}/${file}`, 'utf-8');
186
+ for (const pattern of dangerousPatterns) {
187
+ expect(content, `${file} contains potential secret`).not.toMatch(pattern);
188
+ }
189
+ }
190
+ });
191
+ ```
192
+
193
+ ### Phase 3: Script Wiring
194
+
195
+ Wire these tests into `package.json` to make them easily executable by CI or other skills.
196
+
197
+ ```json
198
+ {
199
+ "scripts": {
200
+ "test": "vitest",
201
+ "test:gate": "vitest run --reporter=verbose",
202
+ "test:watch": "vitest watch"
203
+ }
204
+ }
205
+ ```
206
+
207
+ ### Phase 4: Secret Hygiene and Ignore Configuration
208
+
209
+ **NEVER commit `.env` or `.dev.vars`.** Ensure tests do not expose actual production secrets.
210
+
211
+ 1. **Check `.gitignore`:**
212
+ ```bash
213
+ grep -E "node_modules|\.env|\.dev\.vars" .gitignore
214
+ # Must exist, if not, add them.
215
+ ```
216
+ 2. **Define Mock Env:**
217
+ Create a `.env.test` file (this CAN be committed) with safe, mock values if needed by the test environment.
218
+
219
+ ### Phase 5: Verification
220
+
221
+ Run the test gate to prove it works before declaring the task complete.
222
+
223
+ ```bash
224
+ npm run test:gate
225
+ ```
226
+
227
+ ## Integration with Other Skills
228
+
229
+ | Skill | Relationship |
230
+ |---|---|
231
+ | `cm-safe-deploy` | `test:gate` is Gate 2 in the safe deploy pipeline. |
232
+ | `cm-project-bootstrap` | Should invoke `cm-test-gate` during Phase 7 (Infrastructure Setup). |
233
+ | `cm-safe-i18n` | Relies on the i18n tests set up in Phase 2, Layer 4. |
234
+ | `cm-secret-shield` | Layer 5 security scan uses Secret Shield patterns. |
235
+
236
+ ## Red Flags - STOP and Fix
237
+
238
+ - Setting up tests but not creating the `test:gate` run script.
239
+ - Combining all tests into one massive `app.test.js` file.
240
+ - Skipping the `frontend-safety.test.ts` layer for SPA/monolith projects.
241
+ - Using real production database credentials in the test setup.
242
+ - Ignoring test failures and proceeding anyway.
@@ -0,0 +1,291 @@
1
+ ---
2
+ name: cm-ui-preview
3
+ description: "Master Design Skill. Orchestrates AI-powered UI generation using Google Stitch MCP and Pencil.dev MCP, guided by cm-ux-master intelligence and professional prompt enhancement pipelines. Implements the 'Stitch Build Loop', 'Pencil Build Loop', 'Prompt Optimization Structure', and strict design system adherence to generate production-ready UI previews before coding."
4
+ ---
5
+
6
+ # UI Preview — The Master Design Orchestrator
7
+
8
+ > **See it before you build it.**
9
+ > This skill transforms vague user requests into precise, structured 'Construction Blueprints' for AI design generators (Google Stitch or Pencil.dev), ensuring UI outputs are professional, consistent with project branding, and ergonomically sound.
10
+
11
+ ## When to Use
12
+
13
+ **ALWAYS trigger when the task involves building, redesigning, or modifying UI:**
14
+ - Creating new pages, screens, or layouts
15
+ - Building components (forms, cards, dashboards)
16
+ - Restyling or beautifying existing UIs
17
+ - Translating a wireframe or concept into high-fidelity UI
18
+ - Working with `.pen` design files (Pencil.dev)
19
+
20
+ **Trigger keywords:** build UI, design page, create screen, landing page, dashboard layout, UI designer, use stitch, stitch me a ui, use pencil, .pen file, redesign, restyle
21
+
22
+ ## Architecture & Workflow (End-to-End)
23
+
24
+ This skill operates as a pipeline. **Do not skip steps.**
25
+
26
+ ```
27
+ ┌─────────────────────────────────────────────────────────┐
28
+ │ cm-ui-preview Master Workflow │
29
+ ├─────────────────────────────────────────────────────────┤
30
+ │ │
31
+ │ Step 1: PREFLIGHT & INTENT │
32
+ │ ├── Detect task: New UI vs. Refine/Beautify │
33
+ │ └── Detect tools: Stitch MCP / Pencil MCP / Both │
34
+ │ │
35
+ │ Step 2: DESIGN SYSTEM EXTRACTION (The Source of Truth) │
36
+ │ ├── Check: .stitch/DESIGN.md, .pen files, css tokens │
37
+ │ └── Fallback: Trigger `cm-design-system` to generate │
38
+ │ │
39
+ │ Step 3: PROMPT ENHANCEMENT (The Build Blueprint) │
40
+ │ ├── Project Overview (What, who, style vibe) │
41
+ │ ├── Design System Specs (Colors, Typography, Layout) │
42
+ │ └── Page Structure (Core function + Specific areas) │
43
+ │ │
44
+ │ Step 4a: STITCH EXECUTION (Quick Concept) │
45
+ │ ├── create_project() │
46
+ │ ├── generate_screen_from_text() │
47
+ │ ├── Present link + AI insights to user │
48
+ │ └── User Decision: Confirm / Edit / Skip │
49
+ │ │
50
+ │ Step 4b: PENCIL EXECUTION (Precise Control) │
51
+ │ ├── get_editor_state() / open_document() │
52
+ │ ├── get_guidelines() + get_style_guide() │
53
+ │ ├── batch_design() — Insert components & layout │
54
+ │ ├── get_screenshot() — Visual verification │
55
+ │ └── User Decision: Confirm / Edit / Skip │
56
+ │ │
57
+ │ Step 5: FINALIZATION & BATON PASS │
58
+ │ ├── Save state (.stitch/next-prompt.md or .pen file) │
59
+ │ └── Hand off to cm-execution for actual coding │
60
+ │ │
61
+ └─────────────────────────────────────────────────────────┘
62
+ ```
63
+
64
+ ## Step 1: Preflight & Intent Classification
65
+
66
+ ### 1a. Tool Detection (REQUIRED)
67
+
68
+ Detect which design MCP tools are available:
69
+
70
+ ```
71
+ ┌──────────────┬──────────────┬───────────────────────────────┐
72
+ │ Stitch only │ Pencil only │ Both available │
73
+ ├──────────────┼──────────────┼───────────────────────────────┤
74
+ │ Use Stitch │ Use Pencil │ Ask user preference: │
75
+ │ (quick │ (detailed │ - "Quick concept" → Stitch │
76
+ │ concept) │ control) │ - "Precise control" → Pencil │
77
+ │ │ │ - Default: Stitch (faster) │
78
+ └──────────────┴──────────────┴───────────────────────────────┘
79
+ ```
80
+
81
+ - **Stitch MCP:** Check if `create_project` and `generate_screen_from_text` are available.
82
+ - **Pencil MCP:** Check if `get_editor_state` and `batch_design` are available.
83
+ - **Neither:** Proceed with Prompt-Only generation (output the blueprint for manual use).
84
+
85
+ ### 1b. Intent Classification
86
+
87
+ - **New Screen:** Proceed with full generation (Step 4a or 4b).
88
+ - **Refine/Beautify (edit):**
89
+ - Stitch: Use `edit_screens()` on existing screen IDs.
90
+ - Pencil: Use `batch_design()` with Update (U) operations on existing nodes.
91
+
92
+ ## Step 2: Design System Extraction (Source of Truth)
93
+
94
+ Before assembly, you MUST establish the design constraints.
95
+
96
+ **Look for:**
97
+ - `DESIGN.md` or `.stitch/DESIGN.md` (Primary source for Stitch)
98
+ - Existing `.pen` files in the project (Primary source for Pencil)
99
+ - `design-system/MASTER.md` (Legacy format from `cm-ux-master`)
100
+ - `.cm/design-tokens.css` or Tailwind configs
101
+
102
+ **CRITICAL STANDARD:**
103
+ A valid Stitch design file MUST conform to the `skills/cm-ux-master/DESIGN_STANDARD_TEMPLATE.md` standard. It must include both:
104
+ 1. The Markdown structure (Overview, Colors, Typography, Spacing & Shapes, Components, Do's and Don'ts).
105
+ 2. The hidden JSON block delimited EXACTLY by `<!-- STITCH_TOKENS_START -->` and `<!-- STITCH_TOKENS_END -->`.
106
+
107
+ **For Pencil.dev:** Design tokens from `DESIGN.md` can be translated to `.pen` file variables via `mcp_pencil_set_variables`. The Pencil MCP also provides built-in style guides via `get_style_guide_tags` and `get_style_guide`.
108
+
109
+ **If no design system exists or it's in a legacy format:**
110
+ You MUST fallback to the pre-built default design system: `skills/cm-design-system/resources/shadcn-default.md`. Read this file and inject its contents (including the `<!-- STITCH_TOKENS_START -->` block) into your prompt.
111
+ *Suggest running `cm-design-system` if the user wants to extract a custom design instead of using the default Shadcn minimalist style.*
112
+
113
+ ## Step 3: Prompt Enhancement Pipeline (CRITICAL)
114
+
115
+ **DO NOT send vague prompts to Stitch (e.g., "Make a login page").**
116
+ You must assemble an "Optimized Prompt Structure" — a detailed construction blueprint.
117
+
118
+ Structure your prompt exactly like this:
119
+
120
+ ```markdown
121
+ [Overall vibe, mood, and purpose of the page: e.g., "A modern fintech dashboard for B2B users. Professional, trustworthy, high data density, light mode."]
122
+
123
+ **DESIGN SYSTEM (REQUIRED):**
124
+ [Inject the full contents of DESIGN.md here. It MUST include the <!-- STITCH_TOKENS_START --> ... <!-- STITCH_TOKENS_END --> block so the Stitch engine ingests the design tokens properly.]
125
+
126
+ **PAGE STRUCTURE & FUNCTION:**
127
+ ### 1. Dashboard Home
128
+ **Core function**: Overview of recent transactions and account health.
129
+ - **Top Nav**: Brand logo, Global Search input, User Avatar dropdown.
130
+ - **Hero/Header**: Greeting "Welcome back, {User}", Total Balance callout (Large bold text).
131
+ - **Main Function Area**:
132
+ - Left col: Line chart showing 30-day revenue.
133
+ - Right col: Vertical list of "Recent Transactions" (Icon, Title, Date, Amount (Green/Red)).
134
+ - **Action Area**: Primary CTA "Send Money" (Blue fill, large), Secondary "Download Statement" (Outline).
135
+ ```
136
+
137
+ *Refine UI terminology:* Replace "nice buttons" with "Primary CTA", replace "boxes" with "Cards". Apply relevant constraints from `cm-ux-master` (e.g., Miller's Law for chunking lists).
138
+
139
+ > **Note for Pencil path:** The same prompt structure is used for your own reasoning. You will then translate the blueprint into `batch_design` operations (see Step 4b).
140
+
141
+ ## Step 4a: Stitch Execution (Quick Concept)
142
+
143
+ > Use this path when Stitch MCP is available and user wants fast concept generation.
144
+
145
+ 1. **Project Creation:**
146
+ ```javascript
147
+ mcp_StitchMCP_create_project({ title: "UI Preview — {Feature}" })
148
+ ```
149
+ 2. **Screen Generation:**
150
+ ```javascript
151
+ mcp_StitchMCP_generate_screen_from_text({
152
+ projectId: "<id>",
153
+ prompt: "<Your Optimized Prompt Blueprint>",
154
+ deviceType: "DESKTOP" // or MOBILE
155
+ })
156
+ ```
157
+ 3. **User Presentation:**
158
+ Show the output, provide the URL, and present the **AI Insights** (from the tool's `outputComponents` response).
159
+
160
+ ```markdown
161
+ 🎨 **UI Preview Generated (Stitch)!**
162
+
163
+ - **View & Edit:** [Google Stitch Link]
164
+ - **AI Insights:** [Any suggestions or notes returned by Stitch]
165
+
166
+ What's next?
167
+ 1. ✅ **Confirm** — I will write the code matching this design exactly.
168
+ 2. ✏️ **Edit** — Tell me what to change, I'll update the preview.
169
+ 3. ⏭️ **Skip** — Proceed straight to coding.
170
+ ```
171
+
172
+ ## Step 4b: Pencil Execution (Precise Control)
173
+
174
+ > Use this path when Pencil MCP is available and user wants pixel-level design control, or when working with existing `.pen` files.
175
+
176
+ ### 4b.1: Initialize
177
+
178
+ ```javascript
179
+ // Check current editor state (or open existing .pen file)
180
+ mcp_pencil_get_editor_state({ include_schema: true })
181
+
182
+ // If no document is open, create a new one or open an existing .pen file
183
+ mcp_pencil_open_document({ filePathOrTemplate: "new" })
184
+ // OR
185
+ mcp_pencil_open_document({ filePathOrTemplate: "/path/to/project/design.pen" })
186
+ ```
187
+
188
+ ### 4b.2: Load Design Guidelines & Style
189
+
190
+ ```javascript
191
+ // Get design rules for the target platform
192
+ mcp_pencil_get_guidelines({ topic: "web-app" }) // or "mobile-app", "landing-page"
193
+
194
+ // Get style inspiration
195
+ mcp_pencil_get_style_guide_tags() // Returns available tags
196
+ mcp_pencil_get_style_guide({ tags: ["modern", "dashboard", "dark", "website", "minimal"] })
197
+ ```
198
+
199
+ ### 4b.3: Apply Design Tokens (from DESIGN.md)
200
+
201
+ If a `DESIGN.md` exists with tokens, map them to `.pen` variables:
202
+
203
+ ```javascript
204
+ mcp_pencil_set_variables({
205
+ filePath: "design.pen",
206
+ variables: {
207
+ "primary": { "type": "color", "value": "#3B82F6" },
208
+ "secondary": { "type": "color", "value": "#10B981" },
209
+ "surface": { "type": "color", "value": "#FFFFFF" },
210
+ "text-primary": { "type": "color", "value": "#0F172A" },
211
+ "border-radius": { "type": "number", "value": 8 }
212
+ }
213
+ })
214
+ ```
215
+
216
+ ### 4b.4: Build Layout with batch_design
217
+
218
+ Use the prompt blueprint from Step 3 to construct the UI:
219
+
220
+ ```javascript
221
+ // Read available design system components first
222
+ mcp_pencil_batch_get({
223
+ filePath: "design.pen",
224
+ patterns: [{ reusable: true }],
225
+ readDepth: 2,
226
+ searchDepth: 3
227
+ })
228
+
229
+ // Then build the layout using Insert (I), Update (U), etc.
230
+ mcp_pencil_batch_design({
231
+ filePath: "design.pen",
232
+ operations: `
233
+ screen=I(document,{type:"frame",name:"Dashboard",width:1440,height:900,fill:"#FFFFFF",layout:"horizontal"})
234
+ sidebar=I(screen,{type:"frame",name:"Sidebar",width:240,height:"fill_container",fill:"#0F172A",layout:"vertical",padding:16,gap:8})
235
+ main=I(screen,{type:"frame",name:"Main Content",width:"fill_container",height:"fill_container",layout:"vertical",padding:32,gap:24})
236
+ header=I(main,{type:"frame",name:"Header",width:"fill_container",height:64,layout:"horizontal"})
237
+ title=I(header,{type:"text",content:"Dashboard",fontSize:24,fontWeight:"bold"})
238
+ `
239
+ })
240
+ ```
241
+
242
+ ### 4b.5: Verify with Screenshot
243
+
244
+ ```javascript
245
+ mcp_pencil_get_screenshot({ filePath: "design.pen", nodeId: "<screen-id>" })
246
+ ```
247
+
248
+ Analyze the screenshot for visual issues, then present to user:
249
+
250
+ ```markdown
251
+ 🎨 **UI Preview Generated (Pencil.dev)!**
252
+
253
+ - **File:** `design.pen` (editable locally)
254
+ - **Screenshot:** [embedded image]
255
+
256
+ What's next?
257
+ 1. ✅ **Confirm** — I will write the code matching this design exactly.
258
+ 2. ✏️ **Edit** — Tell me what to change, I'll update the `.pen` file.
259
+ 3. 🔄 **Export** — Export to PNG/PDF for stakeholder review.
260
+ 4. ⏭️ **Skip** — Proceed straight to coding.
261
+ ```
262
+
263
+ ### Pencil Quick Reference
264
+
265
+ | Operation | Use For | Example |
266
+ |-----------|---------|---------|
267
+ | `I(parent, data)` | Insert new node | `I(screen, {type:"frame", ...})` |
268
+ | `U(path, data)` | Update existing node | `U("nodeId", {fill:"#FFF"})` |
269
+ | `C(path, parent, data)` | Copy/duplicate | `C("screenId", document, {name:"V2"})` |
270
+ | `R(path, data)` | Replace child in instance | `R("inst/slot", {type:"text",...})` |
271
+ | `D(nodeId)` | Delete node | `D("oldNodeId")` |
272
+ | `G(nodeId, type, prompt)` | Generate/stock image | `G(heroImg, "stock", "office")` |
273
+
274
+ ## Step 5: Finalization & Baton Pass
275
+
276
+ - **If Confirm:** Proceed to code implementation. You MUST follow the visual layout, spacing, and colors shown in the preview (Stitch or Pencil).
277
+ - **If Edit:**
278
+ - Stitch: Call `mcp_StitchMCP_edit_screens()` with the specific element changes.
279
+ - Pencil: Call `mcp_pencil_batch_design()` with Update/Replace operations.
280
+ - **Baton Update (Optional but Recommended):**
281
+ - Stitch: Maintain a `.stitch/next-prompt.md` for session continuity.
282
+ - Pencil: The `.pen` file itself serves as the persistent design artifact.
283
+ - **Export (Pencil only):** Use `mcp_pencil_export_nodes()` to produce PNG/PDF assets for stakeholder review.
284
+
285
+ ## Anti-Patterns (Strict Prohibitions)
286
+
287
+ - ⛔ **NO VAGUE PROMPTS:** Never pass user input straight to Stitch without the Step 3 Enhancement Pipeline.
288
+ - ⛔ **NO FAKE SUCCESS:** If the MCP tool fails or isn't connected, do not hallucinate a success message or URL.
289
+ - ⛔ **NO CODING (Yet):** This phase is purely for DESIGN PREVIEW. Do not write React/Vue code until the user clicks "Confirm" or "Skip".
290
+ - ⛔ **NO APP SCAFFOLDING:** Do not initialize project codebases in this workflow.
291
+ - ⛔ **NO RAW .PEN READS:** Never use `view_file` or `grep_search` on `.pen` files. Always use `mcp_pencil_batch_get`.
@@ -0,0 +1,54 @@
1
+ # Design System
2
+
3
+ ## Overview
4
+ - **Personality:** [e.g. Professional and trustworthy, Playful and vibrant]
5
+ - **Density:** [e.g. High density for data-rich dashboards, Spacious for consumer apps]
6
+
7
+ ## Colors
8
+ - **Primary:** [Hex]
9
+ - **Secondary:** [Hex]
10
+ - **Tertiary:** [Hex]
11
+ - **Neutral:** [Hex]
12
+ *Note: Use primary colors sparingly for the most important actions. Ensure WCAG AA 4.5:1 contrast.*
13
+
14
+ ## Typography
15
+ - **Headlines:** [Font Family]
16
+ - **Body:** [Font Family]
17
+ - **Labels:** [Font Family]
18
+ *Note: Avoid using more than two font weights on a single screen to maintain clarity.*
19
+
20
+ ## Spacing & Shapes
21
+ - **Grid:** [e.g. columns, gutters, margins]
22
+ - **Shapes:** [e.g. Rounded (8px), Sharp (0px)]
23
+ - **Elevation:** [e.g. Flat, Subtle, Deep shadows]
24
+ *Note: Do not mix rounded and sharp corners within the same view.*
25
+
26
+ ## Components
27
+ - **Buttons:** [Radius, padding, border styles]
28
+ - **Inputs:** [Focus states, borders, background variances]
29
+ - **Chips/Lists:** [Spacing, icon sizes, heights]
30
+
31
+ ## Do's and Don'ts
32
+ - Do: [Action to encourage]
33
+ - Don't: [Action to avoid]
34
+
35
+ <!-- STITCH_TOKENS_START -->
36
+ {
37
+ "version": "1",
38
+ "colors": {
39
+ "primary": "",
40
+ "secondary": "",
41
+ "tertiary": "",
42
+ "neutral": ""
43
+ },
44
+ "typography": {
45
+ "headlines": "",
46
+ "body": "",
47
+ "labels": ""
48
+ },
49
+ "shapes": {
50
+ "radius": "",
51
+ "elevation": ""
52
+ }
53
+ }
54
+ <!-- STITCH_TOKENS_END -->