# `/ba-develop` — Du PRD au code`/ba-develop` — From PRD to code

Une fois qu'une PRD a passé l'audit (score GO ≥ 80), `/ba-develop` orchestre 4 phases séquentielles pour générer le code complet d'un module. C'est la dernière commande que vous tapez : à sa sortie, le module est compilé, testé, et fonctionnel — aucune action manuelle requise derrière. Once a PRD passes audit (GO score ≥ 80), `/ba-develop` orchestrates 4 sequential phases to generate the full module code. It is the last command you type: when it returns, the module compiles, passes tests, and is functional — no manual action required afterwards.

## Vue d'ensemble du pipeline Pipeline at a glance

4 phases séquentielles, chacune isolée dans son propre subagent, séparées par des gates bloquants qui interdisent toute progression sur un drift détecté. Les deux audits symétriques (`audit-dev-api` en sortie de Phase 2 et `audit-dev-frontend` en sortie de Phase 3) verrouillent l'alignement entre le pagespec (source de vérité métier) et le code généré. 4 sequential phases, each isolated in its own subagent, separated by blocking gates that forbid progression on any detected drift. The two symmetric audits (`audit-dev-api` exiting Phase 2 and `audit-dev-frontend` exiting Phase 3) lock the alignment between the pagespec (business source of truth) and the generated code.

## Détail des 4 phases The 4 phases in detail

Chaque phase est un subagent isolé qui reçoit UNE slice du PRD. Une porte (gate) vérifie compilation + tests + audit dédié avant d'autoriser la phase suivante. Each phase runs as an isolated subagent that receives ONE PRD slice. A gate verifies compile + tests + dedicated audit before allowing the next phase to start.

Phase Phase | Nom Name | Skills mobilisées Mobilised skills | Sortie Output | Gate Gate
--- | --- | --- | --- | ---
0 | Core Foundation Seed Core Foundation Seed | `backend-core-seed` | Navigation, rôles, permissions de l'app App navigation, roles, permissions | build + tests
1 | Domain + Data Domain + Data | `backend-data-layer`, `backend-seed-data` | Entités, EF configs, migrations, seed Entities, EF configs, migrations, seed | build + tests
2 | Business + API Business + API | `backend-business-layer`, `backend-controller` | CQRS, validators, controllers RBAC, actions custom alignées sur le pagespec CQRS, validators, RBAC controllers, custom actions aligned with the pagespec | build + tests + `/audit-dev-api` (DEV-API-010/011)
3 | Frontend Frontend | `scaffold-theme`, `scaffold-layout`, `frontend-component`, `frontend-api-client`, `frontend-auth` | Pages, routes, API client, hooks d'auth, boutons custom (kind:api → hook, kind:navigate → `navigate()`)Pages, routes, API client, auth hooks, custom buttons (kind:api → hook, kind:navigate → `navigate()`) | build + tests + `/audit-dev-frontend` (DEV-UI-019..021) + smoke-test

À la sortie de la phase 3, le module est livré et fonctionnel (compilation + tests OK, smoke-test HTTP vert sur toutes les routes). At the end of phase 3, the module is delivered and functional (compile + tests OK, HTTP smoke-test green on all routes).

## Garanties Guarantees

- Aucun stub : règles métier et use cases sont implémentés, pas laissés vides.No stubs: business rules and use cases are implemented, not left empty.
- FK réelles : `relations[]` du PRD se traduit en `HasForeignKey()` + navigation + `OnDelete`.Real FKs: PRD `relations[]` map to `HasForeignKey()` + navigation + `OnDelete`.
- Phase 0 déterministe : la navigation + les rôles + les permissions sont écrites en un seul shot.Deterministic Phase 0: navigation + roles + permissions are written in a single shot.
- Gates entre phases : compile + tests + coverage avant de passer à la suivante.Gates between phases: compile + tests + coverage before moving to the next.

## Propagation des actions custom Custom-action propagation

Quand un pagespec déclare des actions au-delà des CRUD standard (par exemple `syncFromPce` kind:api ou `openHistory` kind:navigate), `/ba-develop` les propage verbatim à toutes les couches qui doivent les voir. Le champ `endpoint` du pagespec est l'unique source de vérité — il est compilé sans transformation dans le route attribute du Controller et dans l'URL axios du service. When a pagespec declares actions beyond the standard CRUD (e.g. `syncFromPce` kind:api or `openHistory` kind:navigate), `/ba-develop` propagates them verbatim to every layer that must see them. The pagespec's `endpoint` field is the single source of truth — it is compiled without transformation into the Controller route attribute and into the service's axios URL.

