@atlashub/smartstack-cli 2.2.0 → 2.4.0

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

@@ -0,0 +1,1119 @@
+---
+name: step-05-handoff
+description: Development handoff - file mapping, BR-to-code, API endpoints, prd.json, progress tracker
+model: sonnet
+next_step: null
+---
+
+# Step 5: Handoff
+
+## MANDATORY EXECUTION RULES
+
+- **ALWAYS** verify status = "consolidated" before proceeding
+- **ALWAYS** ask user for implementation strategy preference (multi-module only)
+- **ALWAYS** derive prd.json from feature.json (NEVER independently)
+- **NEVER** invent entities/FRs/BRs not in feature.json
+- **ALL** API routes from specification.apiEndpoints (exact copy)
+- **Permission** paths from specification.permissionMatrix (full format)
+- **ALWAYS** generate 5 CORE SeedData task entries per module
+
+## YOUR TASK
+
+Generate the development handoff package: file mapping, BR-to-code mapping, API endpoint summary, prd.json, and progress tracker. For multi-module applications, support both per-module and consolidated handoff approaches.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Verify Consolidation Passed
+
+Use ba-reader to locate the feature and verify consolidation status:
+
+```
+ba-reader.findFeature({feature_id})
+→ Check status = "consolidated"
+```
+
+**IF** status ≠ "consolidated" → **STOP**. Return to step-04-consolidation.md.
+
+Display validation summary:
+
+```
+✓ Consolidation: APPROVED
+✓ Modules: {count} specified and validated
+✓ Cross-module: interactions mapped
+✓ Permissions: coherent
+→ Proceeding to handoff...
+```
+
+Include:
+- Number of modules
+- Number of entities across all modules
+- Number of use cases across all modules
+- Number of business rules across all modules
+- Cross-module interaction count
+
+---
+
+### 2. Implementation Strategy Choice (Multi-Module)
+
+**IF** more than 1 module defined in feature.json:
+
+Ask via AskUserQuestion:
+
+```
+question: "Quelle stratégie d'implémentation préférez-vous ?"
+header: "Stratégie d'implémentation"
+options:
+  - label: "Module par module (Recommandé)"
+    description: "Implémenter chaque module complètement avant de passer au suivant. Suit l'ordre topologique des dépendances."
+  - label: "Couche par couche"
+    description: "Implémenter toutes les entités, puis tous les services, puis tous les contrôleurs, etc. Plus de parallélisation possible mais plus complexe."
+  - label: "Hybride"
+    description: "Modules fondation en premier (couche par couche), puis modules dépendants (module par module)"
+```
+
+Store the chosen strategy in `handoff.implementationStrategy`.
+
+**IF** only 1 module → default to "Module par module" (no choice needed).
+
+---
+
+### 3. Calculate Complexity
+
+For each module in feature.json.modules[], calculate:
+
+```json
+{
+  "complexity": "simple|medium|complex",
+  "complexityDetails": {
+    "entities": {count},
+    "useCases": {count},
+    "businessRules": {count},
+    "calculated": "{level} (≤X entities, ≤Y UCs, ≤Z BRs)"
+  }
+}
+```
+
+| Criteria | Simple | Medium | Complex |
+|----------|--------|--------|---------|
+| Entities | ≤3 | ≤6 | >6 |
+| Use Cases | ≤5 | ≤12 | >12 |
+| Business Rules | ≤10 | ≤20 | >20 |
+
+**Global complexity** = highest complexity across all modules.
+
+Example:
+- Module A: 4 entities, 6 use cases, 8 BRs → **simple**
+- Module B: 8 entities, 15 use cases, 25 BRs → **complex**
+- Overall: **complex**
+
+---
+
+### 4. Map Specification to Files
+
+> **IMPORTANT:** Generate `handoff.filesToCreate` as structured object with 7 categories.
+> Each file entry is `{path, type, linkedFRs, linkedUCs, module}`. NO free text.
+> Read `.smartstack/config.json` to extract baseNamespace for project namespace.
+
+**Order by topological dependency** (modules with no deps first, then dependents).
+
+For **EACH module** in topological order:
+
+#### 4.1 Domain Files
+
+From `analysis.entities[]` of the module:
+
+```json
+"domain": [
+  {
+    "path": "src/Domain/Entities/{ModuleName}/{EntityName}.cs",
+    "type": "Entity",
+    "linkedFRs": ["FR-001", "FR-002"],
+    "linkedUCs": ["UC-001"],
+    "module": "{moduleCode}"
+  }
+]
+```
+
+Include:
+- Value objects referenced by entities
+- Enums used in domain
+- Domain exceptions specific to module
+
+#### 4.2 Application Files
+
+From `analysis.useCases[]` of the module:
+
+```json
+"application": [
+  {
+    "path": "src/Application/Services/{ModuleName}/{ServiceName}Service.cs",
+    "type": "Service",
+    "linkedFRs": ["FR-001"],
+    "linkedUCs": ["UC-001", "UC-002"],
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Application/DTOs/{ModuleName}/{DtoName}Dto.cs",
+    "type": "Dto",
+    "linkedUCs": ["UC-001"],
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Application/Validators/{ModuleName}/{ValidatorName}Validator.cs",
+    "type": "Validator",
+    "linkedFRs": ["FR-001"],
+    "module": "{moduleCode}"
+  }
+]
+```
+
+Include:
+- Service per use case cluster (or per domain entity if applicable)
+- DTOs for API contracts
+- Validators for FluentValidation
+- Query handlers
+
+#### 4.3 Infrastructure Files
+
+From `analysis.entities[]` of the module:
+
+```json
+"infrastructure": [
+  {
+    "path": "src/Infrastructure/Repositories/{ModuleName}/{EntityName}Repository.cs",
+    "type": "Repository",
+    "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
+- Specifications if complex queries
+
+#### 4.4 API Files
+
+From `specification.apiEndpoints[]` of the module:
+
+```json
+"api": [
+  {
+    "path": "src/API/Controllers/{ModuleName}Controller.cs",
+    "type": "ApiController",
+    "linkedUCs": ["UC-001", "UC-002"],
+    "linkedFRs": ["FR-001"],
+    "module": "{moduleCode}"
+  }
+]
+```
+
+Include:
+- One controller per domain aggregate root (or logical grouping)
+- Include all HTTP methods (GET, POST, PUT, DELETE, PATCH)
+- Error handling and validation responses
+
+#### 4.5 Frontend Files
+
+From `specification.wireframes[]` and `analysis.useCases[]` of the module:
+
+```json
+"frontend": [
+  {
+    "path": "src/pages/{ModuleName}/{PageName}Page.tsx",
+    "type": "Page",
+    "linkedUCs": ["UC-001", "UC-002"],
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/components/{ModuleName}/{ComponentName}.tsx",
+    "type": "Component",
+    "linkedUCs": ["UC-001"],
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/hooks/use{ModuleName}{Hook}.ts",
+    "type": "Hook",
+    "linkedUCs": ["UC-001", "UC-002"],
+    "module": "{moduleCode}"
+  }
+]
+```
+
+Include:
+- Pages for major use cases
+- Components for reusable UI elements
+- Custom hooks for business logic
+- Forms for data entry
+- List/Detail views
+
+#### 4.6 SeedData Files
+
+**OBLIGATORY:** 5 CORE SeedData entries per module + business seed data:
+
+```json
+"seedData": [
+  {
+    "path": "src/Infrastructure/Data/SeedData/{ModuleName}/NavigationModuleConfiguration.cs",
+    "type": "HasData",
+    "category": "core",
+    "source": "specification.seedDataCore.navigationModules",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Data/SeedData/{ModuleName}/PermissionsConfiguration.cs",
+    "type": "HasData",
+    "category": "core",
+    "source": "specification.seedDataCore.permissions",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Data/SeedData/{ModuleName}/RolesConfiguration.cs",
+    "type": "HasData",
+    "category": "core",
+    "source": "specification.seedDataCore.roles",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Data/SeedData/{ModuleName}/TenantConfiguration.cs",
+    "type": "HasData",
+    "category": "core",
+    "source": "specification.seedDataCore.tenants",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Data/SeedData/{ModuleName}/UserConfiguration.cs",
+    "type": "HasData",
+    "category": "core",
+    "source": "specification.seedDataCore.users",
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Infrastructure/Data/SeedData/{ModuleName}/{Entity}SeedData.cs",
+    "type": "HasData",
+    "category": "business",
+    "source": "specification.seedDataBusiness.{module}",
+    "module": "{moduleCode}"
+  }
+]
+```
+
+Core categories (ALWAYS 5):
+1. NavigationModuleConfiguration (navigation items for module)
+2. PermissionsConfiguration (RBAC permissions)
+3. RolesConfiguration (roles using permissions)
+4. TenantConfiguration (test tenants)
+5. UserConfiguration (test users)
+
+Business categories (from specification.seedDataBusiness):
+- Domain-specific reference data
+- Test data fixtures
+- Lookup tables (statuses, categories, etc.)
+
+#### 4.7 Test Files
+
+```json
+"tests": [
+  {
+    "path": "src/Tests/Unit/Domain/{ModuleName}/{Entity}Tests.cs",
+    "type": "UnitTests",
+    "linkedFRs": ["FR-001"],
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Tests/Unit/Application/{ModuleName}/{ServiceName}ServiceTests.cs",
+    "type": "UnitTests",
+    "linkedFRs": ["FR-001"],
+    "linkedUCs": ["UC-001"],
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Tests/Integration/{ModuleName}/{ApiControllerName}ControllerTests.cs",
+    "type": "IntegrationTests",
+    "linkedUCs": ["UC-001"],
+    "module": "{moduleCode}"
+  },
+  {
+    "path": "src/Tests/Security/{ModuleName}/{ModuleName}SecurityTests.cs",
+    "type": "SecurityTests",
+    "linkedFRs": ["FR-001"],
+    "module": "{moduleCode}"
+  }
+]
+```
+
+Test files:
+- Unit tests for domain entities and value objects
+- Unit tests for services and validators
+- Integration tests for API endpoints
+- Security tests for authorization and tenant isolation
+- E2E tests for critical user flows
+
+---
+
+### 5. Map Business Rules to Code
+
+Derive from `analysis.businessRules[]` of **EACH module**.
+
+Generate complete mapping for each BR:
+
+```json
+{
+  "brToCodeMapping": [
+    {
+      "ruleId": "BR-VAL-001",
+      "title": "Order total must equal sum of item prices",
+      "module": "{moduleCode}",
+      "severity": "critical",
+      "implementationPoints": [
+        {
+          "layer": "Domain",
+          "component": "Order.cs",
+          "method": "CalculateTotal()",
+          "implementation": "Validate sum equals sum of OrderItems.Price"
+        },
+        {
+          "layer": "Application",
+          "component": "CreateOrderService.cs",
+          "method": "Handle()",
+          "implementation": "Calculate total before persisting"
+        },
+        {
+          "layer": "API",
+          "component": "OrdersController.cs",
+          "method": "CreateOrder()",
+          "implementation": "Return validation error if total mismatch"
+        },
+        {
+          "layer": "Frontend",
+          "component": "OrderForm.tsx",
+          "method": "calculateTotal()",
+          "implementation": "Real-time calculation on item change"
+        }
+      ]
+    },
+    {
+      "ruleId": "BR-SEC-002",
+      "title": "User can only view orders from their tenant",
+      "module": "{moduleCode}",
+      "severity": "critical",
+      "implementationPoints": [
+        {
+          "layer": "Domain",
+          "component": "Order.cs",
+          "method": "Validate()",
+          "implementation": "Check TenantId matches user context"
+        },
+        {
+          "layer": "Infrastructure",
+          "component": "OrderRepository.cs",
+          "method": "GetUserOrders()",
+          "implementation": "Filter by TenantId in WHERE clause"
+        },
+        {
+          "layer": "API",
+          "component": "OrdersController.cs",
+          "method": "GetOrders()",
+          "implementation": "Enforce permission check + tenant filter"
+        }
+      ]
+    }
+  ]
+}
+```
+
+For each BR include:
+- **ruleId**: Reference to analysis.businessRules[].id
+- **title**: The rule statement
+- **module**: Which module it belongs to
+- **severity**: "critical", "high", "medium", "low"
+- **implementationPoints**: Array of {layer, component, method, implementation}
+
+Layers: Domain, Application, Infrastructure, API, Frontend
+
+---
+
+### 6. API Endpoint Summary
+
+> **ABSOLUTE RULE:** Copy **EXACTLY** from `specification.apiEndpoints[]`. **NEVER** reinvent routes.
+
+Generate summary with full details:
+
+```json
+{
+  "apiEndpointSummary": [
+    {
+      "operation": "ListOrders",
+      "method": "GET",
+      "route": "/api/business/orders",
+      "linkedUC": "UC-001",
+      "linkedFR": "FR-001",
+      "permissions": ["business.orders.read"],
+      "requestSchema": { "type": "query", "params": ["pageNumber", "pageSize", "status"] },
+      "responseSchema": { "type": "PaginatedOrderDto[]" },
+      "errorCodes": [401, 403, 400, 500],
+      "module": "{moduleCode}"
+    },
+    {
+      "operation": "CreateOrder",
+      "method": "POST",
+      "route": "/api/business/orders",
+      "linkedUC": "UC-002",
+      "linkedFR": "FR-002",
+      "permissions": ["business.orders.create"],
+      "requestSchema": { "type": "body", "schema": "CreateOrderDto" },
+      "responseSchema": { "type": "OrderDto" },
+      "errorCodes": [400, 401, 403, 422, 500],
+      "module": "{moduleCode}"
+    }
+  ]
+}
+```
+
+For each endpoint:
+- **operation**: Use case name or operation name
+- **method**: HTTP method (GET, POST, PUT, DELETE, PATCH)
+- **route**: Full API path from specification
+- **linkedUC**: Use case ID(s) this endpoint implements
+- **linkedFR**: Feature requirement ID(s)
+- **permissions**: Array of exact permission paths
+- **requestSchema**: Input contract (query params or body)
+- **responseSchema**: Output contract
+- **errorCodes**: Expected HTTP error codes
+- **module**: Which module
+
+Total endpoints = count of specification.apiEndpoints[] across all modules.
+
+---
+
+### 7. Generate prd.json
+
+> **FUNDAMENTAL RULE:** prd.json is **DERIVED** from feature.json, **NEVER** generated independently.
+
+**For multi-module, ask user:**
+
+```
+question: "Comment souhaitez-vous structurer le prd.json ?"
+header: "Structure PRD"
+options:
+  - label: "Un par module (Recommandé)"
+    description: "Chaque module a son propre prd.json (.ralph/prd-{module}.json). Plus facile à suivre individuellement."
+  - label: "Consolidé"
+    description: "Un seul prd.json (.ralph/prd.json) avec tous les modules. Vue d'ensemble unique."
+```
+
+**For single-module**, default to single prd.json at `.ralph/prd.json`.
+
+**prd.json structure (per module or consolidated):**
+
+```json
+{
+  "prd": {
+    "version": "2.0.0",
+    "source": {
+      "type": "ba-handoff",
+      "feature_json": "path/to/feature.json",
+      "step": "step-05-handoff",
+      "timestamp": "2026-02-02T14:30:00Z"
+    },
+    "metadata": {
+      "title": "Product Requirements Document - {application} {module}",
+      "status": "handed-off",
+      "createdBy": "business-analyse skill v4.0",
+      "createdAt": "2026-02-02T14:30:00Z"
+    },
+    "project": {
+      "name": "...",
+      "application": "...",
+      "module": "... (or omit for consolidated)",
+      "namespace": "From .smartstack/config.json.baseNamespace"
+    },
+    "overview": {
+      "summary": "From feature.json.specification.overview.summary",
+      "businessGoals": ["Goal 1", "Goal 2"],
+      "stakeholders": ["Stakeholder 1"],
+      "constraints": "From feature.json.specification.overview.constraints"
+    },
+    "requirements": {
+      "functional": {
+        "useCases": [
+          {
+            "id": "UC-001",
+            "title": "...",
+            "description": "...",
+            "actors": ["..."],
+            "steps": "...step 1, step 2...",
+            "postconditions": "..."
+          }
+        ],
+        "features": [
+          {
+            "id": "FR-001",
+            "title": "...",
+            "description": "...",
+            "priority": "must | should | could",
+            "linkedUCs": ["UC-001"]
+          }
+        ]
+      },
+      "nonFunctional": {
+        "performance": "...",
+        "security": "...",
+        "scalability": "...",
+        "usability": "..."
+      }
+    },
+    "businessRules": [
+      {
+        "id": "BR-VAL-001",
+        "title": "...",
+        "description": "...",
+        "type": "validation | constraint | calculation | security",
+        "severity": "critical | high | medium | low",
+        "implementedIn": ["Domain.Order", "API.OrdersController"]
+      }
+    ],
+    "architecture": {
+      "entities": [
+        {
+          "name": "...",
+          "description": "...",
+          "properties": ["prop1: string", "prop2: int"],
+          "relationships": ["Order → Customer", "Order → OrderItems"],
+          "linkedFR": "FR-001"
+        }
+      ],
+      "apiEndpoints": [
+        {
+          "method": "GET",
+          "route": "/api/business/orders",
+          "operation": "ListOrders",
+          "permissions": ["business.orders.read"],
+          "linkedUC": "UC-001"
+        }
+      ],
+      "permissionMatrix": [
+        {
+          "role": "OrderManager",
+          "permissions": ["business.orders.read", "business.orders.create"],
+          "description": "Can view and create orders"
+        }
+      ],
+      "dataModels": "From specification.dataModels"
+    },
+    "implementation": {
+      "strategy": "module-by-module | layer-by-layer | hybrid",
+      "moduleOrder": ["Module1", "Module2", "Module3"],
+      "dependencyOrder": "Topologically ordered based on feature.json.modules[].dependencies",
+      "taskBreakdown": {
+        "domain": "X tasks across entities, value objects, domain logic",
+        "application": "Y tasks across services, DTOs, validators",
+        "infrastructure": "Z tasks across repositories, persistence",
+        "api": "A tasks across controllers, error handling",
+        "frontend": "B tasks across pages, components, hooks",
+        "seedData": "5 CORE + C business seed data tasks",
+        "tests": "D unit + E integration + F security tests",
+        "i18n": "G i18n key implementations"
+      },
+      "totalTasks": "X + Y + Z + A + B + (5 + C) + (D + E + F) + G",
+      "fileMapping": "See handoff.filesToCreate structured object"
+    },
+    "testing": {
+      "unitTests": [
+        {
+          "component": "Domain.Order",
+          "scenarios": ["Valid order creation", "Invalid total rejection"],
+          "coverage": "95%"
+        }
+      ],
+      "integrationTests": [
+        {
+          "endpoint": "POST /api/business/orders",
+          "scenarios": ["Happy path", "Validation failure", "Authorization failure"],
+          "coverage": "90%"
+        }
+      ],
+      "e2eTests": [
+        {
+          "userFlow": "Create Order → View Details → Update Status",
+          "coverage": "End-to-end"
+        }
+      ],
+      "testStrategy": "From specification.testing"
+    },
+    "i18n": {
+      "keys": [
+        {
+          "key": "orders.list.title",
+          "defaultValue": "Orders",
+          "usedIn": ["OrdersPage.tsx"],
+          "linkedUC": "UC-001"
+        }
+      ],
+      "locales": ["fr", "en", "it", "de"],
+      "translationStatus": "From specification.i18n.locales"
+    },
+    "seedData": {
+      "core": {
+        "navigationModules": "Module navigation structure",
+        "permissions": "Role-based permissions",
+        "roles": "Predefined roles",
+        "tenants": "Test tenants",
+        "users": "Test users"
+      },
+      "business": [
+        {
+          "entity": "OrderStatus",
+          "samples": ["Pending", "Confirmed", "Shipped", "Delivered"],
+          "source": "specification.seedDataBusiness"
+        }
+      ]
+    },
+    "risks": "From feature.json.risks (if present)",
+    "schedule": "Estimated based on complexity and strategy"
+  }
+}
+```
+
+**Key rules for prd.json:**
+- Source MUST reference feature.json (traceability)
+- All use cases, features, and business rules come from feature.json
+- API endpoints are EXACT copy from specification.apiEndpoints
+- Module order follows topological dependency order
+- Task breakdown based on filesToCreate count
+- Everything is **derived**, not invented
+
+---
+
+### 8. Initialize Progress Tracker
+
+Generate `.ralph/progress.txt` as main task tracker:
+
+```
+═════════════════════════════════════════════════════════════════
+  SMARTSTACK RALPH LOOP - PROGRESS TRACKER
+  Project: {project_name} | Application: {app_name}
+  Modules: {count} ({moduleOrder.join(', ')})
+  Strategy: {implementation_strategy}
+  Created: {timestamp}
+  Status: HANDED-OFF
+═════════════════════════════════════════════════════════════════
+
+{For each module in topological order:}
+[MODULE: {module_name}] ({complexity})
+  Status: NOT STARTED
+  Dependencies: {list of module dependencies or "FOUNDATION"}
+
+  [DOMAIN] Entity & Value Object Definitions
+    □ Define {Entity1} entity with properties and validation
+    □ Define {Entity2} entity with relationships
+    □ Define {ValueObject1} value object
+    □ Define domain exceptions
+    □ Total: X tasks
+
+  [SEEDDATA-CORE] Core Configuration (MANDATORY)
+    □ NavigationModuleConfiguration - Module navigation structure
+    □ PermissionsConfiguration - RBAC permissions setup
+    □ RolesConfiguration - Predefined roles
+    □ TenantConfiguration - Test tenants
+    □ UserConfiguration - Test users
+    Total: 5 CORE tasks
+
+  [SEEDDATA] Business Reference Data
+    □ Seed {Entity1} reference data
+    □ Seed {Entity2} lookup values
+    □ Total: Y business seed tasks
+
+  [APPLICATION] Services & Business Logic
+    □ Create {ServiceName}Service for {UC1}
+    □ Create {DtoName}Dto for API contracts
+    □ Create {ValidatorName}Validator for input validation
+    □ Implement query handlers
+    Total: Z tasks
+
+  [INFRASTRUCTURE] Repositories & Persistence
+    □ Create {Entity1}Repository with CRUD + custom queries
+    □ Create {Entity2}Repository
+    □ Configure DbContext for module
+    □ Setup specifications for complex queries
+    Total: A tasks
+
+  [API] REST Endpoints & Controllers
+    □ Create {ModuleNameController} GET endpoints (List, GetById)
+    □ Create {ModuleNameController} POST endpoint (Create)
+    □ Create {ModuleNameController} PUT endpoint (Update)
+    □ Create {ModuleNameController} DELETE endpoint (Delete)
+    □ Implement error handling and validation responses
+    Total: B tasks
+
+  [FRONTEND] UI Components & Pages
+    □ Create {ModuleName}Page for listing
+    □ Create {ModuleName}DetailPage for viewing
+    □ Create {ModuleName}Form component for creation/edit
+    □ Create custom hook use{ModuleName}
+    □ Implement pagination, filtering, sorting
+    Total: C tasks
+
+  [I18N] Internationalization Keys
+    □ Define i18n keys for {Module} UI labels
+    □ Setup translations for locales: fr, en, it, de
+    Total: D keys
+
+  [TESTS] Unit & Integration Tests
+    □ Unit tests for {Entity} domain logic
+    □ Unit tests for {ServiceName}Service
+    □ Integration tests for {ModuleNameController}
+    □ Security tests for authorization & tenant isolation
+    □ E2E tests for critical user flows
+    Total: E unit + F integration + G security = H tests
+
+  [QA] Quality Assurance
+    □ Code review against SmartStack conventions
+    □ Test coverage minimum 80%
+    □ Security scan for OWASP vulnerabilities
+    □ Performance testing under load
+    Total: 4 QA tasks
+
+  Module Total: X + 5 + Y + Z + A + B + C + D + H + 4 = {module_total} tasks
+  Estimated Effort: {simple/medium/complex} - {1-3/3-8/8-15} days
+
+{If multi-module:}
+[CROSS-MODULE] Integration Tasks
+  Status: NOT STARTED
+  Dependencies: All modules COMPLETED
+
+  □ Verify cross-module entity relationships
+  □ Test cross-module API dependencies
+  □ Validate permission matrix across modules
+  □ E2E flow tests spanning multiple modules
+  □ Cross-module data consistency checks
+  □ Integration test suite for module interactions
+  Total: 6 CROSS-MODULE tasks
+
+═════════════════════════════════════════════════════════════════
+SUMMARY
+═════════════════════════════════════════════════════════════════
+Total Modules:         {count}
+Total Tasks:           {total_count}
+  - CORE SeedData:     {count} × 5 = {total_core}
+  - Business Tasks:    {total_biz}
+  - Development:       {total_dev}
+  - Tests:             {total_tests}
+  - QA:                {total_qa}
+  - Cross-Module:      {cross_module_count or 0}
+
+Strategy:              {strategy}
+Module Order:          {topological order with dependencies noted}
+
+Complexity Distribution:
+  Simple:   {count} modules ({estimate} days each)
+  Medium:   {count} modules ({estimate} days each)
+  Complex:  {count} modules ({estimate} days each)
+
+Total Effort Estimate:  {total_days} days ({total_hours} hours)
+Per Developer (2):      {total_days / 2} days
+Parallel Potential:     {strategy_efficiency_percent}%
+
+═════════════════════════════════════════════════════════════════
+LEGEND
+═════════════════════════════════════════════════════════════════
+□ = Task not started
+✓ = Task completed
+⚠ = Task in progress
+✗ = Task failed / blocked
+
+COLORS:
+[DOMAIN]      = Domain Model & Business Logic
+[SEEDDATA-CORE] = MANDATORY core configuration (5 entries)
+[SEEDDATA]    = Business reference & lookup data
+[APPLICATION] = Services, DTOs, Validators
+[INFRASTRUCTURE] = Repositories, DbContext, ORM
+[API]         = REST controllers & endpoints
+[FRONTEND]    = React pages, components, hooks
+[I18N]        = Internationalization
+[TESTS]       = Unit, Integration, Security, E2E
+[QA]          = Code quality, coverage, security
+[CROSS-MODULE] = Multi-module integration (if applicable)
+
+═════════════════════════════════════════════════════════════════
+```
+
+**Progress Tracker Rules:**
+- One section per module, in topological order (dependencies first)
+- CORE SeedData ALWAYS 5 entries (mandatory)
+- Business SeedData varies by module
+- Hierarchical task structure (module → layer → tasks)
+- Each task is independent, assignable checkbox
+- Effort estimate per module (simple/medium/complex)
+- Summary with totals across all modules
+- Identified dependencies for parallel execution
+- Cross-module tasks only if multi-module
+
+---
+
+### 9. Write Handoff to Feature.json
+
+Update feature.json with handoff data via ba-writer.
+
+**Application-level (master/root feature):**
+
+```
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "handoff",
+  data: {
+    status: "handed-off",
+    complexity: "{simple|medium|complex}",
+    implementationStrategy: "{strategy}",
+    moduleCount: {count},
+    moduleOrder: [...],
+    totalFilesToCreate: {count},
+    totalTasks: {count},
+    prdStructure: "per-module | consolidated",
+    prdFiles: [
+      { module: "Orders", path: ".ralph/prd-orders.json" },
+      { module: "Customers", path: ".ralph/prd-customers.json" }
+    ],
+    progressTrackerPath: ".ralph/progress.txt",
+    handedOffAt: "2026-02-02T14:30:00Z"
+  }
+})
+```
+
+**Module-level (each feature.json in modules[] with corresponding module feature):**
+
+```
+ba-writer.enrichSection({
+  featureId: {module_feature_id},
+  section: "handoff",
+  data: {
+    status: "handed-off",
+    complexity: "{simple|medium|complex}",
+    filesToCreate: {...}, // Full 7-category structure from step 4
+    brToCodeMapping: [...],  // Full mapping from step 5
+    apiEndpointSummary: [...], // Full summary from step 6
+    prdFile: ".ralph/prd-{module}.json | .ralph/prd.json (if consolidated)",
+    totalFiles: {count},
+    totalTasks: {count},
+    handedOffAt: "2026-02-02T14:30:00Z"
+  }
+})
+```
+
+**Update status:**
+
+```
+ba-writer.updateStatus({
+  featureId: {feature_id},
+  status: "handed-off"
+})
+```
+
+Status journey: analyze → consolidate → **handed-off**
+
+---
+
+### 10. User Choice: Next Agent
+
+Present development options after successful handoff:
+
+```
+═══════════════════════════════════════════════════════════════
+  ✓ HANDOFF COMPLETE - {application_name}
+═══════════════════════════════════════════════════════════════
+
+Modules:   {count} ({names})
+Strategy:  {strategy}
+Files:     {total files across all modules}
+Tasks:     {total tasks} ({core_count} CORE + {biz_count} business + {dev_count} development)
+Complexity: {complexity}
+Effort:    {total_days} days ({total_hours} hours)
+
+Generated Artifacts:
+  ✓ feature.json (master + per-module) - enhanced with handoff section
+  ✓ .ralph/prd.json or .ralph/prd-{module}.json - derived from feature.json
+  ✓ .ralph/progress.txt - comprehensive task tracker
+  ✓ Implementation strategy selected: {strategy}
+
+Next: Choose development approach
+═══════════════════════════════════════════════════════════════
+```
+
+Ask via AskUserQuestion:
+
+```
+question: "Quelle approche de développement souhaitez-vous utiliser ?"
+header: "Approche de développement"
+options:
+  - label: "Feature Full (Recommandé)"
+    description: "Génération parallèle rapide (code + tests). Couverture 70-80%. ~{hours/3} heures."
+  - label: "Ralph Loop"
+    description: "Développement task-driven séquentiel. Couverture 95-100%. ~{hours} heures."
+  - label: "Terminer le BA"
+    description: "Finir l'analyse, développement manuel par l'équipe."
+```
+
+**Recommendations by complexity:**
+- **Simple:** Feature Full (1-3 days) or Ralph Loop (2-4 days)
+- **Medium:** Ralph Loop recommended (5-10 days), Feature Full possible (3-6 days)
+- **Complex:** Ralph Loop strongly recommended (10-20 days), Feature Full (8-12 days)
+
+---
+
+## MODE SUPPORT
+
+### Standard Mode
+
+Full handoff with all implementation details:
+- All 7 file categories
+- Complete BR-to-code mapping
+- Full API endpoint summary
+- Detailed prd.json
+- Comprehensive progress tracker
+
+### Micro Mode (use_case = micro)
+
+Simplified handoff with minimal scope:
+- Only essential CRUD entity + controller
+- 3 core SeedData entries (omit some optional ones)
+- Basic prd.json with simplified sections
+- Lightweight progress.txt
+- Auto-suggest Feature Full for rapid development
+
+### Delta Mode (use_case = refactoring)
+
+Focused handoff for changes:
+- Only affected modules listed
+- Reuse existing implementation patterns
+- Highlight what changed vs baseline
+- Update only affected prd.json sections
+- Progress tracker shows only delta tasks
+
+---
+
+## OUTPUT
+
+> **FORBIDDEN:** Do NOT generate separate JSON files (specification.json, analysis.json, etc.).
+> **ONLY:** feature.json is the mandatory JSON deliverable.
+> **PLUS:** prd.json and progress.txt are additional working files.
+
+This step enriches **feature.json** (master + per-module) with:
+- **handoff** section: complexity, implementationStrategy, moduleOrder, filesToCreate (7 categories), brToCodeMapping, apiEndpointSummary, prdFiles
+- **status:** "handed-off"
+
+Also generates two working files:
+- **.ralph/prd.json** (or .ralph/prd-{module}.json per module structure)
+  - Derived entirely from feature.json
+  - Single source of truth for development team
+  - Includes all entities, use cases, business rules, API endpoints
+  - Task breakdown and implementation sequence
+
+- **.ralph/progress.txt**
+  - Main development task tracker
+  - Hierarchical structure (module → layer → tasks)
+  - Checkboxes for progress tracking
+  - Effort estimates per module
+  - Cross-module integration tasks (if multi-module)
+
+Next agent selection via user question:
+1. **Feature Full** - Parallel rapid code generation (70-80% coverage)
+2. **Ralph Loop** - Sequential task-driven development (95-100% coverage)
+3. **End BA** - Manual development by team
+
+---
+
+## EXAMPLES & TEMPLATES
+
+### Example: Simple Single Module (Orders)
+
+**Feature:** Order Management
+**Module:** Orders (1 entity, 2 use cases, 3 BRs)
+
+**Output:**
+- feature.json with handoff section
+- .ralph/prd.json (single consolidated file)
+- .ralph/progress.txt (~150 lines, 20-30 tasks)
+
+Strategy: Module by module (only 1 module)
+
+### Example: Medium Multi-Module (E-Commerce)
+
+**Feature:** E-Commerce Platform
+**Modules:** Customers (4 entities), Products (6 entities), Orders (8 entities), Invoices (3 entities)
+
+**Dependencies:**
+- Customers: Foundation (no deps)
+- Products: Foundation (no deps)
+- Orders: Depends on Customers + Products
+- Invoices: Depends on Orders
+
+**Output:**
+- feature.json (master + 4 module features) with handoff sections
+- User chooses: per-module prd (.ralph/prd-customers.json, .ralph/prd-products.json, etc.) or consolidated (.ralph/prd.json)
+- .ralph/progress.txt (~400 lines, 100+ tasks)
+- Module order: Customers, Products → Orders → Invoices (topological)
+
+Strategy options: Module by module (recommended), Layer by layer, Hybrid
+
+### Example: Complex Multi-Module (ERP)
+
+**Feature:** Enterprise Resource Planning
+**Modules:** Accounting, Sales, Purchasing, Inventory, HR, Finance (20+ entities total, 50+ use cases, 100+ BRs)
+
+**Output:**
+- feature.json (master + 6 module features) with handoff sections
+- Per-module prd.json (recommended for complexity management)
+- .ralph/progress.txt (~800+ lines, 200+ tasks)
+
+Complexity: Complex (highest across all modules)
+Strategy: Hybrid recommended (Foundation modules layer-by-layer, then dependent modules module-by-module)
+
+---
+
+## VALIDATION CHECKLIST
+
+Before presenting handoff to user:
+
+- [ ] Status verified: "consolidated"
+- [ ] Implementation strategy selected or defaulted
+- [ ] Complexity calculated for each module and overall
+- [ ] filesToCreate: 7 categories complete, no free text
+- [ ] brToCodeMapping: All business rules from analysis.businessRules[] mapped
+- [ ] apiEndpointSummary: Exact copy from specification.apiEndpoints[]
+- [ ] prd.json: Derived from feature.json, not independently generated
+- [ ] prd.json: Includes all UCs, FRs, BRs, entities, API endpoints from source
+- [ ] progress.txt: Hierarchical, all modules in topological order, 5 CORE SeedData per module
+- [ ] Module order: Follows topological dependency graph
+- [ ] feature.json updated: handoff section + status "handed-off"
+- [ ] All paths use project namespace from .smartstack/config.json
+- [ ] No invented requirements (everything traced to feature.json)
+- [ ] User ready for next agent selection
+
+---
+
+## TROUBLESHOOTING
+
+| Issue | Resolution |
+|-------|-----------|
+| Status ≠ "consolidated" | Stop. Return to step-04-consolidation.md. |
+| No specification section | Cannot generate handoff without specification. Return to step-02-specify.md. |
+| Missing apiEndpoints | Copy exact routes from specification.apiEndpoints[] (absolute rule). |
+| BR not in analysis | Do not invent. Update feature.json analysis section. |
+| Circular dependencies | Reorder modules or break circular dependency. Notify user. |
+| prd.json too large | Use per-module structure instead of consolidated (multi-module). |
+| Progress.txt tasks unclear | Ensure each task is atomic and independently assignable. |
+| Module complexity unclear | Recalculate using entity count, UC count, BR count against thresholds. |
+
+---
+
+END OF STEP 5: HANDOFF