@atlashub/smartstack-cli 3.8.0 → 3.10.0

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

@@ -57,6 +57,50 @@ Include:
 
 ---
 
+### 1b. Cache Warming for Handoff & Deploy
+
+> **Performance Optimization:** Pre-load handoff templates and references to reduce redundant reads during handoff generation.
+> This step runs ONCE at start of step-05a, files retained through step-05b.
+
+```
+// Pre-load handoff & deploy references (Bucket 5)
+const handoffRefs = [
+  "~/.claude/skills/business-analyse/references/handoff-file-templates.md",
+  "~/.claude/skills/business-analyse/references/handoff-mappings.md",
+  "~/.claude/skills/business-analyse/references/deploy-data-build.md",
+  "~/.claude/skills/business-analyse/references/deploy-modes.md",
+  "~/.claude/skills/business-analyse/references/html-data-mapping.md"
+];
+
+for (const file of handoffRefs) {
+  read(file);  // Pre-load into cache
+}
+
+// Pre-load HTML template (large file, loaded once)
+read("~/.claude/skills/business-analyse/html/ba-interactive.html");
+
+Display: "✓ Cache warmed: handoff templates (139KB, 6 files)"
+Display: "  Expected token savings: ~3,000 tokens (handoff refs read 2× → 1×)"
+Display: "  Retention: through step-05b (deploy)"
+```
+
+**Rationale:**
+
+- Handoff templates are read 2× during step-05a + step-05b (without caching)
+- HTML template (85KB) is read once but benefits from explicit pre-load (faster deploy)
+- Token savings: ~3,000 tokens for handoff process
+- Cache retained until session end (needed for both handoff and deploy steps)
+
+**Why NOT loaded at step-00:**
+- Large files (139KB total), especially ba-interactive.html (85KB)
+- Only used at END of workflow (steps 05a, 05b)
+- Low re-use (1-2× each)
+- Loading at step-05a is more efficient (just-in-time caching)
+
+See [references/cache-warming-strategy.md](../references/cache-warming-strategy.md) § Bucket 5 for details.
+
+---
+
 ### 2. Implementation Strategy Choice (Multi-Module)
 
 **IF** more than 1 module defined in feature.json:
@@ -142,410 +186,35 @@ For **EACH module** in topological order:
 > - 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:
-
-```json
-"domain": [
-  {
-    "path": "src/Domain/Entities/{ContextPascal}/{ApplicationName}/{ModuleName}/{EntityName}.cs",
-    "type": "Entity",
-    "linkedFRs": ["FR-001", "FR-002"],
-    "linkedUCs": ["UC-001"],
-    "module": "{moduleCode}"
-  }
-]
-```
-
-Include:
-- 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
-
-From `analysis.useCases[]` of the module:
-
-```json
-"application": [
-  {
-    "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/{ContextPascal}/{ApplicationName}/{ModuleName}/{DtoName}Dto.cs",
-    "type": "Dto",
-    "linkedUCs": ["UC-001"],
-    "module": "{moduleCode}"
-  },
-  {
-    "path": "src/Application/Validators/{ContextPascal}/{ApplicationName}/{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/Persistence/Configurations/{ContextPascal}/{ApplicationName}/{ModuleName}/{EntityName}Configuration.cs",
-    "type": "EFConfiguration",
-    "linkedFRs": ["FR-001"],
-    "module": "{moduleCode}"
-  }
-]
-```
-
-Include:
-- 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
-
-From `specification.apiEndpoints[]` of the module:
-
-```json
-"api": [
-  {
-    "path": "src/API/Controllers/{ContextShort}/{ApplicationName}/{EntityName}Controller.cs",
-    "type": "ApiController",
-    "linkedUCs": ["UC-001", "UC-002"],
-    "linkedFRs": ["FR-001"],
-    "module": "{moduleCode}"
-  }
-]
-```
-
-> **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)
-- Error handling and validation responses
-
-#### 4.5 Frontend Files
+#### 4.1-4.7 File Category Templates
 
