@atlashub/smartstack-cli 3.10.0 → 3.12.0

package/templates/skills/business-analyse/steps/step-03a1-setup.md

@@ -0,0 +1,356 @@
+---
+name: step-03a1-setup
+description: Module setup, sections walkthrough, questionnaires, and cross-module references
+model: opus
+next_step: steps/step-03a2-analysis.md
+---
+
+> **Context files:** `_shared.md` | `_elicitation.md` | `_architecture.md` | `_module-loop.md`
+
+# Step 3a1: Setup - Module Initialization
+
+## MANDATORY EXECUTION RULES
+
+- ALWAYS use ULTRATHINK mode
+- This step is EXECUTED ONCE PER MODULE in topological dependency order
+- ALWAYS check workflow state to determine current module
+- ALWAYS reference completed modules when specifying current one
+- **MANDATORY:** Generate and validate an ASCII/SVG mockup for EVERY section (not optional)
+- ALL questions via AskUserQuestion tool
+- ALL communication in `{language}`
+- NEVER skip per-module validation
+- **ID NAMING RULE (MANDATORY, NO EXCEPTION):**
+  All IDs MUST include a module prefix to guarantee application-wide uniqueness.
+  The prefix is derived from the module code initials (2-4 chars):
+    UserManagement → UM | VehicleManagement → VM | PartsInventory → PI
+    RepairManagement → RM | MaintenanceSchedule → MS | DataSync → DS
+    Notifications → NT | Dashboard → DB | Orders → OR | Customers → CU
+
+  Patterns:
+    UC-{PREFIX}-{NNN}        → UC-RM-001, UC-PI-003
+    BR-{CAT}-{PREFIX}-{NNN}  → BR-VAL-RM-001, BR-CALC-PI-002
+    FR-{PREFIX}-{NNN}        → FR-RM-001
+    OBJ-{PREFIX}-{NNN}       → OBJ-RM-001
+    AC-{PREFIX}-{NNN}        → AC-RM-001
+    RISK-{PREFIX}-{NNN}      → RISK-RM-001
+
+  NEVER use bare IDs (UC-001, BR-VAL-001) in multi-module mode.
+- **SCHEMA CONFORMITY RULE:**
+  ALL data MUST fit within the defined feature-schema.json structure.
+  NEVER create custom top-level fields (KPIDefinitions, ChartConfigurations, etc.)
+  Dashboard modules MUST use specification.dashboards[] (it exists in the schema).
+  If truly needed, use specification.extensions: {} (additionalProperties: true).
+
+## YOUR TASK
+
+Specify one module's data model and business logic: walk through sections, define entities, business rules, and validate with client before proceeding to UI specification.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Determine Current Module
+
+```
+ba-reader.readApplicationContext({feature_id})
+→ Read metadata.workflow: moduleOrder, currentModuleIndex, completedModules
+→ currentModule = moduleOrder[currentModuleIndex]
+→ Display: "═══ Module {currentModuleIndex + 1}/{moduleOrder.length}: {currentModule} ═══"
+```
+
+IF module already specified (status = "specified" in master):
+  Increment currentModuleIndex, re-check
+  IF all modules specified → Load step-04-consolidation.md, STOP
+
+### 1b. Cache Warming for Module Loop (FIRST MODULE ONLY)
+
+> **Performance Optimization:** Pre-load module specification references to reduce redundant reads across all modules.
+> This step runs ONLY for the FIRST module (currentModuleIndex = 0), not repeated for subsequent modules.
+
+```
+IF currentModuleIndex === 0:
+  // Pre-load module specification references (Bucket 3)
+  const moduleRefs = [
+    "~/.claude/skills/business-analyse/references/spec-auto-inference.md",
+    "~/.claude/skills/business-analyse/references/ui-resource-cards.md",
+    "~/.claude/skills/business-analyse/references/ui-dashboard-spec.md",
+    "~/.claude/skills/business-analyse/references/cadrage-vibe-coding.md"
+  ];
+
+  for (const file of moduleRefs) {
+    read(file);  // Pre-load into cache
+  }
+
+  Display: "✓ Cache warmed: module specification references (23KB, 4 files)"
+  Display: "  Expected token savings: 75% reduction in reference reads across module loop"
+  Display: "  Retention: until step-04 (after all modules specified)"
+ELSE:
+  // Subsequent modules use cached references (no re-load)
+  Display: "✓ Using cached module references (from first module)"
+```
+
+**Rationale:**
+
+- Module specification references are read 2-3× PER MODULE (5 modules = 10-15 reads without caching)
+- Pre-loading once at start of module loop eliminates 75% of redundant reads
+- Token savings: ~10,000 tokens for a 5-module application
+- Cache retained until step-04 (when consolidation starts, references no longer needed)
+
+See [references/cache-warming-strategy.md](../references/cache-warming-strategy.md) § Bucket 3 for details.
+
+### 2. Initialize Module Feature.json
+
+```
+// Create or load module-level feature.json
+ba-writer.create({
+  scope: "module",
+  applicationRef: {feature_id},
+  moduleCode: {currentModule.code},
+  path: "docs/business/{app}/{module_code}/business-analyse/v1.0/feature.json"
+})
+
+// Inherit application roles from master
+ba-reader.readApplicationContext({feature_id})
+→ Copy cadrage.applicationRoles → module.applicationContext.applicationRoles
+```
+
+// Update module status in master: "pending" → "in-progress"
+ba-writer.updateModuleStatus({feature_id}, {currentModule.code}, "in-progress")
+
+### 2-ter. Derive Module Discovery Section (MANDATORY)
+
+> **The module feature.json MUST have a `discovery` section.** In multi-module mode, derive it from the parent application's `cadrage`. In single-module mode, it should already exist from step-01.
+
+```
+ba-reader.readApplicationContext({feature_id})
+→ Read cadrage: problem, asIs, toBe, trigger, stakeholders, risks, acceptanceCriteria
+
+// Filter to this module's scope
+moduleScope = cadrage.coverageMatrix.filter(cm => cm.module === currentModule.code)
+moduleStakeholders = cadrage.stakeholders.filter(s => s.tasks relevant to this module)
+moduleRisks = cadrage.risks.filter(r => r related to this module)
+
+ba-writer.enrichSection({
+  featureId: {module_feature_id},
+  section: "discovery",
+  data: {
+    problem: cadrage.problem,
+    asIs: cadrage.asIs,
+    toBe: cadrage.toBe,
+    trigger: cadrage.trigger,
+    stakeholders: moduleStakeholders,
+    scope: {
+      mustHave: moduleScope.filter(s => s.category === "mustHave").map(s => s.item),
+      shouldHave: moduleScope.filter(s => s.category === "shouldHave").map(s => s.item),
+      couldHave: moduleScope.filter(s => s.category === "couldHave").map(s => s.item),
+      outOfScope: []
+    },
+    risks: moduleRisks,
+    acceptanceCriteria: cadrage.acceptanceCriteria.filter(ac => relevant to module),
+    codebaseContext: cadrage.codebaseContext
+  }
+})
+```
+
+> **STRUCTURE CARD: discovery** — Same format as cadrage but module-scoped.
+> Fields: `problem`, `asIs`, `toBe`, `trigger`, `stakeholders[]`, `scope{}`, `risks[]`, `acceptanceCriteria[]`, `codebaseContext`, `openQuestions[]`
+
+### 2-bis. Coverage Verification (MANDATORY)
+
+> **Before specifying any module, verify that the coverageMatrix from cadrage covers this module.**
+
+```
+ba-reader.readApplicationContext({feature_id})
+→ Read cadrage.coverageMatrix[]
+→ Filter entries where module = {currentModule.code}
+→ Group by category: mustHave, shouldHave, couldHave
+```
+
+Display to client:
+```
+Module {currentModule}: Coverage from original brief
+
+| # | Requirement | Category |
+|---|-------------|----------|
+| 1 | {item} | {category} |
+| ... | ... | ... |
+
+Total: {N} requirements mapped to this module
+  - Must-have: {count}
+  - Should-have: {count}
+  - Could-have: {count}
+```
+
+**VALIDATION:** If mustHave count = 0 AND module is in must priority:
+  → WARNING: "Module {currentModule} is must-priority but has no must-have requirements in coverageMatrix. Verify cadrage coverage."
+
+**POST-SPECIFICATION CHECK (at end of module, before advancing):**
+  For EACH mustHave item in coverageMatrix for this module:
+    → Verify at least 1 UC exists that covers this requirement
+    → If uncovered: BLOCK and ask client to either add a UC or reclassify the requirement
+
+### 3. Section Walkthrough with Client
+
+> **This is the key interactive phase aligned with the 5-level SmartStack hierarchy.**
+> Level 3 = Module, Level 4 = Section, Level 5 = Resource
+
+#### 3a. Identify Module Sections
+
+For each module, propose standard sections based on module type:
+
+| Module Type | Typical Sections |
+|-------------|-----------------|
+| data-centric | list, detail, create, edit |
+| workflow | list, detail, create, edit, approve, history |
+| integration | list, detail, config, sync, logs |
+| reporting | dashboard, detail, export, schedule |
+| full-module | list, detail, create, edit, approve, history, reports, settings |
+
+Ask via AskUserQuestion:
+
+```
+question: "Quelles sections le module {currentModule} doit-il avoir ?"
+header: "Sections"
+multiSelect: true
+options:
+  - label: "Liste"
+    description: "Page de liste avec filtres, tri et pagination"
+  - label: "Détail"
+    description: "Page de détail d'un enregistrement"
+  - label: "Création/Édition"
+    description: "Formulaire de création et de modification"
+  - label: "Validation/Approbation"
+    description: "Workflow de validation avec changement de statut"
+  - label: "Dashboard"
+    description: "Tableau de bord avec KPIs, graphiques (Recharts) et métriques clés"
+```
+
+#### 3a-depth. Determine Specification Depth
+
+> **Based on module complexity and type, determine how deeply to specify sections and resources.**
+> **This avoids over-specifying simple modules and under-specifying complex ones.**
+
+Read from application master:
+```
+ba-reader.readApplicationContext({feature_id})
+→ module = modules.find(m => m.code === currentModule)
+→ complexity = module.estimatedComplexity   // simple | medium | complex
+→ featureType = module.featureType          // data-centric | workflow | integration | reporting | full-module
+```
+
+**Depth decision matrix:**
+
+| Complexity | featureType | Depth | Behavior |
+|---|---|---|---|
+| simple | data-centric | **convention** | Auto-generate sections + resources from entities. Quick client validation. |
+| simple | reporting | **convention** | Standard dashboard template. Quick validation. |
+| simple | * | **convention** | Standard sections for featureType. Quick validation. |
+| medium | data-centric | **override** | Auto-generate then ask client which sections to customize. |
+| medium | workflow | **full** | State machine required → always full. |
+| medium | * | **override** | Auto-generate then ask client to customize. |
+| complex | * | **full** | Full specification: state machine, typed columns, conditional actions. |
+| * | workflow | **full** | Always full for workflow modules (state machine is mandatory). |
+
+Display to client:
+```
+"Module {currentModule}: complexité {complexity}, type {featureType} → profondeur: {depth}"
+```
+
+**IF depth = convention:**
+  - Execute 3a-infer (auto-inference) → generates sections + resources
+  - Execute 3b (wireframes) for each section
+  - Skip 3a-bis detailed walkthrough → present auto-generated spec for quick validation
+  - Ask client: "La spécification auto-générée convient-elle, ou souhaitez-vous personnaliser certaines sections ?"
+    - If client says OK → proceed to step 4 (questionnaires)
+    - If client wants changes → switch to **override** for specified sections
+
+**IF depth = override:**
+  - Execute 3a-infer (auto-inference) → generates base sections + resources
+  - Ask client: "Quelles sections souhaitez-vous personnaliser ?"
+  - For selected sections → execute full 3a-bis + 3b + 3b-ter
+  - For other sections → keep auto-generated spec
+
+**IF depth = full:**
+  - Execute standard flow: 3a-bis → 3b → 3b-bis → 3b-ter → 3c → 3d (as currently defined below)
+  - PLUS: 3a-state (state machine definition) for entities with status fields
+
+#### 3a-infer. Auto-Infer Resources from Entities (Convention/Override)
+
+> **For convention and override depths, auto-generate resource details from entity definitions.**
+> **The goal: produce a complete spec without manual input, that the client only validates.**
+
+**Prerequisites:** Entity attributes must be defined (from step 6) OR anticipated from decomposition.
+
+See [references/spec-auto-inference.md](../references/spec-auto-inference.md) for complete inference rules:
+- Entity attribute → SmartTable column mapping (9 type rules)
+- Entity attribute → SmartForm field mapping (8 type rules)
+- Auto-generated sections per featureType (5 types)
+- Section generation rules (list, create, detail, edit, dashboard)
+- Status/lifecycle enhancement rules
+
+Write auto-generated sections to `specification.sections[]` via ba-writer.enrichSection()
+
+### 4. Conditional Questionnaires
+
+Based on module type, load questionnaires per-module:
+
+| Condition | Category | Questionnaire |
+|-----------|----------|---------------|
+| Always | 04 | `questionnaire/04-data.md` |
+| Has UI sections | 07 | `questionnaire/07-ui.md` |
+| Has lifecycle | 11 | `questionnaire/11-data-lifecycle.md` |
+| Has migration needs | 12 | `questionnaire/12-migration.md` |
+| References other modules | 13 | `questionnaire/13-cross-module.md` |
+| Documentation needed | 10 | `questionnaire/10-documentation.md` |
+
+Ask via AskUserQuestion, 1-2 batches per category.
+
+#### Store Documentation Requirements
+
+If questionnaire 10 was loaded, persist answers in feature.json:
+
+```
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "documentation",
+  data: {
+    userDocRequired: {Q10.1 answer == "Yes"},
+    techDocRequired: {Q10.2 answer == "Yes"},
+    status: "pending"
+  }
+})
+```
+
+This data will be consumed by `/application` step-08 to auto-generate in-app documentation.
+
+### 5. Cross-Module References
+
+> Reference completed modules to help define current one.
+
+```
+completedModules = ba-reader.getCompletedModulesSummary({feature_id})
+→ Returns max 100 lines summary: entity names, key BRs, permissions
+
+Display: "Modules déjà spécifiés : {completedModules.map(m => m.code).join(', ')}"
+```
+
+For each completed module's entities, ask:
+
+```
+question: "Le module {currentModule} référence-t-il des entités de {completedModule} ?"
+header: "Références"
+multiSelect: true
+options:
+  - label: "{Entity1} (FK)"
+    description: "Référence directe via clé étrangère"
+  - label: "{Entity2} (Lookup)"
+    description: "Table de référence / lookup"
+  - label: "Aucune"
+    description: "Pas de référence à {completedModule}"
+```
+
+---
+
+## NEXT STEP
+
+Load: `./step-03a2-analysis.md`

