@atlashub/smartstack-cli 2.0.0 → 2.2.0

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

@@ -0,0 +1,1593 @@
+# Step 04: Handoff
+
+> **Version:** 3.0.0
+> **Name:** step-04-handoff
+> **Next step:** null (final step in business-analyse)
+> **Purpose:** Generate development handoff package (feature.json.handoff + .ralph/prd.json) ready for coding
+> **Input:** feature.json (specification + validation sections, status: "approved")
+> **Output:** feature.json.handoff enriched + .ralph/prd.json + .ralph/progress.txt + status: "handed-off"
+
+---
+
+## 1. Introduction
+
+This step **finalizes the transition** from business analysis to development. You will:
+
+1. **Verify validation passed** - Ensure status is "approved"
+2. **Explore existing patterns** - Search for similar modules, code generators, or scaffolding agents
+3. **Map specification to files** - Document which backend/frontend/seeddata tables implement each requirement
+4. **Generate implementation instructions** - Task breakdown for developers
+5. **Map business rules to code** - Where each BR will be validated
+6. **Define API endpoints** - RESTful routes for all operations
+7. **Test requirements** - Unit, integration, and E2E test mapping
+8. **Plan i18n keys** - Translation keys for UI and messages
+9. **Generate Ralph Loop prd.json** - Comprehensive product requirements document
+10. **Initialize progress tracker** - Progress.txt for monitoring completion
+
+---
+
+## 2. Mode Support
+
+### Standard Mode
+Execute full handoff with all implementation details.
+
+### Micro Mode
+IF use_case = micro:
+- Simplified handoff with minimal tasks
+- Only essential CRUD endpoints
+- Basic prd.json (fewer layers, simplified task decomposition)
+- Auto-suggest Feature Full agent for fast scaffolding
+
+### Delta Mode
+IF use_case = refactoring:
+- Generate handoff only for affected features
+- Reuse existing implementation patterns
+- Update prd.json only for changed sections
+
+---
+
+## 2. Verify Validation Passed
+
+### 2.1 Check Status
+
+Before proceeding, verify:
+
+```json
+{
+  "validation": {
+    "status": "approved" ✓,
+    "approvalMode": "standard|force",
+    "approvedAt": "2025-02-01T10:35:00Z",
+    "decision": {
+      "approved": true
+    }
+  }
+}
+```
+
+**Issue:** If status ≠ "approved" → **Stop. Return to step-03-validate.md.**
+
+### 2.2 Validation Summary
+
+Display summary before proceeding:
+
+```
+Validating approval status...
+✓ Validation: APPROVED
+✓ Specification: Complete & consistent
+✓ Decision: Ready for handoff
+
+Proceeding to implementation planning...
+```
+
+---
+
+## 3. Explore Existing Patterns
+
+### 3.1 Parallel Agents & Code Generators
+
+Before generating prd.json, check for existing tools:
+
+```
+Searching for similar modules and scaffolding agents...
+
+Available options:
+  1. Feature Full (claude-code skill)     → Fast scaffolding (recommended)
+  2. Ralph Loop (local prd.json runner)  → Task-driven development
+  3. Economy Mode (async generation)     → Large-scale projects
+  4. Custom MCP Tools (SmartStack.mcp)   → Validation & generation
+
+Selected: Feature Full + Ralph Loop
+```
+
+### 3.2 Code Generation Options
+
+Offer user choices:
+
+```json
+{
+  "generationOptions": [
+    {
+      "id": 1,
+      "tool": "Feature Full",
+      "description": "Parallel code generation (C#, React, tests)",
+      "duration": "15-30 min",
+      "coverage": "70-80%"
+    },
+    {
+      "id": 2,
+      "tool": "Ralph Loop",
+      "description": "Task-driven coding (sequential, detailed)",
+      "duration": "1-2 hours",
+      "coverage": "95-100%"
+    },
+    {
+      "id": 3,
+      "tool": "Economy Mode",
+      "description": "Asynchronous generation in background",
+      "duration": "varies",
+      "coverage": "Depends on parallelization"
+    }
+  ],
+  "recommended": "Feature Full + Ralph Loop (combined approach)"
+}
+```
+
+User selects which agent to use in next step.
+
+---
+
+## 4. Map Specification to Files
+
+### 4.1 Backend File Mapping
+
+For each entity in specification.entities[], document implementation files:
+
+```json
+{
+  "fileMapping": {
+    "backend": [
+      {
+        "entity": "Order",
+        "files": [
+          {
+            "path": "src/Domain/Entities/Order.cs",
+            "type": "Entity",
+            "linkedFRs": ["FR-001", "FR-002", "FR-003"]
+          },
+          {
+            "path": "src/Application/Services/OrderService.cs",
+            "type": "Service",
+            "linkedFRs": ["FR-001", "FR-002", "FR-003", "FR-004"]
+          },
+          {
+            "path": "src/API/Controllers/OrdersController.cs",
+            "type": "ApiController",
+            "endpoints": 6,
+            "linkedUCs": ["UC-001", "UC-002", "UC-003", "UC-004", "UC-005", "UC-006"]
+          },
+          {
+            "path": "src/Infrastructure/Repositories/OrderRepository.cs",
+            "type": "Repository",
+            "operations": ["GetAll", "GetById", "Create", "Update", "Delete"]
+          },
+          {
+            "path": "src/Infrastructure/Data/Migrations/AddOrderTable.cs",
+            "type": "Migration",
+            "tables": ["Order", "OrderLine"]
+          },
+          {
+            "path": "src/Tests/Application/OrderServiceTests.cs",
+            "type": "UnitTests",
+            "testCount": 12
+          },
+          {
+            "path": "src/Tests/Integration/OrderApiTests.cs",
+            "type": "IntegrationTests",
+            "testCount": 8
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 4.2 Frontend File Mapping
+
+For each use case in specification.useCases[], document UI files:
+
+```json
+{
+  "fileMapping": {
+    "frontend": [
+      {
+        "useCase": "UC-001: List Orders",
+        "files": [
+          {
+            "path": "src/pages/Orders/OrderListPage.tsx",
+            "type": "Page",
+            "linkedWireframe": "WF-001"
+          },
+          {
+            "path": "src/components/Orders/OrderListTable.tsx",
+            "type": "Component",
+            "linkedFRs": ["FR-001"]
+          },
+          {
+            "path": "src/components/Orders/OrderFilterBar.tsx",
+            "type": "Component",
+            "linkedFRs": ["FR-001"]
+          },
+          {
+            "path": "src/services/api/OrdersApiClient.ts",
+            "type": "ApiClient",
+            "methods": ["getOrders", "searchOrders", "filterOrders"]
+          },
+          {
+            "path": "src/stores/ordersSlice.ts",
+            "type": "Redux Slice",
+            "state": ["orders", "loading", "error", "pagination"]
+          },
+          {
+            "path": "src/tests/pages/OrderListPage.test.tsx",
+            "type": "ComponentTests",
+            "testCount": 8
+          }
+        ]
+      },
+      {
+        "useCase": "UC-002: Create Order",
+        "files": [
+          {
+            "path": "src/pages/Orders/CreateOrderPage.tsx",
+            "type": "Page",
+            "linkedWireframe": "WF-002"
+          },
+          {
+            "path": "src/components/Orders/CreateOrderForm.tsx",
+            "type": "Component",
+            "linkedFRs": ["FR-002", "FR-003"]
+          },
+          {
+            "path": "src/hooks/useOrderForm.ts",
+            "type": "CustomHook",
+            "linkedValidations": ["Validations for Order fields"]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 4.3 SeedData File Mapping
+
+Map 5 mandatory SeedData tables to migration files:
+
+```json
+{
+  "fileMapping": {
+    "seedData": [
+      {
+        "table": "Module_Status",
+        "migrationFile": "src/Infrastructure/Data/Migrations/Seed_Order_Status.cs",
+        "rows": [
+          {
+            "id": 1,
+            "code": "DRAFT",
+            "displayName": "Draft",
+            "description": "Order created but not submitted"
+          },
+          {
+            "id": 2,
+            "code": "SUBMITTED",
+            "displayName": "Submitted for Review",
+            "description": "Order awaiting manager approval"
+          },
+          {
+            "id": 3,
+            "code": "APPROVED",
+            "displayName": "Approved",
+            "description": "Order approved and ready for fulfillment"
+          }
+        ]
+      },
+      {
+        "table": "Module_Priority",
+        "migrationFile": "src/Infrastructure/Data/Migrations/Seed_Order_Priority.cs",
+        "rows": 3
+      },
+      {
+        "table": "Module_Category",
+        "migrationFile": "src/Infrastructure/Data/Migrations/Seed_Order_Category.cs",
+        "rows": 8
+      },
+      {
+        "table": "Module_Type",
+        "migrationFile": "src/Infrastructure/Data/Migrations/Seed_Order_Type.cs",
+        "rows": 4
+      },
+      {
+        "table": "Module_Department",
+        "migrationFile": "src/Infrastructure/Data/Migrations/Seed_Order_Department.cs",
+        "rows": 6
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 5. Generate Implementation Instructions
+
+### 5.1 Backend Implementation Sequence
+
+Create ordered task list:
+
+```json
+{
+  "implementationSequence": {
+    "backend": [
+      {
+        "phase": 1,
+        "name": "Domain Layer",
+        "tasks": [
+          {
+            "taskId": "TASK-001",
+            "title": "Define Order entity",
+            "linkedFRs": ["FR-001"],
+            "file": "src/Domain/Entities/Order.cs",
+            "priority": 1,
+            "effort": "2h"
+          },
+          {
+            "taskId": "TASK-002",
+            "title": "Define order status enum",
+            "linkedFRs": ["FR-001"],
+            "file": "src/Domain/Entities/OrderStatus.cs",
+            "priority": 2,
+            "effort": "1h"
+          }
+        ]
+      },
+      {
+        "phase": 2,
+        "name": "SeedData Layer",
+        "tasks": [
+          {
+            "taskId": "TASK-003",
+            "title": "Create SeedData migration for Order_Status",
+            "linkedFRs": [],
+            "file": "src/Infrastructure/Data/Migrations/Seed_Order_Status.cs",
+            "priority": 1,
+            "effort": "1h"
+          }
+        ]
+      },
+      {
+        "phase": 3,
+        "name": "Application Layer",
+        "tasks": [
+          {
+            "taskId": "TASK-004",
+            "title": "Create OrderService with CRUD operations",
+            "linkedFRs": ["FR-001", "FR-002", "FR-003", "FR-004"],
+            "file": "src/Application/Services/OrderService.cs",
+            "priority": 1,
+            "effort": "4h"
+          }
+        ]
+      },
+      {
+        "phase": 4,
+        "name": "Infrastructure Layer",
+        "tasks": [
+          {
+            "taskId": "TASK-005",
+            "title": "Create OrderRepository",
+            "linkedFRs": ["FR-001"],
+            "file": "src/Infrastructure/Repositories/OrderRepository.cs",
+            "priority": 1,
+            "effort": "2h"
+          }
+        ]
+      },
+      {
+        "phase": 5,
+        "name": "API Layer",
+        "tasks": [
+          {
+            "taskId": "TASK-006",
+            "title": "Create OrdersController with endpoints",
+            "linkedUCs": ["UC-001", "UC-002", "UC-003"],
+            "file": "src/API/Controllers/OrdersController.cs",
+            "priority": 1,
+            "effort": "3h"
+          }
+        ]
+      },
+      {
+        "phase": 6,
+        "name": "Frontend Layer",
+        "tasks": [
+          {
+            "taskId": "TASK-007",
+            "title": "Create OrderListPage component",
+            "linkedUCs": ["UC-001"],
+            "file": "src/pages/Orders/OrderListPage.tsx",
+            "priority": 1,
+            "effort": "3h"
+          }
+        ]
+      },
+      {
+        "phase": 7,
+        "name": "i18n Layer",
+        "tasks": [
+          {
+            "taskId": "TASK-008",
+            "title": "Add i18n keys for Order module",
+            "file": "src/locales/en/orders.json",
+            "priority": 2,
+            "effort": "1h"
+          }
+        ]
+      },
+      {
+        "phase": 8,
+        "name": "Tests & Validation",
+        "tasks": [
+          {
+            "taskId": "TASK-009",
+            "title": "Unit tests for OrderService",
+            "linkedFRs": ["FR-001", "FR-002"],
+            "file": "src/Tests/Application/OrderServiceTests.cs",
+            "priority": 1,
+            "effort": "2h"
+          },
+          {
+            "taskId": "TASK-010",
+            "title": "Integration tests for OrdersController",
+            "linkedUCs": ["UC-001", "UC-002"],
+            "file": "src/Tests/Integration/OrderApiTests.cs",
+            "priority": 1,
+            "effort": "2h"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 5.2 Decomposition Rules
+
+For task breakdown:
+
+| Layer | Unit | Tasks |
+|-------|------|-------|
+| **Domain** | Entity + Enum | 1-3 per entity |
+| **SeedData** | Table | 1 per table |
+| **Application** | Service | 1 per major feature (CRUD + business logic) |
+| **Infrastructure** | Repository | 1 per entity |
+| **API** | Controller | 1 per resource |
+| **Frontend** | Page/Component | 1 per major UC |
+| **i18n** | Locales | 1 for all keys |
+| **Tests** | Suite | 1 unit + 1 integration per layer |
+
+---
+
+## 6. Map Business Rules to Code
+
+### 6.1 BR Implementation Mapping
+
+For each business rule, specify where it will be validated:
+
+```json
+{
+  "businessRuleMappings": [
+    {
+      "ruleId": "BR-001",
+      "title": "Order number must be unique",
+      "implementationPoints": [
+        {
+          "layer": "Domain",
+          "component": "Order.cs",
+          "method": "Validate()",
+          "implementation": "Throw DomainException if duplicate"
+        },
+        {
+          "layer": "Infrastructure",
+          "component": "OrderRepository.cs",
+          "method": "Create()",
+          "implementation": "Check uniqueness before INSERT"
+        },
+        {
+          "layer": "API",
+          "component": "OrdersController.cs",
+          "method": "CreateOrder()",
+          "implementation": "Validate via service, return 409 Conflict if duplicate"
+        },
+        {
+          "layer": "Frontend",
+          "component": "CreateOrderForm.tsx",
+          "method": "validateOrderNumber()",
+          "implementation": "Real-time validation via API endpoint"
+        }
+      ]
+    },
+    {
+      "ruleId": "BR-002",
+      "title": "Only Manager can approve orders",
+      "implementationPoints": [
+        {
+          "layer": "API",
+          "component": "OrdersController.cs",
+          "method": "[Authorize(Roles = \"Manager\")]",
+          "implementation": "Attribute-based authorization"
+        },
+        {
+          "layer": "Application",
+          "component": "OrderService.cs",
+          "method": "ApproveOrder()",
+          "implementation": "Check user role, throw UnauthorizedAccessException if not Manager"
+        },
+        {
+          "layer": "Frontend",
+          "component": "OrderDetailPage.tsx",
+          "method": "canApprove()",
+          "implementation": "Hide/disable Approve button for non-managers"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 6.2 Validation Rules Implementation
+
+Map validations to code layers:
+
+```json
+{
+  "validationMappings": [
+    {
+      "validation": "OrderNumber: required, unique, max 20 chars",
+      "domain": "Order.cs: Field attribute + Validate() method",
+      "database": "CREATE UNIQUE INDEX idx_Order_OrderNumber; CHECK length(OrderNumber) <= 20",
+      "service": "OrderService.cs: Pre-save validation",
+      "api": "OrdersController.cs: ModelState validation",
+      "frontend": "CreateOrderForm.tsx: Inline validation + API check"
+    }
+  ]
+}
+```
+
+---
+
+## 7. Define API Endpoints
+
+### 7.1 RESTful Route Mapping
+
+For each use case, define API endpoints:
+
+```json
+{
+  "apiEndpoints": [
+    {
+      "useCase": "UC-001: List Orders",
+      "method": "GET",
+      "route": "/api/v1/orders",
+      "description": "Retrieve paginated list of orders with filtering and sorting",
+      "parameters": [
+        {
+          "name": "page",
+          "type": "int",
+          "default": 1,
+          "description": "Page number (1-indexed)"
+        },
+        {
+          "name": "pageSize",
+          "type": "int",
+          "default": 25,
+          "values": [10, 25, 50, 100]
+        },
+        {
+          "name": "status",
+          "type": "string",
+          "values": ["Draft", "Submitted", "Approved", "Shipped", "Delivered"],
+          "optional": true
+        },
+        {
+          "name": "sortBy",
+          "type": "string",
+          "values": ["orderNumber", "orderDate", "status"],
+          "default": "orderDate"
+        },
+        {
+          "name": "sortDir",
+          "type": "string",
+          "values": ["asc", "desc"],
+          "default": "desc"
+        }
+      ],
+      "response": {
+        "statusCode": 200,
+        "body": {
+          "data": [
+            {
+              "id": "int",
+              "orderNumber": "string",
+              "orderDate": "datetime",
+              "status": "string"
+            }
+          ],
+          "pagination": {
+            "page": "int",
+            "pageSize": "int",
+            "totalPages": "int",
+            "totalRecords": "int"
+          }
+        }
+      },
+      "linkedFRs": ["FR-001"],
+      "permissions": ["Read"]
+    },
+    {
+      "useCase": "UC-002: Create Order",
+      "method": "POST",
+      "route": "/api/v1/orders",
+      "description": "Create new order with validation",
+      "requestBody": {
+        "orderNumber": "string (required, unique)",
+        "orderDate": "datetime (required, not future)",
+        "customerId": "int (required, FK)",
+        "status": "string (default: Draft)"
+      },
+      "response": {
+        "statusCode": 201,
+        "body": {
+          "id": "int",
+          "orderNumber": "string",
+          "orderDate": "datetime",
+          "createdBy": "string",
+          "createdDate": "datetime"
+        }
+      },
+      "errors": [
+        {
+          "statusCode": 400,
+          "code": "VALIDATION_FAILED",
+          "message": "Validation failed: [field details]"
+        },
+        {
+          "statusCode": 409,
+          "code": "DUPLICATE_ORDER_NUMBER",
+          "message": "Order number already exists"
+        }
+      ],
+      "linkedFRs": ["FR-002", "FR-003"],
+      "permissions": ["Create"]
+    },
+    {
+      "useCase": "UC-003: View Order Detail",
+      "method": "GET",
+      "route": "/api/v1/orders/{id}",
+      "description": "Retrieve full order details including lines and history",
+      "parameters": [
+        {
+          "name": "id",
+          "type": "int",
+          "required": true,
+          "location": "path"
+        }
+      ],
+      "response": {
+        "statusCode": 200,
+        "body": {
+          "id": "int",
+          "orderNumber": "string",
+          "orderDate": "datetime",
+          "customerId": "int",
+          "status": "string",
+          "lines": [
+            {
+              "id": "int",
+              "productId": "int",
+              "quantity": "int",
+              "unitPrice": "decimal"
+            }
+          ]
+        }
+      },
+      "linkedFRs": ["FR-001"],
+      "permissions": ["Read"]
+    }
+  ]
+}
+```
+
+### 7.2 Endpoint Summary Table
+
+```json
+{
+  "endpointSummary": [
+    {
+      "operation": "List",
+      "method": "GET",
+      "route": "/api/v1/orders",
+      "linkedUC": "UC-001",
+      "permissions": "Read"
+    },
+    {
+      "operation": "Create",
+      "method": "POST",
+      "route": "/api/v1/orders",
+      "linkedUC": "UC-002",
+      "permissions": "Create"
+    },
+    {
+      "operation": "Read",
+      "method": "GET",
+      "route": "/api/v1/orders/{id}",
+      "linkedUC": "UC-003",
+      "permissions": "Read"
+    },
+    {
+      "operation": "Update",
+      "method": "PUT",
+      "route": "/api/v1/orders/{id}",
+      "linkedUC": "UC-004",
+      "permissions": "Update"
+    },
+    {
+      "operation": "Delete",
+      "method": "DELETE",
+      "route": "/api/v1/orders/{id}",
+      "linkedUC": "UC-005",
+      "permissions": "Delete"
+    },
+    {
+      "operation": "Approve",
+      "method": "POST",
+      "route": "/api/v1/orders/{id}/approve",
+      "linkedUC": "UC-006",
+      "permissions": "Approve"
+    }
+  ],
+  "totalEndpoints": 6
+}
+```
+
+---
+
+## 8. Test Requirements
+
+### 8.1 Unit Test Coverage
+
+For each service/component, define test cases:
+
+```json
+{
+  "unitTests": [
+    {
+      "testClass": "OrderServiceTests",
+      "testCases": [
+        {
+          "testName": "CreateOrder_WithValidData_ReturnsSuccess",
+          "linkedFR": "FR-002",
+          "givenState": "Valid order data",
+          "when": "CreateOrder() called",
+          "then": "Returns new order with ID"
+        },
+        {
+          "testName": "CreateOrder_WithDuplicateOrderNumber_ThrowsException",
+          "linkedBR": "BR-001",
+          "givenState": "Order with number ORD-001 exists",
+          "when": "CreateOrder(ORD-001) called",
+          "then": "Throws DuplicateOrderNumberException"
+        },
+        {
+          "testName": "ApproveOrder_ByNonManager_ThrowsUnauthorized",
+          "linkedBR": "BR-002",
+          "givenState": "Order exists, user is User role",
+          "when": "ApproveOrder() called",
+          "then": "Throws UnauthorizedAccessException"
+        }
+      ],
+      "coverage": "95%"
+    }
+  ]
+}
+```
+
+### 8.2 Integration Test Coverage
+
+For APIs, define integration tests:
+
+```json
+{
+  "integrationTests": [
+    {
+      "testClass": "OrdersControllerTests",
+      "testCases": [
+        {
+          "testName": "GetOrders_WithoutAuth_Returns401",
+          "when": "GET /api/v1/orders without token",
+          "then": "Returns 401 Unauthorized"
+        },
+        {
+          "testName": "CreateOrder_WithInvalidData_Returns400",
+          "when": "POST /api/v1/orders with missing orderNumber",
+          "then": "Returns 400 BadRequest with validation errors"
+        },
+        {
+          "testName": "CreateOrder_ByAuthorizedUser_Returns201",
+          "linkedUC": "UC-002",
+          "when": "POST /api/v1/orders with valid data by authorized user",
+          "then": "Returns 201 Created with order details"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 8.3 E2E Test Coverage
+
+For critical user journeys:
+
+```json
+{
+  "e2eTests": [
+    {
+      "journey": "Create and Approve Order",
+      "scenario": "User creates order, manager approves it",
+      "steps": [
+        "1. Navigate to /orders",
+        "2. Click 'Create New Order'",
+        "3. Fill form and submit",
+        "4. Verify order created with Draft status",
+        "5. Login as manager",
+        "6. Navigate to order detail",
+        "7. Click 'Approve'",
+        "8. Verify status changed to Approved"
+      ],
+      "linkedUCs": ["UC-002", "UC-006"]
+    }
+  ]
+}
+```
+
+---
+
+## 9. Plan i18n Keys
+
+### 9.1 i18n Key Mapping
+
+For all user-facing strings, define translation keys:
+
+```json
+{
+  "i18nKeys": [
+    {
+      "key": "orders.menu.label",
+      "defaultText": "Orders",
+      "context": "Menu item"
+    },
+    {
+      "key": "orders.list.title",
+      "defaultText": "Order Management",
+      "context": "Page title"
+    },
+    {
+      "key": "orders.list.createButton",
+      "defaultText": "Create New Order",
+      "context": "Button label"
+    },
+    {
+      "key": "orders.list.columns.orderNumber",
+      "defaultText": "Order Number",
+      "context": "Table column header"
+    },
+    {
+      "key": "orders.list.columns.orderDate",
+      "defaultText": "Order Date",
+      "context": "Table column header"
+    },
+    {
+      "key": "orders.list.columns.status",
+      "defaultText": "Status",
+      "context": "Table column header"
+    },
+    {
+      "key": "orders.form.labels.orderNumber",
+      "defaultText": "Order Number",
+      "context": "Form field label"
+    },
+    {
+      "key": "orders.form.labels.orderDate",
+      "defaultText": "Order Date",
+      "context": "Form field label"
+    },
+    {
+      "key": "orders.form.validations.orderNumberRequired",
+      "defaultText": "Order number is required",
+      "context": "Validation message"
+    },
+    {
+      "key": "orders.form.validations.orderNumberFormat",
+      "defaultText": "Format must be ORD-XXXXXX",
+      "context": "Validation message"
+    },
+    {
+      "key": "orders.messages.createdSuccess",
+      "defaultText": "Order {orderNumber} created successfully",
+      "context": "Success message",
+      "variables": ["orderNumber"]
+    },
+    {
+      "key": "orders.messages.approvedSuccess",
+      "defaultText": "Order approved",
+      "context": "Success message"
+    },
+    {
+      "key": "orders.messages.notFound",
+      "defaultText": "Order not found",
+      "context": "Error message"
+    },
+    {
+      "key": "orders.enums.status.draft",
+      "defaultText": "Draft",
+      "context": "Enum value"
+    },
+    {
+      "key": "orders.enums.status.submitted",
+      "defaultText": "Submitted for Review",
+      "context": "Enum value"
+    },
+    {
+      "key": "orders.enums.status.approved",
+      "defaultText": "Approved",
+      "context": "Enum value"
+    }
+  ],
+  "totalKeys": 16,
+  "locales": ["en", "fr", "es", "de"]
+}
+```
+
+### 9.2 i18n File Structure
+
+```
+src/locales/
+├── en/
+│   ├── common.json
+│   ├── orders.json          ← Order module strings
+│   └── ...
+├── fr/
+│   ├── common.json
+│   ├── orders.json
+│   └── ...
+└── es/
+    ├── common.json
+    └── orders.json
+```
+
+---
+
+## 10. Ralph Loop prd.json Generation
+
+### 10.1 PRD Document Structure
+
+Generate comprehensive product requirements document:
+
+```json
+{
+  "prd": {
+    "version": "2.0.0",
+    "source": {
+      "type": "ba-handoff",
+      "feature_json": "docs/feature.json"
+    },
+    "metadata": {
+      "title": "[Module Name] - Product Requirements Document",
+      "description": "[Module scope description]",
+      "createdAt": "2025-02-01T11:00:00Z",
+      "createdBy": "business-analyse skill v3.0",
+      "status": "handed-off",
+      "lastModified": "2025-02-01T11:00:00Z"
+    },
+    "project": {
+      "name": "[Project Name]",
+      "module": "[Module Name]",
+      "version": "1.0.0"
+    },
+    "overview": {
+      "summary": "[Executive summary from scope]",
+      "businessGoals": "[From scope.businessObjectives]",
+      "stakeholders": "[From discovery.stakeholders]",
+      "successCriteria": "[From scope.successCriteria]"
+    },
+    "requirements": {
+      "functional": {
+        "useCases": "[From specification.useCases]",
+        "requirements": "[From specification.functionalRequirements]",
+        "scenarios": "[From specification.gherkinScenarios]"
+      },
+      "nonfunctional": {
+        "performance": "[From specification.validations if applicable]",
+        "security": "[From specification.auditingPolicy]",
+        "scalability": "[Derived from business rules]"
+      }
+    },
+    "architecture": {
+      "entities": "[From specification.entities]",
+      "dataModel": "[From specification.entities relationships]",
+      "apiEndpoints": "[From handoff.apiEndpoints]",
+      "permissions": "[From specification.permissionMatrix]"
+    },
+    "implementation": {
+      "taskBreakdown": "[From handoff.implementationSequence]",
+      "fileMapping": "[From handoff.fileMapping]",
+      "dependencies": "[From specification.crossModuleDependencies]",
+      "seedData": "[From specification.navigationHierarchy.seedDataRequired]"
+    },
+    "testing": {
+      "unitTests": "[From handoff.unitTests]",
+      "integrationTests": "[From handoff.integrationTests]",
+      "e2eTests": "[From handoff.e2eTests]",
+      "testCoverage": 80
+    },
+    "i18n": {
+      "keys": "[From handoff.i18nKeys]",
+      "locales": ["en", "fr", "es", "de"]
+    }
+  }
+}
+```
+
+### 10.2 Ralph Loop Task Decomposition
+
+Critical section: Layer-by-layer task breakdown:
+
+```json
+{
+  "tasks": {
+    "decompositionRules": {
+      "granularity": "2-3 hour tasks (developer focus)",
+      "layerOrder": ["Domain", "SeedData", "Application", "Infrastructure", "API", "Frontend", "i18n", "Tests", "Validation"],
+      "dependencies": "Domain → SeedData → Application → Infrastructure → API & Frontend → i18n → Tests",
+      "parallelization": "Infrastructure & Frontend can run in parallel after API definition"
+    },
+    "layers": [
+      {
+        "layerId": "DOMAIN",
+        "name": "Domain Layer",
+        "description": "Entity definitions, enums, validation rules",
+        "tasks": [
+          {
+            "id": "TASK-DOMAIN-001",
+            "title": "Define Order entity with validation",
+            "description": "[From specification.entities[Order]]",
+            "effort": "2h",
+            "dependencies": [],
+            "linkedFRs": ["FR-001"],
+            "linkedBRs": ["BR-001", "BR-003"],
+            "acceptance": "Order.cs created with all fields, required validation, state machine"
+          }
+        ]
+      },
+      {
+        "layerId": "SEEDDATA",
+        "name": "SeedData Layer",
+        "description": "Lookup tables and reference data",
+        "tasks": [
+          {
+            "id": "TASK-SEED-001",
+            "title": "Create Order_Status SeedData migration",
+            "description": "[From specification.navigationHierarchy.seedDataRequired[0]]",
+            "effort": "1h",
+            "dependencies": ["TASK-DOMAIN-001"],
+            "linkedFRs": [],
+            "acceptance": "Migration creates Order_Status table with 5 status values seeded"
+          }
+        ]
+      },
+      {
+        "layerId": "APPLICATION",
+        "name": "Application Layer",
+        "description": "Business logic, services, use case orchestration",
+        "tasks": [
+          {
+            "id": "TASK-APP-001",
+            "title": "Implement OrderService (CRUD + Approve)",
+            "description": "[From specification.functionalRequirements FR-001 to FR-004]",
+            "effort": "4h",
+            "dependencies": ["TASK-DOMAIN-001", "TASK-SEED-001"],
+            "linkedFRs": ["FR-001", "FR-002", "FR-003", "FR-004"],
+            "linkedUCs": ["UC-001", "UC-002", "UC-003", "UC-004"],
+            "acceptance": "OrderService has methods: GetAll, GetById, Create, Update, Approve with business rule validation"
+          }
+        ]
+      },
+      {
+        "layerId": "INFRASTRUCTURE",
+        "name": "Infrastructure Layer",
+        "description": "Data access, repositories, database operations",
+        "tasks": [
+          {
+            "id": "TASK-INFRA-001",
+            "title": "Create OrderRepository with filtering & sorting",
+            "description": "[From apiEndpoints.parameters: page, pageSize, status, sortBy]",
+            "effort": "2h",
+            "dependencies": ["TASK-DOMAIN-001"],
+            "linkedFRs": ["FR-001"],
+            "acceptance": "OrderRepository has GetAll(filter, sort, pagination) method"
+          }
+        ]
+      },
+      {
+        "layerId": "API",
+        "name": "API Layer",
+        "description": "REST endpoints, request/response handling",
+        "tasks": [
+          {
+            "id": "TASK-API-001",
+            "title": "Create OrdersController with 6 endpoints",
+            "description": "[From apiEndpoints: GET /orders, POST /orders, GET /orders/{id}, PUT /orders/{id}, DELETE /orders/{id}, POST /orders/{id}/approve]",
+            "effort": "3h",
+            "dependencies": ["TASK-APP-001"],
+            "linkedUCs": ["UC-001", "UC-002", "UC-003", "UC-004", "UC-005", "UC-006"],
+            "acceptance": "Controller has all 6 endpoints with proper HTTP methods, status codes, error handling"
+          }
+        ]
+      },
+      {
+        "layerId": "FRONTEND",
+        "name": "Frontend Layer",
+        "description": "UI pages, components, state management",
+        "tasks": [
+          {
+            "id": "TASK-FE-001",
+            "title": "Create OrderListPage with table and filters",
+            "description": "[From wireframe WF-001]",
+            "effort": "3h",
+            "dependencies": ["TASK-API-001"],
+            "linkedUCs": ["UC-001"],
+            "linkedFRs": ["FR-001"],
+            "acceptance": "Page displays paginated order list, supports filtering by status, sorting, search"
+          },
+          {
+            "id": "TASK-FE-002",
+            "title": "Create CreateOrderForm with validation",
+            "description": "[From wireframe WF-002, specification.validations]",
+            "effort": "3h",
+            "dependencies": ["TASK-API-001"],
+            "linkedUCs": ["UC-002"],
+            "linkedFRs": ["FR-002", "FR-003"],
+            "acceptance": "Form validates all fields inline, shows error messages, prevents submission if invalid"
+          }
+        ]
+      },
+      {
+        "layerId": "I18N",
+        "name": "i18n Layer",
+        "description": "Translation keys and localization",
+        "tasks": [
+          {
+            "id": "TASK-I18N-001",
+            "title": "Add Order module translation keys",
+            "description": "[From i18nKeys list]",
+            "effort": "1h",
+            "dependencies": ["TASK-FE-001", "TASK-FE-002"],
+            "linkedFRs": [],
+            "acceptance": "16 i18n keys added to en/orders.json, ready for translation"
+          }
+        ]
+      },
+      {
+        "layerId": "TESTS",
+        "name": "Tests & Validation Layer",
+        "description": "Unit, integration, and E2E tests",
+        "tasks": [
+          {
+            "id": "TASK-TEST-001",
+            "title": "Unit tests for OrderService",
+            "description": "[From unitTests: 12 test cases]",
+            "effort": "2h",
+            "dependencies": ["TASK-APP-001"],
+            "linkedFRs": ["FR-001", "FR-002", "FR-003", "FR-004"],
+            "acceptance": "12 unit tests covering CRUD, validation, authorization"
+          },
+          {
+            "id": "TASK-TEST-002",
+            "title": "Integration tests for OrdersController",
+            "description": "[From integrationTests: 8 test cases]",
+            "effort": "2h",
+            "dependencies": ["TASK-API-001"],
+            "linkedUCs": ["UC-001", "UC-002", "UC-003"],
+            "acceptance": "8 integration tests covering all endpoints, auth, error handling"
+          },
+          {
+            "id": "TASK-TEST-003",
+            "title": "E2E test for Order creation and approval flow",
+            "description": "[From e2eTests: Create and Approve Order journey]",
+            "effort": "2h",
+            "dependencies": ["TASK-FE-002"],
+            "linkedUCs": ["UC-002", "UC-006"],
+            "acceptance": "E2E test covers complete user journey from create to approve"
+          }
+        ]
+      },
+      {
+        "layerId": "VALIDATION",
+        "name": "Validation & QA Layer",
+        "description": "Final validation against requirements",
+        "tasks": [
+          {
+            "id": "TASK-VALIDATION-001",
+            "title": "Verify all FRs implemented and tested",
+            "description": "[Cross-reference FR vs implementation]",
+            "effort": "1h",
+            "dependencies": ["TASK-TEST-003"],
+            "linkedFRs": ["FR-001", "FR-002", "FR-003", "FR-004"],
+            "acceptance": "All FRs have corresponding code and tests"
+          },
+          {
+            "id": "TASK-VALIDATION-002",
+            "title": "Verify all BRs validated in code",
+            "description": "[Cross-reference BR vs validation points]",
+            "effort": "1h",
+            "dependencies": ["TASK-TEST-003"],
+            "linkedBRs": ["BR-001", "BR-002", "BR-003"],
+            "acceptance": "All BRs have corresponding validation in at least one layer"
+          }
+        ]
+      }
+    ],
+    "totalTasks": 15,
+    "totalEffort": "28h",
+    "estimatedDuration": "1 week (4 developers in parallel)"
+  }
+}
+```
+
+### 10.3 prd.json v2.0.0 Schema Validation
+
+Ensure prd.json follows SmartStack schema:
+
+```json
+{
+  "validation": {
+    "schema": "prd.json v2.0.0",
+    "checks": [
+      {
+        "field": "version",
+        "required": true,
+        "value": "2.0.0",
+        "status": "PASS" ✓
+      },
+      {
+        "field": "source",
+        "required": true,
+        "value": {
+          "type": "ba-handoff",
+          "feature_json": "docs/feature.json"
+        },
+        "status": "PASS" ✓
+      },
+      {
+        "field": "tasks",
+        "required": true,
+        "taskCount": 15,
+        "layerCount": 9,
+        "status": "PASS" ✓
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 11. Initialize Progress Tracker
+
+### 11.1 Create .ralph/progress.txt
+
+Initialize progress tracking file:
+
+```
+═════════════════════════════════════════════════════════════════
+  SMARTSTACK RALPH LOOP - PROGRESS TRACKER
+  Project: [Project Name] | Module: [Module Name]
+  Created: 2025-02-01T11:00:00Z
+  Status: HANDED-OFF
+═════════════════════════════════════════════════════════════════
+
+LAYER BREAKDOWN (28h total effort):
+
+[DOMAIN] Domain Layer (2h)
+  □ TASK-DOMAIN-001: Define Order entity (2h)
+    Status: pending
+    Assigned: [TBD]
+    Started: [TBD]
+    Completed: [TBD]
+    Progress: 0%
+
+[SEEDDATA] SeedData Layer (1h)
+  □ TASK-SEED-001: Create Order_Status migration (1h)
+    Status: pending
+    Assigned: [TBD]
+    Started: [TBD]
+    Completed: [TBD]
+    Progress: 0%
+
+[APPLICATION] Application Layer (4h)
+  □ TASK-APP-001: Implement OrderService (4h)
+    Status: pending
+    Assigned: [TBD]
+    Started: [TBD]
+    Completed: [TBD]
+    Progress: 0%
+    Subtasks:
+      - GetAll() method
+      - GetById() method
+      - Create() method with validation
+      - Update() method
+      - Approve() method with authorization
+
+[INFRASTRUCTURE] Infrastructure Layer (2h)
+  □ TASK-INFRA-001: Create OrderRepository (2h)
+    Status: pending
+    Assigned: [TBD]
+    Started: [TBD]
+    Completed: [TBD]
+    Progress: 0%
+
+[API] API Layer (3h)
+  □ TASK-API-001: Create OrdersController (3h)
+    Status: pending
+    Assigned: [TBD]
+    Started: [TBD]
+    Completed: [TBD]
+    Progress: 0%
+    Endpoints:
+      - GET /api/v1/orders (List)
+      - POST /api/v1/orders (Create)
+      - GET /api/v1/orders/{id} (Detail)
+      - PUT /api/v1/orders/{id} (Update)
+      - DELETE /api/v1/orders/{id} (Delete)
+      - POST /api/v1/orders/{id}/approve (Approve)
+
+[FRONTEND] Frontend Layer (6h)
+  □ TASK-FE-001: Create OrderListPage (3h)
+    Status: pending
+    Assigned: [TBD]
+    Progress: 0%
+  □ TASK-FE-002: Create CreateOrderForm (3h)
+    Status: pending
+    Assigned: [TBD]
+    Progress: 0%
+
+[I18N] i18n Layer (1h)
+  □ TASK-I18N-001: Add translation keys (1h)
+    Status: pending
+    Progress: 0%
+    Keys: 16 total
+      □ Menu labels (1)
+      □ Page titles (1)
+      □ Column headers (3)
+      □ Form labels (2)
+      □ Validation messages (4)
+      □ Success messages (2)
+      □ Error messages (2)
+      □ Enum values (3)
+
+[TESTS] Tests & Validation Layer (6h)
+  □ TASK-TEST-001: Unit tests for OrderService (2h)
+    Status: pending
+    Progress: 0%
+    Cases: 12 unit tests
+  □ TASK-TEST-002: Integration tests for OrdersController (2h)
+    Status: pending
+    Progress: 0%
+    Cases: 8 integration tests
+  □ TASK-TEST-003: E2E test for Order flow (2h)
+    Status: pending
+    Progress: 0%
+    Cases: 1 E2E scenario
+
+[VALIDATION] Validation & QA Layer (2h)
+  □ TASK-VALIDATION-001: Verify FRs implemented (1h)
+    Status: pending
+    Progress: 0%
+  □ TASK-VALIDATION-002: Verify BRs validated (1h)
+    Status: pending
+    Progress: 0%
+
+═════════════════════════════════════════════════════════════════
+SUMMARY
+═════════════════════════════════════════════════════════════════
+Total Tasks:           15
+Total Effort:          28 hours
+Completed:             0 (0%)
+In Progress:           0 (0%)
+Pending:               15 (100%)
+Blocked:               0 (0%)
+
+Dependencies:
+  Domain → SeedData → Application → Infrastructure
+         ↘                                    ↙
+           ↓                                ↓
+         API ←─────────── Frontend
+           ↓                  ↓
+         i18n & Tests ← ─────┘
+           ↓
+       Validation
+
+Critical Path: Domain → SeedData → App → Infra → API → Tests (18h)
+Parallel Path: Frontend (6h) can start after API definition
+
+═════════════════════════════════════════════════════════════════
+NOTES
+═════════════════════════════════════════════════════════════════
+- Start Domain tasks immediately (critical path dependency)
+- Frontend & Infrastructure can run in parallel after API is stubbed
+- Tests should not begin until implementation 80% complete
+- Update this file daily during development
+- Colors: 🟢 Done | 🟡 In Progress | 🔴 Pending | ⚫ Blocked
+
+═════════════════════════════════════════════════════════════════
+```
+
+### 11.2 Progress Tracking Integration
+
+Link progress.txt to feature.json:
+
+```json
+{
+  "handoff": {
+    "progressFile": ".ralph/progress.txt",
+    "progressTracking": {
+      "enabled": true,
+      "updateFrequency": "daily",
+      "statusOptions": ["pending", "in_progress", "completed", "blocked"],
+      "links": {
+        "feature_json": "docs/feature.json",
+        "prd_json": ".ralph/prd.json",
+        "progress_txt": ".ralph/progress.txt"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 12. User Choice: Next Agent
+
+### 12.1 Present Options
+
+After generating prd.json, offer user choices:
+
+```
+Handoff package ready!
+
+Generated:
+  ✓ feature.json.handoff section
+  ✓ .ralph/prd.json (product requirements)
+  ✓ .ralph/progress.txt (task tracker)
+
+Next step: Choose your development approach
+
+Options:
+  1. [Feature Full] Fast scaffolding + test generation
+     Duration: 15-30 min | Coverage: 70-80%
+     ✓ Fast iteration | ✓ Tests included
+     ✗ May need manual polish
+
+  2. [Ralph Loop] Task-driven development
+     Duration: 1-2 hours | Coverage: 95-100%
+     ✓ Comprehensive | ✓ Detailed implementation
+     ✗ Slower, more verbose
+
+  3. [Feature Full] Parallel multi-layer generation
+     Duration: 30-45 min | Coverage: 80-90%
+     ✓ Balanced | ✓ All layers in parallel
+     ✗ Complex orchestration
+
+  4. [End BA] Finish business analysis, manual development
+     Duration: 0 min | Coverage: Depends on developers
+     ✓ Gives team freedom | ✓ Lighter handoff
+     ✗ No code generation
+
+Recommended: Option 1 (Feature Full) for fast MVP, then Option 2 (Ralph Loop) for polish.
+
+Select option: [ ]
+```
+
+### 12.2 Remove Old Documentation Option
+
+Remove step-06 from final choice:
+- ~~[Generate HTML documentation]~~ - NOT AVAILABLE in v3.0
+- Keep: Ralph Loop, Feature Full, End BA
+
+---
+
+## 13. Execution Workflow
+
+### 13.1 Handoff Sequence
+
+1. **Verify validation passed** (status: "approved")
+2. **Explore existing patterns** (check for code generators)
+3. **Map to files** (document implementation locations)
+4. **Generate implementation instructions** (task breakdown)
+5. **Map BRs to code** (validation points)
+6. **Define API endpoints** (RESTful routes)
+7. **Plan tests** (coverage strategy)
+8. **Plan i18n** (translation keys)
+9. **Generate prd.json** (comprehensive requirements)
+10. **Initialize progress.txt** (task tracker)
+11. **Present user choices** (next agent selection)
+
+### 13.2 Output Summary
+
+Display final summary:
+
+```
+═══════════════════════════════════════════════════════════════
+✓ HANDOFF COMPLETE
+═══════════════════════════════════════════════════════════════
+
+Module:               Orders
+Status:               handed-off
+Specification:        11 sections complete
+Validation:           approved
+Implementation:       Ready to code
+
+Generated Files:
+  ✓ docs/feature.json (specification + validation + handoff)
+  ✓ .ralph/prd.json (v2.0.0 with 15 tasks)
+  ✓ .ralph/progress.txt (progress tracker)
+
+Statistics:
+  - Use cases:        6 (UC-001 → UC-006)
+  - Requirements:     12 FRs
+  - Business rules:   5 BRs (mapped to code)
+  - API endpoints:    6 REST routes
+  - Components:       8 frontend components
+  - Tests:            20 test cases (unit + integration + E2E)
+  - i18n keys:        16 translation keys
+  - Implementation:   15 tasks across 9 layers
+  - Total effort:     28 hours
+
+Dependencies:
+  ✓ Domain → SeedData → Application → Infrastructure → API → Frontend
+  ✓ Tests & i18n run in parallel
+  ✓ Validation confirms all FRs/BRs covered
+
+Next Step: Choose development approach (Feature Full / Ralph Loop / Manual)
+
+═══════════════════════════════════════════════════════════════
+```
+
+---
+
+## OUTPUT
+
+This step enriches **feature.json** with:
+- **handoff** section containing file mappings, implementation instructions, BR mappings, API endpoints, test plans, and i18n keys
+- **Status:** "handed-off"
+
+Also generates:
+- **.ralph/prd.json** - Comprehensive product requirements (v2.0.0 schema)
+- **.ralph/progress.txt** - Task progress tracker with 15 implementation tasks
+
+**Standard mode:** Full handoff with all implementation details.
+**Micro mode:** Simplified handoff with minimal tasks, auto-suggest Feature Full.
+**Delta mode:** Handoff for affected features only, reuse existing patterns.
+
+Next agent selection: Feature Full, Ralph Loop, or End BA.