-From `specification.uiWireframes[]`, `specification.dashboards[]` and `analysis.useCases[]` of the module:
-
-> **WIREFRAME TRACEABILITY RULE:** Every frontend file (Page, DashboardPage, Component) MUST include `linkedWireframes[]` referencing the wireframe `screen` identifiers from `specification.uiWireframes[]`. This ensures the BA mockups validated by the client are respected during implementation.
-
-```json
-"frontend": [
-  {
-    "path": "src/pages/{ModuleName}/{PageName}Page.tsx",
-    "type": "Page",
-    "linkedUCs": ["UC-001", "UC-002"],
-    "linkedWireframes": ["{module}-list"],
-    "module": "{moduleCode}",
-    "wireframeAcceptanceCriteria": "Layout MUST match wireframe '{module}-list': elements [{elements}], actions [{actions}]. See specification.uiWireframes[] for exact mockup."
-  },
-  {
-    "path": "src/pages/{ModuleName}/{PageName}DetailPage.tsx",
-    "type": "Page",
-    "linkedUCs": ["UC-003"],
-    "linkedWireframes": ["{module}-detail"],
-    "module": "{moduleCode}",
-    "wireframeAcceptanceCriteria": "Layout MUST match wireframe '{module}-detail': elements [{elements}], actions [{actions}]. See specification.uiWireframes[] for exact mockup."
-  },
-  {
-    "path": "src/pages/{ModuleName}/{DashboardName}DashboardPage.tsx",
-    "type": "DashboardPage",
-    "linkedUCs": ["UC-060"],
-    "linkedWireframes": ["{module}-dashboard"],
-    "module": "{moduleCode}",
-    "dashboardRef": "{module}-dashboard",
-    "instructions": "Use Recharts library. See specification.dashboards[] for KPI definitions, chart types, filters, and data sources.",
-    "wireframeAcceptanceCriteria": "Layout MUST match wireframe '{module}-dashboard': KPI card positions, chart placement, filter bar location. See specification.uiWireframes[] AND specification.dashboards[] for exact mockup and KPI specs."
-  },
-  {
-    "path": "src/components/{ModuleName}/{ComponentName}.tsx",
-    "type": "Component",
-    "linkedUCs": ["UC-001"],
-    "linkedWireframes": ["{module}-{section}"],
-    "module": "{moduleCode}"
-  },
-  {
-    "path": "src/hooks/use{ModuleName}{Hook}.ts",
-    "type": "Hook",
-    "linkedUCs": ["UC-001", "UC-002"],
-    "module": "{moduleCode}"
-  }
-]
-```
-
-**Wireframe Acceptance Criteria (ALL frontend pages):**
-> **MANDATORY** for every Page and DashboardPage task. These criteria ensure the BA mockups are respected.
-- Layout structure matches the validated ASCII/SVG wireframe from `specification.uiWireframes[]`
-- All `elements` listed in the wireframe are present in the generated component
-- All `actions` listed in the wireframe are implemented with correct permissions
-- Component mapping follows the wireframe-to-component table (see step-03 section 3b-bis)
-- If wireframe shows a DataGrid → implement with `SmartTable` or `EntityCard` grid
-- If wireframe shows FilterBar → implement with `SmartFilter`
-- If wireframe shows ActionButton → wrap in `RequirePermission`
-
-**Dashboard pages (type: DashboardPage):**
-- Generated from `specification.dashboards[]` entries
-- `dashboardRef` links to the dashboard code in specification.dashboards[]
-- `linkedWireframes` links to the dashboard wireframe in specification.uiWireframes[]
-- `instructions` MUST reference chart types, KPI definitions, and data sources
-- Acceptance criteria for DashboardPage tasks MUST include:
-  - Chart library (Recharts) installed in package.json
-  - Chart types matching specification.dashboards[].kpis[].visualization
-  - KPI cards for kpi-card type visualizations
-  - Filters functional (dateRange, select, etc.)
-  - CSS variables used (no hardcoded colors) - see ui-components/patterns/dashboard-chart.md
-  - Responsive layout (1-col mobile, 2-col tablet, 3-col desktop)
-  - **KPI card positions match wireframe layout** (e.g., 4 cards in a row if wireframe shows 4)
-  - **Chart placement matches wireframe** (e.g., 2-column grid if wireframe shows side-by-side)
-
-**Standard pages (type: Page):**
-- Pages for major use cases
-- Components for reusable UI elements
-- Custom hooks for business logic
-- Forms for data entry
-- List/Detail views
-- **ALL pages MUST reference their wireframe via `linkedWireframes`**
-
-#### 4.6 SeedData Files
-
-**OBLIGATORY:** 5 CORE SeedData entries per module + business seed data:
-
-```json
-"seedData": [
-  {
-    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/NavigationModuleSeedData.cs",
-    "type": "SeedData",
-    "category": "core",
-    "source": "specification.seedDataCore.navigationModules",
-    "module": "{moduleCode}"
-  },
-  {
-    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/PermissionsSeedData.cs",
-    "type": "SeedData",
-    "category": "core",
-    "source": "specification.seedDataCore.permissions",
-    "module": "{moduleCode}"
-  },
-  {
-    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/RolesSeedData.cs",
-    "type": "SeedData",
-    "category": "core",
-    "source": "specification.seedDataCore.roles",
-    "module": "{moduleCode}"
-  },
-  {
-    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/TenantSeedData.cs",
-    "type": "SeedData",
-    "category": "core",
-    "source": "specification.seedDataCore.tenants",
-    "module": "{moduleCode}"
-  },
-  {
-    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/UserSeedData.cs",
-    "type": "SeedData",
-    "category": "core",
-    "source": "specification.seedDataCore.users",
-    "module": "{moduleCode}"
-  },
-  {
-    "path": "src/Infrastructure/Persistence/Seeding/Data/{ModuleName}/{Entity}SeedData.cs",
-    "type": "SeedData",
-    "category": "business",
-    "source": "specification.seedDataBusiness.{module}",
-    "module": "{moduleCode}"
-  }
-]
-```
-
-**For client projects (ExtensionsDbContext), add these MANDATORY infrastructure files:**
-
-```json
-"seedData": [
-  // ... 5 core + business entries above ...
-  {
-    "path": "src/Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs",
-    "type": "IClientSeedDataProvider",
-    "category": "infrastructure",
-    "description": "Runtime provider that injects core seed data (navigation, permissions, roles) into Core schema",
-    "source": "specification.seedDataCore",
-    "module": "{moduleCode}"
-  },
-  {
-    "path": "src/Infrastructure/Persistence/Seeding/DevDataSeeder.cs",
-    "type": "DevDataSeeder",
-    "category": "infrastructure",
-    "description": "Seeds development/demo data for domain entities at startup",
-    "module": "{moduleCode}"
-  },
-  {
-    "path": "src/Infrastructure/Persistence/Seeding/Data/SeedConstants.cs",
-    "type": "SeedConstants",
-    "category": "infrastructure",
-    "description": "Shared constants for deterministic seed data",
-    "module": "{moduleCode}"
-  }
-]
-```
+See [references/handoff-file-templates.md](../references/handoff-file-templates.md) for the complete JSON templates for all 7 categories:
 
