@llipe.com/dev-tasks 0.6.4 → 0.6.5

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 (143) hide show
  1. package/.claude/agents/developer.md +294 -0
  2. package/.claude/agents/github-ops.md +407 -0
  3. package/.claude/agents/housekeeping.md +109 -0
  4. package/.claude/agents/technical-writer.md +390 -0
  5. package/.claude/agents/ux-engineer.md +184 -0
  6. package/.claude/agents/verifier.md +276 -0
  7. package/.claude/commands/developer.md +272 -0
  8. package/.claude/commands/github-ops.md +10 -0
  9. package/.claude/commands/housekeeping.md +10 -0
  10. package/.claude/commands/planner.md +506 -0
  11. package/.claude/commands/product-engineer.md +263 -0
  12. package/.claude/commands/technical-writer.md +10 -0
  13. package/.claude/commands/ux-engineer.md +10 -0
  14. package/.claude/commands/verifier-audit.md +10 -0
  15. package/.claude/commands/verifier-design.md +10 -0
  16. package/.claude/hooks/git-guard.sh +95 -0
  17. package/.claude/skills/activity-contract-test-design/SKILL.md +122 -0
  18. package/.claude/skills/activity-drift-reconciliation/SKILL.md +133 -0
  19. package/.claude/skills/activity-e2e-test-design/SKILL.md +124 -0
  20. package/.claude/skills/activity-edge-case-refinement/SKILL.md +146 -0
  21. package/.claude/skills/activity-generate-spec/SKILL.md +137 -0
  22. package/.claude/skills/activity-generate-stories/SKILL.md +243 -0
  23. package/.claude/skills/activity-init/SKILL.md +162 -0
  24. package/.claude/skills/activity-publish-github/SKILL.md +116 -0
  25. package/.claude/skills/activity-random-test-tactics/SKILL.md +181 -0
  26. package/.claude/skills/activity-refine/SKILL.md +236 -0
  27. package/.claude/skills/git-ops/SKILL.md +221 -0
  28. package/.claude/skills/implement/SKILL.md +129 -0
  29. package/.claude/skills/memo-cli-usage/REFERENCE.md +798 -0
  30. package/.claude/skills/memo-cli-usage/SKILL.md +144 -0
  31. package/.claude/skills/plan/SKILL.md +145 -0
  32. package/.claude/skills/webapp-mockup/SKILL.md +76 -0
  33. package/.claude/skills/webapp-mockup/scripts/scaffold-mockup.sh +469 -0
  34. package/.github/agents/developer.agent.md +293 -0
  35. package/.github/agents/github-ops.agent.md +416 -0
  36. package/.github/agents/housekeeping.agent.md +109 -0
  37. package/.github/agents/planner.agent.md +496 -0
  38. package/.github/agents/product-engineer.agent.md +262 -0
  39. package/.github/agents/technical-writer.agent.md +389 -0
  40. package/.github/agents/ux-engineer.agent.md +183 -0
  41. package/.github/agents/verifier.agent.md +275 -0
  42. package/.github/instructions/domain/nextjs-pages-components.instructions.md +375 -0
  43. package/.github/instructions/implement.instructions.md +128 -0
  44. package/.github/instructions/plan.instructions.md +144 -0
  45. package/.github/prompts/developer-execute.prompt.md +13 -0
  46. package/.github/prompts/github-ops.prompt.md +16 -0
  47. package/.github/prompts/housekeeping.prompt.md +16 -0
  48. package/.github/prompts/planner-resume.prompt.md +13 -0
  49. package/.github/prompts/planner.prompt.md +18 -0
  50. package/.github/prompts/product-engineer-feature.prompt.md +21 -0
  51. package/.github/prompts/product-engineer-init.prompt.md +16 -0
  52. package/.github/prompts/product-engineer-issue.prompt.md +19 -0
  53. package/.github/prompts/technical-writer.prompt.md +21 -0
  54. package/.github/prompts/ux-engineer.prompt.md +14 -0
  55. package/.github/prompts/verifier-audit.prompt.md +33 -0
  56. package/.github/prompts/verifier-design.prompt.md +28 -0
  57. package/.github/skills/activity-contract-test-design/SKILL.md +117 -0
  58. package/.github/skills/activity-drift-reconciliation/SKILL.md +128 -0
  59. package/.github/skills/activity-e2e-test-design/SKILL.md +119 -0
  60. package/.github/skills/activity-edge-case-refinement/SKILL.md +141 -0
  61. package/.github/skills/activity-generate-spec/SKILL.md +132 -0
  62. package/.github/skills/activity-generate-stories/SKILL.md +238 -0
  63. package/.github/skills/activity-init/SKILL.md +157 -0
  64. package/.github/skills/activity-publish-github/SKILL.md +111 -0
  65. package/.github/skills/activity-random-test-tactics/SKILL.md +176 -0
  66. package/.github/skills/activity-refine/SKILL.md +231 -0
  67. package/.github/skills/git-ops/SKILL.md +216 -0
  68. package/.github/skills/memo-cli-usage/REFERENCE.md +798 -0
  69. package/.github/skills/memo-cli-usage/SKILL.md +144 -0
  70. package/.github/skills/webapp-mockup/SKILL.md +71 -0
  71. package/.github/skills/webapp-mockup/scripts/scaffold-mockup.sh +469 -0
  72. package/.kiro/agents/developer.md +305 -0
  73. package/.kiro/agents/github-ops.md +428 -0
  74. package/.kiro/agents/housekeeping.md +122 -0
  75. package/.kiro/agents/planner.md +530 -0
  76. package/.kiro/agents/product-engineer.md +294 -0
  77. package/.kiro/agents/technical-writer.md +408 -0
  78. package/.kiro/agents/ux-engineer.md +200 -0
  79. package/.kiro/agents/verifier.md +275 -0
  80. package/.kiro/hooks/git-guard.json +16 -0
  81. package/.kiro/hooks/scripts/git-guard.sh +116 -0
  82. package/.kiro/skills/activity-contract-test-design/SKILL.md +122 -0
  83. package/.kiro/skills/activity-drift-reconciliation/SKILL.md +133 -0
  84. package/.kiro/skills/activity-e2e-test-design/SKILL.md +124 -0
  85. package/.kiro/skills/activity-edge-case-refinement/SKILL.md +146 -0
  86. package/.kiro/skills/activity-generate-spec/SKILL.md +137 -0
  87. package/.kiro/skills/activity-generate-stories/SKILL.md +243 -0
  88. package/.kiro/skills/activity-init/SKILL.md +162 -0
  89. package/.kiro/skills/activity-publish-github/SKILL.md +116 -0
  90. package/.kiro/skills/activity-random-test-tactics/SKILL.md +181 -0
  91. package/.kiro/skills/activity-refine/SKILL.md +236 -0
  92. package/.kiro/skills/git-ops/SKILL.md +221 -0
  93. package/.kiro/skills/memo-cli-usage/REFERENCE.md +798 -0
  94. package/.kiro/skills/memo-cli-usage/SKILL.md +144 -0
  95. package/.kiro/skills/webapp-mockup/SKILL.md +76 -0
  96. package/.kiro/steering/git-guard-notice.md +11 -0
  97. package/.kiro/steering/implement.md +129 -0
  98. package/.kiro/steering/nextjs-pages-components.md +376 -0
  99. package/.kiro/steering/plan.md +145 -0
  100. package/AGENTS.md +122 -0
  101. package/CHANGELOG.md +18 -2
  102. package/CLAUDE.md +94 -0
  103. package/README.md +6 -6
  104. package/dist/adapters/cli/extract-all.js +4 -4
  105. package/dist/adapters/cli/extract-component.d.ts +1 -1
  106. package/dist/adapters/cli/extract-component.js +4 -4
  107. package/dist/adapters/cli/parse-args.d.ts +1 -0
  108. package/dist/adapters/cli/parse-args.d.ts.map +1 -1
  109. package/dist/adapters/cli/parse-args.js +4 -0
  110. package/dist/adapters/cli/parse-args.js.map +1 -1
  111. package/dist/bin/dev-tasks.js +23 -9
  112. package/dist/bin/dev-tasks.js.map +1 -1
  113. package/dist/bin/dt.js +3 -3
  114. package/dist/core/distribution/index.d.ts +5 -3
  115. package/dist/core/distribution/index.d.ts.map +1 -1
  116. package/dist/core/distribution/index.js +3 -2
  117. package/dist/core/distribution/index.js.map +1 -1
  118. package/dist/core/distribution/install.d.ts +20 -8
  119. package/dist/core/distribution/install.d.ts.map +1 -1
  120. package/dist/core/distribution/install.js +76 -36
  121. package/dist/core/distribution/install.js.map +1 -1
  122. package/dist/core/distribution/manifest.d.ts +25 -2
  123. package/dist/core/distribution/manifest.d.ts.map +1 -1
  124. package/dist/core/distribution/manifest.js +29 -2
  125. package/dist/core/distribution/manifest.js.map +1 -1
  126. package/dist/core/distribution/migrate.d.ts +6 -3
  127. package/dist/core/distribution/migrate.d.ts.map +1 -1
  128. package/dist/core/distribution/migrate.js +21 -19
  129. package/dist/core/distribution/migrate.js.map +1 -1
  130. package/dist/core/distribution/profiles.d.ts +30 -0
  131. package/dist/core/distribution/profiles.d.ts.map +1 -0
  132. package/dist/core/distribution/profiles.js +57 -0
  133. package/dist/core/distribution/profiles.js.map +1 -0
  134. package/dist/core/distribution/update.d.ts +6 -4
  135. package/dist/core/distribution/update.d.ts.map +1 -1
  136. package/dist/core/distribution/update.js +22 -22
  137. package/dist/core/distribution/update.js.map +1 -1
  138. package/dist/core/extract/component.d.ts +9 -9
  139. package/dist/core/extract/component.js +5 -5
  140. package/dist/core/extract/report.d.ts +1 -1
  141. package/dist/core/extract/report.js +1 -1
  142. package/package.json +15 -2
  143. package/skills/.gitkeep +0 -0
