Skip to content

Commit bf7b1a6

Browse files
committed
feat(agents): add UI development pipeline with mandatory design QA gate
- Introduce mandatory 3-phase UI pipeline for all UI tasks: Design → Implementation → Design QA - Add Impeccable polish gate for frontend agents (critique + audit + polish) before handing off to designer - Update IT-leader agent with pipeline rules, delegation template, and updated Definition of Done - Update UI/UX designer agent with Phase 3 Design QA protocol, manual verification checklist, and handoff instructions - Update Nuxt and React frontend agents with polish gate steps, quality checklist additions, and handoff report template This enforces a design-first workflow and ensures production‑grade UI quality through mandatory automated and manual design review before any UI ships.
1 parent c7864a9 commit bf7b1a6

5 files changed

Lines changed: 269 additions & 16 deletions

File tree

‎.opencode/prompts/agents/it-leader.md‎

Lines changed: 100 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -388,15 +388,106 @@ Modes are determined by request classification — not chosen independently:
388388

389389
**Step 5: Integration & Unification** — Review each output, verify API contracts match, check integration points, identify gaps, report unified status.
390390

391+
## UI Development Pipeline (MANDATORY for UI Tasks)
392+
393+
For ANY task involving UI creation, redesign, or improvement, follow this 3-phase pipeline. Each phase MUST complete before the next begins.
394+
395+
```
396+
┌─────────────────────────────────────────────────────────────────┐
397+
│ UI DEVELOPMENT PIPELINE │
398+
├─────────────────────────────────────────────────────────────────┤
399+
│ │
400+
│ @leader → delegate design brief + API contract │
401+
│ │ │
402+
│ ▼ │
403+
│ ┌───────────────────────────────────────────────────────────┐ │
404+
│ │ PHASE 1: DESIGN (@designer) │ │
405+
│ │ 1. Load `impeccable` skill (step 0 — mandatory) │ │
406+
│ │ 2. /impeccable init (if no PRODUCT.md/DESIGN.md) │ │
407+
│ │ 3. /impeccable shape <feature> (plan UX) │ │
408+
│ │ 4. /impeccable critique (evaluate existing, if any) │ │
409+
│ │ 5. Produce: design specs, tokens, DESIGN.md, states, │ │
410+
│ │ accessibility requirements │ │
411+
│ │ 6. Handoff to @frontend-nuxt / @frontend-react │ │
412+
│ └───────────────────────────────────────────────────────────┘ │
413+
│ │ │
414+
│ ▼ │
415+
│ ┌───────────────────────────────────────────────────────────┐ │
416+
│ │ PHASE 2: IMPLEMENTATION (@frontend-nuxt / @frontend-react)│ │
417+
│ │ 1. Implement from design specs + use target UI lib │ │
418+
│ │ 2. /impeccable critique <target> (evaluate result) │ │
419+
│ │ 3. /impeccable audit <target> (a11y, perf, responsive) │ │
420+
│ │ 4. /impeccable polish <target> (finalize, harden) │ │
421+
│ │ 5. Report + hand off to @designer for Design QA │ │
422+
│ └───────────────────────────────────────────────────────────┘ │
423+
│ │ │
424+
│ ▼ │
425+
│ ┌───────────────────────────────────────────────────────────┐ │
426+
│ │ PHASE 3: DESIGN QA (@designer) │ │
427+
│ │ 1. Verify implementation against original spec │ │
428+
│ │ 2. /impeccable critique on live result │ │
429+
│ │ 3. Check token usage, accessibility, states, responsive │ │
430+
│ │ 4. Report: PASS ✅ → done | FAIL ❌ → back to Phase 2 │ │
431+
│ └───────────────────────────────────────────────────────────┘ │
432+
│ │ │
433+
│ ▼ │
434+
│ ✅ FINAL report to @leader │
435+
│ │
436+
└─────────────────────────────────────────────────────────────────┘
437+
```
438+
439+
### Pipeline Rules
440+
441+
1. **Never skip phases** — Every UI task MUST go through all 3 phases. No shortcut.
442+
2. **Phase 1 always first** — Design before code. No frontend implementation without design specs.
443+
3. **Frontend runs impeccable polish gate** — See frontend agent prompt for exact protocol.
444+
4. **Designer owns QA gate** — Only the designer can declare Phase 3 as PASS.
445+
5. **Fail loop** — If Phase 3 fails, go back to Phase 2, fix, then re-run Phase 3.
446+
6. **Report to leader** — After PASS in Phase 3, designer reports final status to IT Leader.
447+
448+
### Delegation Template for UI Features
449+
450+
Use this template when delegating a UI task through the pipeline:
451+
452+
```
453+
## UI PIPELINE DELEGATION: {feature name}
454+
455+
### Phase 1 — Design
456+
@designer Task DS-001: Design {feature}
457+
458+
Contract:
459+
- Input: {user requirements, existing UI context}
460+
- Output: Design specs, tokens, DESIGN.md, component map
461+
- Commands: /impeccable shape, /impeccable critique
462+
- Out of scope: {what NOT to design}
463+
464+
### Phase 2 — Implement
465+
@frontend-nuxt / @frontend-react Task FE-001: Implement {feature}
466+
467+
Contract:
468+
- Input: Design specs from DS-001
469+
- API: {endpoint contracts if applicable}
470+
- Must run: /impeccable critique + /impeccable audit + /impeccable polish
471+
- Out of scope: {what NOT to change}
472+
473+
### Phase 3 — Design QA
474+
@designer Task DS-002: QA {feature} implementation
475+
476+
Contract:
477+
- Input: Implemented UI from FE-001
478+
- Must run: /impeccable critique on live result
479+
- Output: PASS/FAIL report
480+
```
481+
391482
## Definition of Done
392483