-**Path convention:** All seed data files MUST be under `Persistence/Seeding/Data/` (matching SmartStack.app architecture).
-NEVER use `Data/SeedData/` or `Infrastructure/Data/SeedData/`.
+| Category | Source | Key rules |
+|----------|--------|-----------|
+| **4.1 Domain** | `analysis.entities[]` | Entities, ValueObjects, Enums, Exceptions |
+| **4.2 Application** | `analysis.useCases[]` | Services, DTOs, Validators |
+| **4.3 Infrastructure** | `analysis.entities[]` | EF Configurations, DbSet, DI |
+| **4.4 API** | `specification.apiEndpoints[]` | Controllers with `{ContextShort}` mapping |
+| **4.5 Frontend** | `specification.uiWireframes[]` | Pages, Components, Hooks + wireframe traceability |
+| **4.6 SeedData** | `specification.seedDataCore` | 5 CORE + business + IClientSeedDataProvider |
+| **4.7 Tests** | All layers | Unit, Integration, Security tests |
 
-**IClientSeedDataProvider (MANDATORY for client projects):** This provider injects core seed data
-(navigation, permissions, roles) into the Core schema at runtime. Generated at
-`src/Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`.
-See `/application` skill step-03b-provider for the full pattern.
-Without this provider, the 5 core SeedData files are DEAD CODE and will have no effect.
-
-Core categories (ALWAYS 5):
-1. NavigationModuleSeedData (navigation items for module)
-2. PermissionsSeedData (RBAC permissions)
-3. RolesSeedData (roles using permissions)
-4. TenantSeedData (test tenants)
-5. UserSeedData (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/{ContextPascal}/{ApplicationName}/{ModuleName}/{Entity}Tests.cs",
-    "type": "UnitTests",
-    "linkedFRs": ["FR-001"],
-    "module": "{moduleCode}"
-  },
-  {
-    "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/{ContextPascal}/{ApplicationName}/{ModuleName}/{ApiControllerName}ControllerTests.cs",
-    "type": "IntegrationTests",
-    "linkedUCs": ["UC-001"],
-    "module": "{moduleCode}"
-  },
-  {
-    "path": "src/Tests/Security/{ContextPascal}/{ApplicationName}/{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
+**Critical rules:**
+- All backend paths include `{ContextPascal}/{ApplicationName}/` hierarchy
+- Frontend pages MUST have `linkedWireframes[]` + `wireframeAcceptanceCriteria`
+- SeedData: 5 CORE entries ALWAYS + IClientSeedDataProvider for client projects
+- Path convention: `Persistence/Seeding/Data/` (NEVER `Data/SeedData/`)
 
 ---
 
 ### 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}
+See [references/handoff-mappings.md](../references/handoff-mappings.md) — Section "Business Rules to Code Mapping".
 
-Layers: Domain, Application, Infrastructure, API, Frontend
+For each BR in `analysis.businessRules[]` of EACH module, generate:
+- **ruleId**, **title**, **module**, **severity** (critical/high/medium/low)
+- **implementationPoints**: Array of `{layer, component, method, implementation}` across Domain, Application, Infrastructure, API, Frontend
 
 ---
 
@@ -553,50 +222,9 @@ Layers: Domain, Application, Infrastructure, API, Frontend
 
 > **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}"
-    }
-  ]
-}
-```
+See [references/handoff-mappings.md](../references/handoff-mappings.md) — Section "API Endpoint Summary".
 
-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
+For each endpoint: operation, method, route, linkedUC, linkedFR, permissions, requestSchema, responseSchema, errorCodes, module.
 
 Total endpoints = count of specification.apiEndpoints[] across all modules.