@llipe.com/dev-tasks 0.9.2 → 0.11.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 (69) hide show
  1. package/.claude/agents/developer.md +11 -0
  2. package/.claude/agents/qa-engineer.md +31 -2
  3. package/.claude/agents/researcher.md +96 -0
  4. package/.claude/agents/ux-engineer.md +118 -114
  5. package/.claude/commands/planner.md +22 -7
  6. package/.claude/commands/product-engineer.md +37 -10
  7. package/.claude/commands/researcher.md +28 -0
  8. package/.claude/skills/activity-codebase-research/SKILL.md +158 -0
  9. package/.claude/skills/activity-contract-validation/SKILL.md +167 -0
  10. package/.claude/skills/activity-e2e-test-implementation/SKILL.md +156 -0
  11. package/.claude/skills/activity-integration-test-implementation/SKILL.md +156 -0
  12. package/.claude/skills/activity-refine/SKILL.md +1 -0
  13. package/.claude/skills/activity-test-standards/SKILL.md +41 -0
  14. package/.claude/skills/ux-scaffold/SKILL.md +129 -0
  15. package/.claude/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
  16. package/.claude/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
  17. package/.claude/skills/ux-theme-gen/SKILL.md +149 -0
  18. package/.github/agents/developer.agent.md +11 -0
  19. package/.github/agents/planner.agent.md +22 -7
  20. package/.github/agents/product-engineer.agent.md +37 -10
  21. package/.github/agents/qa-engineer.agent.md +30 -3
  22. package/.github/agents/researcher.agent.md +96 -0
  23. package/.github/agents/ux-engineer.agent.md +119 -114
  24. package/.github/prompts/researcher.prompt.md +29 -0
  25. package/.github/skills/activity-codebase-research/SKILL.md +158 -0
  26. package/.github/skills/activity-contract-validation/SKILL.md +167 -0
  27. package/.github/skills/activity-e2e-test-implementation/SKILL.md +156 -0
  28. package/.github/skills/activity-integration-test-implementation/SKILL.md +156 -0
  29. package/.github/skills/activity-refine/SKILL.md +6 -0
  30. package/.github/skills/activity-test-standards/SKILL.md +41 -0
  31. package/.github/skills/ux-scaffold/SKILL.md +129 -0
  32. package/.github/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
  33. package/.github/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
  34. package/.github/skills/ux-theme-gen/SKILL.md +149 -0
  35. package/.kiro/agents/developer.md +11 -0
  36. package/.kiro/agents/planner.md +22 -7
  37. package/.kiro/agents/product-engineer.md +37 -10
  38. package/.kiro/agents/qa-engineer.md +30 -3
  39. package/.kiro/agents/researcher.md +99 -0
  40. package/.kiro/agents/ux-engineer.md +119 -132
  41. package/.kiro/agents/verifier.md +1 -1
  42. package/.kiro/skills/activity-codebase-research/SKILL.md +158 -0
  43. package/.kiro/skills/activity-contract-validation/SKILL.md +167 -0
  44. package/.kiro/skills/activity-e2e-test-implementation/SKILL.md +156 -0
  45. package/.kiro/skills/activity-integration-test-implementation/SKILL.md +156 -0
  46. package/.kiro/skills/activity-refine/SKILL.md +1 -0
  47. package/.kiro/skills/activity-test-standards/SKILL.md +41 -0
  48. package/.kiro/skills/ux-scaffold/SKILL.md +129 -0
  49. package/.kiro/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
  50. package/.kiro/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
  51. package/.kiro/skills/ux-theme-gen/SKILL.md +149 -0
  52. package/AGENTS.md +91 -214
  53. package/CHANGELOG.md +64 -0
  54. package/CLAUDE.md +3 -2
  55. package/DESIGN.md +233 -0
  56. package/README.md +31 -28
  57. package/TESTING.md +19 -11
  58. package/bundle-manifest.json +1 -0
  59. package/dist/core/distribution/doctor.d.ts +2 -2
  60. package/dist/core/distribution/doctor.js +3 -3
  61. package/dist/core/distribution/profiles.d.ts.map +1 -1
  62. package/dist/core/distribution/profiles.js +1 -1
  63. package/dist/core/distribution/profiles.js.map +1 -1
  64. package/package.json +4 -3
  65. package/.claude/skills/webapp-mockup/SKILL.md +0 -76
  66. package/.claude/skills/webapp-mockup/scripts/scaffold-mockup.sh +0 -469
  67. package/.github/skills/webapp-mockup/SKILL.md +0 -71
  68. package/.github/skills/webapp-mockup/scripts/scaffold-mockup.sh +0 -469
  69. package/.kiro/skills/webapp-mockup/SKILL.md +0 -76
