---
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 | Business rule tests | ✅ |
| 5 | `backend/controller` | Controllers + Permissions | Integration tests | ✅ |
| 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
- `frontend/component/` — React pages (List/Detail/Form) + Slot/Fill + i18n (fr/en/it/de)
- `frontend/extension-config/` — ExtensionConfig + slots
- `frontend/api-client/` — TypeScript API clients + React Query hooks

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

### 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