Phase Phase | Pour `kind: api` For `kind: api` | Pour `kind: navigate` For `kind: navigate`
--- | --- | ---
2 (Business) | Recette canonique ou stub `NotImplementedException` avec `// TODO[UC-…]`Canonical recipe or `NotImplementedException` stub with `// TODO[UC-…]` | —
2 (Controller) | `[HttpVerb("<endpoint>")]` + `[RequirePermission("…")]` | —
3 (Service.ts) | `apiClient.<verb>('/api/.../<endpoint>')` + hook React Query React Query hook | —
3 (Bouton) | Importe le hook + appelle `.mutate()` au clic Imports the hook + calls `.mutate()` on click | Importe `useNavigate` + appelle `navigate(targetRoute)`. Aucun hook, aucun appel axios.Imports `useNavigate` + calls `navigate(targetRoute)`. No hook, no axios call.
Gate Phase 2 Phase 2 gate | Cross-check : chaque `kind:api` du pagespec doit avoir un `[HttpVerb("<endpoint>")]` matching côté Controller, sinon la phase échoue.Cross-check: every pagespec `kind:api` action must have a matching `[HttpVerb("<endpoint>")]` on the Controller, otherwise the phase fails. |

Les audits dev symétriques verrouillent l'alignement après génération : The symmetric dev audits lock the alignment after generation:

Phase Phase | Audit exécuté automatiquement Audit invoked automatically | Règles bloquantes Blocking rules
--- | --- | ---
2 (Backend) | `audit-dev-api --mode audit` | DEV-API-010 (pagespec → controller), DEV-API-011 (warn)
3 (Frontend) | `audit-dev-frontend --mode audit` | DEV-UI-019 / DEV-UI-020 / DEV-UI-021

Garantie de fin de pipeline — un drift entre pagespec et Controller (cas classique Gesa : `POST /sync-from-pce` côté frontend, `[HttpPost("sync-from-proconcept")]` côté backend → 405 garanti) est bloqué au gate avant Phase 3, avec un message précis (« Controller manquant pour action `<endpoint>` du pagespec `<file>` »). Aucune commande utilisateur n'est requise après `/ba-develop` — quand la commande retourne avec succès, le module est 100 % opérationnel. End-of-pipeline guarantee — any drift between pagespec and Controller (classic Gesa case: `POST /sync-from-pce` on the frontend, `[HttpPost("sync-from-proconcept")]` on the backend → guaranteed 405) is blocked at the gate before Phase 3, with a precise message ("Controller missing for action `<endpoint>` from pagespec `<file>`"). No user command is required after `/ba-develop` — when the command returns successfully, the module is 100 % operational.

## Trois niveaux d'orchestration Three orchestration levels

Selon la portée du travail, trois entrées sont disponibles. Elles partagent toutes le même moteur (les 4 phases ci-dessus) mais varient en cardinalité. Depending on the scope of work, three entry points are available. They all share the same engine (the 4 phases above) but vary in cardinality.

Portée Scope | Skill Skill | Lit Reads | Effet Effect
--- | --- | --- | ---
1 module module | `/ba-develop <APP>/<MODULE>` | `prd.md` + slices + `pagespecs/*.md` | 4 phases séquentielles sur ce module 4 sequential phases on that module
1+ applications applications | `/ba-create-plan-development <APP1> [APP2]…` | `entité.md` des apps of the apps | Construit le graphe FK cross-module + tri topologique → `dev-plan.md` Builds cross-module FK graph + topological sort → `dev-plan.md`
Exécution du plan Plan execution | `/ba-develop-plan [--waves 1,2]` | `dev-plan.json` | Lance une vague à la fois ; dans chaque vague, un `/ba-develop` par module en parallèle ; gate entre vagues Runs one wave at a time; within a wave, one `/ba-develop` per module in parallel; gate between waves

### Cycle multi-module — comment ça marche Multi-module cycle — how it works

Le multi-module fonctionne en deux temps : Multi-module works in two steps:

1. Génération du plan : `/ba-create-plan-development APP_A APP_B` lit chaque `entité.md`, détecte les FK cross-module, trie les modules par dépendance en vagues parallélisables, et écrit `dev-plan.json`.Plan generation: `/ba-create-plan-development APP_A APP_B` reads every `entité.md`, detects cross-module FKs, sorts modules by dependency into parallelisable waves, and writes `dev-plan.json`.
2. Exécution du plan : `/ba-develop-plan` traite une vague à la fois. Dans chaque vague, il lance un subagent `/ba-develop` par module en parallèle ; une fois les N modules terminés, un gate compile + tests sur l'ensemble doit passer avant la vague suivante.Plan execution: `/ba-develop-plan` processes one wave at a time. Within each wave it launches one `/ba-develop` subagent per module in parallel; once the N modules complete, a compile + tests gate over the whole set must pass before the next wave starts.

Exemple : un plan à 3 vagues sur 2 applications. Example: a 3-wave plan over 2 applications.

Vague Wave | Modules développés en parallèle Modules developed in parallel | Gate de sortie Exit gate
--- | --- | ---
1 | `APP_A/Module_A1`, `APP_A/Module_A2`, `APP_B/Module_B1` | compile + tests des 3 modules compile + tests of the 3 modules
2 | `APP_A/Module_A3`, `APP_B/Module_B2` | compile + tests des 2 modules compile + tests of the 2 modules
3 | `APP_B/Module_B3` | smoke-test final final smoke-test

Pourquoi des vagues ? Un module qui possède une entité référencée comme FK par un autre module doit être livré avant ses dépendants. Les vagues encodent cet ordre tout en autorisant le maximum de parallélisme. Why waves? A module whose entity is referenced as an FK by another module must ship before its dependents. Waves encode that ordering while allowing maximum parallelism.

## Outil de remédiation — projets legacy Remediation tool — legacy projects

Pour les projets qui ont été développés avant la propagation typée des actions (custom actions en texte libre dans `screen.md`, drifts `pagespec / Controller / service.ts` accumulés), un CLI standalone cartographie les désalignements sans rien modifier par défaut : For projects developed before typed action propagation existed (free-text custom actions in `screen.md`, accumulated `pagespec / Controller / service.ts` drifts), a standalone CLI maps the misalignments without modifying anything by default:

    npx tsx templates/skills/development/audit-dev-frontend/cli/audit-dev-actions-alignment/index.ts `
      --project-path "<chemin>/web/<app>-web" `
      --backend-path "<chemin>" `
      --module-path  "<chemin>/.smartstack/ba/<APP>/<MODULE>" `
      --mode report-only

Sortie : `_audit/actions-alignment.md` listant les drifts par catégorie (`ACTION-DRIFT-001..005`) avec, pour chaque drift, le pagespec / Controller / service concerné et la commande de correction. Le mode `--mode apply` existe (opt-in) avec `--source-of-truth pagespec|controller` pour choisir qui gagne — toujours à utiliser avec un commit propre derrière. Output: `_audit/actions-alignment.md` listing drifts per category (`ACTION-DRIFT-001..005`) with, for each, the affected pagespec / Controller / service and the fix command. The `--mode apply` mode exists (opt-in) with `--source-of-truth pagespec|controller` to choose who wins — always use it with a clean commit behind.

Quand l'utiliser : on hérite d'un projet ancien ; on observe un bug HTTP 405 / 404 sur un bouton ; on veut auditer un module avant de le migrer au format custom actions typé. When to use it: inheriting an old project; observing a 405 / 404 HTTP bug on a button; auditing a module before migrating it to typed custom actions.

## Skills orchestrées Orchestrated skills

La table ci-dessous liste toutes les skills mobilisées (planification, backend, frontend, audits, tests) : The table below lists every mobilised skill (planning, backend, frontend, audits, tests):

## Skills orchestrées par `/ba-develop`

## Skills orchestrated by `/ba-develop`

### business-analyse (1)

`/ba-create-plan-development` business-analyse

Generates a phased development plan ordering modules by their cross-module data-model dependencies. Reads entité.md across selected applications, builds a dependency graph, topological-sorts into parallel development waves, and writes dev-plan.md. Invoke between the BA audit phase and /ba-develop.

args: `<APP1> [APP2] …`
Bash Read Glob

### devApi (1)

`/audit-dev-api` devApi

Audit code generated by the API phase against the PRD slice — controllers, routes, HTTP actions, RBAC attributes, DTOs, integration tests

