@atlashub/smartstack-cli 3.5.0 → 3.7.0

package/templates/skills/business-analyse/steps/step-05a-handoff.md

@@ -1,6 +1,6 @@
 ---
 name: step-05a-handoff
-description: Build handoff data - file mapping, BR-to-code, API summary - write to feature.json
+description: Build development handoff data, map business rules to code, write handoff to feature.json
 model: sonnet
 next_step: steps/step-05b-deploy.md
 ---
@@ -21,7 +21,7 @@ next_step: steps/step-05b-deploy.md
 
 ## YOUR TASK
 
-Build the development handoff data (file mapping, BR-to-code, API summary) and write it to EACH module feature.json AND master feature.json. This step focuses on DATA — artifacts (prd.json, progress.txt, HTML) are generated in step-05b.
+Build the development handoff data: verify consolidation, choose implementation strategy, calculate complexity, map specification to files (7 categories), map business rules to code, generate API endpoint summary, and write handoff to EACH module feature.json.
 
 ---
 
@@ -122,6 +122,26 @@ Example:
 
 For **EACH module** in topological order:
 
+> **PATH HIERARCHY CONVENTION:** All backend file paths MUST include the context and application hierarchy.
+> Derive from module feature.json metadata:
+> - `{ContextPascal}` = PascalCase of `metadata.context` (e.g., `"business"` → `"Business"`)
+> - `{ApplicationName}` = `metadata.application` (e.g., `"HumanResources"`)
+> - `{ModuleName}` = `metadata.module` (e.g., `"Projects"`)
+>
+> **Controller context-to-folder mapping (`{ContextShort}`):**
+> | metadata.context | Controller Folder |
+> |-----------------|-------------------|
+> | `business` | `Business` |
+> | `platform` | `Admin` |
+> | `personal` | `User` |
+>
+> **Example** for context=business, application=HumanResources, module=Projects:
+> - Domain: `src/Domain/Entities/Business/HumanResources/Projects/Project.cs`
+> - Application: `src/Application/Services/Business/HumanResources/Projects/ProjectService.cs`
+> - Infrastructure: `src/Infrastructure/Persistence/Configurations/Business/HumanResources/Projects/ProjectConfiguration.cs`
+> - API: `src/API/Controllers/Business/HumanResources/ProjectsController.cs`
+> - Tests: `src/Tests/Unit/Domain/Business/HumanResources/Projects/ProjectTests.cs`
+
 #### 4.1 Domain Files
 
 From `analysis.entities[]` of the module:
@@ -129,7 +149,7 @@ From `analysis.entities[]` of the module:
 ```json
 "domain": [
   {
-    "path": "src/Domain/Entities/{ModuleName}/{EntityName}.cs",
+    "path": "src/Domain/Entities/{ContextPascal}/{ApplicationName}/{ModuleName}/{EntityName}.cs",
     "type": "Entity",
     "linkedFRs": ["FR-001", "FR-002"],
     "linkedUCs": ["UC-001"],
@@ -139,9 +159,9 @@ From `analysis.entities[]` of the module:
 ```
 
 Include:
-- Value objects referenced by entities
-- Enums used in domain
-- Domain exceptions specific to module
+- Value objects referenced by entities (`src/Domain/Entities/{ContextPascal}/{ApplicationName}/{ModuleName}/{ValueObject}.cs`)
+- Enums used in domain (`src/Domain/Enums/{ContextPascal}/{ApplicationName}/{ModuleName}/{EnumName}.cs`)
+- Domain exceptions specific to module (`src/Domain/Exceptions/{ContextPascal}/{ApplicationName}/{ModuleName}/{ExceptionName}.cs`)
 
 #### 4.2 Application Files
 