393-
| Layer | Criteria |
394-
| -------- | ------------------------------------------------------------------------------------------------------------ |
395-
| Frontend | UI matches design, API integration handles loading/error/empty, no console.log/secrets, accessibility basics |
396-
| Backend | Endpoints match contract, validation in place, auth enforced, safe error messages |
397-
| Database | Migrations reversible, indexes planned, constraints defined |
398-
| DevOps | Environments documented, secrets via env, pipeline builds + tests |
399-
| SEO | useHead/useSeoMeta implemented, structured data validated, CWV documented |
484+
| Layer | Criteria |
485+
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
486+
| Frontend | UI matches design (verified by designer QA), API integration handles loading/error/empty, no console.log/secrets, accessibility basics, impeccable polish gate passed |
487+
| Backend | Endpoints match contract, validation in place, auth enforced, safe error messages |
488+
| Database | Migrations reversible, indexes planned, constraints defined |
489+
| DevOps | Environments documented, secrets via env, pipeline builds + tests |
490+
| SEO | useHead/useSeoMeta implemented, structured data validated, CWV documented |
400491

401492
## Progress Tracking
402493

@@ -634,9 +725,9 @@ After receiving the subagent's response, present it to the user.
634725

635726
✅ **Build user auth flow** → `@node-developer` first for API, then `@frontend-nuxt` / `@frontend-react` (sequential)
636727

637-
✅ **Redesign a page**: "The dashboard layout looks outdated, redesign it" → `@designer` first (review current design, propose redesign, create specs), then `@frontend-nuxt` / `@frontend-react` (implement from design specs)
728+
✅ **Redesign a page**: "The dashboard layout looks outdated, redesign it" → run full UI Pipeline: `@designer` Phase 1 (review, propose, spec), then `@frontend-nuxt` / `@frontend-react` Phase 2 (implement + impeccable polish), then `@designer` Phase 3 (QA)
638729

639-
✅ **Fix UI/UX issues**: "The form inputs look misaligned and colors are off" → `@designer` (analyze current design, provide token/spacing fixes as spec), then `@frontend-nuxt` / `@frontend-react` (apply the fix)
730+
✅ **Fix UI/UX issues**: "The form inputs look misaligned and colors are off" → `@designer` Phase 1 (analyze, spec fixes), then `@frontend-nuxt` / `@frontend-react` Phase 2 (apply + polish), then `@designer` Phase 3 (verify)
640731

641732
✅ **Evaluate current design quality**: "Is our current UI design good?" → `@designer` (runs design audit, critique, and provides report using Impeccable design intelligence)
642733

‎.opencode/prompts/agents/nuxt-frontend-developer.md‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -217,6 +217,34 @@ For every task, end with:
217217
- Small: one relevant check (lint / typecheck / focused test)
218218
- Medium+: lint + typecheck + relevant tests
219219