### devCore (1)

`/audit-dev-core` devCore

Audit code generated by Phase 0 (Core Foundation Seed) — every PRD module must have nav + roles + permissions in the 5 Core providers, DI registration must be in place, and the providers must be deterministic (no hand-edits).

### devData (1)

`/audit-dev-data` devData

Audit code generated by the Data phase against the PRD slice — migrations, seed providers, navigation/permissions coverage, FK constraints, drift detection

### devDomain (1)

`/audit-dev-domain` devDomain

Audit code generated by the Domain phase against the PRD slice — entity files, FK pairing, naming, traceability, drift detection

### development/audit (2)

`/audit` development/audit

Audit du code genere contre les conventions SmartStack (i18n, React, structure, routing dynamique, RBAC, securite)

`/audit-routing-dynamic` development/audit

Audit READ-ONLY des skills de developpement SmartStack pour verifier leur conformite a l'architecture de routing dynamique DB-driven (PageRegistry + componentRegistry + DynamicRouter). Produit un rapport textuel sans modifier aucun skill.

### development/backend (6)

`/backend-business-layer` development/backend

Generates full CQRS stack — Commands, Queries, Handlers, DTOs, Validators, Service interface + implementation — on SmartStack NuGet abstractions (ICoreDbContext, MediatR, FluentValidation).

`/backend-controller` development/backend

Generates API controllers with NavRoute, RequirePermission, auto-mapped DTO → Command conversions, and module-scoped permission classes, consuming NuGet packages (SmartStack.Core, SmartStack.Api, MediatR).

`/backend-core-seed` development/backend

Phase 0 of /ba-develop — generates one Core Foundation Seed bundle per declared application (5 IClientSeedDataProvider classes per app covering navigation + roles + permissions + role-permission mappings + dev test users) by invoking the deterministic `scaffold-core-seed` CLI. Zero creative work for the agent: the spec is built by the Studio backend (`prepareCoreSeedContext`) from the BA menu / actors / permissions and dropped to a temp file before this skill runs.

`/backend-data-layer` development/backend

Generates Domain entities with BaseEntity (SmartStack.Core.Domain NuGet), domain events, soft-delete, EF Core configurations with schema targeting, and migrations.

`/backend-seed-data` development/backend

Generates module-scoped IClientSeedDataProvider implementations for reference data (lookup tables, enum codes) and per-module overrides. Cross-app navigation, roles, permissions, and role-permission mappings are NOT this skill's job — they live in scaffold-core-seed (Phase 0). Output goes under Persistence/Seeding/Applications/{AppPascal}/Modules/{ModuleCode}/ to mirror the per-application module layout.

`/dotnet-structure` development/backend

.NET Clean Architecture 4-layer SmartStack

### development/debug (6)

`/audit-bug` development/debug

Refine a user-reported bug — rephrase, classify, and cross-reference the code in the current worktree.

`/debug` development/debug

Diagnose and auto-fix SmartStack dev-runner issues (backend + frontend)

`/debug-backend` development/debug

Diagnose and auto-fix SmartStack .NET backend failures

`/debug-frontend` development/debug

Diagnose and auto-fix SmartStack React+Vite frontend failures

`/discuss-bug` development/debug

Conversational triage on a tracked bug — answer the user, decide whether to reopen the fix or re-audit, never modify code directly.

`/fix-bug` development/debug

Implement a fix for a user-reported bug — edit code, verify, commit atomically with a traceable message.

### development/frontend (7)

`/frontend-api-client` development/frontend

Generates TypeScript service clients + React Query hooks using smartstackClient (shared axios instance from @atlashub/smartstack npm package) and direct REST paths (/api/{module}/{plural}).

`/frontend-auth` development/frontend

Scaffold the per-project useAuth hook + PermissionGuard component

`/frontend-component` development/frontend

Generates React page components (list, detail, form) consuming @atlashub/smartstack npm package: PermissionGuard, Slot, SmartStackProvider. i18n keys are split per entity to prevent concurrent-generation overwrites.

`/frontend-extension-config` development/frontend

Generates ExtensionConfig (@atlashub/smartstack) with slot definitions that mirror the <Slot name="..."> calls emitted by frontend/component.

`/frontend-routes` development/frontend

Generates PageRegistry registrations for SmartStack's DB-driven routing (DynamicRouter). Validates componentKey format before emission and fails loud on bad specs rather than producing silent-spinner registries.

