@llipe.com/dev-tasks 0.6.1 → 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.
- package/.claude/agents/developer.md +294 -0
- package/.claude/agents/github-ops.md +407 -0
- package/.claude/agents/housekeeping.md +109 -0
- package/.claude/agents/technical-writer.md +390 -0
- package/.claude/agents/ux-engineer.md +184 -0
- package/.claude/agents/verifier.md +276 -0
- package/.claude/commands/developer.md +272 -0
- package/.claude/commands/github-ops.md +10 -0
- package/.claude/commands/housekeeping.md +10 -0
- package/.claude/commands/planner.md +506 -0
- package/.claude/commands/product-engineer.md +263 -0
- package/.claude/commands/technical-writer.md +10 -0
- package/.claude/commands/ux-engineer.md +10 -0
- package/.claude/commands/verifier-audit.md +10 -0
- package/.claude/commands/verifier-design.md +10 -0
- package/.claude/hooks/git-guard.sh +95 -0
- package/.claude/skills/activity-contract-test-design/SKILL.md +122 -0
- package/.claude/skills/activity-drift-reconciliation/SKILL.md +133 -0
- package/.claude/skills/activity-e2e-test-design/SKILL.md +124 -0
- package/.claude/skills/activity-edge-case-refinement/SKILL.md +146 -0
- package/.claude/skills/activity-generate-spec/SKILL.md +137 -0
- package/.claude/skills/activity-generate-stories/SKILL.md +243 -0
- package/.claude/skills/activity-init/SKILL.md +162 -0
- package/.claude/skills/activity-publish-github/SKILL.md +116 -0
- package/.claude/skills/activity-random-test-tactics/SKILL.md +181 -0
- package/.claude/skills/activity-refine/SKILL.md +236 -0
- package/.claude/skills/git-ops/SKILL.md +221 -0
- package/.claude/skills/implement/SKILL.md +129 -0
- package/.claude/skills/memo-cli-usage/REFERENCE.md +798 -0
- package/.claude/skills/memo-cli-usage/SKILL.md +144 -0
- package/.claude/skills/plan/SKILL.md +145 -0
- package/.claude/skills/webapp-mockup/SKILL.md +76 -0
- package/.claude/skills/webapp-mockup/scripts/scaffold-mockup.sh +469 -0
- package/.github/agents/developer.agent.md +293 -0
- package/.github/agents/github-ops.agent.md +416 -0
- package/.github/agents/housekeeping.agent.md +109 -0
- package/.github/agents/planner.agent.md +496 -0
- package/.github/agents/product-engineer.agent.md +262 -0
- package/.github/agents/technical-writer.agent.md +389 -0
- package/.github/agents/ux-engineer.agent.md +183 -0
- package/.github/agents/verifier.agent.md +275 -0
- package/.github/instructions/domain/nextjs-pages-components.instructions.md +375 -0
- package/.github/instructions/implement.instructions.md +128 -0
- package/.github/instructions/plan.instructions.md +144 -0
- package/.github/prompts/developer-execute.prompt.md +13 -0
- package/.github/prompts/github-ops.prompt.md +16 -0
- package/.github/prompts/housekeeping.prompt.md +16 -0
- package/.github/prompts/planner-resume.prompt.md +13 -0
- package/.github/prompts/planner.prompt.md +18 -0
- package/.github/prompts/product-engineer-feature.prompt.md +21 -0
- package/.github/prompts/product-engineer-init.prompt.md +16 -0
- package/.github/prompts/product-engineer-issue.prompt.md +19 -0
- package/.github/prompts/technical-writer.prompt.md +21 -0
- package/.github/prompts/ux-engineer.prompt.md +14 -0
- package/.github/prompts/verifier-audit.prompt.md +33 -0
- package/.github/prompts/verifier-design.prompt.md +28 -0
- package/.github/skills/activity-contract-test-design/SKILL.md +117 -0
- package/.github/skills/activity-drift-reconciliation/SKILL.md +128 -0
- package/.github/skills/activity-e2e-test-design/SKILL.md +119 -0
- package/.github/skills/activity-edge-case-refinement/SKILL.md +141 -0
- package/.github/skills/activity-generate-spec/SKILL.md +132 -0
- package/.github/skills/activity-generate-stories/SKILL.md +238 -0
- package/.github/skills/activity-init/SKILL.md +157 -0
- package/.github/skills/activity-publish-github/SKILL.md +111 -0
- package/.github/skills/activity-random-test-tactics/SKILL.md +176 -0
- package/.github/skills/activity-refine/SKILL.md +231 -0
- package/.github/skills/git-ops/SKILL.md +216 -0
- package/.github/skills/memo-cli-usage/REFERENCE.md +798 -0
- package/.github/skills/memo-cli-usage/SKILL.md +144 -0
- package/.github/skills/webapp-mockup/SKILL.md +71 -0
- package/.github/skills/webapp-mockup/scripts/scaffold-mockup.sh +469 -0
- package/.kiro/agents/developer.md +305 -0
- package/.kiro/agents/github-ops.md +428 -0
- package/.kiro/agents/housekeeping.md +122 -0
- package/.kiro/agents/planner.md +530 -0
- package/.kiro/agents/product-engineer.md +294 -0
- package/.kiro/agents/technical-writer.md +408 -0
- package/.kiro/agents/ux-engineer.md +200 -0
- package/.kiro/agents/verifier.md +275 -0
- package/.kiro/hooks/git-guard.json +16 -0
- package/.kiro/hooks/scripts/git-guard.sh +116 -0
- package/.kiro/skills/activity-contract-test-design/SKILL.md +122 -0
- package/.kiro/skills/activity-drift-reconciliation/SKILL.md +133 -0
- package/.kiro/skills/activity-e2e-test-design/SKILL.md +124 -0
- package/.kiro/skills/activity-edge-case-refinement/SKILL.md +146 -0
- package/.kiro/skills/activity-generate-spec/SKILL.md +137 -0
- package/.kiro/skills/activity-generate-stories/SKILL.md +243 -0
- package/.kiro/skills/activity-init/SKILL.md +162 -0
- package/.kiro/skills/activity-publish-github/SKILL.md +116 -0
- package/.kiro/skills/activity-random-test-tactics/SKILL.md +181 -0
- package/.kiro/skills/activity-refine/SKILL.md +236 -0
- package/.kiro/skills/git-ops/SKILL.md +221 -0
- package/.kiro/skills/memo-cli-usage/REFERENCE.md +798 -0
- package/.kiro/skills/memo-cli-usage/SKILL.md +144 -0
- package/.kiro/skills/webapp-mockup/SKILL.md +76 -0
- package/.kiro/steering/git-guard-notice.md +11 -0
- package/.kiro/steering/implement.md +129 -0
- package/.kiro/steering/nextjs-pages-components.md +376 -0
- package/.kiro/steering/plan.md +145 -0
- package/AGENTS.md +122 -0
- package/CHANGELOG.md +40 -2
- package/CLAUDE.md +94 -0
- package/README.md +33 -18
- package/dist/adapters/cli/extract-all.js +4 -4
- package/dist/adapters/cli/extract-component.d.ts +1 -1
- package/dist/adapters/cli/extract-component.js +4 -4
- package/dist/adapters/cli/parse-args.d.ts +1 -0
- package/dist/adapters/cli/parse-args.d.ts.map +1 -1
- package/dist/adapters/cli/parse-args.js +4 -0
- package/dist/adapters/cli/parse-args.js.map +1 -1
- package/dist/bin/dev-tasks.js +23 -9
- package/dist/bin/dev-tasks.js.map +1 -1
- package/dist/bin/dt.js +3 -3
- package/dist/core/distribution/index.d.ts +5 -3
- package/dist/core/distribution/index.d.ts.map +1 -1
- package/dist/core/distribution/index.js +3 -2
- package/dist/core/distribution/index.js.map +1 -1
- package/dist/core/distribution/install.d.ts +20 -8
- package/dist/core/distribution/install.d.ts.map +1 -1
- package/dist/core/distribution/install.js +76 -36
- package/dist/core/distribution/install.js.map +1 -1
- package/dist/core/distribution/manifest.d.ts +25 -2
- package/dist/core/distribution/manifest.d.ts.map +1 -1
- package/dist/core/distribution/manifest.js +29 -2
- package/dist/core/distribution/manifest.js.map +1 -1
- package/dist/core/distribution/migrate.d.ts +6 -3
- package/dist/core/distribution/migrate.d.ts.map +1 -1
- package/dist/core/distribution/migrate.js +21 -19
- package/dist/core/distribution/migrate.js.map +1 -1
- package/dist/core/distribution/profiles.d.ts +30 -0
- package/dist/core/distribution/profiles.d.ts.map +1 -0
- package/dist/core/distribution/profiles.js +57 -0
- package/dist/core/distribution/profiles.js.map +1 -0
- package/dist/core/distribution/update.d.ts +6 -4
- package/dist/core/distribution/update.d.ts.map +1 -1
- package/dist/core/distribution/update.js +22 -22
- package/dist/core/distribution/update.js.map +1 -1
- package/dist/core/extract/component.d.ts +9 -9
- package/dist/core/extract/component.js +5 -5
- package/dist/core/extract/report.d.ts +1 -1
- package/dist/core/extract/report.js +1 -1
- package/package.json +37 -18
- package/skills/.gitkeep +0 -0
|
@@ -0,0 +1,376 @@
|
|
|
1
|
+
---
|
|
2
|
+
inclusion: fileMatch
|
|
3
|
+
fileMatchPattern: "**/app/**/*.tsx"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- Consumers: adjust fileMatchPattern to match your Next.js app path. For React Native projects, replace with a react-native steering file (see issue #13). -->
|
|
7
|
+
|
|
8
|
+
# Rule: Keep Next.js Pages and React Components Consistent
|
|
9
|
+
|
|
10
|
+
> **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).
|
|
11
|
+
|
|
12
|
+
## Goal
|
|
13
|
+
|
|
14
|
+
Guide GitHub Copilot when creating or editing Next.js pages and React components so the UI stays consistent in:
|
|
15
|
+
|
|
16
|
+
- libraries and dependencies
|
|
17
|
+
- component patterns
|
|
18
|
+
- page structure
|
|
19
|
+
- styling conventions
|
|
20
|
+
- accessibility
|
|
21
|
+
- testing expectations
|
|
22
|
+
- general visual design
|
|
23
|
+
|
|
24
|
+
## Scope
|
|
25
|
+
|
|
26
|
+
Apply these rules to UI work inside `src/app` and `src/components`.
|
|
27
|
+
|
|
28
|
+
This project uses:
|
|
29
|
+
|
|
30
|
+
- **Next.js 16+** with **App Router**
|
|
31
|
+
- **React 19**
|
|
32
|
+
- **TypeScript strict mode**
|
|
33
|
+
- **Tailwind CSS** as the preferred styling foundation for page and component UI work
|
|
34
|
+
- **Zod** for validation
|
|
35
|
+
- local app components and utilities only
|
|
36
|
+
|
|
37
|
+
## Library and Dependency Rules
|
|
38
|
+
|
|
39
|
+
1. You **SHOULD** prefer the current stack only.
|
|
40
|
+
|
|
41
|
+
- Use built-in React and Next.js APIs first.
|
|
42
|
+
- Use existing local helpers from `@/lib/*` and local components from `@/components/*`.
|
|
43
|
+
- Use `zod`-based validators from `@/lib/validation/*` for form validation.
|
|
44
|
+
- Prefer `Tailwind CSS` for styling and visual consistency.
|
|
45
|
+
|
|
46
|
+
2. You **MUST** use Tailwind CSS as the default styling system.
|
|
47
|
+
|
|
48
|
+
- Treat Tailwind as the standard foundation for layout, spacing, color, typography, and state styles.
|
|
49
|
+
- Prefer utility classes over ad hoc CSS approaches for page and component implementation.
|
|
50
|
+
- If reusable patterns emerge, extract local primitives in `src/components/ui`.
|
|
51
|
+
|
|
52
|
+
3. You **MUST NOT** introduce an opinionated component library by default.
|
|
53
|
+
|
|
54
|
+
- 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.
|
|
55
|
+
- You **MUST NOT** assume `shadcn/ui` is available unless it already exists in the app.
|
|
56
|
+
- You **MUST NOT** introduce `shadcn/ui` by default. Reevaluate it only if the project explicitly chooses it as a product and engineering decision.
|
|
57
|
+
|
|
58
|
+
4. You **MUST NOT** solve simple UI problems with extra dependencies.
|
|
59
|
+
|
|
60
|
+
- Prefer plain React components and existing utility-class styling.
|
|
61
|
+
- If a reusable primitive is needed, create it locally in `src/components/ui`.
|
|
62
|
+
|
|
63
|
+
5. You **SHOULD** prefer local UI primitives before external component kits.
|
|
64
|
+
|
|
65
|
+
- Build and reuse a small internal set of primitives such as `Button`, `Input`, `Card`, `Badge`, `Alert`, and `PageHeader`.
|
|
66
|
+
- Keep those primitives aligned with the approved palette and accessibility rules.
|
|
67
|
+
|
|
68
|
+
6. You **MUST** keep app boundaries strict.
|
|
69
|
+
- You **MUST NOT** import UI or business logic from sibling apps.
|
|
70
|
+
- Only use shared packages when they are already intended for cross-app use.
|
|
71
|
+
|
|
72
|
+
## Component and Page Architecture
|
|
73
|
+
|
|
74
|
+
### General Rules
|
|
75
|
+
|
|
76
|
+
1. You **MUST** default to Server Components.
|
|
77
|
+
|
|
78
|
+
- Pages and components **SHOULD** remain server components unless they need client-only features.
|
|
79
|
+
- You **MUST** add `'use client'` only when the component uses state, effects, browser APIs, event handlers, or client hooks such as `useRouter()`.
|
|
80
|
+
|
|
81
|
+
2. You **MUST** keep pages thin.
|
|
82
|
+
|
|
83
|
+
- A page **SHOULD** primarily define metadata, route-level composition, and high-level layout.
|
|
84
|
+
- Move repeated UI sections into components.
|
|
85
|
+
- Move validation, formatting, mapping, and business rules into `@/lib`.
|
|
86
|
+
|
|
87
|
+
3. You **MUST** keep components focused.
|
|
88
|
+
|
|
89
|
+
- One component **SHOULD** have one clear responsibility.
|
|
90
|
+
- If JSX becomes long or repeats existing patterns, extract smaller subcomponents.
|
|
91
|
+
|
|
92
|
+
4. You **SHOULD** prefer composition over large monolithic components.
|
|
93
|
+
|
|
94
|
+
- Build pages from small sections such as page header, content card, form section, status panel, or empty state.
|
|
95
|
+
|
|
96
|
+
5. **Use project import conventions**.
|
|
97
|
+
- Prefer `@/` aliases for app-local imports.
|
|
98
|
+
- Keep imports grouped as: React/Next, third-party, app-local.
|
|
99
|
+
|
|
100
|
+
### File Naming and Exports
|
|
101
|
+
|
|
102
|
+
1. Follow the **existing codebase convention** for file names:
|
|
103
|
+
|
|
104
|
+
- component files: kebab-case, e.g. `login-form.tsx`, `auth-error-display.tsx`
|
|
105
|
+
- page files: Next.js App Router defaults such as `page.tsx`, `layout.tsx`
|
|
106
|
+
- test files: same base name with `.test.tsx`
|
|
107
|
+
|
|
108
|
+
2. Use **PascalCase** for exported React component names.
|
|
109
|
+
|
|
110
|
+
- Example: file `login-form.tsx` exports `LoginForm`.
|
|
111
|
+
|
|
112
|
+
3. Keep related tests close to the page or component when practical.
|
|
113
|
+
|
|
114
|
+
## Next.js-Specific Rules
|
|
115
|
+
|
|
116
|
+
1. **Export `metadata` for pages when relevant**.
|
|
117
|
+
|
|
118
|
+
- Public and major app pages **SHOULD** provide title and description.
|
|
119
|
+
- Keep titles consistent with the product name of your app.
|
|
120
|
+
|
|
121
|
+
2. **Use the right navigation primitive**.
|
|
122
|
+
|
|
123
|
+
- Use `Link` from `next/link` for internal navigation in rendered UI.
|
|
124
|
+
- Use `redirect()` in server-side route/page flows.
|
|
125
|
+
- Use `useRouter()` only in client components when navigation must happen after a client event.
|
|
126
|
+
|
|
127
|
+
3. **Use App Router conventions**.
|
|
128
|
+
|
|
129
|
+
- Route-level concerns stay in `src/app/...`.
|
|
130
|
+
- Reusable UI goes in `src/components/...`.
|
|
131
|
+
- Do not hide route-specific business logic inside presentational components.
|
|
132
|
+
|
|
133
|
+
4. **Prefer route-group consistency**.
|
|
134
|
+
|
|
135
|
+
- Public auth screens **SHOULD** match the current auth page pattern.
|
|
136
|
+
- Protected pages **SHOULD** match the existing protected layout and page shell.
|
|
137
|
+
|
|
138
|
+
5. **Prefer server-first data fetching**.
|
|
139
|
+
|
|
140
|
+
- Fetch data in Server Components by default.
|
|
141
|
+
- Use client-side fetching only when the UI requires interactive, user-driven, or live-updating state.
|
|
142
|
+
- Do not move simple read-only page data fetching into client components unless there is a clear product need.
|
|
143
|
+
|
|
144
|
+
6. **Keep async boundaries intentional**.
|
|
145
|
+
- Server Components **SHOULD** handle initial page data and route-level loading needs.
|
|
146
|
+
- Client components **SHOULD** focus on interaction, optimistic UI, transient state, and browser-only behavior.
|
|
147
|
+
|
|
148
|
+
## Styling and Design Rules
|
|
149
|
+
|
|
150
|
+
1. **Follow the existing utility-class styling approach**.
|
|
151
|
+
|
|
152
|
+
- Match the current class patterns already used across the app.
|
|
153
|
+
- Do not introduce inline style objects unless there is no reasonable alternative.
|
|
154
|
+
- You **MUST NOT** introduce CSS-in-JS.
|
|
155
|
+
|
|
156
|
+
2. **Use the approved app color palette**.
|
|
157
|
+
|
|
158
|
+
- Base palette:
|
|
159
|
+
- Sky Blue (Light): `#8ecae6`
|
|
160
|
+
- Blue Green: `#219ebc`
|
|
161
|
+
- Deep Space Blue: `#023047`
|
|
162
|
+
- Amber Flame: `#ffb703`
|
|
163
|
+
- Tiger Orange: `#fb8500`
|
|
164
|
+
- Neutral surfaces:
|
|
165
|
+
- Primary light surfaces **SHOULD** prefer white or near-white backgrounds.
|
|
166
|
+
- Dark sections may use dark gray or near-black backgrounds when stronger contrast or emphasis is needed.
|
|
167
|
+
- Semantic usage guidance:
|
|
168
|
+
- Primary brand/background accent: Deep Space Blue
|
|
169
|
+
- Secondary accent and interactive emphasis: Blue Green
|
|
170
|
+
- Supporting light highlight/background tint: Sky Blue
|
|
171
|
+
- Attention, highlights, badges, and positive energy moments: Amber Flame
|
|
172
|
+
- Strong CTA, active emphasis, or warning-energy accent: Tiger Orange
|
|
173
|
+
|
|
174
|
+
3. **Translate the palette into a consistent UI language**.
|
|
175
|
+
|
|
176
|
+
- Prefer white, off-white, dark gray, and near-black as the structural backgrounds.
|
|
177
|
+
- Use the palette colors as accents, emphasis colors, and branded surfaces.
|
|
178
|
+
- Avoid rainbow-like mixing of all five colors in the same component.
|
|
179
|
+
- A single screen **SHOULD** usually have:
|
|
180
|
+
- one dominant brand color
|
|
181
|
+
- one supporting accent color
|
|
182
|
+
- neutral backgrounds
|
|
183
|
+
- Preserve readable contrast for text, borders, and interactive states.
|
|
184
|
+
|
|
185
|
+
4. **Preferred visual roles**.
|
|
186
|
+
|
|
187
|
+
- App shell, headers, hero bands, and primary branded panels: Deep Space Blue
|
|
188
|
+
- Links, secondary buttons, focus states, and info accents: Blue Green
|
|
189
|
+
- Soft highlights, subtle banners, or decorative backgrounds: Sky Blue
|
|
190
|
+
- Status chips, counters, feature highlights, and attention markers: Amber Flame
|
|
191
|
+
- Primary CTA emphasis, strong hover accents, and promotional emphasis: Tiger Orange
|
|
192
|
+
- Default content surfaces: white
|
|
193
|
+
- Optional high-contrast surfaces: dark gray / black
|
|
194
|
+
|
|
195
|
+
5. **Preserve current layout patterns**.
|
|
196
|
+
|
|
197
|
+
- Public/auth pages usually use a centered container with `min-h-screen`, a neutral background, and a card-style form panel.
|
|
198
|
+
- Protected pages usually use a page shell with a header area, content cards, and responsive spacing.
|
|
199
|
+
|
|
200
|
+
6. **Prefer reusable visual patterns**.
|
|
201
|
+
|
|
202
|
+
- Cards: `rounded-lg bg-white p-6 shadow`
|
|
203
|
+
- Section headings: bold dark text with consistent margin spacing
|
|
204
|
+
- Inputs: bordered, rounded, neutral background, visible focus state
|
|
205
|
+
- Primary buttons: Tiger Orange or Deep Space Blue background with white text and clear disabled state
|
|
206
|
+
- Secondary buttons: white or dark surface with Blue Green accents and visible border/focus styles
|
|
207
|
+
- Alert panels: semantic border/background/text color combinations
|
|
208
|
+
|
|
209
|
+
7. You **MUST** avoid one-off visual decisions.
|
|
210
|
+
|
|
211
|
+
- You **MUST NOT** invent a new color palette for a single page.
|
|
212
|
+
- You **MUST NOT** mix drastically different spacing, corner radius, or button styles on similar screens.
|
|
213
|
+
- You **MUST NOT** introduce arbitrary hex colors outside the approved palette unless the user explicitly requests it or accessibility requires it.
|
|
214
|
+
- If a pattern repeats, you **SHOULD** extract a reusable component.
|
|
215
|
+
|
|
216
|
+
8. You **MUST** design mobile-first.
|
|
217
|
+
|
|
218
|
+
- Start with small-screen layouts and scale up for tablet and desktop.
|
|
219
|
+
- Every new page and major component **SHOULD** work across small, medium, and large breakpoints.
|
|
220
|
+
- Prefer progressive enhancement of spacing, grid layout, and density instead of separate disconnected layouts.
|
|
221
|
+
|
|
222
|
+
9. **Use dark surfaces deliberately**.
|
|
223
|
+
|
|
224
|
+
- Prefer dark gray or near-black backgrounds for app shell elements, navigation, hero sections, or emphasis panels.
|
|
225
|
+
- Prefer light surfaces for dense forms, data entry, tables, and long-reading content unless a specific design requires otherwise.
|
|
226
|
+
- Keep contrast high when palette accents are placed on dark backgrounds.
|
|
227
|
+
|
|
228
|
+
10. **Move toward reusable design tokens and shared patterns**.
|
|
229
|
+
|
|
230
|
+
- When colors, spacing, radius, shadows, or typography styles repeat, prefer centralizing them through shared utility patterns or local primitives.
|
|
231
|
+
- Avoid scattering slightly different visual values across many components.
|
|
232
|
+
|
|
233
|
+
## Forms and Validation
|
|
234
|
+
|
|
235
|
+
1. **Reuse validation patterns already present in the app**.
|
|
236
|
+
|
|
237
|
+
- Use validators from `@/lib/validation/*`.
|
|
238
|
+
- Keep validation messages explicit and user-friendly.
|
|
239
|
+
- Validate before submitting.
|
|
240
|
+
|
|
241
|
+
2. **Keep form UX consistent**.
|
|
242
|
+
|
|
243
|
+
- Use labels for every field.
|
|
244
|
+
- Show inline field-level validation errors near the relevant field.
|
|
245
|
+
- Show request or auth failures in a clear alert area.
|
|
246
|
+
- Reflect loading and disabled states during submission.
|
|
247
|
+
|
|
248
|
+
3. **Do not put schema logic inside JSX files when it already belongs in `lib/validation`**.
|
|
249
|
+
|
|
250
|
+
4. **Use a consistent submission pattern**.
|
|
251
|
+
- Prefer a single clear pattern per feature for form submission and mutation handling.
|
|
252
|
+
- Keep form UI concerns in the component and keep request, validation, and transformation logic in route handlers, server actions, or `@/lib` helpers as appropriate.
|
|
253
|
+
- Do not mix multiple submission patterns in the same feature without a clear reason.
|
|
254
|
+
|
|
255
|
+
## Accessibility Rules
|
|
256
|
+
|
|
257
|
+
1. Use semantic HTML first.
|
|
258
|
+
|
|
259
|
+
- Use `main`, `section`, `header`, `form`, `label`, `button`, and heading levels correctly.
|
|
260
|
+
|
|
261
|
+
2. Every interactive element must be accessible.
|
|
262
|
+
|
|
263
|
+
- Inputs must be associated with labels.
|
|
264
|
+
- Buttons must have an explicit `type`.
|
|
265
|
+
- Error messages should use `role="alert"` when appropriate.
|
|
266
|
+
- Disabled and loading states must be visually and semantically clear.
|
|
267
|
+
|
|
268
|
+
3. Preserve keyboard and focus behavior.
|
|
269
|
+
|
|
270
|
+
- Keep visible focus styles.
|
|
271
|
+
- Do not remove focus indicators.
|
|
272
|
+
|
|
273
|
+
4. Prefer readable copy.
|
|
274
|
+
|
|
275
|
+
- Avoid vague CTA text like `Submit` when a clearer label such as `Sign in` or `Save changes` is possible.
|
|
276
|
+
|
|
277
|
+
5. Keep interface copy concise and operational.
|
|
278
|
+
- Prefer plain English.
|
|
279
|
+
- Avoid overly promotional or marketing-heavy language in product screens.
|
|
280
|
+
- Labels, helper text, empty states, and errors should be direct and specific.
|
|
281
|
+
|
|
282
|
+
## Data and State Rules
|
|
283
|
+
|
|
284
|
+
1. **Keep presentation separate from business logic**.
|
|
285
|
+
|
|
286
|
+
- Formatting, validation, error mapping, and API transformations belong outside presentational JSX where possible.
|
|
287
|
+
|
|
288
|
+
2. **Keep client state minimal**.
|
|
289
|
+
|
|
290
|
+
- Only store what the component truly owns.
|
|
291
|
+
- Prefer derived state over duplicated state.
|
|
292
|
+
|
|
293
|
+
3. **Be explicit with empty, error, and loading states**.
|
|
294
|
+
|
|
295
|
+
- Pages and components should not silently fail.
|
|
296
|
+
|
|
297
|
+
4. **Use consistent fallback state patterns**.
|
|
298
|
+
- Empty states should explain what is missing and what the user can do next.
|
|
299
|
+
- Loading states should use lightweight skeletons, placeholders, or progress text that match the surrounding layout.
|
|
300
|
+
- Error states should clearly state the problem and, when possible, the next recovery action.
|
|
301
|
+
|
|
302
|
+
## Primitive Component Rules
|
|
303
|
+
|
|
304
|
+
1. Local primitives should follow a consistent API when applicable.
|
|
305
|
+
|
|
306
|
+
- Support shared props such as `variant`, `size`, and `className` where those concepts make sense.
|
|
307
|
+
- Forward native element props whenever practical.
|
|
308
|
+
- Preserve accessible defaults.
|
|
309
|
+
|
|
310
|
+
2. Interactive primitives should support standard states.
|
|
311
|
+
|
|
312
|
+
- Include disabled styles where relevant.
|
|
313
|
+
- Include loading states for action-triggering controls when relevant.
|
|
314
|
+
- Keep focus styles visible and consistent.
|
|
315
|
+
|
|
316
|
+
3. Do not create multiple competing primitive patterns.
|
|
317
|
+
- Reuse or extend the existing primitive instead of creating a near-duplicate version.
|
|
318
|
+
|
|
319
|
+
## Icons and Motion
|
|
320
|
+
|
|
321
|
+
1. Icons are allowed, but they must stay consistent.
|
|
322
|
+
|
|
323
|
+
- Prefer a single lightweight icon library across the app if one is introduced.
|
|
324
|
+
- Do not mix multiple icon libraries in the same application.
|
|
325
|
+
- If no icon library is present for the feature, prefer inline SVG or local icon components instead of adding a dependency casually.
|
|
326
|
+
|
|
327
|
+
2. Keep motion subtle.
|
|
328
|
+
- Prefer simple CSS or utility-based transitions for hover, focus, expand/collapse, and feedback states.
|
|
329
|
+
- Avoid heavy or decorative animation by default.
|
|
330
|
+
- Do not add animation libraries unless the user explicitly requests them.
|
|
331
|
+
|
|
332
|
+
## Testing Rules
|
|
333
|
+
|
|
334
|
+
1. New pages and interactive components should include or update tests.
|
|
335
|
+
2. Use the existing Jest + Testing Library setup.
|
|
336
|
+
3. Prefer queries by role, label, and visible text.
|
|
337
|
+
4. Use `data-testid` only when semantic queries are not stable enough.
|
|
338
|
+
5. Test the user-visible behavior:
|
|
339
|
+
- rendering
|
|
340
|
+
- validation errors
|
|
341
|
+
- loading states
|
|
342
|
+
- disabled states
|
|
343
|
+
- navigation intent
|
|
344
|
+
- success and failure feedback
|
|
345
|
+
|
|
346
|
+
## Consistency Checklist
|
|
347
|
+
|
|
348
|
+
Before finishing a page or component, verify:
|
|
349
|
+
|
|
350
|
+
- It uses existing Next.js and React patterns.
|
|
351
|
+
- It does not add unnecessary dependencies.
|
|
352
|
+
- It matches the current app styling.
|
|
353
|
+
- It uses semantic, accessible markup.
|
|
354
|
+
- It keeps business logic outside presentational code when possible.
|
|
355
|
+
- It reuses or extracts shared UI patterns instead of duplicating them.
|
|
356
|
+
- It includes or updates tests when behavior changes.
|
|
357
|
+
|
|
358
|
+
## Avoid These Defaults
|
|
359
|
+
|
|
360
|
+
- Adding a new UI framework without approval
|
|
361
|
+
- Adding custom design systems unrelated to current screens
|
|
362
|
+
- Mixing multiple styling approaches in the same feature
|
|
363
|
+
- Making every component a client component
|
|
364
|
+
- Putting API/business logic directly into presentational JSX
|
|
365
|
+
- Using internal `<a href>` links where `Link` is more appropriate
|
|
366
|
+
- Creating visually inconsistent buttons, cards, or form layouts
|
|
367
|
+
|
|
368
|
+
## Preferred Outcome
|
|
369
|
+
|
|
370
|
+
Every new page or component should feel like it belongs to the same product:
|
|
371
|
+
|
|
372
|
+
- same stack
|
|
373
|
+
- same structure
|
|
374
|
+
- same interaction patterns
|
|
375
|
+
- same visual language
|
|
376
|
+
- same quality bar for accessibility and testing
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
---
|
|
2
|
+
inclusion: fileMatch
|
|
3
|
+
fileMatchPattern: "workstream/**"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Activity: Plan Implementation
|
|
7
|
+
|
|
8
|
+
> **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).
|
|
9
|
+
|
|
10
|
+
## Goal
|
|
11
|
+
|
|
12
|
+
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.
|
|
13
|
+
|
|
14
|
+
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).
|
|
15
|
+
|
|
16
|
+
## Mode Detection
|
|
17
|
+
|
|
18
|
+
| Input | Mode | Source |
|
|
19
|
+
| ----------------------------------- | ---------------- | ---------------------------------------------------------------- |
|
|
20
|
+
| User stories file + story selection | **Stories Mode** | `user-stories-[prd-name].md` |
|
|
21
|
+
| Refined GitHub Issue | **Issue Mode** | `issue-[number]-[name]-refinement.md` or the GitHub Issue itself |
|
|
22
|
+
|
|
23
|
+
## Process
|
|
24
|
+
|
|
25
|
+
1. **Receive Context:** User provides the reference to the source document.
|
|
26
|
+
2. **Review Available Work:** You **MUST** read the source and list available stories or the issue scope.
|
|
27
|
+
3. **Select Scope:** In Stories Mode, you **MUST** ask which stories to include. In Issue Mode, the scope is the single issue.
|
|
28
|
+
4. **Generate Task List:** You **MUST** produce a `tasks-*.md` file in the required format.
|
|
29
|
+
5. **Publish to GitHub:** You **MUST** update the corresponding GitHub Issue(s) with the task checklist by delegating to `github-ops` whenever possible.
|
|
30
|
+
6. **Save Output.**
|
|
31
|
+
|
|
32
|
+
## Package Manager and Command Standards
|
|
33
|
+
|
|
34
|
+
- For JavaScript/TypeScript repositories, you **MUST** prefer `pnpm` over `npm` for install and script execution.
|
|
35
|
+
- You **MAY** fall back to `npm` only when `pnpm` is unavailable or the project is explicitly npm-locked.
|
|
36
|
+
- Generated tasks for JS/TS projects **MUST** use canonical `package.json` script names when available:
|
|
37
|
+
- `lint`, `lint:fix`
|
|
38
|
+
- `format`, `format:check`
|
|
39
|
+
- `typecheck`
|
|
40
|
+
- `test`, `test:unit`, `test:integration`, `test:e2e`
|
|
41
|
+
- `audit`
|
|
42
|
+
- `validate` (aggregate gate script)
|
|
43
|
+
|
|
44
|
+
## Clarifying Questions
|
|
45
|
+
|
|
46
|
+
- In Stories Mode: "Which stories would you like to include? (Recommended: 1-3 stories)"
|
|
47
|
+
- "Should I update the GitHub Issues with the task checklist now (delegating to github-ops)?"
|
|
48
|
+
- "Is this a greenfield/new project, or an existing codebase?"
|
|
49
|
+
- "Are there specific implementation details or dependencies I should consider?"
|
|
50
|
+
- "Do any selected stories involve data model creation? What sample/seed data should be included?"
|
|
51
|
+
|
|
52
|
+
## Output Format
|
|
53
|
+
|
|
54
|
+
The task list **MUST** follow this structure:
|
|
55
|
+
|
|
56
|
+
```markdown
|
|
57
|
+
# Implementation Plan - [Name]
|
|
58
|
+
|
|
59
|
+
## Relevant Files
|
|
60
|
+
|
|
61
|
+
- `path/to/file1.ts` - [Description]
|
|
62
|
+
- `path/to/file2.ts` - [Description]
|
|
63
|
+
|
|
64
|
+
## Tasks
|
|
65
|
+
|
|
66
|
+
- [ ] 1.0 Implement Story [ID]: [Story Title] (or: Implement Issue [#] - [Github_Issue_URL]: [Title])
|
|
67
|
+
|
|
68
|
+
- [ ] 1.1 [First implementation step]
|
|
69
|
+
- [ ] 1.2 [Second implementation step]
|
|
70
|
+
- [ ] 1.x Verify Acceptance Criterion: [Criterion 1]
|
|
71
|
+
- [ ] 1.y Verify Acceptance Criterion: [Criterion 2]
|
|
72
|
+
- [ ] 1.z Run Tests: [Test Requirements]
|
|
73
|
+
|
|
74
|
+
- [ ] 2.0 Implement Story [ID]: [Story Title] (or: Implement Issue [#] - [Github_Issue_URL]: [Title])
|
|
75
|
+
- [ ] 2.1 [First implementation step]
|
|
76
|
+
- ...
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Conversion Guidelines
|
|
80
|
+
|
|
81
|
+
When converting a **User Story** or **Refined Issue** to a **Parent Task**:
|
|
82
|
+
|
|
83
|
+
1. **Title:** You **MUST** use the format `Implement Story [ID]: [Title]` or `Implement Issue [#]: [Title]`.
|
|
84
|
+
2. **Sub-tasks:**
|
|
85
|
+
- You **MUST** convert every item in the **Implementation Steps** section into a sub-task.
|
|
86
|
+
- You **MUST** add explicit sub-tasks for each **Acceptance Criterion** verification.
|
|
87
|
+
|
|
88
|
+
- You **MUST** add explicit sub-tasks for each **Testing** requirement (unit/integration/manual/edge cases).
|
|
89
|
+
- You **MUST** include explicit validation means for each major behavior:
|
|
90
|
+
- Automated verification (test command or script).
|
|
91
|
+
- Manual/UI verification path when user-visible behavior is affected.
|
|
92
|
+
- You **MUST** include an acceptance-criteria-to-tests mapping step so each AC is explicitly covered.
|
|
93
|
+
- For JS/TS repositories, testing and quality tasks **MUST** reference canonical script names (`pnpm run <script>` preferred).
|
|
94
|
+
- 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.
|
|
95
|
+
- Migration flows **MUST** include: create migration artifact, document rollback/impact, request user confirmation before apply, apply migration after confirmation, and verify applied state.
|
|
96
|
+
- If the story involves data models, you **SHOULD** include a sub-task to generate seed data.
|
|
97
|
+
|
|
98
|
+
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.
|
|
99
|
+
4. **Relevant Files:** You **MUST** aggregate all "Files to Create/Modify" from selected stories into the top-level `Relevant Files` section.
|
|
100
|
+
|
|
101
|
+
## Greenfield Project — Task 0
|
|
102
|
+
|
|
103
|
+
If this is a **greenfield project** or a **new component**, you **MUST** include a **Task 0: Project Setup** as the first parent task:
|
|
104
|
+
|
|
105
|
+
```markdown
|
|
106
|
+
- [ ] 0.0 Project Setup
|
|
107
|
+
- [ ] 0.1 Initialize project structure and package management
|
|
108
|
+
- [ ] 0.2 Set up version control and repository structure
|
|
109
|
+
- [ ] 0.3 Configure environment variables (.env, .env.example)
|
|
110
|
+
- [ ] 0.4 Set up development environment (dependencies, build tools, linting, formatting)
|
|
111
|
+
- [ ] 0.5 Create initial documentation (README, CONTRIBUTING, setup instructions)
|
|
112
|
+
- [ ] 0.6 Create seed data generation script (if using database)
|
|
113
|
+
- [ ] 0.7 Verify local development environment works (test build, tests pass, seed data loads)
|
|
114
|
+
- [ ] 0.8 Publish initial project to GitHub (if not already done)
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
**When to include Task 0:**
|
|
118
|
+
|
|
119
|
+
- ✅ First time setting up a new repository
|
|
120
|
+
- ✅ Starting a new microservice or component
|
|
121
|
+
- ✅ Setting up isolated development environment for greenfield features
|
|
122
|
+
- ✅ Database setup with initial schema
|
|
123
|
+
- ❌ Extensions to existing projects (skip if dependencies already installed)
|
|
124
|
+
|
|
125
|
+
## Output
|
|
126
|
+
|
|
127
|
+
- **Format:** Markdown (`.md`)
|
|
128
|
+
- **Location:** `/workstream/`
|
|
129
|
+
- **Filename:**
|
|
130
|
+
- Stories Mode: `tasks-[prd-name]-plan.md`
|
|
131
|
+
- Issue Mode: `tasks-issue-[issue-number]-[issue-name].md`
|
|
132
|
+
|
|
133
|
+
## Final Instructions
|
|
134
|
+
|
|
135
|
+
1. You **MUST NOT** start implementing.
|
|
136
|
+
2. You **MUST** read the source document (user stories or refined issue).
|
|
137
|
+
3. In Stories Mode, you **MUST** list available stories and ask the user for their selection.
|
|
138
|
+
4. You **MUST** convert the selection into the strict task list format.
|
|
139
|
+
5. You **MUST** ensure all Implementation Steps, Acceptance Criteria, and Testing requirements are preserved as sub-tasks.
|
|
140
|
+
6. For JS/TS repositories, you **MUST** prefer `pnpm` commands and canonical script names in generated tasks.
|
|
141
|
+
7. You **MUST** ensure each task includes both implementation and test/validation steps, including edge-case validation.
|
|
142
|
+
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.
|
|
143
|
+
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.
|
|
144
|
+
10. You **MUST** save the task list file.
|
|
145
|
+
11. You **MUST** inform the user they can now use the **implement** activity to start coding.
|
package/AGENTS.md
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# dev-tasks
|
|
2
|
+
|
|
3
|
+
A set of agents, skills, and instructions for GitHub Copilot, Claude Code, Kiro, and other AI coding agents to run structured, PRD-driven development workflows.
|
|
4
|
+
|
|
5
|
+
## Core Idea
|
|
6
|
+
|
|
7
|
+
This system brings structure and clarity to AI-assisted development by:
|
|
8
|
+
|
|
9
|
+
- Defining scope with Product Requirements Documents (PRDs)
|
|
10
|
+
- Breaking requirements into actionable, implementation-ready tasks
|
|
11
|
+
- Guiding the AI to tackle one task at a time with checkpoints for review
|
|
12
|
+
- Providing specialized **agents** that orchestrate the workflow end-to-end
|
|
13
|
+
- Enforcing documentation, branch discipline, and GitHub-as-source-of-truth
|
|
14
|
+
- Standardizing visual design decisions through `/DESIGN.md` as the canonical UI contract
|
|
15
|
+
- **Test-first design as the default**: `verifier` (Design Mode) produces compliance test plans before implementation, and `developer` writes tests before code
|
|
16
|
+
|
|
17
|
+
## Design Standard Contract (DESIGN.md)
|
|
18
|
+
|
|
19
|
+
`/DESIGN.md` is the canonical design-system artifact for this repository.
|
|
20
|
+
|
|
21
|
+
- `ux-engineer` **MUST** use `/DESIGN.md` as the primary style source for mockups.
|
|
22
|
+
- `product-engineer` **MUST** reference `/DESIGN.md` for UI-impacting specs and stories.
|
|
23
|
+
- `developer` **MUST** validate UI changes against `/DESIGN.md` and update it when the visual contract changes.
|
|
24
|
+
- `planner` **MUST** require DESIGN.md compliance in UI-impacting delegated runs.
|
|
25
|
+
|
|
26
|
+
If `/DESIGN.md` is missing and the requested scope includes UI work, agents **MUST** create a baseline DESIGN.md before finalizing design-dependent outputs.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Taxonomy: Agent vs Skill vs Instruction
|
|
31
|
+
|
|
32
|
+
| Concept | Purpose | Loaded When |
|
|
33
|
+
| --------------- | ----------------------------------------------------------- | ---------------------------- |
|
|
34
|
+
| **Agent** | Autonomous role with decision-making and handoff discipline | Invoked by name (`@agent`) |
|
|
35
|
+
| **Skill** | Reusable on-demand capability (procedures/activities) | On demand (invoked by agent) |
|
|
36
|
+
| **Instruction** | Scoped rule enforced automatically for matching context | Auto-applied by runtime |
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Agents
|
|
41
|
+
|
|
42
|
+
| Agent | File | Purpose |
|
|
43
|
+
| -------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
44
|
+
| **product-engineer** | `product-engineer.agent.md` | Preparation agent — owns the full pre-coding chain: PRD, spec, stories, plan. Owns drift-reconciliation (`activity-drift-reconciliation`) for findings handed off by `developer`/`planner`. Hands off to `developer` or `planner` for execution. |
|
|
45
|
+
| **developer** | `developer.agent.md` | Execution agent — implements code from an existing task list. Runs `implement`, including a mandatory, non-skippable `verifier` audit before every PR is marked ready. |
|
|
46
|
+
| **planner** | `planner.agent.md` | Multi-story orchestration — dependency-ordered sequential execution with checkpoint/resume, a mandatory per-story and PRD-level rollup `verifier` audit gate, and one consolidated integration PR. |
|
|
47
|
+
| **technical-writer** | `technical-writer.agent.md` | Autonomous documentation maintenance |
|
|
48
|
+
| **housekeeping** | `housekeeping.agent.md` | Lint, type, and test-wiring fixes |
|
|
49
|
+
| **github-ops** | `github-ops.agent.md` | GitHub consistency — standardizes issues, PRs, branches, labels, milestones, comments, and enforces merge authority policy |
|
|
50
|
+
| **ux-engineer** | `ux-engineer.agent.md` | UX prototyping and gap analysis — turns PRD/SPEC into testable mockups and feeds refinements back to `product-engineer` |
|
|
51
|
+
| **verifier** | `verifier.agent.md` | Verification agent — owns compliance test-plan design (`design` mode) and post-implementation grey-box fidelity auditing (`audit` mode) against codebase, `/workstream`, tests, and PRD/spec intent |
|
|
52
|
+
|
|
53
|
+
## Skills
|
|
54
|
+
|
|
55
|
+
Skills are on-demand capabilities invoked by agents — **not** loaded unless explicitly referenced.
|
|
56
|
+
|
|
57
|
+
### Activity Skills
|
|
58
|
+
|
|
59
|
+
| Skill | Directory | Purpose | Primary Consumer |
|
|
60
|
+
| --------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
|
|
61
|
+
| **activity-init** | `skills/activity-init/` | Establish product context and technical guidelines | `product-engineer` |
|
|
62
|
+
| **activity-refine** | `skills/activity-refine/` | Clarify scope — issue refinement or full PRD creation | `product-engineer` |
|
|
63
|
+
| **activity-generate-spec** | `skills/activity-generate-spec/` | Transform PRD into technical specification | `product-engineer` |
|
|
64
|
+
| **activity-generate-stories** | `skills/activity-generate-stories/` | Break spec into user stories with coverage validation | `product-engineer` |
|
|
65
|
+
| **activity-publish-github** | `skills/activity-publish-github/` | Publish stories as GitHub Issues via MCP | `product-engineer` |
|
|
66
|
+
| **activity-e2e-test-design** | `skills/activity-e2e-test-design/` | End-to-end black-box test scenario generation from spec/stories | `verifier` |
|
|
67
|
+
| **activity-contract-test-design** | `skills/activity-contract-test-design/` | Consumer/provider contract and schema compatibility test strategy | `verifier` |
|
|
68
|
+
| **activity-edge-case-refinement** | `skills/activity-edge-case-refinement/` | Systematic edge-case discovery by category with concrete examples | `verifier` |
|
|
69
|
+
| **activity-random-test-tactics** | `skills/activity-random-test-tactics/` | Randomized, fuzz, and property-inspired test generation with reproducibility | `verifier` |
|
|
70
|
+
| **activity-drift-reconciliation** | `skills/activity-drift-reconciliation/` | Routes verifier drift findings into task-list/checklist expansion, new issues, or PRD/spec changelog write-back (human-confirmed) | `product-engineer` |
|
|
71
|
+
|
|
72
|
+
### Operational Skills
|
|
73
|
+
|
|
74
|
+
| Skill | Directory | Purpose | Primary Consumer |
|
|
75
|
+
| ------------------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
|
|
76
|
+
| **git-ops** | `skills/git-ops/` | Branch management, rebase, merge, conflict resolution, recovery | `developer`, `planner` |
|
|
77
|
+
| **webapp-mockup** | `skills/webapp-mockup/` | Scaffold and generate React mockup apps for UX testing | `ux-engineer` |
|
|
78
|
+
| **memo-cli-usage** | `skills/memo-cli-usage/` | Read and write architectural decisions to a shared Qdrant knowledge base for multi-session, multi-agent, and team-wide context continuity | `technical-writer`, `developer` |
|
|
79
|
+
|
|
80
|
+
### Third-Party Skills
|
|
81
|
+
|
|
82
|
+
| Skill | Directory | Purpose | Primary Consumer |
|
|
83
|
+
| ------------------------------- | ------------------------------------- | ------------------------------------- | -------------------------- |
|
|
84
|
+
| **vercel-composition-patterns** | `skills/vercel-composition-patterns/` | Vercel component composition patterns | `developer`, `ux-engineer` |
|
|
85
|
+
| **vercel-react-best-practices** | `skills/vercel-react-best-practices/` | Vercel React best practices | `developer`, `ux-engineer` |
|
|
86
|
+
|
|
87
|
+
## Instructions (Scoped)
|
|
88
|
+
|
|
89
|
+
Instructions are scoped via `applyTo`/`fileMatchPattern` and auto-applied to matching files.
|
|
90
|
+
|
|
91
|
+
| Instruction | File | Scope | Purpose |
|
|
92
|
+
| --------------------------- | ------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------ |
|
|
93
|
+
| **plan** | `plan.instructions.md` | `workstream/**` | Convert stories or refined issues into execution-ready task lists |
|
|
94
|
+
| **implement** | `implement.instructions.md` | `workstream/**/tasks-*.md` | Execute task list with step-gated approval, branching, and PR discipline |
|
|
95
|
+
| **nextjs-pages-components** | `domain/nextjs-pages-components.instructions.md` | `**/app/**/*.tsx` | Next.js + React conventions |
|
|
96
|
+
|
|
97
|
+
## Prompts
|
|
98
|
+
|
|
99
|
+
See individual agent files for invocation modes and entry points. Reference: Copilot (`.github/prompts/`), Claude Code (`.claude/commands/`), Kiro (embedded in `.kiro/agents/`).
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## General Agent Guidelines
|
|
104
|
+
|
|
105
|
+
All AI coding agents working in this repository **MUST**:
|
|
106
|
+
|
|
107
|
+
- Always create feature branches — never commit to the default branch
|
|
108
|
+
- Use Conventional Commits (`feat`, `fix`, `chore`, `docs`, etc.)
|
|
109
|
+
- Create PRs for review — never self-merge into `main`
|
|
110
|
+
- **PRs targeting `main` require user approval** — no agent may merge into the default branch
|
|
111
|
+
- Follow testing, linting, and documentation standards from `technical-guidelines.md`
|
|
112
|
+
- Reference GitHub Issues in branch names and commits
|
|
113
|
+
- Treat `/DESIGN.md` as the source of truth for visual tokens, components, and design guidance
|
|
114
|
+
- Prefer `pnpm` over `npm` for JS/TS workflows
|
|
115
|
+
- Use canonical script names: `lint`, `format:check`, `typecheck`, `test`, `audit`, `validate`
|
|
116
|
+
- Enforce quality gates before completion: `test`, `lint`, `format:check`, `typecheck`, `audit`
|
|
117
|
+
- Use the `git-ops` skill for branch management, rebase, and conflict resolution
|
|
118
|
+
- The `verifier` audit is mandatory and non-skippable before every PR is marked ready. Drift findings are non-blocking and route to `product-engineer`'s `activity-drift-reconciliation`.
|
|
119
|
+
- **Test-first design is the default:** `product-engineer` recommends `verifier` Design Mode after planning; `developer` writes tests before implementation code; `planner` checks for test plans and enforces test-first in developer handoffs
|
|
120
|
+
- If `memo-cli` is installed and configured: agents **MUST** read/write entries per their role (see agent files for details)
|
|
121
|
+
|
|
122
|
+
For workflow chains and sequencing diagrams, see [`docs/workflow-chains.md`](docs/workflow-chains.md).
|