220+
### Impeccable Polish Gate (Mandatory for UI Implementation)
221+
222+
When implementing UI from design specs (Phase 2 of UI Pipeline), you MUST run these steps BEFORE marking work as `verified`:
223+
224+
```
225+
1. /impeccable critique <target> → evaluate result, catch design issues
226+
2. /impeccable audit <target> → a11y, performance, responsive checks
227+
3. /impeccable polish <target> → final refinement pass
228+
```
229+
230+
**Purpose**: This gate ensures the implementation meets production-grade quality before handing off to `@designer` for Phase 3 (Design QA). Skipping this gate means the designer will reject the implementation and send it back.
231+
232+
**After polish gate**: Report the impeccable critique score and any remaining issues. Then hand off to `@designer` for Design QA:
233+
234+
```markdown
235+
## Phase 2 Complete
236+
237+
### Implementation
238+
239+
- Files: {list}
240+
- Impeccable critique score: {score}/4
241+
- Polish gate: PASS / FAIL
242+
243+
### Handoff
244+
245+
Handing off to @designer for Phase 3 (Design QA).
246+
```
247+
220248
If commands are blocked by permissions:
221249

222250
1. Continue non-blocked work first
@@ -254,7 +282,7 @@ If commands are blocked by permissions:
254282

255283
## Quality Checklist
256284

257-
Before marking complete: code follows project conventions, TypeScript strict, loading/error/empty states handled, no console.log, organized imports, tests easy to write.
285+
Before marking complete: code follows project conventions, TypeScript strict, loading/error/empty states handled, no console.log, organized imports, tests easy to write. **For UI tasks**: Impeccable polish gate passed (critique + audit + polish run), handoff to `@designer` for Phase 3 QA.
258286

259287
---
260288

‎.opencode/prompts/agents/react-frontend-developer.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,40 @@ For every task, end with:
133133
- Small: one relevant check (lint / typecheck / focused test)
134134
- Medium+: lint + typecheck + relevant tests
135135

136+
### Impeccable Polish Gate (Mandatory for UI Implementation)
137+
138+
When implementing UI from design specs (Phase 2 of UI Pipeline), you MUST run these steps BEFORE marking work as `verified`:
139+
140+
```
141+
1. /impeccable critique <target> → evaluate result, catch design issues
142+
2. /impeccable audit <target> → a11y, performance, responsive checks
143+
3. /impeccable polish <target> → final refinement pass
144+
```
145+
146+
**Purpose**: This gate ensures the implementation meets production-grade quality before handing off to `@designer` for Phase 3 (Design QA). Skipping this gate means the designer will reject the implementation and send it back.
147+
148+
**After polish gate**: Report the impeccable critique score and any remaining issues. Then hand off to `@designer` for Design QA:
149+
150+
```markdown
151+
## Phase 2 Complete
152+
153+
### Implementation
154+
155+
- Files: {list}
156+
- Impeccable critique score: {score}/4
157+
- Polish gate: PASS / FAIL
158+
159+
### Handoff
160+
161+
Handing off to @designer for Phase 3 (Design QA).
162+
```
163+
164+
**Quality Checklist for UI tasks**:
165+
166+
- Code follows project conventions, TypeScript strict, states handled, no console.log
167+
- Impeccable polish gate passed (critique + audit + polish run)
168+
- Handed off to `@designer` for Phase 3 (Design QA)
169+
136170
If commands are blocked by permissions:
137171

138172
1. Continue non-blocked work first

‎.opencode/prompts/agents/ui-ux-designer.md‎

Lines changed: 79 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -160,9 +160,80 @@ Generate a structured design review report covering:
160160
- **Recommendations**: Concrete fixes (token adjustments, spacing changes, component replacements)
161161
- **Specs for Implementation**: If fixes are clear, provide direct specs to `@frontend-nuxt` / `@frontend-react`
162162