@@ -150,20 +170,20 @@ From `analysis.useCases[]` of the module:
 ```json
 "application": [
   {
-    "path": "src/Application/Services/{ModuleName}/{ServiceName}Service.cs",
+    "path": "src/Application/Services/{ContextPascal}/{ApplicationName}/{ModuleName}/{ServiceName}Service.cs",
     "type": "Service",
     "linkedFRs": ["FR-001"],
     "linkedUCs": ["UC-001", "UC-002"],
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Application/DTOs/{ModuleName}/{DtoName}Dto.cs",
+    "path": "src/Application/DTOs/{ContextPascal}/{ApplicationName}/{ModuleName}/{DtoName}Dto.cs",
     "type": "Dto",
     "linkedUCs": ["UC-001"],
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Application/Validators/{ModuleName}/{ValidatorName}Validator.cs",
+    "path": "src/Application/Validators/{ContextPascal}/{ApplicationName}/{ModuleName}/{ValidatorName}Validator.cs",
     "type": "Validator",
     "linkedFRs": ["FR-001"],
     "module": "{moduleCode}"
@@ -184,24 +204,18 @@ From `analysis.entities[]` of the module:
 ```json
 "infrastructure": [
   {
-    "path": "src/Infrastructure/Repositories/{ModuleName}/{EntityName}Repository.cs",
-    "type": "Repository",
+    "path": "src/Infrastructure/Persistence/Configurations/{ContextPascal}/{ApplicationName}/{ModuleName}/{EntityName}Configuration.cs",
+    "type": "EFConfiguration",
     "linkedFRs": ["FR-001"],
     "module": "{moduleCode}"
-  },
-  {
-    "path": "src/Infrastructure/Persistence/{ModuleName}DbContext.cs",
-    "type": "DbContext",
-    "linkedFRs": ["FR-001", "FR-002"],
-    "module": "{moduleCode}"
   }
 ]
 ```
 
 Include:
-- Repository per entity
-- DbContext configuration (if module-specific)
-- Unit of Work pattern if applicable
+- EF Core configuration per entity (`Persistence/Configurations/{ContextPascal}/{ApplicationName}/{ModuleName}/`)
+- DbSet registration in `IExtensionsDbContext` / `ExtensionsDbContext`
+- DI registration in `DependencyInjection.cs`
 - Specifications if complex queries
 
 #### 4.4 API Files
@@ -211,7 +225,7 @@ From `specification.apiEndpoints[]` of the module:
 ```json
 "api": [
   {
-    "path": "src/API/Controllers/{ModuleName}Controller.cs",
+    "path": "src/API/Controllers/{ContextShort}/{ApplicationName}/{EntityName}Controller.cs",
     "type": "ApiController",
     "linkedUCs": ["UC-001", "UC-002"],
     "linkedFRs": ["FR-001"],
@@ -220,6 +234,8 @@ From `specification.apiEndpoints[]` of the module:
 ]
 ```
 
+> **Context-to-folder mapping (`{ContextShort}`):** `business` → `Business`, `platform` → `Admin`, `personal` → `User`
+
 Include:
 - One controller per domain aggregate root (or logical grouping)
 - Include all HTTP methods (GET, POST, PUT, DELETE, PATCH)
@@ -415,26 +431,26 @@ Business categories (from specification.seedDataBusiness):
 ```json
 "tests": [
   {
-    "path": "src/Tests/Unit/Domain/{ModuleName}/{Entity}Tests.cs",
+    "path": "src/Tests/Unit/Domain/{ContextPascal}/{ApplicationName}/{ModuleName}/{Entity}Tests.cs",
     "type": "UnitTests",
     "linkedFRs": ["FR-001"],
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Tests/Unit/Application/{ModuleName}/{ServiceName}ServiceTests.cs",
+    "path": "src/Tests/Unit/Application/{ContextPascal}/{ApplicationName}/{ModuleName}/{ServiceName}ServiceTests.cs",
     "type": "UnitTests",
     "linkedFRs": ["FR-001"],
     "linkedUCs": ["UC-001"],
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Tests/Integration/{ModuleName}/{ApiControllerName}ControllerTests.cs",
+    "path": "src/Tests/Integration/{ContextPascal}/{ApplicationName}/{ModuleName}/{ApiControllerName}ControllerTests.cs",
     "type": "IntegrationTests",
     "linkedUCs": ["UC-001"],
     "module": "{moduleCode}"
   },
   {
-    "path": "src/Tests/Security/{ModuleName}/{ModuleName}SecurityTests.cs",
+    "path": "src/Tests/Security/{ContextPascal}/{ApplicationName}/{ModuleName}/{ModuleName}SecurityTests.cs",
     "type": "SecurityTests",
     "linkedFRs": ["FR-001"],
     "module": "{moduleCode}"
@@ -595,17 +611,18 @@ Total endpoints = count of specification.apiEndpoints[] across all modules.
 #### 7a. Module Handoff Loop (MANDATORY)
 
 > **STRUCTURE CARD: handoff** — Field names are EXACT. Include ALL fields below.
+> **PATH RULE:** All backend paths MUST include `{ContextPascal}/{ApplicationName}/` hierarchy (see section 4).
 > ```json
 > {
 >   "complexity": "simple|medium|complex",
 >   "filesToCreate": {
->     "domain": [{"path": "...", "type": "Entity|ValueObject|Enum", "linkedFRs": [], "linkedUCs": [], "module": "..."}],
->     "application": [{"path": "...", "type": "Service|Dto|Validator", "linkedFRs": [], "linkedUCs": [], "module": "..."}],
->     "infrastructure": [{"path": "...", "type": "Repository|DbContext", "linkedFRs": [], "module": "..."}],
->     "api": [{"path": "...", "type": "ApiController", "linkedUCs": [], "linkedFRs": [], "module": "..."}],
->     "frontend": [{"path": "...", "type": "Page|Component|Hook|DashboardPage", "linkedUCs": [], "linkedWireframes": [], "module": "..."}],
->     "seedData": [{"path": "...", "type": "HasData", "category": "core|business", "source": "...", "module": "..."}],
->     "tests": [{"path": "...", "type": "UnitTests|IntegrationTests|SecurityTests", "linkedFRs": [], "linkedUCs": [], "module": "..."}]
+>     "domain": [{"path": "src/Domain/Entities/{Ctx}/{App}/{Mod}/{Entity}.cs", "type": "Entity|ValueObject|Enum", "linkedFRs": [], "linkedUCs": [], "module": "..."}],
+>     "application": [{"path": "src/Application/Services/{Ctx}/{App}/{Mod}/{Svc}Service.cs", "type": "Service|Dto|Validator", "linkedFRs": [], "linkedUCs": [], "module": "..."}],
+>     "infrastructure": [{"path": "src/Infrastructure/Persistence/Configurations/{Ctx}/{App}/{Mod}/{Entity}Configuration.cs", "type": "EFConfiguration", "linkedFRs": [], "module": "..."}],
+>     "api": [{"path": "src/API/Controllers/{CtxShort}/{App}/{Entity}Controller.cs", "type": "ApiController", "linkedUCs": [], "linkedFRs": [], "module": "..."}],
+>     "frontend": [{"path": "src/pages/{Mod}/{Page}Page.tsx", "type": "Page|Component|Hook|DashboardPage", "linkedUCs": [], "linkedWireframes": [], "module": "..."}],
+>     "seedData": [{"path": "src/Infrastructure/Persistence/Seeding/Data/{Mod}/...SeedData.cs", "type": "SeedData", "category": "core|business", "source": "...", "module": "..."}],
+>     "tests": [{"path": "src/Tests/Unit/Domain/{Ctx}/{App}/{Mod}/{Entity}Tests.cs", "type": "UnitTests|IntegrationTests|SecurityTests", "linkedFRs": [], "linkedUCs": [], "module": "..."}]
 >   },
 >   "brToCodeMapping": [{"ruleId": "BR-...", "files": ["path1", "path2"], "implementation": "description"}],
 >   "apiEndpointSummary": [{"method": "GET|POST|PUT|DELETE", "path": "/api/...", "permission": "business.{app}.{module}.{action}", "linkedUC": "UC-..."}],
@@ -625,10 +642,10 @@ Total endpoints = count of specification.apiEndpoints[] across all modules.
 2. moduleFeatureId = modules[i].featureJsonPath or find via ba-reader.findFeature()
 3. Read the module feature.json via ba-reader.findFeature(moduleFeatureId)
 4. Build the handoff payload for THIS module:
-   - complexity (from step 3 calculation)
-   - filesToCreate (full 7-category structure from step 4, filtered for this module)
-   - brToCodeMapping (from step 5, filtered for this module)
-   - apiEndpointSummary (from step 6, filtered for this module)
+   - complexity (from section 3 calculation)
+   - filesToCreate (full 7-category structure from section 4, filtered for this module)
+   - brToCodeMapping (from section 5, filtered for this module)
+   - apiEndpointSummary (from section 6, filtered for this module)
    - prdFile path
    - totalFiles count
    - totalTasks count
@@ -696,29 +713,32 @@ FOR each module in modules[]:
 IF count < modules.length:
   → BLOCKING ERROR: {modules.length - count} modules missing handoff
   → List the missing modules by name
-  → DO NOT proceed to step 10
-  → Return to 9a for missing modules only
+  → DO NOT proceed to step-05b
+  → Return to 7a for missing modules only
 
 IF count === modules.length:
   ba-writer.updateStatus({feature_id}, "handed-off")
   Display: "✓ Handoff complet: {count}/{modules.length} modules avec handoff valide"
 ```
 
-Status journey: analyze → consolidate → **handed-off**
+Status journey: analyze → consolidate → handed-off
 
 ---
 
-## SELF-VERIFICATION (MANDATORY before loading step-05b)
+## SELF-VERIFICATION
 
 Before proceeding to step-05b-deploy.md, VERIFY:
 
-1. **ALL module feature.json** have `handoff` section with 7 categories in `filesToCreate` (domain, application, infrastructure, api, frontend, seedData, tests)
-2. **ALL module feature.json** have `handoff.brToCodeMapping.length > 0`
-3. **ALL module feature.json** status = "handed-off"
-4. **Master feature.json** has `handoff` section with implementationStrategy, moduleOrder, totalFilesToCreate
-5. **Master status** = "handed-off"
+1. **filesToCreate** has all 7 categories populated (domain, application, infrastructure, api, frontend, seedData, tests) for each module
+2. **Complexity** calculated for all modules
+3. **Implementation strategy** chosen (for multi-module features)
+4. **ALL module feature.json** have `handoff.brToCodeMapping.length > 0`
+5. **ALL module feature.json** have `handoff.apiEndpointSummary.length > 0`
+6. **ALL module feature.json** status = "handed-off"
+7. **Master feature.json** has `handoff` section with implementationStrategy, moduleOrder, totalFilesToCreate
+8. **Master status** = "handed-off"
 
-**IF any check fails → FIX before proceeding.** Do NOT generate artifacts (prd.json, progress.txt) without complete handoff data.
+**IF any check fails → FIX before proceeding.**
 
 ---