`/frontend-structure` development/frontend

React + Vite + Tailwind + SmartStack frontend structure (npm consumer of @atlashub/smartstack)

`/ui-polish` development/frontend

Audits and auto-fixes React pages in a generated SmartStack frontend against the customisation-ui design system standards (CSS variable tokens, PageTemplate wrapper, DataTable/EntityCard components, lucide-react icons, semantic badges, permission keys, i18n namespaces). Produces a violation report (audit mode) or applies mechanical fixes (apply mode) based on tokens.json. Invoked after Phase 4 of ba-develop to guarantee visual consistency with the reference app.

### development/run (3)

`/run` development/run

Kill orphans + launch backend + frontend, auto-retry on failure

`/run-backend` development/run

Kill stale .Api processes, launch dotnet run, verify /health — retry loop

`/run-frontend` development/run

Kill stale Vite, npm run dev, verify /, retry loop

### development/smoke-test (1)

`/smoke-test` development/smoke-test

Runtime smoke-test for a freshly-generated SmartStack.app project. Starts the backend (`dotnet run`) and the frontend (`npm run dev`) in the background, waits for both to become reachable, then probes every page route and every API endpoint scaffolded by the pipeline. Fails the run if ANY endpoint returns a 4xx/5xx status code or if any page is missing from disk. Designed to be the final gate of `ba-develop` so cross-stack drift surfaces in CI rather than at the user's first manual `npm run dev`.

### development/testing (3)

`/development-testing-fix-build` development/testing

Auto-correct a SINGLE compilation error surfaced by the Studio's Dev Runner (dotnet CS####, tsc TS####, vite resolve). The caller provides one `BuildError` with file/line/column/code/message. Your job is to apply the MINIMUM patch to make that specific error go away, without refactoring surrounding code. Invoked by `build-fix-runner.ts` in a retry loop (max 15 iterations, convergence guard, rebuild-and-reparse after each attempt).

`/development-testing-ui-test` development/testing

Phase 5 UI tests — drives dev-browser to navigate every scaffolded page, submit forms with role-based seeded users, and auto-correct failures via the existing fix-bug skill loop (max 50 iterations per test). Runs after the frontend scaffolders complete (routes + component + api-client + extension-config) and verifies the full backend ↔ frontend round-trip.

`/smoke-http` development/testing

HTTP smoke prober for generated SmartStack applications. Given a list of URLs (frontend routes + backend API endpoints), fetches each one, follows redirects, applies retry-on-startup, and returns a JSON report of 200/non-200 results. Invoked after Phase 4 of ba-develop to detect broken routes and missing API endpoints before the user ever sees a 404 in the browser.

### devFrontend (3)

`/audit-dev-frontend` devFrontend

Audit code generated by the Frontend phase against the PRD slice — page coverage, registry wiring, lazy-import integrity, i18n namespaces, drift detection

`/scaffold-layout` devFrontend

Scaffold the app-level layout shell (PageTemplate + AppShell) reading nav from /api/navigation/menu, honoring per-app branding via @customised marker.

`/scaffold-theme` devFrontend

Bootstrap src/index.css with Tailwind v4 + Shoelace token overrides + design tokens from the PRD theme slice (or SmartStack defaults). Idempotent overwrite.

### infrastructure (2)

`/ba-develop` infrastructure

Consumes a module's PRD on disk (`prd.md` + 3 phase slices + `pagespecs/*.md` under `.smartstack/ba/<APP>/<MODULE>/`) and drives development through 4 sequential phases (Core Foundation Seed → Entities → API → Frontend), each running as a subagent. Phase 0 is deterministic — the agent invokes scaffold-core-seed to write the per-app navigation + roles + permissions in one shot, eliminating the silent empty-module regression. Gates between phases verify compile + tests + per-module coverage before advancing. Invoked after `/ba-create-prd` + `/ba-audit-prd` (dev-ready GO, score ≥ 80).

`/ba-develop-plan` infrastructure

Orchestrates multi-module development across applications by executing the phased plan from /ba-create-plan-development. Reads dev-plan.json, runs a preflight check, then drives wave-by-wave execution: for each wave, launches one /ba-develop subagent per module (parallel within a wave), gates between waves (compile + tests for all modules), and reports unified results.

args: `[--waves 1,2]`
Agent Bash Read Glob Grep Skill