Claude-Code-Workflow/.codex/skills/team-frontend/instructions/agent-instruction.md

Agent Instruction Template -- Team Frontend

Base instruction template for CSV wave agents. The orchestrator dynamically customizes this per role during Phase 1, writing role-specific versions to role-instructions/{role}.md.

Purpose

Phase	Usage
Phase 1	Coordinator generates per-role instruction from this template
Phase 2	Injected as instruction parameter to spawn_agents_on_csv

---

Base Instruction Template

## TASK ASSIGNMENT -- Team Frontend

### MANDATORY FIRST STEPS
1. Read shared discoveries: <session-folder>/discoveries.ndjson (if exists, skip if not)
2. Read project context: .workflow/project-tech.json (if exists)

---

## Your Task

**Task ID**: {id}
**Title**: {title}
**Role**: {role}
**Pipeline Mode**: {pipeline_mode}
**Scope**: {scope}
**Review Type**: {review_type}

### Task Description
{description}

### Previous Tasks' Findings (Context)
{prev_context}

---

## Execution Protocol

1. **Read discoveries**: Load <session-folder>/discoveries.ndjson for shared exploration findings
2. **Use context**: Apply previous tasks' findings from prev_context above
3. **Execute task**: Follow role-specific instructions below
4. **Share discoveries**: Append exploration findings to shared board:
   ```bash
   echo '{"ts":"<ISO8601>","worker":"{id}","type":"<type>","data":{...}}' >> <session-folder>/discoveries.ndjson

5. Report result: Return JSON via report_agent_job_result

Discovery Types to Share

• tech_stack_detected: {stack, framework, ui_lib} -- Tech stack identification
• design_pattern_found: {pattern_name, location, description} -- Existing design pattern
• token_generated: {category, count, supports_dark_mode} -- Design token category created
• file_modified: {file, change, lines_added} -- File change performed
• issue_found: {file, line, severity, description} -- Issue discovered
• anti_pattern_violation: {pattern, file, line, description} -- Anti-pattern detected
• artifact_produced: {name, path, producer, type} -- Deliverable created

---

Output (report_agent_job_result)

Return JSON: { "id": "{id}", "status": "completed" | "failed", "findings": "Key discoveries and implementation notes (max 500 chars)", "artifacts_produced": "semicolon-separated paths of produced files", "qa_score": "", "qa_verdict": "", "error": "" }

---

## Role-Specific Customization

The coordinator generates per-role instruction variants during Phase 1. Each variant adds role-specific execution guidance to Step 3.

### For Analyst Role

3. Execute:
   • Detect tech stack from package.json (react, nextjs, vue, svelte, html-tailwind)
   • Detect existing design system via Glob: **/token., **/.css
   • Retrieve design intelligence via ui-ux-pro-max skill:
     • Full design system: Skill(skill="ui-ux-pro-max", args=" --design-system")
     • UX guidelines: Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")
     • Tech stack guide: Skill(skill="ui-ux-pro-max", args=" --stack ")
   • Fallback if skill unavailable: generate from LLM general design knowledge
   • Analyze existing codebase patterns (color palette, typography, spacing, components)
   • Optional: WebSearch for " web design trends best practices"
   • Compile design-intelligence.json with: _source, industry, detected_stack, design_system, ux_guidelines, stack_guidelines, recommendations
   • Write requirements.md summarizing all requirements
   • Output to /artifacts/analysis/

### For Architect Role

3. Execute:
   • Load design-intelligence.json from analyst output
   • Generate design token system (design-tokens.json) with categories:
     • color: primary, secondary, background, surface, text, CTA (light + dark mode)
     • typography: font families, font sizes (scale)
     • spacing: xs through 2xl
     • border-radius: sm, md, lg, full
     • shadow: sm, md, lg
     • transition: fast, normal, slow
   • Use $type + $value format (Design Tokens Community Group)
   • Generate component specs in component-specs/ directory:
     • Design reference (style, stack)
     • Props table (name, type, default, description)
     • Variants table
     • Accessibility requirements (role, keyboard, ARIA, contrast)
     • Anti-patterns to avoid
   • Generate project structure (project-structure.md) using stack-specific layout
   • Output to /artifacts/architecture/

### For Developer Role

3. Execute:
   • Load design tokens, component specs, and project structure from architect output
   • Generate CSS custom properties from design-tokens.json:
     • color -> --color-, typography -> --font-, --text-, spacing -> --space-
     • Add @media (prefers-color-scheme: dark) override for color tokens
   • Implement components following specs and coding standards:
     • Use design token CSS variables -- never hardcode colors/spacing
     • All interactive elements: cursor: pointer
     • Transitions: 150-300ms via var(--duration-normal)
     • Text contrast: minimum 4.5:1 ratio
     • Include focus-visible styles for keyboard navigation
     • Support prefers-reduced-motion
     • Responsive: mobile-first with md/lg breakpoints
     • No emoji as functional icons
   • Self-validate: scan for hardcoded colors, missing cursor-pointer, missing focus styles
   • Auto-fix where possible
   • Output to src/ directory (codebase files) + implementation summary

### For QA Role

3. Execute:
   • Load design intelligence and design tokens for compliance checks
   • Collect files to review based on review_type:
     • architecture-review: /artifacts/architecture/**/*
     • code-review: src/**/*.{tsx,jsx,vue,svelte,html,css}
     • final: src/**/*.{tsx,jsx,vue,svelte,html,css}
   • Execute 5-dimension audit:
     • Dim 1 Code Quality (0.20): file length, console.log, empty catch, unused imports
     • Dim 2 Accessibility (0.25): alt text, labels, headings, focus styles, ARIA
     • Dim 3 Design Compliance (0.20): hardcoded colors, spacing, anti-patterns
     • Dim 4 UX Best Practices (0.20): cursor-pointer, transitions, responsive, states
     • Dim 5 Pre-Delivery (0.15): final checklist (code-review/final types only)
   • Calculate weighted score: sum(dimension_score * weight)
   • Determine verdict: score >= 8 AND critical == 0 -> PASSED; score >= 6 AND critical == 0 -> PASSED_WITH_WARNINGS; else -> FIX_REQUIRED
   • Write audit report to /artifacts/qa/
   • Set qa_score and qa_verdict in output

---

## Quality Requirements

All agents must verify before reporting complete:

| Requirement | Criteria |
|-------------|----------|
| Files produced | Verify all claimed artifacts exist via Read |
| Files modified | Verify content actually changed |
| Findings accuracy | Findings reflect actual work done |
| Discovery sharing | At least 1 discovery shared to board |
| Error reporting | Non-empty error field if status is failed |
| QA fields | qa_score and qa_verdict set for QA role tasks |

---

## Placeholder Reference

| Placeholder | Resolved By | When |
|-------------|------------|------|
| `<session-folder>` | Skill designer (Phase 1) | Literal path baked into instruction |
| `{id}` | spawn_agents_on_csv | Runtime from CSV row |
| `{title}` | spawn_agents_on_csv | Runtime from CSV row |
| `{description}` | spawn_agents_on_csv | Runtime from CSV row |
| `{role}` | spawn_agents_on_csv | Runtime from CSV row |
| `{pipeline_mode}` | spawn_agents_on_csv | Runtime from CSV row |
| `{scope}` | spawn_agents_on_csv | Runtime from CSV row |
| `{review_type}` | spawn_agents_on_csv | Runtime from CSV row |
| `{prev_context}` | spawn_agents_on_csv | Runtime from CSV row |