---
name: react-feature-scaffold
description: Create, scaffold, or extend React projects with a closed feature-first architecture based on thin route entrypoints, real implementations in src/features, shared cross-cutting foundations, Vite, TypeScript, React Router, and Vitest. Use when Codex must build a new React codebase or add features without creating duplicate sources of truth, leaking domain logic into src/pages or src/app/router.tsx, or drifting from a layered feature structure.
---

# React Feature Scaffold

Inspect the repository first. Reuse existing conventions when they already match the target architecture. If the repository is empty or does not yet have the required structure, scaffold from `assets/templates/`.

This skill is intentionally closed: it reduces architectural freedom so the project stays consistent as it grows.

## Load These References Only When Needed

- `references/project-structure.md`: target folder layout and ownership boundaries
- `references/decision-rules.md`: rules for when to create `model`, `controller`, and `services`
- `references/auth-reference.md`: complete reference for provider, validation, service, and guard layering
- `references/validation-checklist.md`: checks to run before finishing

## Bundled Template

Use `assets/templates/` when the repository needs a baseline React/Vite/TypeScript scaffold with:

- `src/app` for bootstrap, providers, router, guards, and shell composition only
- `src/pages` for thin route entrypoints only
- `src/features/<feature>` for real implementation
- `src/shared` for shared UI, theme, and utilities
- `src/styles` for app-wide styles
- `src/test` for testing setup

The template includes:

- one complete auth/login example using `model`, `controller`, `services`, `view`, provider, and route guard
- one stateful example feature using `view`, `model`, and `controller`
- one thin page wrapper that delegates to a feature implementation
- alias configuration via `@/*`
- `react-router-dom`, `vitest`, and `testing-library`

The template also bundles example test files as `*.template-test.tsx.txt`. Rename them back to `*.test.tsx` after copying the template into a fresh target project. They stay inactive here so the host repository test runner does not execute template examples against the host aliases.

## Required Architecture Rules

- Keep `src/app` limited to app bootstrap, providers, routing, guards, and shell composition.
- Keep `src/pages` limited to thin route entrypoints. Pages must delegate to `src/features`.
- Place real feature UI, state, metadata, mocks, and feature-specific helpers under `src/features/<feature>`.
- Use `src/shared` only for reusable primitives and cross-cutting concerns.
- Do not place domain logic in `src/app/router.tsx`.
- Do not duplicate implementations between `src/pages` and `src/features`.
- When a route needs a page component, make it a thin wrapper that imports the real feature page and immediately returns it.
- Keep naming stable and predictable. Prefer one canonical implementation path per responsibility.

## Scaffold Workflow

1. Inspect the repository for existing `src/app`, `src/pages`, `src/features`, `src/shared`, routing, test setup, and aliases.
2. If the target structure already exists, extend it instead of replacing it.
3. If the target structure does not exist, copy the minimum necessary baseline from `assets/templates/`.
4. Create new features under `src/features/<feature>`.
5. Add route entrypoints under `src/pages/...` only as thin wrappers.
6. Update `src/app/router.tsx` to compose routes, never to hold business logic.
7. Add or update tests when behavior or architectural guarantees materially change.

## Decision Policy

- Create `model` when the feature contains types, metadata, static content, validation, or shaping rules.
- Create `controller` only when the feature has meaningful state, orchestration, or interaction logic.
- Create `services` only when the feature integrates with external systems or needs a boundary for async orchestration.
- When the repository needs a canonical full-stack feature example, prefer `auth` as the architectural reference because it demonstrates provider, storage, validation, controller, service, view, and route protection together.
- Do not create empty folders only for symmetry.
- If a requested implementation would leave two real sources of truth for the same feature, consolidate before finishing.

## Expected Output

- Summarize the architectural changes.
- Identify any thin wrappers that were added.
- State whether any intentional architectural debt remains.
- Mention validation results from the relevant checks.