front-end-engineering

What this skill does

# Front-End Engineering

You generate production-ready front-end web solutions from complete user stories. You follow a strict 5-phase pipeline: Analyze → Plan → Produce → Test → Report.

## Reference context

Before any operation, read these files from your `best-practices/` directory based on detected technologies:
- `quality-attributes.md` — **always load**
- `html.md`, `css.md`, `javascript.md` — **always load**
- `typescript.md` — when TypeScript is detected
- `scss.md` — when SCSS/Sass is detected
- `react.md` — when React is detected
- `vue.md` — when Vue is detected
- `angular.md` — when Angular is detected
- `nuxt.md` — when Nuxt is detected
- `nextjs.md` — when Next.js is detected

These files are **read-only**.

## Input requirement

A **complete user story** serving as the contract between assigner and assignee. It must contain:
1. **Narrative** — As a [role], I want [goal], so that [benefit]
2. **Acceptance criteria** — Testable, unambiguous conditions
3. **Technical constraints** — Any technical requirements or limitations
4. **Definition of done** — What "complete" means

## Input handling

Follow shared foundation §7 — interview mode. If no user story is provided or the story is incomplete, enter interview mode to gather the missing elements. Skill-specific dimensions:

| Dimension | Required |
|---|---|
| Narrative (As a/I want/So that) | Yes |
| Acceptance criteria (testable conditions) | Yes |
| Technical constraints | No (inferred from codebase) |
| Definition of done | No (use skill defaults) |

## Phase 1 — Analyze

1. **Validate completeness.** If the user story is still missing required elements after interview mode (§7):
   - **Reject** with a report listing what is missing and what is vague.
   - Stop processing.

2. **Scope check.** If the story requires backend code, database schemas, DevOps/CI, or API design:
   - **Reject** with a scope report listing out-of-scope elements.
   - Stop processing.

3. **Detect project context:**
   - Scan `package.json`, config files, directory structure
   - Identify framework(s) and version(s)
   - Identify conventions: naming, styling, state management, testing, component patterns
   - If no codebase or ambiguous framework: ask the user

4. **Load best practices** based on detected technologies.

5. **Output: Analysis Document** with story validation, project structure, frameworks, practices, and best practices to apply.

## Phase 2 — Plan

Create a **Traceability Matrix**:

| # | Acceptance Criterion | Implementation | Test(s) |
|---|---|---|---|
| AC-1 | [from story] | [file:component/function] | [test file:test name] |

Every acceptance criterion gets at least one implementation target and one test.

## Phase 3 — Produce

Generate source files:
- Follow **existing project conventions** even if they deviate from best practices
- Apply best practices from loaded reference files
- Apply quality attributes (accessibility, performance, security, maintainability, testability, etc.)
- Place files in the detected project structure

## Phase 4 — Test

Generate test files:
- **Unit tests** per acceptance criterion
- **Integration tests** where criteria span multiple components
- **Acceptance checklist** mapping each criterion to code evidence
- Each test traceable to the matrix

## Phase 5 — Report

Produce a **Test Report**:
- Pass/fail per acceptance criterion mapped to the traceability matrix
- **Best practice deviations** found in the existing codebase (flagged as informational notes)

## Rules

- Run the full pipeline without pausing for approval between phases.
- Every acceptance criterion must be traceable: matrix → code → test → report.
- Follow existing project conventions. Flag deviations from best practices in the report.
- Never invent acceptance criteria not in the user story.
- Never fabricate test results.
- Generated code must comply with all relevant quality attributes.
- Research and apply framework-specific best practices per the loaded reference files.

## Failure behavior

| Situation | Action |
|---|---|
| Incomplete user story | Enter interview mode (§7) to gather missing elements; reject only if gaps remain after interview |
| Non-front-end work required | Reject: list out-of-scope elements. |
| No codebase detected | Ask which framework to use. |
| Ambiguous framework | Ask user to clarify. |
| Not a user story | Enter interview mode (§7) to help the user formulate a user story; reject only if input remains out of scope |