@@ -0,0 +1,183 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+
4
+ # scaffold-full.sh — Generate a react-full mockup via shadcn CLI.
5
+ # Creates a Vite + React + Tailwind v4 + shadcn/ui project, then
6
+ # replaces the default theme with ux-theme-gen output.
7
+ #
8
+ # Usage:
9
+ # ./scripts/scaffold-full.sh <feature> <variant-num> <output-dir> [theme-css-path]
10
+ #
11
+ # Example:
12
+ # ./scripts/scaffold-full.sh billing 1 /mockups/mockup-billing-1 /mockups/.theme/theme.css
13
+ #
14
+ # Prerequisites:
15
+ # - Node.js >= 24
16
+ # - pnpm available (preferred) or npm
17
+ # - Internet access for npm create vite + shadcn init
18
+
19
+ SHADCN_VERSION="4.18.0"
20
+
21
+ usage() {
22
+ echo "Usage: $0 <feature> <variant-num> <output-dir> [theme-css-path]"
23
+ echo ""
24
+ echo " feature Feature slug (lowercase, hyphenated)"
25
+ echo " variant-num Variant number (integer)"
26
+ echo " output-dir Directory to create the project in (must not exist)"
27
+ echo " theme-css-path Path to theme.css from ux-theme-gen (optional; merged after scaffold)"
28
+ exit 1
29
+ }
30
+
31
+ if [[ $# -lt 3 || $# -gt 4 ]]; then
32
+ usage
33
+ fi
34
+
35
+ FEATURE="$(echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')"
36
+ VARIANT="$2"
37
+ OUTPUT_DIR="$3"
38
+ THEME_CSS="${4:-}"
39
+
40
+ if [[ -z "$FEATURE" ]]; then
41
+ echo "Error: <feature> produced an empty slug."
42
+ exit 1
43
+ fi
44
+
45
+ if ! [[ "$VARIANT" =~ ^[0-9]+$ ]]; then
46
+ echo "Error: <variant-num> must be an integer."
47
+ exit 1
48
+ fi
49
+
50
+ if [[ -d "$OUTPUT_DIR" ]]; then
51
+ echo "Error: output directory already exists: $OUTPUT_DIR"
52
+ exit 1
53
+ fi
54
+
55
+ # Detect package manager
56
+ PM="npm"
57
+ if command -v pnpm >/dev/null 2>&1; then
58
+ PM="pnpm"
59
+ fi
60
+
61
+ echo "[scaffold-full] Creating Vite + React project at: $OUTPUT_DIR"
62
+ echo "[scaffold-full] Package manager: $PM"
63
+ echo "[scaffold-full] shadcn version: ${SHADCN_VERSION}"
64
+
65
+ # Step 1: Create Vite project
66
+ CI=1 npm_config_yes=true npm create vite@latest "$OUTPUT_DIR" -- --template react-ts
67
+
68
+ # Step 2: Install dependencies with pnpm (or npm)
69
+ pushd "$OUTPUT_DIR" >/dev/null
70
+
71
+ if [[ "$PM" == "pnpm" ]]; then
72
+ pnpm install
73
+ else
74
+ npm install
75
+ fi
76
+
77
+ # Step 3: Install Tailwind v4 + Vite plugin (replaces postcss/autoprefixer pattern)
78
+ $PM add tailwindcss@^4 @tailwindcss/vite@^4 tw-animate-css@^1.4
79
+
80
+ # Step 4: Configure vite.config.ts with tailwindcss plugin and path alias
81
+ cat > vite.config.ts << 'VITE_EOF'
82
+ import path from "path"
83
+ import tailwindcss from "@tailwindcss/vite"
84
+ import react from "@vitejs/plugin-react"
85
+ import { defineConfig } from "vite"
86
+
87
+ export default defineConfig({
88
+ plugins: [react(), tailwindcss()],
89
+ resolve: {
90
+ alias: {
91
+ "@": path.resolve(__dirname, "./src"),
92
+ },
93
+ },
94
+ })
95
+ VITE_EOF
96
+
97
+ # Step 5: Create minimal index.css for shadcn init to find
98
+ cat > src/index.css << 'CSS_EOF'
99
+ @import "tailwindcss";
100
+ CSS_EOF
101
+
102
+ # Step 6: Run shadcn init (writes components.json, updates deps, creates utils)
103
+ npx --yes "shadcn@${SHADCN_VERSION}" init \
104
+ --base radix \
105
+ --preset nova \
106
+ --css-variables \
107
+ --yes \
108
+ --silent
109
+
110
+ echo "[scaffold-full] shadcn init complete."
111
+
112
+ # Step 7: Merge theme.css if provided
113
+ if [[ -n "$THEME_CSS" && -f "$THEME_CSS" ]]; then
114
+ echo "[scaffold-full] Merging theme from: $THEME_CSS"
115
+ # The shadcn init writes its own :root block into src/index.css.
116
+ # We replace the :root and @theme inline sections with the DESIGN.md-derived ones.
117
+ # Strategy: append our theme.css content after the @import lines.
118
+ # The agent should refine this merge based on actual content.
119
+
120
+ # Extract @import lines from current index.css
121
+ IMPORTS=$(grep -E "^@import" src/index.css || true)
122
+
123
+ # Rebuild index.css: imports + our theme + base layer
124
+ {
125
+ echo "$IMPORTS"
126
+ echo ""
127
+ cat "$THEME_CSS"
128
+ echo ""
129
+ echo "@layer base {"
130
+ echo " * {"
131
+ echo " @apply border-border outline-ring/50;"
132
+ echo " }"
133
+ echo " body {"
134
+ echo " @apply bg-background text-foreground;"
135
+ echo " }"
136
+ echo "}"
137
+ } > src/index.css
138
+
139
+ echo "[scaffold-full] Theme merged into src/index.css"
140
+ fi
141
+
142
+ # Step 8: Create a placeholder App.tsx
143
+ cat > src/App.tsx << 'APP_EOF'
144
+ import "./index.css"
145
+
146
+ export default function App() {
147
+ return (
148
+ <main className="mx-auto max-w-4xl px-4 py-10">
149
+ <header className="mb-8 rounded-xl border bg-card p-5 shadow-sm">
150
+ <p className="mb-2 text-xs font-semibold uppercase tracking-wide text-secondary-foreground">
151
+ Mockup — Variant VARIANT_NUM
152
+ </p>
153
+ <h1 className="text-2xl font-semibold">FEATURE_NAME</h1>
154
+ <p className="mt-2 text-sm text-muted-foreground">
155
+ This is a full-fidelity mockup scaffold. Implement screens and interactions here.
156
+ </p>
157
+ </header>
158
+
159
+ {/* Agent: implement mockup screens below */}
160
+ <section className="rounded-xl border bg-card p-5 shadow-sm" data-ac="AC-TODO">
161
+ <h2 className="text-lg font-semibold">Screen Content</h2>
162
+ <p className="mt-2 text-sm text-muted-foreground">
163
+ Replace this with the actual mockup implementation.
164
+ </p>
165
+ </section>
166
+ </main>
167
+ )
168
+ }
169
+ APP_EOF
170
+
171
+ # Replace placeholders
172
+ sed -i '' "s/VARIANT_NUM/${VARIANT}/g" src/App.tsx
173
+ sed -i '' "s/FEATURE_NAME/${FEATURE}/g" src/App.tsx
174
+
175
+ # Clean up Vite default files
176
+ rm -f src/App.css src/assets/react.svg public/vite.svg
177
+
178
+ popd >/dev/null
179
+
180
+ echo ""
181
+ echo "[scaffold-full] Done. Project created at: $OUTPUT_DIR"
182
+ echo " cd $OUTPUT_DIR"
183
+ echo " $PM run dev"
@@ -0,0 +1,235 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+
4
+ # scaffold-lite.sh — Generate a navigable html-lite mockup scaffold.
5
+ # All screens are self-contained HTML files styled from DESIGN.md tokens.
6
+ #
7
+ # Usage:
8
+ # ./scripts/scaffold-lite.sh <feature> <variant-num> <theme-css-path> <output-dir>
9
+ #
10
+ # Example:
11
+ # ./scripts/scaffold-lite.sh onboarding 1 /mockups/.theme/theme.css docs/requirements/mockups/onboarding/
12
+
13
+ usage() {
14
+ echo "Usage: $0 <feature> <variant-num> <theme-css-path> <output-dir>"
15
+ echo ""
16
+ echo " feature Feature slug (lowercase, hyphenated)"
17
+ echo " variant-num Variant number (integer)"
18
+ echo " theme-css-path Path to the generated theme.css from ux-theme-gen"
19
+ echo " output-dir Directory to create the mockup in"
20
+ exit 1
21
+ }
22
+
23
+ if [[ $# -ne 4 ]]; then
24
+ usage
25
+ fi
26
+
27
+ FEATURE="$(echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')"
28
+ VARIANT="$2"
29
+ THEME_CSS="$3"
30
+ OUTPUT_DIR="$4"
31
+
32
+ if [[ -z "$FEATURE" ]]; then
33
+ echo "Error: <feature> produced an empty slug."
34
+ exit 1
35
+ fi
36
+
37
+ if ! [[ "$VARIANT" =~ ^[0-9]+$ ]]; then
38
+ echo "Error: <variant-num> must be an integer."
39
+ exit 1
40
+ fi
41
+
42
+ if [[ ! -f "$THEME_CSS" ]]; then
43
+ echo "Error: theme.css not found at: $THEME_CSS"
44
+ echo "Run ux-theme-gen first to generate theme artifacts from DESIGN.md."
45
+ exit 1
46
+ fi
47
+
48
+ # Extract :root block from theme.css to inline in HTML files
49
+ ROOT_STYLES=$(sed -n '/:root/,/^}/p' "$THEME_CSS")
50
+ THEME_INLINE=$(sed -n '/@theme inline/,/^}/p' "$THEME_CSS")
51
+
52
+ mkdir -p "$OUTPUT_DIR"
53
+
54
+ # Screen types the agent will fill with content
55
+ SCREENS=(
56
+ "happy:Primary flow — success state"
57
+ "error-validation:Form validation failures"
58
+ "error-server:Server or network error state"
59
+ "error-permission:Permission denied or unauthorized"
60
+ "empty:No data or first-use experience"
61
+ "loading:Skeleton screens and spinners"
62
+ "edge-overflow:Long text, many items"
63
+ "edge-zero:Zero items, disabled states"
64
+ )
65
+
66
+ # Generate individual screen files
67
+ for entry in "${SCREENS[@]}"; do
68
+ name="${entry%%:*}"
69
+ desc="${entry#*:}"
70
+ filename="screen-${name}.html"
71
+
72
+ cat > "${OUTPUT_DIR}/${filename}" << SCREEN_EOF
73
+ <!DOCTYPE html>
74
+ <html lang="en">
75
+ <head>
76
+ <meta charset="UTF-8">
77
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
78
+ <title>${FEATURE} v${VARIANT} — ${name}</title>
79
+ <style>
80
+ ${ROOT_STYLES}
81
+
82
+ * { margin: 0; padding: 0; box-sizing: border-box; }
83
+ body {
84
+ font-family: system-ui, -apple-system, sans-serif;
85
+ background: var(--background);
86
+ color: var(--foreground);
87
+ min-height: 100vh;
88
+ padding: 1rem;
89
+ }
90
+ .nav-strip {
91
+ display: flex; gap: 0.5rem; padding: 0.75rem 1rem;
92
+ background: var(--muted); border-radius: 0.5rem;
93
+ margin-bottom: 1.5rem; flex-wrap: wrap; font-size: 0.875rem;
94
+ }
95
+ .nav-strip a { color: var(--primary); text-decoration: none; }
96
+ .nav-strip a:hover { text-decoration: underline; }
97
+ .nav-strip .current { font-weight: 700; color: var(--foreground); }
98
+ .screen-content {
99
+ border: 1px solid var(--border); border-radius: 0.75rem;
100
+ padding: 2rem; min-height: 60vh;
101
+ }
102
+ .screen-content h1 { font-size: 1.5rem; margin-bottom: 1rem; }
103
+ .screen-content .description { color: var(--muted-foreground); margin-bottom: 2rem; }
104
+ .banner {
105
+ background: var(--accent); color: var(--accent-foreground);
106
+ padding: 0.75rem 1rem; border-radius: 0.5rem; margin-bottom: 1.5rem;
107
+ font-size: 0.875rem;
108
+ }
109
+ </style>
110
+ </head>
111
+ <body>
112
+ <nav class="nav-strip">
113
+ <a href="index.html">Index</a>
114
+ SCREEN_EOF
115
+
116
+ # Add prev/next/related links placeholder
117
+ cat >> "${OUTPUT_DIR}/${filename}" << 'NAV_EOF'
118
+ <!-- Agent: replace with actual prev/next links based on screen order -->
119
+ <span class="current">CURRENT_SCREEN</span>
120
+ </nav>
121
+
122
+ <div class="banner">
123
+ Partial mockup — variant VARIANT_NUM of feature FEATURE_NAME. Extend with actual UI content.
124
+ </div>
125
+
126
+ <main class="screen-content" data-ac="AC-TODO">
127
+ <h1>SCREEN_TITLE</h1>
128
+ <p class="description">SCREEN_DESC</p>
129
+
130
+ <!-- Agent: implement the screen content here -->
131
+ <p style="color: var(--muted-foreground); font-style: italic;">
132
+ Screen content to be implemented by ux-engineer.
133
+ </p>
134
+ </main>
135
+ </body>
136
+ </html>
137
+ NAV_EOF
138
+
139
+ # Replace placeholders
140
+ sed -i '' "s/CURRENT_SCREEN/${name}/g" "${OUTPUT_DIR}/${filename}"
141
+ sed -i '' "s/VARIANT_NUM/${VARIANT}/g" "${OUTPUT_DIR}/${filename}"
142
+ sed -i '' "s/FEATURE_NAME/${FEATURE}/g" "${OUTPUT_DIR}/${filename}"
143
+ sed -i '' "s/SCREEN_TITLE/${name}/g" "${OUTPUT_DIR}/${filename}"
144
+ sed -i '' "s/SCREEN_DESC/${desc}/g" "${OUTPUT_DIR}/${filename}"
145
+ done
146
+
147
+ # Generate index.html
148
+ cat > "${OUTPUT_DIR}/index.html" << INDEX_EOF
149
+ <!DOCTYPE html>
150
+ <html lang="en">
151
+ <head>
152
+ <meta charset="UTF-8">
153
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
154
+ <title>${FEATURE} v${VARIANT} — Screen Index</title>
155
+ <style>
156
+ ${ROOT_STYLES}
157
+
158
+ * { margin: 0; padding: 0; box-sizing: border-box; }
159
+ body {
160
+ font-family: system-ui, -apple-system, sans-serif;
161
+ background: var(--background);
162
+ color: var(--foreground);
163
+ min-height: 100vh;
164
+ padding: 2rem;
165
+ max-width: 800px; margin: 0 auto;
166
+ }
167
+ h1 { font-size: 2rem; margin-bottom: 0.5rem; }
168
+ .subtitle { color: var(--muted-foreground); margin-bottom: 2rem; }
169
+ .screen-list { list-style: none; }
170
+ .screen-list li {
171
+ border: 1px solid var(--border); border-radius: 0.5rem;
172
+ padding: 1rem; margin-bottom: 0.75rem;
173
+ }
174
+ .screen-list a { color: var(--primary); text-decoration: none; font-weight: 600; }
175
+ .screen-list a:hover { text-decoration: underline; }
176
+ .screen-list .desc { color: var(--muted-foreground); font-size: 0.875rem; margin-top: 0.25rem; }
177
+ .screen-map { margin-top: 2rem; padding: 1.5rem; border: 1px solid var(--border); border-radius: 0.75rem; }
178
+ .screen-map h2 { margin-bottom: 1rem; }
179
+ pre { background: var(--muted); padding: 1rem; border-radius: 0.5rem; overflow-x: auto; font-size: 0.8rem; }
180
+ </style>
181
+ </head>
182
+ <body>
183
+ <h1>${FEATURE} — Variant ${VARIANT}</h1>
184
+ <p class="subtitle">Lite mockup — open any screen below. All links are relative and work from file://.</p>
185
+
186
+ <ul class="screen-list">
187
+ INDEX_EOF
188
+
189
+ for entry in "${SCREENS[@]}"; do
190
+ name="${entry%%:*}"
191
+ desc="${entry#*:}"
192
+ cat >> "${OUTPUT_DIR}/index.html" << ITEM_EOF
193
+ <li>
194
+ <a href="screen-${name}.html">${name}</a>
195
+ <div class="desc">${desc}</div>
196
+ </li>
197
+ ITEM_EOF
198
+ done
199
+
200
+ cat >> "${OUTPUT_DIR}/index.html" << FOOTER_EOF
201
+ </ul>
202
+
203
+ <div class="screen-map">
204
+ <h2>Screen Map</h2>
205
+ <pre><code>
206
+ See screen-map.md for the Mermaid source.
207
+ Agent: embed a rendered diagram here or link to screen-map.md.
208
+ </code></pre>
209
+ </div>
210
+ </body>
211
+ </html>
212
+ FOOTER_EOF
213
+
214
+ # Generate screen-map.md placeholder
215
+ cat > "${OUTPUT_DIR}/screen-map.md" << MAP_EOF
216
+ # Screen Map — ${FEATURE} v${VARIANT}
217
+
218
+ \`\`\`mermaid
219
+ flowchart LR
220
+ happy[Happy Path] --> error-validation[Validation Error]
221
+ happy --> empty[Empty State]
222
+ happy --> loading[Loading]
223
+ error-validation --> happy
224
+ error-server[Server Error] --> happy
225
+ error-permission[Permission Denied] --> happy
226
+ empty --> happy
227
+ edge-overflow[Overflow] --> happy
228
+ edge-zero[Zero Items] --> happy
229
+ \`\`\`
230
+
231
+ > Agent: update this diagram to reflect the actual navigation flow derived from the PRD/spec.
232
+ MAP_EOF
233
+
234
+ echo "Done. Lite scaffold created at: ${OUTPUT_DIR}"
235
+ echo " index.html + $(echo "${SCREENS[@]}" | wc -w | tr -d ' ') screen files + screen-map.md"
@@ -0,0 +1,149 @@
1
+ ---
2
+ name: ux-theme-gen
3
+ description: "Generate platform-specific theme artifacts from DESIGN.md. Use when mockups or production code need consumable tokens derived from the canonical design contract."
4
+ ---
5
+
6
+ # UX Theme Generation
7
+
8
+ ## Purpose
9
+
10
+ Transform the YAML front matter in `/DESIGN.md` into consumable theme artifacts that mockups and production code import directly. This eliminates hand-copied colour values and keeps every surface aligned with the declared contract.
11
+
12
+ ## When to Use
13
+
14
+ - Before generating any mockup (Phase 0 of `ux-engineer`).
15
+ - When `developer` needs production theme files aligned with DESIGN.md.
16
+ - After filling or updating DESIGN.md tokens.
17
+ - When a stale theme artifact is detected (its tokens don't match DESIGN.md).
18
+
19
+ ## Inputs
20
+
21
+ | Input | Required | Default |
22
+ | --------------------------------------- | -------- | ------------------ |
23
+ | `/DESIGN.md` | yes | — |
24
+ | `theme_output` path (from front matter) | no | `/mockups/.theme/` |
25
+
26
+ ## Contract Check (Must Run First)
27
+
28
+ Before generating any artifact:
29
+
30
+ 1. Read `/DESIGN.md` front matter.
31
+ 2. If `status: placeholder` → **refuse** with: "DESIGN.md is an unfilled placeholder. Run ux-engineer to fill it first."
32
+ 3. If any `"<unfilled>"` sentinel remains in the token groups (`colors`, `typography`, `rounded`, `spacing`) → **refuse** and list the unfilled fields.
33
+ 4. Resolve `{colors.x}` / `{typography.y}` style references. If a reference points to an unfilled or missing key → **refuse** and report the broken reference.
34
+ 5. Only proceed to generation if all checks pass.
35
+
36
+ ## Outputs
37
+
38
+ Generated into `{theme_output}` (default `/mockups/.theme/`):
39
+
40
+ | File | Content | When |
41
+ | ------------- | ------------------------------------------------------------------ | ------------------------------------------------ |
42
+ | `theme.css` | `:root` token declarations + `@theme inline` block for Tailwind v4 | always |
43
+ | `tokens.json` | Raw JSON: all token groups as a flat or nested object | always |
44
+ | `rn-theme.ts` | TypeScript theme object for React Native | only when `platform` includes `mobile` or `both` |
45
+
46
+ ### `theme.css` structure
47
+
48
+ ```css
49
+ /* DO NOT EDIT — generated from /DESIGN.md by ux-theme-gen */
50
+
51
+ @theme inline {
52
+ --font-sans: "<fontFamily from typography.body-md>";
53
+ --color-background: var(--background);
54
+ --color-foreground: var(--foreground);
55
+ --color-primary: var(--primary);
56
+ --color-primary-foreground: var(--primary-foreground);
57
+ /* ... one --color-* per semantic slot ... */
58
+ --radius-sm: <rounded.sm>;
59
+ --radius-md: <rounded.md>;
60
+ --radius-lg: <rounded.lg>;
61
+ }
62
+
63
+ :root {
64
+ --background: <colors.background>;
65
+ --foreground: <colors.foreground>;
66
+ --primary: <colors.primary>;
67
+ --primary-foreground: <colors.primary-foreground>;
68
+ /* ... all semantic slots ... */
69
+ --radius: <rounded.md>;
70
+ }
71
+
72
+ .dark {
73
+ /* dark-mode overrides if declared in DESIGN.md */
74
+ }
75
+ ```
76
+
77
+ ### Colour handling
78
+
79
+ - Emit colour values **exactly as declared** in DESIGN.md (hex, rgb, hsl, oklch — whatever the consumer wrote).
80
+ - Do **not** convert between colour spaces. `@theme` accepts any valid CSS colour.
81
+ - If DESIGN.md uses hex and the consumer later wants OKLCH, that is a DESIGN.md authoring decision, not a generator decision.
82
+
83
+ ### Slot mapping
84
+
85
+ The semantic slots below are the ones Tailwind v4 + shadcn components consume via `@theme inline`. `ux-theme-gen` maps from DESIGN.md token names to these slots:
86
+
87
+ | DESIGN.md token | CSS variable | @theme inline mapping |
88
+ | ------------------------------- | -------------------------- | --------------------------------------------------------------- |
89
+ | `colors.background` | `--background` | `--color-background: var(--background)` |
90
+ | `colors.foreground` | `--foreground` | `--color-foreground: var(--foreground)` |
91
+ | `colors.primary` | `--primary` | `--color-primary: var(--primary)` |
92
+ | `colors.primary-foreground` | `--primary-foreground` | `--color-primary-foreground: var(--primary-foreground)` |
93
+ | `colors.secondary` | `--secondary` | `--color-secondary: var(--secondary)` |
94
+ | `colors.secondary-foreground` | `--secondary-foreground` | `--color-secondary-foreground: var(--secondary-foreground)` |
95
+ | `colors.muted` | `--muted` | `--color-muted: var(--muted)` |
96
+ | `colors.muted-foreground` | `--muted-foreground` | `--color-muted-foreground: var(--muted-foreground)` |
97
+ | `colors.accent` | `--accent` | `--color-accent: var(--accent)` |
98
+ | `colors.accent-foreground` | `--accent-foreground` | `--color-accent-foreground: var(--accent-foreground)` |
99
+ | `colors.destructive` | `--destructive` | `--color-destructive: var(--destructive)` |
100
+ | `colors.destructive-foreground` | `--destructive-foreground` | `--color-destructive-foreground: var(--destructive-foreground)` |
101
+ | `colors.border` | `--border` | `--color-border: var(--border)` |
102
+ | `colors.input` | `--input` | `--color-input: var(--input)` |
103
+ | `colors.ring` | `--ring` | `--color-ring: var(--ring)` |
104
+ | `colors.card` | `--card` | `--color-card: var(--card)` |
105
+ | `colors.card-foreground` | `--card-foreground` | `--color-card-foreground: var(--card-foreground)` |
106
+
107
+ Tokens in `colors-extended` get their own `--<name>` variable in `:root` and a `--color-<name>` in `@theme inline`.
108
+
109
+ ### `tokens.json` structure
110
+
111
+ ```json
112
+ {
113
+ "colors": { "background": "#...", "foreground": "#...", ... },
114
+ "colors-extended": { ... },
115
+ "typography": { ... },
116
+ "rounded": { "sm": "6px", "md": "8px", "lg": "12px" },
117
+ "spacing": { "xs": "4px", ... }
118
+ }
119
+ ```
120
+
121
+ ### Generated file header
122
+
123
+ Every generated file **MUST** start with:
124
+
125
+ ```
126
+ /* DO NOT EDIT — generated from /DESIGN.md by ux-theme-gen */
127
+ ```
128
+
129
+ (or the equivalent comment syntax for `.ts` / `.json`).
130
+
131
+ ## Rules
132
+
133
+ 1. **Read-only on DESIGN.md** — never modify the contract.
134
+ 2. **Refuse on placeholder** — never generate from unfilled tokens.
135
+ 3. **No colour-space conversion** — emit values as declared.
136
+ 4. **Idempotent** — running twice with the same DESIGN.md produces byte-identical output.
137
+ 5. **Regenerable** — hand-edits to generated files are findings; the correct fix is to update DESIGN.md and regenerate.
138
+ 6. **Independent of mockup workflow** — `developer` can invoke this skill directly for production theming.
139
+
140
+ ## Acceptance Checklist
141
+
142
+ - Contract check runs before any file is written
143
+ - Refuses against a placeholder or partially-unfilled DESIGN.md
144
+ - Generated `theme.css` uses `@theme inline` (Tailwind v4 pattern)
145
+ - Generated `tokens.json` is valid JSON with all token groups
146
+ - `rn-theme.ts` is only produced when `platform` includes `mobile` or `both`
147
+ - No hardcoded palette values exist in output (all derived from DESIGN.md)
148
+ - Every generated file carries the DO-NOT-EDIT header
149
+ - Output directory matches `theme_output` from front matter or defaults to `/mockups/.theme/`
@@ -138,12 +138,23 @@ Follow `.kiro/steering/implement.md`:
138
138
  | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
139
139
  | `product-engineer` | Produces the task lists and refined issues that `developer` executes |
140
140
  | `planner` | Orchestrates multi-story runs — delegates each story to `developer` in Execute Mode with an integration branch override |
141
+ | `researcher` | May be invoked by `developer` for troubleshooting/diagnosis when a bug or regression is unclear; conditional, never mandatory |
141
142
  | `verifier` | Invoked by `developer` in `audit` mode, post-implementation and pre-PR-ready, mandatory and non-skippable — reports fidelity/drift; findings route to `product-engineer`'s `activity-drift-reconciliation` for remediation |
142
143
  | `qa-engineer` | Invoked by `developer` at the completion gate, before the `verifier` audit — owns the testing standard, missing test harnesses, and coverage/gap reporting; `developer` still authors feature tests under rule 19 |
143
144
  | `technical-writer` | Invoked by `developer` before PR is marked ready — updates `/docs` |
144
145
  | `housekeeping` | Can be invoked during implementation for lint/type/test-wiring fixes |
145
146
  | `github-ops` | Defines conventions for all GitHub artifacts — `developer` follows these rules |
146
147
 
148
+ ### Codebase Research for Troubleshooting (Conditional)
149
+
150
+ When diagnosing a bug, regression, or unclear failure during implementation, you **SHOULD** invoke `researcher` if:
151
+
152
+ - The failure spans multiple modules and the root cause is not immediately apparent.
153
+ - The area is unfamiliar or lacks documentation.
154
+ - Multiple hypotheses need codebase evidence to disambiguate.
155
+
156
+ **Skip when:** the failure is localized to a single file or function, or the root cause is already identified. This is a recommended diagnostic tool, not a mandatory gate.
157
+
147
158
  ---
148
159
 
149
160
  ## Autonomous Behavior Contract
@@ -84,6 +84,20 @@ If any required input is missing, ask one focused question with a default option
84
84
 
85
85
  ---
86
86
 
87
+ ## Codebase Research for Pre-Orchestration (Conditional)
88
+
89
+ Before parsing stories and building the dependency graph, you **SHOULD** invoke `researcher` if:
90
+
91
+ - The stories span multiple modules or packages whose dependencies are not yet established.
92
+ - The orchestration involves unfamiliar areas of the codebase.
93
+ - Story ordering requires understanding cross-module data flow or contract boundaries.
94
+
95
+ **Skip when:** story dependencies are already explicit in the task file, the codebase is small and well-understood, or a non-stale research artifact already covers the scope.
96
+
97
+ When triggered, delegate to `researcher` with the orchestration question (e.g., "What are the dependency relationships between modules X, Y, and Z?"). Consume the resulting `/workstream/research-*.md` artifact to inform dependency ordering in Phase 1.
98
+
99
+ ---
100
+
87
101
  ## Phase 0 - Discover Task Source
88
102
 
89
103
  ### Option A - File in /workstream
@@ -456,15 +470,16 @@ Planner **MUST NOT** allow multiple open story PRs to merge concurrently.
456
470
  After all stories are merged into integration:
457
471
 
458
472
  1. Run full integration test suite on integration branch.
459
- 2. Invoke `verifier` in `audit` mode for a **PRD-level rollup audit** against the full integrated scope (all merged stories on the integration branch, cross-checked against the source PRD/spec/milestone). This is mandatory and non-skippable — it runs whether or not any story-level drift was previously reported. Post the resulting human-readable summary to the plan/milestone issue via `github-ops` comment conventions. Rollup drift findings **MUST NOT** block the consolidated PR handoff; Unintended/Intended drift routes to `product-engineer`'s `activity-drift-reconciliation` flow.
460
- 3. Invoke `technical-writer` for a planner-level drift/stale-doc validation pass against integrated changes; unresolved drift **MUST** block handoff.
461
- 4. Open one consolidated PR from integration branch to `main`.
462
- 5. **Do NOT merge.** Notify the user that the consolidated PR is ready for their review.
463
- 6. Wait for the user to approve and merge the PR into `main`.
464
- 7. Before final handoff, **MUST** ensure the local working branch is the integration branch used for this run:
473
+ 2. Invoke `qa-engineer` at **PRD scope** (all packages affected by the merged stories, all layers) for a coverage and gap rollup. Report a PRD-level `coverage_gate` that aggregates per-story gates. Scope to packages affected by the merged stories, not the entire workspace.
474
+ 3. Invoke `verifier` in `audit` mode for a **PRD-level rollup audit** against the full integrated scope (all merged stories on the integration branch, cross-checked against the source PRD/spec/milestone). This is mandatory and non-skippable — it runs whether or not any story-level drift was previously reported. Post the resulting human-readable summary to the plan/milestone issue via `github-ops` comment conventions. Rollup drift findings **MUST NOT** block the consolidated PR handoff; Unintended/Intended drift routes to `product-engineer`'s `activity-drift-reconciliation` flow.
475
+ 4. Invoke `technical-writer` for a planner-level drift/stale-doc validation pass against integrated changes; unresolved drift **MUST** block handoff.
476
+ 5. Open one consolidated PR from integration branch to `main`.
477
+ 6. **Do NOT merge.** Notify the user that the consolidated PR is ready for their review.
478
+ 7. Wait for the user to approve and merge the PR into `main`.
479
+ 8. Before final handoff, **MUST** ensure the local working branch is the integration branch used for this run:
465
480
  - Preferred: run `git checkout integration/<plan-id>-<short-description>`.
466
481
  - Alternative (if checkout is not possible in the current runtime): explicitly verify and report current branch, and provide the exact checkout command the user can run.
467
- 8. Final user response **MUST** include a `PR Directives (User Action Required)` section with:
482
+ 9. Final user response **MUST** include a `PR Directives (User Action Required)` section with:
468
483
  - consolidated PR URL
469
484
  - current CI/check status
470
485
  - exact required user actions: review, approve, and merge