@@ -0,0 +1,375 @@
1
+ ---
2
+ applyTo: "**/app/**/*.tsx"
3
+ ---
4
+
5
+ <!-- Consumers: adjust applyTo to match your Next.js app path. For React Native projects, replace with a react-native steering file (see issue #13). -->
6
+
7
+ # Rule: Keep Next.js Pages and React Components Consistent
8
+
9
+ > **RFC 2119 Notice:** The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
10
+
11
+ ## Goal
12
+
13
+ Guide GitHub Copilot when creating or editing Next.js pages and React components so the UI stays consistent in:
14
+
15
+ - libraries and dependencies
16
+ - component patterns
17
+ - page structure
18
+ - styling conventions
19
+ - accessibility
20
+ - testing expectations
21
+ - general visual design
22
+
23
+ ## Scope
24
+
25
+ Apply these rules to UI work inside `src/app` and `src/components`.
26
+
27
+ This project uses:
28
+
29
+ - **Next.js 16+** with **App Router**
30
+ - **React 19**
31
+ - **TypeScript strict mode**
32
+ - **Tailwind CSS** as the preferred styling foundation for page and component UI work
33
+ - **Zod** for validation
34
+ - local app components and utilities only
35
+
36
+ ## Library and Dependency Rules
37
+
38
+ 1. You **SHOULD** prefer the current stack only.
39
+
40
+ - Use built-in React and Next.js APIs first.
41
+ - Use existing local helpers from `@/lib/*` and local components from `@/components/*`.
42
+ - Use `zod`-based validators from `@/lib/validation/*` for form validation.
43
+ - Prefer `Tailwind CSS` for styling and visual consistency.
44
+
45
+ 2. You **MUST** use Tailwind CSS as the default styling system.
46
+
47
+ - Treat Tailwind as the standard foundation for layout, spacing, color, typography, and state styles.
48
+ - Prefer utility classes over ad hoc CSS approaches for page and component implementation.
49
+ - If reusable patterns emerge, extract local primitives in `src/components/ui`.
50
+
51
+ 3. You **MUST NOT** introduce an opinionated component library by default.
52
+
53
+ - You **MUST NOT** add MUI, Chakra UI, Ant Design, Radix wrappers, styled-components, Emotion, Framer Motion, or similar libraries unless the user explicitly asks for them.
54
+ - You **MUST NOT** assume `shadcn/ui` is available unless it already exists in the app.
55
+ - You **MUST NOT** introduce `shadcn/ui` by default. Reevaluate it only if the project explicitly chooses it as a product and engineering decision.
56
+
57
+ 4. You **MUST NOT** solve simple UI problems with extra dependencies.
58
+
59
+ - Prefer plain React components and existing utility-class styling.
60
+ - If a reusable primitive is needed, create it locally in `src/components/ui`.
61
+
62
+ 5. You **SHOULD** prefer local UI primitives before external component kits.
63
+
64
+ - Build and reuse a small internal set of primitives such as `Button`, `Input`, `Card`, `Badge`, `Alert`, and `PageHeader`.
65
+ - Keep those primitives aligned with the approved palette and accessibility rules.
66
+
67
+ 6. You **MUST** keep app boundaries strict.
68
+ - You **MUST NOT** import UI or business logic from sibling apps.
69
+ - Only use shared packages when they are already intended for cross-app use.
70
+
71
+ ## Component and Page Architecture
72
+
73
+ ### General Rules
74
+
75
+ 1. You **MUST** default to Server Components.
76
+
77
+ - Pages and components **SHOULD** remain server components unless they need client-only features.
78
+ - You **MUST** add `'use client'` only when the component uses state, effects, browser APIs, event handlers, or client hooks such as `useRouter()`.
79
+
80
+ 2. You **MUST** keep pages thin.
81
+
82
+ - A page **SHOULD** primarily define metadata, route-level composition, and high-level layout.
83
+ - Move repeated UI sections into components.
84
+ - Move validation, formatting, mapping, and business rules into `@/lib`.
85
+
86
+ 3. You **MUST** keep components focused.
87
+
88
+ - One component **SHOULD** have one clear responsibility.
89
+ - If JSX becomes long or repeats existing patterns, extract smaller subcomponents.
90
+
91
+ 4. You **SHOULD** prefer composition over large monolithic components.
92
+
93
+ - Build pages from small sections such as page header, content card, form section, status panel, or empty state.
94
+
95
+ 5. **Use project import conventions**.
96
+ - Prefer `@/` aliases for app-local imports.
97
+ - Keep imports grouped as: React/Next, third-party, app-local.
98
+
99
+ ### File Naming and Exports
100
+
101
+ 1. Follow the **existing codebase convention** for file names:
102
+
103
+ - component files: kebab-case, e.g. `login-form.tsx`, `auth-error-display.tsx`
104
+ - page files: Next.js App Router defaults such as `page.tsx`, `layout.tsx`
105
+ - test files: same base name with `.test.tsx`
106
+
107
+ 2. Use **PascalCase** for exported React component names.
108
+
109
+ - Example: file `login-form.tsx` exports `LoginForm`.
110
+
111
+ 3. Keep related tests close to the page or component when practical.
112
+
113
+ ## Next.js-Specific Rules
114
+
115
+ 1. **Export `metadata` for pages when relevant**.
116
+
117
+ - Public and major app pages **SHOULD** provide title and description.
118
+ - Keep titles consistent with the product name of your app.
119
+
120
+ 2. **Use the right navigation primitive**.
121
+
122
+ - Use `Link` from `next/link` for internal navigation in rendered UI.
123
+ - Use `redirect()` in server-side route/page flows.
124
+ - Use `useRouter()` only in client components when navigation must happen after a client event.
125
+
126
+ 3. **Use App Router conventions**.
127
+
128
+ - Route-level concerns stay in `src/app/...`.
129
+ - Reusable UI goes in `src/components/...`.
130
+ - Do not hide route-specific business logic inside presentational components.
131
+
132
+ 4. **Prefer route-group consistency**.
133
+
134
+ - Public auth screens **SHOULD** match the current auth page pattern.
135
+ - Protected pages **SHOULD** match the existing protected layout and page shell.
136
+
137
+ 5. **Prefer server-first data fetching**.
138
+
139
+ - Fetch data in Server Components by default.
140
+ - Use client-side fetching only when the UI requires interactive, user-driven, or live-updating state.
141
+ - Do not move simple read-only page data fetching into client components unless there is a clear product need.
142
+
143
+ 6. **Keep async boundaries intentional**.
144
+ - Server Components **SHOULD** handle initial page data and route-level loading needs.
145
+ - Client components **SHOULD** focus on interaction, optimistic UI, transient state, and browser-only behavior.
146
+
147
+ ## Styling and Design Rules
148
+
149
+ 1. **Follow the existing utility-class styling approach**.
150
+
151
+ - Match the current class patterns already used across the app.
152
+ - Do not introduce inline style objects unless there is no reasonable alternative.
153
+ - You **MUST NOT** introduce CSS-in-JS.
154
+
155
+ 2. **Use the approved app color palette**.
156
+
157
+ - Base palette:
158
+ - Sky Blue (Light): `#8ecae6`
159
+ - Blue Green: `#219ebc`
160
+ - Deep Space Blue: `#023047`
161
+ - Amber Flame: `#ffb703`
162
+ - Tiger Orange: `#fb8500`
163
+ - Neutral surfaces:
164
+ - Primary light surfaces **SHOULD** prefer white or near-white backgrounds.
165
+ - Dark sections may use dark gray or near-black backgrounds when stronger contrast or emphasis is needed.
166
+ - Semantic usage guidance:
167
+ - Primary brand/background accent: Deep Space Blue
168
+ - Secondary accent and interactive emphasis: Blue Green
169
+ - Supporting light highlight/background tint: Sky Blue
170
+ - Attention, highlights, badges, and positive energy moments: Amber Flame
171
+ - Strong CTA, active emphasis, or warning-energy accent: Tiger Orange
172
+
173
+ 3. **Translate the palette into a consistent UI language**.
174
+
175
+ - Prefer white, off-white, dark gray, and near-black as the structural backgrounds.
176
+ - Use the palette colors as accents, emphasis colors, and branded surfaces.
177
+ - Avoid rainbow-like mixing of all five colors in the same component.
178
+ - A single screen **SHOULD** usually have:
179
+ - one dominant brand color
180
+ - one supporting accent color
181
+ - neutral backgrounds
182
+ - Preserve readable contrast for text, borders, and interactive states.
183
+
184
+ 4. **Preferred visual roles**.
185
+
186
+ - App shell, headers, hero bands, and primary branded panels: Deep Space Blue
187
+ - Links, secondary buttons, focus states, and info accents: Blue Green
188
+ - Soft highlights, subtle banners, or decorative backgrounds: Sky Blue
189
+ - Status chips, counters, feature highlights, and attention markers: Amber Flame
190
+ - Primary CTA emphasis, strong hover accents, and promotional emphasis: Tiger Orange
191
+ - Default content surfaces: white
192
+ - Optional high-contrast surfaces: dark gray / black
193
+
194
+ 5. **Preserve current layout patterns**.
195
+
196
+ - Public/auth pages usually use a centered container with `min-h-screen`, a neutral background, and a card-style form panel.
197
+ - Protected pages usually use a page shell with a header area, content cards, and responsive spacing.
198
+
199
+ 6. **Prefer reusable visual patterns**.
200
+
201
+ - Cards: `rounded-lg bg-white p-6 shadow`
202
+ - Section headings: bold dark text with consistent margin spacing
203
+ - Inputs: bordered, rounded, neutral background, visible focus state
204
+ - Primary buttons: Tiger Orange or Deep Space Blue background with white text and clear disabled state
205
+ - Secondary buttons: white or dark surface with Blue Green accents and visible border/focus styles
206
+ - Alert panels: semantic border/background/text color combinations
207
+
208
+ 7. You **MUST** avoid one-off visual decisions.
209
+
210
+ - You **MUST NOT** invent a new color palette for a single page.
211
+ - You **MUST NOT** mix drastically different spacing, corner radius, or button styles on similar screens.
212
+ - You **MUST NOT** introduce arbitrary hex colors outside the approved palette unless the user explicitly requests it or accessibility requires it.
213
+ - If a pattern repeats, you **SHOULD** extract a reusable component.
214
+
215
+ 8. You **MUST** design mobile-first.
216
+
217
+ - Start with small-screen layouts and scale up for tablet and desktop.
218
+ - Every new page and major component **SHOULD** work across small, medium, and large breakpoints.
219
+ - Prefer progressive enhancement of spacing, grid layout, and density instead of separate disconnected layouts.
220
+
221
+ 9. **Use dark surfaces deliberately**.
222
+
223
+ - Prefer dark gray or near-black backgrounds for app shell elements, navigation, hero sections, or emphasis panels.
224
+ - Prefer light surfaces for dense forms, data entry, tables, and long-reading content unless a specific design requires otherwise.
225
+ - Keep contrast high when palette accents are placed on dark backgrounds.
226
+
227
+ 10. **Move toward reusable design tokens and shared patterns**.
228
+
229
+ - When colors, spacing, radius, shadows, or typography styles repeat, prefer centralizing them through shared utility patterns or local primitives.
230
+ - Avoid scattering slightly different visual values across many components.
231
+
232
+ ## Forms and Validation
233
+
234
+ 1. **Reuse validation patterns already present in the app**.
235
+
236
+ - Use validators from `@/lib/validation/*`.
237
+ - Keep validation messages explicit and user-friendly.
238
+ - Validate before submitting.
239
+
240
+ 2. **Keep form UX consistent**.
241
+
242
+ - Use labels for every field.
243
+ - Show inline field-level validation errors near the relevant field.
244
+ - Show request or auth failures in a clear alert area.
245
+ - Reflect loading and disabled states during submission.
246
+
247
+ 3. **Do not put schema logic inside JSX files when it already belongs in `lib/validation`**.
248
+
249
+ 4. **Use a consistent submission pattern**.
250
+ - Prefer a single clear pattern per feature for form submission and mutation handling.
251
+ - Keep form UI concerns in the component and keep request, validation, and transformation logic in route handlers, server actions, or `@/lib` helpers as appropriate.
252
+ - Do not mix multiple submission patterns in the same feature without a clear reason.
253
+
254
+ ## Accessibility Rules
255
+
256
+ 1. Use semantic HTML first.
257
+
258
+ - Use `main`, `section`, `header`, `form`, `label`, `button`, and heading levels correctly.
259
+
260
+ 2. Every interactive element must be accessible.
261
+
262
+ - Inputs must be associated with labels.
263
+ - Buttons must have an explicit `type`.
264
+ - Error messages should use `role="alert"` when appropriate.
265
+ - Disabled and loading states must be visually and semantically clear.
266
+
267
+ 3. Preserve keyboard and focus behavior.
268
+
269
+ - Keep visible focus styles.
270
+ - Do not remove focus indicators.
271
+
272
+ 4. Prefer readable copy.
273
+
274
+ - Avoid vague CTA text like `Submit` when a clearer label such as `Sign in` or `Save changes` is possible.
275
+
276
+ 5. Keep interface copy concise and operational.
277
+ - Prefer plain English.
278
+ - Avoid overly promotional or marketing-heavy language in product screens.
279
+ - Labels, helper text, empty states, and errors should be direct and specific.
280
+
281
+ ## Data and State Rules
282
+
283
+ 1. **Keep presentation separate from business logic**.
284
+
285
+ - Formatting, validation, error mapping, and API transformations belong outside presentational JSX where possible.
286
+
287
+ 2. **Keep client state minimal**.
288
+
289
+ - Only store what the component truly owns.
290
+ - Prefer derived state over duplicated state.
291
+
292
+ 3. **Be explicit with empty, error, and loading states**.
293
+
294
+ - Pages and components should not silently fail.
295
+
296
+ 4. **Use consistent fallback state patterns**.
297
+ - Empty states should explain what is missing and what the user can do next.
298
+ - Loading states should use lightweight skeletons, placeholders, or progress text that match the surrounding layout.
299
+ - Error states should clearly state the problem and, when possible, the next recovery action.
300
+
301
+ ## Primitive Component Rules
302
+
303
+ 1. Local primitives should follow a consistent API when applicable.
304
+
305
+ - Support shared props such as `variant`, `size`, and `className` where those concepts make sense.
306
+ - Forward native element props whenever practical.
307
+ - Preserve accessible defaults.
308
+
309
+ 2. Interactive primitives should support standard states.
310
+
311
+ - Include disabled styles where relevant.
312
+ - Include loading states for action-triggering controls when relevant.
313
+ - Keep focus styles visible and consistent.
314
+
315
+ 3. Do not create multiple competing primitive patterns.
316
+ - Reuse or extend the existing primitive instead of creating a near-duplicate version.
317
+
318
+ ## Icons and Motion
319
+
320
+ 1. Icons are allowed, but they must stay consistent.
321
+
322
+ - Prefer a single lightweight icon library across the app if one is introduced.
323
+ - Do not mix multiple icon libraries in the same application.
324
+ - If no icon library is present for the feature, prefer inline SVG or local icon components instead of adding a dependency casually.
325
+
326
+ 2. Keep motion subtle.
327
+ - Prefer simple CSS or utility-based transitions for hover, focus, expand/collapse, and feedback states.
328
+ - Avoid heavy or decorative animation by default.
329
+ - Do not add animation libraries unless the user explicitly requests them.
330
+
331
+ ## Testing Rules
332
+
333
+ 1. New pages and interactive components should include or update tests.
334
+ 2. Use the existing Jest + Testing Library setup.
335
+ 3. Prefer queries by role, label, and visible text.
336
+ 4. Use `data-testid` only when semantic queries are not stable enough.
337
+ 5. Test the user-visible behavior:
338
+ - rendering
339
+ - validation errors
340
+ - loading states
341
+ - disabled states
342
+ - navigation intent
343
+ - success and failure feedback
344
+
345
+ ## Consistency Checklist
346
+
347
+ Before finishing a page or component, verify:
348
+
349
+ - It uses existing Next.js and React patterns.
350
+ - It does not add unnecessary dependencies.
351
+ - It matches the current app styling.
352
+ - It uses semantic, accessible markup.
353
+ - It keeps business logic outside presentational code when possible.
354
+ - It reuses or extracts shared UI patterns instead of duplicating them.
355
+ - It includes or updates tests when behavior changes.
356
+
357
+ ## Avoid These Defaults
358
+
359
+ - Adding a new UI framework without approval
360
+ - Adding custom design systems unrelated to current screens
361
+ - Mixing multiple styling approaches in the same feature
362
+ - Making every component a client component
363
+ - Putting API/business logic directly into presentational JSX
364
+ - Using internal `<a href>` links where `Link` is more appropriate
365
+ - Creating visually inconsistent buttons, cards, or form layouts
366
+
367
+ ## Preferred Outcome
368
+
369
+ Every new page or component should feel like it belongs to the same product:
370
+
371
+ - same stack
372
+ - same structure
373
+ - same interaction patterns
374
+ - same visual language
375
+ - same quality bar for accessibility and testing
@@ -0,0 +1,128 @@
1
+ ---
2
+ applyTo: "workstream/**/tasks-*.md"
3
+ ---
4
+
5
+ # Activity: Implement Task List
6
+
7
+ > **RFC 2119 Notice:** The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
8
+
9
+ ## Goal
10
+
11
+ Execute a task list step-by-step with strict sequencing, proper branching, PR workflow, GitHub Issue synchronization, and user approval gates.
12
+
13
+ This is the **single source of truth** for execution rules. All agents and workflows that perform implementation **MUST** follow these rules.
14
+
15
+ ## Context
16
+
17
+ This activity assumes:
18
+
19
+ - A task list file exists in `/workstream/tasks-*.md`.
20
+ - The corresponding GitHub Issue exists and includes a checklist.
21
+ - GitHub is the source of truth for execution status.
22
+
23
+ ## Package Manager and Command Standards
24
+
25
+ - For JavaScript/TypeScript repositories, you **MUST** prefer `pnpm` over `npm` for dependency and script commands.
26
+ - You **MAY** use `npm` only when `pnpm` is unavailable or the project is explicitly npm-locked.
27
+ - For JS/TS repositories, quality and test execution **MUST** use canonical `package.json` script names where available: `lint`, `format:check`, `typecheck`, `test`, `audit`, and `validate`.
28
+
29
+ ---
30
+
31
+ ## Before Starting Work
32
+
33
+ 1. You **MUST** confirm the GitHub Issue is open.
34
+ 2. You **MUST** create a new branch from the latest default branch by delegating branch naming and creation to `github-ops` whenever possible.
35
+ - Branch format: `issue/<issue-number>-<short-description>` or `story/<id>-<short-description>`
36
+ 3. You **MUST** open a **draft Pull Request** by delegating to `github-ops` whenever possible.
37
+ - Base branch is the default branch unless an orchestrating caller explicitly provides a base-branch override.
38
+ - PR title **MUST** follow Conventional Commits (e.g., `feat: implement issue 37`).
39
+ - PR description **MUST** include `Closes #<issue-number>`.
40
+ 4. You **MUST** ensure the task list in the GitHub Issue matches the local `/workstream/tasks-*.md` file.
41
+
42
+ If `github-ops` delegation is unavailable in the current runtime, you **MUST** apply `github-ops` conventions directly and explicitly note that fallback in your status output.
43
+
44
+ ---
45
+
46
+ ## During Implementation
47
+
48
+ ### Step-by-Step Execution
49
+
50
+ - You **MUST** execute **one sub-task at a time**.
51
+ - You **MUST NOT** start the next sub-task until the user grants permission (says "yes" or "y").
52
+ - After completing each sub-task, you **MUST** immediately:
53
+ 1. Mark it `[x]` in the local task file.
54
+ 2. Mark it `[x]` in the GitHub Issue checklist.
55
+ 3. Stop and wait for user approval before proceeding.
56
+
57
+ ### Parent Task Completion
58
+
59
+ - When **all** sub-tasks under a parent task are `[x]`, you **MUST** also mark the **parent task** as `[x]`.
60
+
61
+ ### Task List Maintenance
62
+
63
+ - You **MUST** regularly update the task list file after finishing significant work.
64
+ - You **MUST** add newly discovered tasks as they emerge.
65
+ - You **MUST** keep the "Relevant Files" section accurate and up to date with every file created or modified.
66
+ - You **MUST** keep the local task list and the GitHub Issue checklist aligned at all times.
67
+ - If drift is detected between local and GitHub, you **MUST** reconcile immediately and report the reconciliation.
68
+ - If schema/data-model changes are in scope, migration artifacts **MUST** be tracked in the task list unless an explicit opt-out rationale is documented.
69
+
70
+ ### Progress Updates
71
+
72
+ - You **SHOULD** add brief issue or PR comments for major milestones or meaningful changes.
73
+ - You **SHOULD** route issue/PR comment updates through `github-ops` whenever possible.
74
+
75
+ ---
76
+
77
+ ## Before Closing a Story/Issue
78
+
79
+ 1. All acceptance criteria **MUST** be verified.
80
+ 2. All tests listed in the checklist **MUST** be completed and passing.
81
+ 3. The following quality gates **MUST** be completed and passing before completion:
82
+ - `test`
83
+ - `lint`
84
+ - `format:check`
85
+ - `typecheck`
86
+ - `audit`
87
+ 4. For schema/data-model changes, migration handling **MUST** satisfy all of the following:
88
+ - migration artifact created (unless documented opt-out)
89
+ - rollback/impact notes captured
90
+ - explicit user confirmation obtained before any migration apply command
91
+ - apply step executed only after user confirmation
92
+ - post-apply verification recorded
93
+ 5. `technical-writer` validation **MUST** include a drift/stale-doc check report, and completion **MUST NOT** proceed while unresolved drift remains.
94
+ 6. A `verifier` audit in `audit` mode **MUST** have run against the delivered implementation, with its human-readable summary posted to the issue/PR. This gate is mandatory and non-skippable — it **MUST NOT** be skipped regardless of drift findings, and drift findings reported by this audit **MUST NOT** block completion. This condition is satisfied once the audit has run and been posted; any resulting drift is handled by `product-engineer`'s `activity-drift-reconciliation` flow after this gate, not before it.
95
+ 7. The PR **MUST** be converted from draft to ready for review.
96
+ 8. The PR **MUST** be approved by the appropriate reviewer per the merge authority policy in `github-ops`:
97
+ - PRs targeting an **integration branch**: `planner` reviews and approves.
98
+ - PRs targeting **`main`**: the **user** reviews and approves.
99
+ 9. The PR **MUST** be merged by the authorized party (planner for integration branches, user for `main`).
100
+ 10. You **MUST NOT** close the GitHub Issue until the PR is approved **AND** merged.
101
+ 11. You **MUST NOT** close the issue while the PR is still in draft or pending review.
102
+ 12. You **MUST** notify the user when the PR is ready for review — explicitly inform them so they can review and merge.
103
+
104
+ ---
105
+
106
+ ## GitHub Execution Rules Summary
107
+
108
+ | Phase | Rule |
109
+ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
110
+ | **Before coding** | Confirm issue open → Create branch (`github-ops`) → Open draft PR (`github-ops`) → Sync checklists |
111
+ | **During coding** | One sub-task at a time → Mark `[x]` locally + GitHub → Wait for approval |
112
+ | **Before closing** | All ACs verified → Quality gates pass (test/lint/format/typecheck/audit) → migration confirmation/apply/verify (when applicable) → docs drift check clear → verifier audit run + summary posted (non-blocking on drift) → PR ready → Approved → Merged → Then close issue |
113
+
114
+ ---
115
+
116
+ ## Output
117
+
118
+ - Keep all changes and status updates in GitHub and `/workstream/tasks-*.md`.
119
+ - You **MUST** check which sub-task is next before starting work.
120
+ - After implementing a sub-task, you **MUST** update the file and then pause for user approval.
121
+
122
+ ## Final Instructions
123
+
124
+ 1. You **MUST** always respect the task list execution order.
125
+ 2. You **MUST** keep the GitHub Issue updated with checklist and progress comments.
126
+ 3. You **MUST** ensure branch, PR, and issue naming follow `github-ops` conventions.
127
+ 4. You **MUST** stop after each sub-task and request user approval.
128
+ 5. You **MUST NOT** close a GitHub Issue without confirming the PR has been reviewed, approved, and merged.
@@ -0,0 +1,144 @@
1
+ ---
2
+ applyTo: "workstream/**"
3
+ ---
4
+
5
+ # Activity: Plan Implementation
6
+
7
+ > **RFC 2119 Notice:** The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
8
+
9
+ ## Goal
10
+
11
+ Convert selected User Stories or a refined GitHub Issue into a structured, execution-ready task list. The task list drives the **implement** activity and keeps the GitHub Issue checklist in sync.
12
+
13
+ This activity adapts to the input — it works with a user stories file (from the PRD workflow) or a refined issue (from the single-issue workflow).
14
+
15
+ ## Mode Detection
16
+
17
+ | Input | Mode | Source |
18
+ | ----------------------------------- | ---------------- | ---------------------------------------------------------------- |
19
+ | User stories file + story selection | **Stories Mode** | `user-stories-[prd-name].md` |
20
+ | Refined GitHub Issue | **Issue Mode** | `issue-[number]-[name]-refinement.md` or the GitHub Issue itself |
21
+
22
+ ## Process
23
+
24
+ 1. **Receive Context:** User provides the reference to the source document.
25
+ 2. **Review Available Work:** You **MUST** read the source and list available stories or the issue scope.
26
+ 3. **Select Scope:** In Stories Mode, you **MUST** ask which stories to include. In Issue Mode, the scope is the single issue.
27
+ 4. **Generate Task List:** You **MUST** produce a `tasks-*.md` file in the required format.
28
+ 5. **Publish to GitHub:** You **MUST** update the corresponding GitHub Issue(s) with the task checklist by delegating to `github-ops` whenever possible.
29
+ 6. **Save Output.**
30
+
31
+ ## Package Manager and Command Standards
32
+
33
+ - For JavaScript/TypeScript repositories, you **MUST** prefer `pnpm` over `npm` for install and script execution.
34
+ - You **MAY** fall back to `npm` only when `pnpm` is unavailable or the project is explicitly npm-locked.
35
+ - Generated tasks for JS/TS projects **MUST** use canonical `package.json` script names when available:
36
+ - `lint`, `lint:fix`
37
+ - `format`, `format:check`
38
+ - `typecheck`
39
+ - `test`, `test:unit`, `test:integration`, `test:e2e`
40
+ - `audit`
41
+ - `validate` (aggregate gate script)
42
+
43
+ ## Clarifying Questions
44
+
45
+ - In Stories Mode: "Which stories would you like to include? (Recommended: 1-3 stories)"
46
+ - "Should I update the GitHub Issues with the task checklist now (delegating to github-ops)?"
47
+ - "Is this a greenfield/new project, or an existing codebase?"
48
+ - "Are there specific implementation details or dependencies I should consider?"
49
+ - "Do any selected stories involve data model creation? What sample/seed data should be included?"
50
+
51
+ ## Output Format
52
+
53
+ The task list **MUST** follow this structure:
54
+
55
+ ```markdown
56
+ # Implementation Plan - [Name]
57
+
58
+ ## Relevant Files
59
+
60
+ - `path/to/file1.ts` - [Description]
61
+ - `path/to/file2.ts` - [Description]
62
+
63
+ ## Tasks
64
+
65
+ - [ ] 1.0 Implement Story [ID]: [Story Title] (or: Implement Issue [#] - [Github_Issue_URL]: [Title])
66
+
67
+ - [ ] 1.1 [First implementation step]
68
+ - [ ] 1.2 [Second implementation step]
69
+ - [ ] 1.x Verify Acceptance Criterion: [Criterion 1]
70
+ - [ ] 1.y Verify Acceptance Criterion: [Criterion 2]
71
+ - [ ] 1.z Run Tests: [Test Requirements]
72
+
73
+ - [ ] 2.0 Implement Story [ID]: [Story Title] (or: Implement Issue [#] - [Github_Issue_URL]: [Title])
74
+ - [ ] 2.1 [First implementation step]
75
+ - ...
76
+ ```
77
+
78
+ ## Conversion Guidelines
79
+
80
+ When converting a **User Story** or **Refined Issue** to a **Parent Task**:
81
+
82
+ 1. **Title:** You **MUST** use the format `Implement Story [ID]: [Title]` or `Implement Issue [#]: [Title]`.
83
+ 2. **Sub-tasks:**
84
+ - You **MUST** convert every item in the **Implementation Steps** section into a sub-task.
85
+ - You **MUST** add explicit sub-tasks for each **Acceptance Criterion** verification.
86
+
87
+ - You **MUST** add explicit sub-tasks for each **Testing** requirement (unit/integration/manual/edge cases).
88
+ - You **MUST** include explicit validation means for each major behavior:
89
+ - Automated verification (test command or script).
90
+ - Manual/UI verification path when user-visible behavior is affected.
91
+ - You **MUST** include an acceptance-criteria-to-tests mapping step so each AC is explicitly covered.
92
+ - For JS/TS repositories, testing and quality tasks **MUST** reference canonical script names (`pnpm run <script>` preferred).
93
+ - If schema or data-model changes are involved, migration tasks are **required by default**; omission is allowed only with an explicit documented opt-out rationale.
94
+ - Migration flows **MUST** include: create migration artifact, document rollback/impact, request user confirmation before apply, apply migration after confirmation, and verify applied state.
95
+ - If the story involves data models, you **SHOULD** include a sub-task to generate seed data.
96
+
97
+ 3. **Context:** You **MAY** add a `> Note:` block under the parent task for quick reference (User Story text or Business Rules), but the checkbox structure **MUST** remain clean.
98
+ 4. **Relevant Files:** You **MUST** aggregate all "Files to Create/Modify" from selected stories into the top-level `Relevant Files` section.
99
+
100
+ ## Greenfield Project — Task 0
101
+
102
+ If this is a **greenfield project** or a **new component**, you **MUST** include a **Task 0: Project Setup** as the first parent task:
103
+
104
+ ```markdown
105
+ - [ ] 0.0 Project Setup
106
+ - [ ] 0.1 Initialize project structure and package management
107
+ - [ ] 0.2 Set up version control and repository structure
108
+ - [ ] 0.3 Configure environment variables (.env, .env.example)
109
+ - [ ] 0.4 Set up development environment (dependencies, build tools, linting, formatting)
110
+ - [ ] 0.5 Create initial documentation (README, CONTRIBUTING, setup instructions)
111
+ - [ ] 0.6 Create seed data generation script (if using database)
112
+ - [ ] 0.7 Verify local development environment works (test build, tests pass, seed data loads)
113
+ - [ ] 0.8 Publish initial project to GitHub (if not already done)
114
+ ```
115
+
116
+ **When to include Task 0:**
117
+
118
+ - ✅ First time setting up a new repository
119
+ - ✅ Starting a new microservice or component
120
+ - ✅ Setting up isolated development environment for greenfield features
121
+ - ✅ Database setup with initial schema
122
+ - ❌ Extensions to existing projects (skip if dependencies already installed)
123
+
124
+ ## Output
125
+
126
+ - **Format:** Markdown (`.md`)
127
+ - **Location:** `/workstream/`
128
+ - **Filename:**
129
+ - Stories Mode: `tasks-[prd-name]-plan.md`
130
+ - Issue Mode: `tasks-issue-[issue-number]-[issue-name].md`
131
+
132
+ ## Final Instructions
133
+
134
+ 1. You **MUST NOT** start implementing.
135
+ 2. You **MUST** read the source document (user stories or refined issue).
136
+ 3. In Stories Mode, you **MUST** list available stories and ask the user for their selection.
137
+ 4. You **MUST** convert the selection into the strict task list format.
138
+ 5. You **MUST** ensure all Implementation Steps, Acceptance Criteria, and Testing requirements are preserved as sub-tasks.
139
+ 6. For JS/TS repositories, you **MUST** prefer `pnpm` commands and canonical script names in generated tasks.
140
+ 7. You **MUST** ensure each task includes both implementation and test/validation steps, including edge-case validation.
141
+ 8. For schema/data-model changes, you **MUST** include migration lifecycle tasks and an explicit user-confirmation gate before applying migrations unless an opt-out rationale is documented.
142
+ 9. You **MUST** update the corresponding GitHub Issue(s) with the task checklist by delegating to `github-ops` whenever possible. If no issue exists, you **MUST** ask the user whether to create one first.
143
+ 10. You **MUST** save the task list file.
144
+ 11. You **MUST** inform the user they can now use the **implement** activity to start coding.
@@ -0,0 +1,13 @@
1
+ ---
2
+ agent: developer
3
+ description: "Execute an existing task list using the developer agent — Execute Mode."
4
+ ---
5
+
6
+ Run the `developer` agent in Execute Mode against an existing task file:
7
+
8
+ - **Repository:** `<owner/repo>`
9
+ - **GitHub Issue:** `#<issue-number>`
10
+ - **Task list path:** `workstream/<tasks-prd-XXX-description.md>`
11
+ - **Execution mode:** step-gated _(change to `pre-approved autonomous sequential` to run autonomously)_
12
+
13
+ The agent will run `implement` directly — `refine`, `plan`, and all spec/story activities are skipped. Use this when a planning pass has already been completed and the task file is fully scoped.
@@ -0,0 +1,16 @@
1
+ ---
2
+ agent: github-ops
3
+ description: "Audit and standardize GitHub artifacts — issues, PRs, branches, labels, and milestones."
4
+ ---
5
+
6
+ Run the `github-ops` agent to enforce GitHub consistency conventions:
7
+
8
+ - **Repository:** `<owner/repo>`
9
+ - **Scope** _(choose one or more)_:
10
+ - `audit` — scan all open issues and PRs for convention violations
11
+ - `issue #<number>` — standardize a specific issue
12
+ - `pr #<number>` — standardize a specific pull request
13
+ - `labels` — reconcile labels against the standard taxonomy
14
+ - `milestones` — audit milestone naming and structure
15
+
16
+ The agent will produce a compliance report, apply auto-fixable corrections (title format, label names, body structure), and escalate items that require a human decision.