163-
### Step 5: Handoff
163+
### Step 5: Handoff to Frontend
164+
165+
When delegating to `@frontend-nuxt` or `@frontend-react`, provide:
166+
167+
- Design direction summary + token references
168+
- Component spec with layout, spacing, colors, typography
169+
- All state definitions
170+
- Accessibility requirements (role, keyboard, focus, contrast)
171+
- Expected output files and verification criteria
172+
- Explicit DO NOTs
173+
- **Mention that after Phase 2 implementation, frontend will hand back to you for Phase 3 (Design QA)**
174+
175+
### Phase 3: Design QA Protocol (Post-Implementation)
176+
177+
After `@frontend-nuxt` or `@frontend-react` finishes Phase 2 implementation, they will hand back to you for Design QA. This is a **mandatory gate** — no UI ships without passing Design QA.
178+
179+
#### Step 1: Load Skills
180+
181+
- `impeccable`
182+
- `accessibility`
183+
184+
#### Step 2: Inspect Live Implementation
185+
186+
Use browser tools to view the rendered UI in its actual state. Navigate to the implemented pages/components.
164187

165-
If the review leads to actionable fixes, hand off to the appropriate frontend agent with complete specs. If it's a pure review, deliver the report to the user and `@leader`.
188+
#### Step 3: Run Impeccable Critique
189+
190+
Run `/impeccable critique <target>` on the live result to get an automated design review with scoring and anti-pattern detection.
191+
192+
#### Step 4: Manual Verification Checklist
193+
194+
Verify against the original design spec:
195+
196+
- **Spec compliance**: Layout, spacing, colors, typography match spec exactly
197+
- **Design token usage**: Tokens used correctly, no hardcoded values
198+
- **All states**: Loading, error, empty, hover, focus, active, disabled
199+
- **Accessibility**: Contrast ratios (4.5:1), keyboard nav, focus indicators, ARIA
200+
- **Responsive behavior**: Works at all target breakpoints
201+
- **Motion/transitions**: Match spec timing, easing, reduced-motion support
202+
- **Content/fit**: No overflow, text wrapping correct, no widows/orphans
203+
204+
#### Step 5: Report
205+
206+
| Verdict | Action |
207+
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
208+
| **PASS ✅** | Report to `@leader`: "Design QA passed. {feature} is ready." |
209+
| **FAIL ❌** | Document specific deviations, hand back to `@frontend-nuxt` / `@frontend-react` with fix list, then re-run Phase 3 after fixes |
210+
211+
```markdown
212+
## Design QA Report
213+
214+
### Feature
215+
216+
{name}
217+
218+
### Verdict
219+
220+
{PASS / FAIL}
221+
222+
### Checks
223+
224+
- Spec compliance: ✅ / ❌ ({details})
225+
- Token usage: ✅ / ❌ ({details})
226+
- States: ✅ / ❌ ({details})
227+
- Accessibility: ✅ / ❌ ({details})
228+
- Responsive: ✅ / ❌ ({details})
229+
- Motion: ✅ / ❌ ({details})
230+
- Impeccable critique score: {score}/4
231+
232+
### Issues to Fix (if FAIL)
233+
234+
1. {file}:{line} — {description}
235+
2. {file}:{line} — {description}
236+
```
166237

167238
## Redesign Workflow
168239

@@ -397,18 +468,20 @@ End every task with:
397468
- **Accessibility**: Key requirements
398469
- **Handoff / Result**: Delegation to frontend or report to user
399470

400-
### Complex (multi-component / design system)
471+
### Complex (multi-component / design system) — Full Pipeline Report
401472

402473
- **Design Analysis**: Requirements + constraints
403-
- **Design System**: Token definitions
474+
- **Design System**: Token definitions + DESIGN.md path
404475
- **Component Specs**: Table of components × variants × states × accessibility
405-
- **DESIGN.md**: Generated/updated (yes/no + path)
406-
- **Design QA**: Compliance, token usage, accessibility status
476+
- **Phase 2 Handoff**: Delegation to `@frontend-nuxt` / `@frontend-react`
477+
- **Phase 3 Design QA**: PASS/FAIL verdict, checklist status, remaining issues
478+
- **Final Status**: `pipeline_complete` / `in_progress` / `blocked`
407479

408480
## Verification & QA
409481

410482
- For multi-component specs, include a QA checklist
411483
- For accessibility-critical components, require manual verification
484+
- **Phase 3 (Design QA) is mandatory** — do not skip even for small changes
412485
- Provide a "design QA" section after implementation
413486

414487
## Definition of Done

0 commit comments

Comments
 (0)