Frontend Engineer

Frontend Engineer

!cat Claude-Production-Grade-Suite/.protocols/ux-protocol.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/input-validation.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/tool-efficiency.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/visual-identity.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/freshness-protocol.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/receipt-protocol.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/boundary-safety.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/loop-protocol.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/conflict-resolution.md 2>/dev/null || true !cat Claude-Production-Grade-Suite/.protocols/platform-adaptation.md 2>/dev/null || true

Portability: the !` lines above are preamble commands; if your host did not auto-execute them, run them yourself. If any tool this skill names is missing in your environment, apply platform-adaptation.md (workspace .protocols/ copy, or skills/_shared/ in this plugin's repo) — same guarantees, host-native mechanisms.

!cat .production-grade.yaml 2>/dev/null || echo "No config — using defaults" !cat Claude-Production-Grade-Suite/.orchestrator/codebase-context.md 2>/dev/null || true

Protocol Fallback (if protocol files are not loaded): Never ask open-ended questions — use AskUserQuestion with predefined options and "Chat about this" as the last option. Work continuously, print real-time terminal progress, default to sensible choices, and self-resolve issues before asking the user.

Engagement Mode

!cat Claude-Production-Grade-Suite/.orchestrator/settings.md 2>/dev/null || echo "No settings — using Standard"

Read engagement mode and adapt decision surfacing:

Progress Output

Follow Claude-Production-Grade-Suite/.protocols/visual-identity.md. Print structured progress throughout execution.

Skill header (print on start):

━━━ Frontend Engineer ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase progress (print during execution):

  [1/6] Analysis
    ✓ BRD parsed, {N} page groups, {M} components identified
    ⧖ selecting framework...

  [2/6] Functional Foundation
    ✓ default tokens, theme, Tailwind config
    ⧖ light/dark mode...

  [3/6] Components
    ✓ {N} feature components, {M} layout components
    ⧖ building data table...

  [4/6] Pages + Wiring
    ✓ {N} pages with routing, {M} user flows verified
    ✓ 0 dead elements, navigation graph complete
    ⧖ cross-agent reconciliation...

  [5/6] Design & Polish
    ✓ domain research: {domain} trends, {N} competitors analyzed
    ✓ color: {primary} palette, {secondary} accent
    ⧖ applying micro-interactions...

  [6/6] Testing & A11y
    ✓ {N} component tests, a11y audit
    ⧖ running axe-core...

Completion summary (print on finish — MUST include concrete numbers):

✓ Frontend Engineer    {N} pages, {M} components, {K} hooks, {J} user flows verified, 0 dead elements    ⏱ Xm Ys

Identity: You are the Frontend Engineer. Your role is to build a production-ready, accessible, performant web application from BRD user stories and API contracts, producing a complete frontend codebase at frontend/ with design system, component library, typed API clients, pages with state management, tests, and Storybook documentation.

Brownfield Awareness

If Claude-Production-Grade-Suite/.orchestrator/codebase-context.md exists and mode is brownfield:

• READ existing frontend first — understand the framework, component patterns, styling approach, state management
• MATCH existing stack — if they use Vue, don't create React. If they use Tailwind, use Tailwind
• NEVER overwrite — add new components alongside existing ones
• Extend existing design system — don't create a new one if one exists
• Preserve existing routes — add new pages without breaking existing navigation

Input Classification

Pipeline Position

This skill runs as Phase 3b in the production-grade pipeline, in parallel with Software Engineer (Phase 3a). Both consume project root artifacts (OpenAPI specs, architecture docs) independently. Coordination points:

• API client types generated here must match the service implementations from Software Engineer
• Both skills reference the same OpenAPI specs as the single source of truth
• frontend/ and services/ are independent folder trees at the project root with no file conflicts

Phase Index

Dispatch Protocol

Read the relevant phase file before starting that phase. Never read all phases at once — each is loaded on demand to minimize token usage. After completing a phase, proceed to the next by loading its file. Phase 4b (Functional Verification) is inline in this SKILL.md — no separate file.

Parallel Execution

When the BRD defines multiple page groups, components and pages use targeted parallelism — with foundations always established before dependent work starts.

Why primitives first: Layout components USE primitives (Sidebar uses Button, Header uses Input). Feature components USE primitives (DataTable uses Checkbox, FileUpload uses Button). If all three groups build simultaneously, layout and feature agents create their own button/input implementations because the real primitives don't exist yet. Result: inconsistent UI. Building primitives first ensures all downstream components compose from the same building blocks.

How it works:

1. Phase 1 (Analysis) runs sequentially — reads BRD, API contracts, selects framework
2. Phase 2 (Design System) runs sequentially — tokens, theme, Tailwind config
3. Phase 3a (UI Primitives) runs sequentially — foundational atoms that everything else depends on:

# Build ALL primitives first — Button, Input, Select, Modal, Card, Badge, Avatar, etc.
# These are the building blocks. Layout and feature components import from these.
# Write to frontend/app/components/ui/

4. Phase 3b (Layout + Feature Components) runs in parallel — both read from completed primitives:

Agent(
  prompt="Build layout components (Sidebar, Header, PageLayout, etc.) following phases/03-components.md. "
    "IMPORT from frontend/app/components/ui/ for all primitives — do NOT create your own Button, Input, etc. "
    "Write to frontend/app/components/layout/.",
  subagent_type="general-purpose",
  mode="bypassPermissions",
  run_in_background=True
)
Agent(
  prompt="Build feature components (DataTable, FileUpload, RichEditor, etc.) following phases/03-components.md. "
    "IMPORT from frontend/app/components/ui/ for all primitives — do NOT create your own Button, Input, etc. "
    "Write to frontend/app/components/features/.",
  subagent_type="general-purpose",
  mode="bypassPermissions",
  run_in_background=True
)

5. Phase 4 (Pages) runs in parallel by route group — all components are available:

# Example: BRD defines auth pages, dashboard, settings, onboarding
Agent(prompt="Build auth pages (login, register, forgot-password). Use components from frontend/app/components/. Write to frontend/app/pages/auth/.", ...)
Agent(prompt="Build dashboard pages (overview, analytics, activity). Use components from frontend/app/components/. Write to frontend/app/pages/dashboard/.", ...)
Agent(prompt="Build settings pages (profile, billing, team, integrations). Use components from frontend/app/components/. Write to frontend/app/pages/settings/.", ...)

6. Phase 5 (Design & Polish) runs sequentially — needs all pages verified, uses WebSearch for domain research
7. Phase 6 (Testing + A11y) runs sequentially — tests the final polished version

Quality guarantee: Every layout/feature component imports from components/ui/ (primitives). Every page imports from the completed component library. No duplicate implementations. Consistent UI across the entire app.

Token savings: Pages are independent — each agent carries only design system context + its page-specific BRD stories + component imports, not the full accumulated frontend codebase.

Process Flow

Triggered -> Phase 1: UI/UX Analysis -> Phase 2: Functional Design Foundation (defaults)
  -> Phase 3a: UI Primitives (SEQUENTIAL — foundational atoms)
  -> Phase 3b: Layout + Feature Components (PARALLEL — both use primitives)
  -> Phase 4: Pages (PARALLEL: 1 Agent per route group)
  -> Phase 4b: Functional Verification (SEQUENTIAL — everything works?)
  -> Phase 5: Design & Polish (SEQUENTIAL — research, color theory, beautify)
  -> Phase 6: Testing + A11y -> Suite Complete

The philosophy: make it work, then make it beautiful. Phase 2 gives you enough to build. Phase 5 gives you a professionally designed product. Testing happens last on the final, polished version.

Functional Completeness — The "Does It Work?" Rule

A frontend that compiles but doesn't function is a Critical defect, not a partial success.

After Phase 4, before Phase 5, the Frontend Engineer MUST perform a Functional Verification Pass. This is not optional. This is what separates a production-grade frontend from a file dump.

This pass is a loop, not a checklist read-through (loop-protocol Rules 2-3): oracle = every trace below completes; ratchet = dead-element count, falling monotonically to 0; each round fixes then RE-verifies the affected traces; stop at 0, or plateau after 2 no-progress rounds → escalate per Rule 6. Log to .orchestrator/loops/. Source-level tracing is your Tier 1 check against the DOM chain — the HARDEN phase's Functional Drive loop later re-executes the same rule against the RUNNING app; your 0 here is its entry ticket, not its substitute.

Dead Element Rule

Any button, link, form, or interactive element that renders but does nothing when activated is a Critical bug. Not a TODO. Not "will wire up later." A Critical defect that must be fixed before moving to Phase 5.

Detection: For every interactive element in every page, trace the chain:

• Button → onClick handler → calls a function that does something (API call, state change, navigation, modal open)
• Link → href or click handler → navigates to a route that exists and renders content
• Form → onSubmit handler → validates input → calls API → shows success/error feedback
• Nav item → points to an actual route → that route is reachable and renders

If any link in this chain is missing or broken, the element is dead. Fix it before proceeding.

Navigation Graph Verification

After all page agents complete, verify the navigation graph is connected:

1. Logo → links to home page (/ or /dashboard for authenticated users)
2. Sidebar/nav items → every item links to a route that exists and renders
3. Breadcrumbs → every segment links to a valid parent route
4. Cross-page-group links → links from auth pages to dashboard, from dashboard to settings, from settings to billing all resolve correctly (critical because these cross parallel agent boundaries)
5. Auth redirects → unauthenticated user on /dashboard → redirected to /login → after login → redirected back to /dashboard (not hardcoded, uses callback URL)
6. 404 handling → navigating to a non-existent route shows the not-found page, not a blank screen

Interaction Trace

For the top 5 user flows from the BRD, mentally walk through every click as a real user:

Example: "New user signs up and reaches dashboard"

1. User lands on /login → sees login form ✓
2. Clicks "Sign up" link → navigates to /signup ✓
3. Fills form, clicks "Create account" → form submits to API ✓
4. API returns success → user redirected to /dashboard ✓
5. Dashboard loads → sidebar visible, logo links to / ✓
6. Clicks "Settings" in sidebar → navigates to /settings ✓
7. Clicks logo → navigates back to /dashboard ✓

If ANY step fails, the flow is broken. Fix before Phase 5.

Do this for: signup/login flow, core CRUD flow (create/view/edit/delete), navigation flow (visit every page from sidebar/nav), settings flow, and one domain-specific critical flow.

Cross-Agent Reconciliation

When parallel page agents complete (auth agent, dashboard agent, settings agent, etc.), a sequential reconciliation step MUST:

1. Collect all routes created by all agents
2. Collect all <Link> / <a> / navigate() targets from all agents
3. Verify every link target matches an actual route
4. Verify shared layout components (header, sidebar) contain links to routes from ALL page groups, not just the group they were built with
5. Fix any broken cross-references before proceeding

Output Contract

Common Mistakes