package/templates/skills/business-analyse/steps/step-03a2-analysis.md

@@ -0,0 +1,143 @@
+---
+name: step-03a2-analysis
+description: Analysis section - objectives, entities, business rules, process flow
+model: opus
+next_step: steps/step-03b-ui.md
+---
+
+> **Context files:** `_shared.md` | `_elicitation.md` | `_architecture.md` | `_module-loop.md`
+
+# Step 3a2: Analysis - Entities & Business Logic
+
+## MANDATORY EXECUTION RULES
+
+- ALWAYS use ULTRATHINK mode
+- This step follows step-03a1-setup.md (module already initialized)
+- **ID NAMING RULE:** All IDs MUST include module prefix (BR-{CAT}-{PREFIX}-{NNN}, OBJ-{PREFIX}-{NNN}, etc.)
+- **SCHEMA CONFORMITY RULE:** ALL data MUST fit within feature-schema.json structure
+
+## YOUR TASK
+
+Define the module's analysis section: objectives, entities (with attributes and relationships), business rules, process flow, and data lifecycle.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 6. Analysis Section
+
+#### 6a. Objectives
+
+Define measurable business objectives for this module:
+
+> **STRUCTURE CARD: analysis.objectives[]**
+> ```json
+> { "id": "OBJ-{PREFIX}-001", "objective": "Reduce order processing time", "metric": "Average time to fulfillment", "target": "< 4 hours" }
+> ```
+
+#### 6b. Entity Definition
+
+Define entities for this module (business attributes, not technical):
+
+> **STRUCTURE CARD: analysis.entities[]** — Field names are EXACT. Do NOT deviate.
+> ```json
+> {
+>   "name": "PascalCase",
+>   "description": "1-2 sentences describing the entity purpose",
+>   "attributes": [
+>     {
+>       "name": "attributeName",
+>       "description": "What this attribute represents",
+>       "required": true,
+>       "unique": false,
+>       "validation": "Format: XXX-NNNNN, max 100 chars, etc."
+>     }
+>   ],
+>   "relationships": [
+>     { "target": "OtherEntity", "type": "1:1|1:N|N:1|N:M", "description": "description" }
+>   ]
+> }
+> ```
+> **FORBIDDEN fields in attributes:** Do NOT use `type`, `values`, `rules`.
+> Use `description` to explain what the attribute is, `validation` for format/constraint rules, `unique` as boolean.
+
+#### 6c. Process Flow
+
+Define the main business process flow for this module (not lifecycle — that's in 8j):
+
+> **STRUCTURE CARD: analysis.processFlow**
+> ```json
+> {
+>   "entryPoints": ["User navigates to module", "System event triggers action"],
+>   "mainFlow": [
+>     { "step": 1, "actor": "Manager", "action": "Opens the list", "system": "Displays filtered records" },
+>     { "step": 2, "actor": "Manager", "action": "Creates a record", "system": "Validates BR-VAL-{PREFIX}-001" },
+>     { "step": 3, "actor": "System", "action": "Saves record", "system": "Sends notification" }
+>   ],
+>   "decisionPoints": [
+>     { "condition": "Is amount > threshold?", "ifTrue": "Route to approver", "ifFalse": "Auto-approve", "rule": "BR-WF-{PREFIX}-001" }
+>   ],
+>   "alternativeFlows": ["Bulk import via CSV", "Automatic sync from SFTP"]
+> }
+> ```
+> **FORBIDDEN:** Do NOT put lifecycle/state machine data here. Use `specification.lifeCycles[]` for that.
+
+#### 6d. Data Lifecycle
+
+Define data retention and lifecycle policies:
+
+> **STRUCTURE CARD: analysis.dataLifecycle**
+> ```json
+> {
+>   "retentionPeriod": "7 years",
+>   "archiveStrategy": "Move to cold storage after 2 years",
+>   "gdprCompliance": "PII anonymized on request, data export available",
+>   "states": [
+>     { "name": "active", "transitions": ["archived", "deleted"] },
+>     { "name": "archived", "transitions": ["active"] },
+>     { "name": "deleted", "transitions": [] }
+>   ]
+> }
+> ```
+
+### 7. Business Rules Extraction
+
+Extract business rules specific to this module:
+
+> **STRUCTURE CARD: analysis.businessRules[]** — Field names are EXACT. Do NOT deviate.
+> ```json
+> {
+>   "id": "BR-VAL-{PREFIX}-001",
+>   "name": "Short rule name",
+>   "category": "validation|calculation|workflow|security|data",
+>   "statement": "IF {condition} THEN {consequence} ELSE {alternative}",
+>   "priority": "must|should|could",
+>   "conditions": ["Condition 1", "Condition 2"],
+>   "examples": [{ "input": "Order total $5000, budget $2000", "expected": "Order rejected" }],
+>   "testability": "Via unit test with mock data / integration test"
+> }
+> ```
+> **MANDATORY fields:** `id`, `name`, `category`, `statement`, `priority`
+> **FORBIDDEN fields:** Do NOT use `rule`, `condition` (singular), `action`. Use `name` + `statement` (IF/THEN/ELSE format) + `conditions` (array).
+> **ID PATTERN:** `BR-{CAT}-{PREFIX}-{NNN}` where CAT = VAL|CALC|WF|SEC|DATA, PREFIX = module initials (2-4 chars)
+> **category values:** lowercase only: `validation`, `calculation`, `workflow`, `security`, `data`
+
+---
+
+## SELF-VERIFICATION (MANDATORY before loading step-03b-ui)
+
+Before proceeding to step-03b-ui.md, VERIFY:
+
+1. **Module feature.json exists** at expected path (`docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`)
+2. **Module feature.json has analysis section** with `entities[]` (at least 1) and `businessRules[]` (at least 1)
+3. **Module status in master** = "in-progress" (set by section 2 above)
+4. **Master modules[].featureJsonPath** for this module ≠ null (set by ba-writer.create)
+5. **Sections identified** with clear roles and entities assigned
+
+**IF any check fails → FIX before proceeding.** Do NOT load step-03b-ui with incomplete data.
+
+---
+
+## NEXT STEP
+
+Load: `steps/step-03b-ui.md`

package/templates/skills/business-analyse/steps/step-03b-ui.md

@@ -125,6 +125,7 @@ For EACH section confirmed in 3a, build the `specification.sections[]` structure
 See [references/ui-resource-cards.md](../references/ui-resource-cards.md) for exact JSON formats of `specification.sections[]` (SmartTable + SmartForm resources).
 **MANDATORY for SmartTable:** `columnDefs`, `rowActions`, `defaultSort`, `emptyState`
 **MANDATORY for SmartForm:** `fields` with `component` type, `formLayout`
+**FORM FIELD COMPLETENESS RULE:** SmartForm `fields[]` MUST include ALL entity attributes EXCEPT system/audit fields (Id, CreatedAt, CreatedBy, ModifiedAt, ModifiedBy, IsDeleted, TenantId). Missing fields = incomplete form = FAIL.
 
 5. Write `specification.sections[]` via ba-writer.enrichSection()
 
@@ -238,6 +239,8 @@ Before proceeding to step-03c-compile.md, VERIFY:
 3. **All wireframes have layout** with regions and resourceRef references
 4. **All resource references** in layout.regions[].components[].resourceRef exist in sections[].resources[]
 5. **State machines defined** (if module has status fields) in `specification.lifeCycles[]`
+6. **Form field completeness** — SmartForm fields[] covers ALL entity attributes except system/audit fields
+7. **Navigation entries for all sections** — Every section (including dashboard) has a corresponding entry in `specification.navigation.entries[]`
 
 **IF any check fails → FIX before proceeding.** Do NOT load step-03c-compile with incomplete data.
 

package/templates/skills/business-analyse/steps/step-03c-compile.md

@@ -395,7 +395,7 @@ Before loading step-03d-validate, verify all 12 subsections (8a-8l) are populate
 3. **8c. Functional Requirements** - At least 4 FRs with linked UCs and BRs
 4. **8d. Permission Matrix** - Resources and role assignments defined
 5. **8e. Navigation** - Module, sections, and resource routes specified
-6. **8f. SeedData Core** - All 5 arrays populated with structured objects
+6. **8f. SeedData Core** - All 7 arrays populated with structured objects (navigationModules, navigationSections, navigationResources, navigationTranslations, permissions, rolePermissions, permissionConstants)
 7. **8g. Gherkin Scenarios** - BDD scenarios for each major UC
 8. **8h. Validations** - Field rules with error message keys
 9. **8i. Business Messages** - Minimum 4 messages (success, error CRUD, validation, permission)