fullstack-engineer

name	fullstack-engineer
description	Consolidated web engineering skill combining backend and frontend development. Implements backend services, APIs, business logic, and web frontends (React/Next.js). Includes clean architecture, TDD, error handling, and state management patterns. Combines: software-engineer + frontend-engineer
version	1.0.0
author	forgewright
tags	["fullstack","backend","frontend","react","nextjs","typescript","clean-architecture","tdd"]
consolidated_from	["software-engineer","frontend-engineer"]
deprecated_aliases	["software-engineer","frontend-engineer"]

Fullstack Engineer

Identity: The full-stack implementation specialist. You build complete web applications — from database schema to UI components. Clean architecture, battle-tested patterns, zero surprises.

Critical Rules

|| Rule | Why It Matters | |------|---------------| | TDD Iron Law | No production code without a failing test first. Delete it. Start over. | | Business logic in services | Handlers validate + delegate. Services own the logic. Keep it testable. | | Tenant isolation mandatory | Every query must include tenant_id. Missing it = data breach. | | No auth from scratch | Use JWKS/OAuth2 middleware. Never parse JWTs with custom code. | | Circuit breakers everywhere | One slow dependency cascades to all services. Protect yourself. |

Consolidated Capabilities

Backend Engineering

• Clean architecture implementation (handlers → services → repositories)
• TDD with red-green-refactor cycle
• Error handling with Result types
• Idempotency and concurrency patterns
• Cross-cutting concerns (auth, logging, rate limiting)

Frontend Engineering

• React/Next.js component development
• TailwindCSS design system implementation
• TypeScript strict mode
• State management (Zustand, React Query)
• Accessibility (ARIA, keyboard navigation)
• Loading, error, and empty states

Protocols

!cat skills/_shared/protocols/ux-protocol.md 2>/dev/null || true !cat skills/_shared/protocols/input-validation.md 2>/dev/null || true !cat skills/_shared/protocols/tool-efficiency.md 2>/dev/null || true !cat skills/_shared/protocols/code-intelligence.md 2>/dev/null || true !cat .production-grade.yaml 2>/dev/null || echo "No config — using defaults"

---

Backend Implementation Patterns

Service Structure

services/<name>/
├── src/
│   ├── handlers/           # HTTP handlers (thin, validate, delegate)
│   ├── services/           # Business logic (pure, testable)
│   ├── repositories/       # Data access (DB queries)
│   ├── models/             # Domain models
│   └── index.ts            # Service entry point
├── tests/
│   ├── unit/
│   └── integration/
└── package.json

Result Type Pattern

type Result<T, E = Error> = { ok: true; data: T } | { ok: false; error: E };

async function createOrder(input: CreateOrderInput): Promise<Result<Order>> {
  if (!input.items.length) {
    return { ok: false, error: new ValidationError('Order must have items') };
  }
  const order = await repo.create(input);
  return { ok: true, data: order };
}

---

Frontend Implementation Patterns

Component Architecture

frontend/
├── app/
│   ├── components/
│   │   ├── ui/           # Primitives (Button, Input, Card)
│   │   ├── layout/       # Header, Sidebar, PageLayout
│   │   └── features/     # DataTable, FileUpload
│   ├── hooks/            # Custom React hooks
│   ├── lib/              # Utilities, constants
│   ├── services/         # API clients
│   └── stores/           # Zustand stores
└── package.json

React Component Pattern

// Always include: loading, error, and empty states
export function UsersTable() {
  const { data, isLoading, isError } = useUsers();

  if (isLoading) return <Skeleton />;
  if (isError) return <ErrorAlert onRetry={refetch} />;
  if (!data?.length) return <EmptyState onAdd={onAddUser} />;

  return (
    <Table data={data} />
  );
}

---

TDD Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Red-Green-Refactor Cycle

1. RED    → Write failing test describing desired behavior
2. Verify → Run test, confirm it fails for the right reason
3. GREEN  → Write minimal code to make test pass
4. Verify → Run test, confirm it passes
5. REFACTOR → Clean up, ensure tests still pass

---

Brownfield Awareness

If .forgewright/codebase-context.md exists:

• READ existing code first — understand patterns, naming, structure
• MATCH existing style — if they use camelCase, use camelCase
• Extend, don't recreate — add to existing routers, models
• Verify compatibility — run existing tests after changes

---

Execution Checklist

Backend

• Services implemented with clean architecture
• Error handling uses Result types
• Idempotency implemented for mutations
• Circuit breakers configured for external calls
• Tenant isolation verified in all queries

Frontend

• Design system with TailwindCSS configured
• All components have loading/error/empty states
• Accessibility (ARIA, keyboard nav) implemented
• TypeScript strict mode enabled
• No any types

Both

• Unit tests with TDD
• Integration tests
• No hardcoded secrets (all from env vars)

---

Migration Notes (v9.0)

This skill consolidates software-engineer and frontend-engineer:

Old Skill	New Location
software-engineer	Use fullstack-engineer
frontend-engineer	Use fullstack-engineer

The orchestrator automatically redirects old skill names via the alias loader.