Frontend Dev

---
name: frontend-dev
disable-model-invocation: true
description: Implements one frontend or mixed task end-to-end. Stack-agnostic — detects the project's frontend framework from package.json. Reads design source (wireframes or design_source path) and produces working UI matching the task's acceptance criteria.
---

# Frontend Dev

## When to use

- Per-task dispatch by orchestrator when the task is tagged `frontend` or `mixed` (and the mixed slice is UI).

## Preflight

Get your `Touches:` globs by track. Full: from `briefs/task-<n>.md` (Touches, Depends on and Files to read live only in the brief). Lite: from the `Touches:` line in the dispatch prompt. Quick: none; the request text is the brief. These are the file globs you're expected to write to — they define the soft contract that lets the orchestrator dispatch sibling tasks in parallel without file-corruption races.

**Soft contract (honor-based, not enforced):** Stay within `Touches:`. If you must write outside those globs, be honest — list every extra path under `touches_expanded:` in your final YAML report. The orchestrator uses that list to detect sibling collisions; lying about it corrupts other tasks' work.

## Required reading

1. Read `${CLAUDE_PLUGIN_ROOT}/skills/playbook/SKILL.md` — the playbook core (shared contract). Read it before anything else.
2. `references/best-practices.md`
3. `references/pitfalls.md`
4. `references/stack-notes.md` (the section matching the detected stack)
5. `references/examples.md`
6. The current task slice from `<feature folder>/plan.md` — on the full track, read `<feature folder>/briefs/task-<n>.md` instead (the brief is your primary input). Do not read `spec.md` or `plan.md` in full. If the brief is insufficient, return `NEEDS_CONTEXT` naming the missing information. Lite/quick: unchanged (spec.md / request text as dispatched).
7. Wireframes (if present) at `<feature folder>/wireframes/`, or `feature.json.design_source` if set

## Wireframe contract

**Any AC the task covers that references a `wireframes/*.html` path is binding.** Wireframes are NOT optional reference — they are the visual portion of the acceptance contract. Failing to match a wireframe is failing the AC.

Before writing any code:

1. Look for a `**Wireframes:**` line in the brief (full track) or task slice, OR a `Wireframes (binding contract):` header in the orchestrator's dispatch prompt.
2. Open **every** listed wireframe file (Read tool) before composing the implementation.
3. For each wireframe, enumerate the visible columns / elements / states. Compare against the AC list — if the spec has a `## Wireframe acceptance criteria` section, those ACs map 1:1 to wireframe elements.
4. Implement the rendered page so it matches the wireframe **column-for-column / element-for-element**. A missing column, chip, or pill is a review failure.
5. If a wireframe path is referenced in an AC but missing from disk, return `NEEDS_CONTEXT` rather than guessing the design.

This rule overrides any temptation to summarise the wireframe into prose and skip details. The wireframe is the spec.

## The job

1. **Detect stack** from `package.json` (React, Vue, Svelte, vanilla, Next.js, Vite, etc.). Note the framework + UI library + state tool + styling approach.
   If `expo` is a dependency in `package.json`, it is Expo / React Native: if `expo:*` skills are available, invoke `expo:expo-overview` first, then read the "React Native + Expo (Expo Router)" section of `references/stack-notes.md` and the "React Native" section of `references/pitfalls.md`.
2. **Open every wireframe in the binding contract above.** This is step zero of any frontend task — non-negotiable when wireframes are listed.
3. **Re-read existing patterns** — find an existing component of similar shape and follow its conventions (file location, naming, styling, test placement). Do not invent new patterns.
4. **Write code + tests together** when `feature.json.auto_tests == true`. Tests live with the component (e.g., `<Component>.test.tsx` colocated).
5. **Run the project's check commands** (typically `npm run typecheck`, `npm run lint`, `npm test`). Prefer `.dev-cycle/project.json` `commands` (`lint`, `typecheck`, `test`, `format`) when present. Fix any errors before reporting DONE. Run tests with `node <CLI> check --scope touched --files <changed files> --steps test`, or the project test command with a quiet reporter. Never paste full test output into the report.
   If `pnpm-workspace.yaml` exists, run the checks with `pnpm -F <pkg> <script>` or `pnpm -r <script>`.
6. **Check your touched files.** Before reporting DONE, run via Bash `node <CLI> check --scope touched --files <changed files>` (CLI path from the dispatch envelope). On FAILED, fix the issues and re-run once. If it still fails and you cannot fix it, report `DONE_WITH_CONCERNS` with the failing output; the orchestrator may dispatch cli-fallback in diagnose mode. Exit 2 (no check commands found) is not a failure — note it and continue.
7. **Stage but do not commit** — the orchestrator commits.

## Output contract

End with the YAML block plus at most 5 lines of prose; never paste full test or tool output.

```yaml
---
status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
output_file: n/a
summary: <one sentence on what was implemented>
tokens_used: ~<N>k
duration: <Xm Ys>
concerns: <only if DONE_WITH_CONCERNS — e.g., "library X is deprecated, recommend migration in follow-up">
touches_expanded: []   # optional. List every file you wrote that is NOT
                       # matched by the task's declared `Touches:` globs.
                       # Empty list (or omitted) means you stayed within
                       # Touches. The orchestrator reads this to detect
                       # sibling write-collisions in a parallel group —
                       # be honest, the contract is not tool-enforced.
---
```