---
name: development-workflow
description: >
  Development workflow index — drives module development from PRD to
  production-ready SmartStack extension (NuGet + npm) with mandatory tests
  at every layer.
phase: development
allowed-tools: [Read, Glob, Grep]
---

# Development Workflow

Transforms PRD output from Business Analysis into production-ready client
extensions consuming the SmartStack SDK — backend (Clean Architecture + CQRS
on NuGet packages) and frontend (PageRegistry + Slot/Fill on `@atlashub/smartstack`
npm package) — with tests at every layer.

## Workflow

```
PRD (from BA) → planning (human) → 7 scaffold phases → testing → handoff (human)
```

Planning (reading the PRD, producing an execution plan) and final handoff (aggregating
test reports, producing a delivery note) are currently **human-driven** steps. Only the
7 scaffold phases below are automated via skills + CLIs.

| Phase | Skill | Output | Tests | Mandatory |
|-------|-------|--------|-------|-----------|
| 1 | `backend/seed-data` | IClientSeedDataProvider | Seed idempotence | ✅ |
| 2 | `backend/data-layer` | Entities + EF Configs | Entity factory | ✅ |
| 3 | `backend/data-layer` | Migration + DTOs | Migration smoke | ✅ |
| 4 | `backend/business-layer` | CQRS + Handlers + Validators | Handler delegation + service (in-memory `ExtensionsDbContext`) + validator | ✅ |
| 5 | `backend/controller` | Controllers + Permissions | Integration tests — **real SQL Server LocalDB + Respawn** (never InMemory) | ✅ |
| 6 | `frontend/routes` + `frontend/component` + `frontend/extension-config` + `frontend/api-client` | React pages + PageRegistry | Component tests | ✅ |
| 7 | `testing` | Full test suite report | All layers | ✅ |

**Tests are MANDATORY at every phase**: no phase is considered DONE without its
associated test suite green on the client's CI.

### DONE criteria per phase

A phase is DONE only when **all** of the following are true:
1. The CLI (`generate()`) output writes all expected files without errors
2. `dotnet build` (backend) / `tsc --noEmit` (frontend) passes
3. The phase's test suite runs and passes (`dotnet test` / `npm test`)
4. No `TODO` / `FIXME` / `/* map dto fields */` left in generated code
5. SmartStack conventions validated (permission format `app.module.action`, ComponentKey dot-separated, tables prefixed `{domain}_`, random Guids)

If any criterion fails, the phase is rolled back (delete generated files, fix the skill or CLI, re-run).

## Skills Index

### Backend
- `backend/structure/` — Target Clean Architecture (documentation)
- `backend/seed-data/` — IClientSeedDataProvider generation
- `backend/data-layer/` — Entities + EF Core configurations + Migration
- `backend/business-layer/` — CQRS (Commands/Queries/Handlers/DTOs/Validators)
- `backend/controller/` — API Controllers + Permissions

### Frontend
- `frontend/structure/` — Target React + Vite layout (documentation)
- `frontend/routes/` — PageRegistry registrations + componentRegistry.generated.ts (incl. per-page mobile/offline metadata `{ mobile: … }`)
- `frontend/component/` — React pages (List/Detail/Form) + Slot/Fill + i18n (fr/en/it/de) (offline read/write behaviour via `pwa`)
- `frontend/extension-config/` — ExtensionConfig + slots
- `frontend/api-client/` — TypeScript API clients + React Query hooks (+ outbox spec module per offline-write entity)
- `frontend/pwa/` — App-level PWA transform (SW/manifest/icons/registerSW/initOutbox, client mode only) + `aggregate-outbox` (outbox.generated.ts)

### Testing
- `testing/` — Test generation per layer (xUnit + FluentAssertions + Moq + FluentValidation.TestHelper + Vitest)

### Public API (third-party, machine-to-machine)
- `../external-api/` — `/external-api`: publish part of the app as an API a THIRD PARTY consumes.
  The platform whitelists exactly one route prefix for an external application and resolves the
  4th path segment against its endpoint catalogue, so the seam is a table row, not a socle change.
- `audit-dev-external-api/` — DEV-XAPI-001..014: the two failures a browser never reveals — a route
  with no catalogue row (404 for every external app, healthy for a signed-in human) and a catalogue
  permission disagreeing with the compiled constant (403 no re-granting can fix) — plus the
  cross-tenant gate, since a machine caller carries no ambient tenant.

### Audit / Debug / Run
- `audit/` — Post-generation conventions audit
- `audit/routing-dynamic/` — Audit skills themselves against SmartStack dynamic routing
- `debug/` — Bug triage + fix
- `run/` — Launch backend + frontend for local verification

## Architecture Target

Generated code extends SmartStack via packages:
- **Backend (NuGet)**: `SmartStack.Core`, `SmartStack.Application`, `SmartStack.Infrastructure`, `SmartStack.Api`
  - Clean Architecture + CQRS + MediatR + FluentValidation
  - `ICoreDbContext` is the abstraction boundary (never reference `CoreDbContext` concretely)
- **Frontend (npm)**: `@atlashub/smartstack`
  - PageRegistry + DynamicRouter + ProtectedRoute + Slot/Fill + ExtensionConfig
  - `SmartStackProvider` wraps the app at root (`main.tsx`)
- **Data**: `IClientSeedDataProvider` for navigation + RBAC (idempotent, hierarchical)
- **Tests**: xUnit (`[Trait("Category","…")]`, `[Trait("Type","Unit"|"Integration")]`) + Vitest