@atlashub/smartstack-cli 4.18.0 → 4.20.0

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

@@ -0,0 +1,198 @@
+---
+name: step-03-specify
+description: Sequential deep dive per module - entities, BRs, UCs, permissions, screens
+model: opus
+next_step: steps/step-04-consolidate.md
+---
+
+# Step 03 — Specify (Deep Dive per Module)
+
+## Objective
+
+For each module (in dependency order), produce complete specifications: entities, business rules, use cases, permissions, and interface specs (screens).
+
+## Prerequisites
+
+- Step 02 (structure) completed
+- Applications, modules, sections, dependencies identified
+
+## Sequential Execution
+
+**No team mode.** Each module receives 100% of LLM attention for maximum specification quality.
+
+Process modules in topological order (dependencies first):
+```
+For module in topologicalSort(modules):
+    specify(module)
+```
+
+## Per-Module Specification Loop
+
+For each module, execute these sub-steps:
+
+### A. Context Loading
+
+Load via ba-reader:
+- Module's `index.json` (if exists from previous run)
+- Application `cadrage.json` for stakeholder context
+- Completed modules' summaries (compact, <100 lines each)
+
+### B. Entities
+
+For each entity identified in step 02:
+
+```json
+{
+  "name": "Employee",
+  "description": "Represente un employe de l'entreprise",
+  "attributes": [
+    { "name": "code", "type": "string", "required": true, "description": "Identifiant unique" },
+    { "name": "userId", "type": "guid", "required": true, "description": "Reference vers l'utilisateur" },
+    { "name": "departmentId", "type": "guid", "required": true, "description": "Departement d'affectation" },
+    { "name": "hireDate", "type": "date", "required": true, "description": "Date d'embauche" },
+    { "name": "position", "type": "string", "description": "Poste occupe" },
+    { "name": "status", "type": "enum", "options": ["Active", "Inactive", "OnLeave", "Terminated"], "description": "Statut de l'employe" }
+  ],
+  "relationships": [
+    { "target": "Department", "type": "ManyToOne", "description": "Appartient a un departement" },
+    { "target": "Contract", "type": "OneToMany", "description": "Possede plusieurs contrats" }
+  ]
+}
+```
+
+### C. Business Rules
+
+For each entity/process, identify rules:
+
+```json
+{
+  "id": "BR-VAL-EMPLOYEES-001",
+  "name": "Validation date embauche",
+  "category": "validation",
+  "statement": "La date d'embauche ne peut pas etre dans le futur",
+  "example": "Date embauche = 2027-01-01 → erreur car > date du jour",
+  "entities": ["Employee"],
+  "severity": "blocking"
+}
+```
+
+Categories: `validation`, `calculation`, `workflow`, `security`, `data`
+
+### D. Use Cases
+
+For each stakeholder action:
+
+```json
+{
+  "id": "UC-EMPLOYEES-001",
+  "name": "Creer un employe",
+  "actor": "Responsable RH",
+  "preconditions": ["L'utilisateur a la permission HumanResources.Employees.Create"],
+  "steps": [
+    "L'utilisateur ouvre la page de creation",
+    "Il remplit les champs obligatoires (nom, departement, date embauche)",
+    "Il valide le formulaire",
+    "Le systeme verifie les regles metier (BR-VAL-EMPLOYEES-001)",
+    "Le systeme cree l'employe et affiche la fiche"
+  ],
+  "alternative": "Si les donnees sont invalides, le systeme affiche les erreurs",
+  "businessRules": ["BR-VAL-EMPLOYEES-001"],
+  "result": "L'employe est cree avec le statut 'Actif'"
+}
+```
+
+### E. Permissions
+
+Define the permission matrix:
+
+```json
+{
+  "roles": ["RH Admin", "Manager", "Employee"],
+  "matrix": [
+    { "role": "RH Admin", "permissions": ["Read", "Create", "Update", "Delete", "Export"] },
+    { "role": "Manager", "permissions": ["Read", "Export"] },
+    { "role": "Employee", "permissions": ["Read"] }
+  ],
+  "permissionPaths": [
+    "HumanResources.Employees.Read",
+    "HumanResources.Employees.Create",
+    "HumanResources.Employees.Update",
+    "HumanResources.Employees.Delete",
+    "HumanResources.Employees.Export"
+  ]
+}
+```
+
+### F. Interface Specs (Screens)
+
+For each section/resource identified in step 02, specify the full interface:
+
+```json
+{
+  "sectionCode": "list",
+  "sectionLabel": "Liste des employes",
+  "resources": [
+    {
+      "code": "employees-grid",
+      "type": "SmartTable",
+      "label": "Grille des employes",
+      "columns": [
+        { "field": "code", "label": "Code", "type": "text", "sortable": true },
+        { "field": "fullName", "label": "Nom complet", "type": "text", "sortable": true },
+        { "field": "department.name", "label": "Departement", "type": "lookup", "filterable": true },
+        { "field": "status", "label": "Statut", "type": "badge", "filterable": true }
+      ],
+      "actions": ["create", "edit", "delete", "export"],
+      "filters": ["department", "status"],
+      "permission": "HumanResources.Employees.Read"
+    }
+  ]
+}
+```
+
+Resource types:
+- **SmartTable**: columns[], actions[], filters[], permission
+- **SmartForm**: tabs[{ label, fields[{ field, label, type, required, readonly, options }] }], actions[], permission
+- **SmartCard**: columns/fields[], permission
+- **SmartKanban**: options/columns[], permission
+- **SmartDashboard**: kpis[{ label, value }], permission
+- **SmartFilter**: options[], permission
+
+### G. Write & Advance
+
+After completing all sub-steps for a module:
+
+1. Write via ba-writer:
+   - `entities.json`
+   - `rules.json`
+   - `usecases.json`
+   - `permissions.json`
+   - `screens.json`
+   - Update `index.json` (hashes, summary counts)
+
+2. Update module status to `specified`
+
+3. Advance to next module in topological order
+
+### H. Module Completion Check
+
+After all modules are specified:
+- Verify all modules have status `specified`
+- Display summary: total entities, rules, UCs, permissions, screens across all modules
+- Transition to step 04
+
+## POST-CHECK
+
+Before advancing to step 04, verify:
+- [ ] Every module has at least 1 entity
+- [ ] Every module has at least 1 use case
+- [ ] Every module has at least 1 business rule
+- [ ] Every module has permissions defined
+- [ ] Every module has at least 1 screen defined
+- [ ] All entity relationships reference existing entities
+- [ ] All UC business rule references exist
+- [ ] All permission paths follow the convention
+
+## Transition
+
+→ Step 04 (consolidate) — Cross-module validation

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

@@ -0,0 +1,478 @@
+---
+name: step-04-consolidate
+description: Cross-module validation - data model, permissions, E2E flows, approval
+model: opus
+next_step: steps/step-05-deploy.md
+---
+
+> **Context files:** `_shared.md`
+
+# Step 4: Consolidate - Cross-Module Validation & Approval
+
+## MANDATORY EXECUTION RULES
+- ALWAYS load granular JSON files via index.json (entities.json, rules.json, permissions.json, etc.)
+- ALWAYS validate permission coherence across modules
+- ALWAYS execute semantic validation checks
+- NEVER duplicate module content - work with summaries only
+- Single-module shortcut: auto-approve consolidation if only 1 module
+
+## YOUR TASK
+Consolidate all modules by validating cross-module interactions, permission coherence, data model integrity, E2E flows, and global risks. Obtain client approval and write consolidation data to validation.json.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Load Completed Modules & Validate Status
+
+```
+ba-reader.getCompletedModulesSummary({feature_id})
+→ For each module: code, entities[], key BRs, permissions[], dependencies
+→ Max 100 lines per module summary
+
+ba-reader.readApplicationContext({feature_id})
+→ cadrage.applicationRoles, modules[], dependencyGraph
+
+IF status already "consolidated":
+  Display: "Consolidation already completed. Loading step-05-deploy."
+  Load: steps/step-05-deploy.md
+  STOP
+```
+
+### 2. Cross-Module Interaction Analysis
+
+**2a. Load Module Index Files**
+
+For each completed module, read `index.json` and discover granular files:
+
+```javascript
+const moduleFiles = {
+  entities: "entities.json",
+  rules: "rules.json",
+  usecases: "usecases.json",
+  permissions: "permissions.json",
+  screens: "screens.json"
+};
+
+for (const module of completedModules) {
+  const index = ba-reader.readSection(module.code, "index");
+  module.files = index.files;
+  // Load only files needed for consolidation
+  module.entities = ba-reader.readSection(module.code, "entities");
+  module.permissions = ba-reader.readSection(module.code, "permissions");
+}
+```
+
+**2b. Foreign Key References & Shared Entities**
+
+Build entity registry and validate cross-module references:
+
+```javascript
+const entityRegistry = {};
+for (const module of completedModules) {
+  entityRegistry[module.code] = {
+    entities: module.entities.map(e => ({
+      name: e.name,
+      attributes: e.attributes.map(a => a.name),
+      pk: e.attributes.find(a => a.name === "Id" || a.unique)?.name || "Id"
+    }))
+  };
+}
+
+// Detect shared entities
+const sharedEntities = [];
+for (const module of completedModules) {
+  for (const entity of module.entities) {
+    for (const rel of entity.relationships || []) {
+      if (rel.target.includes(".")) {
+        const [targetModule, targetEntity] = rel.target.split(".");
+        if (!entityRegistry[targetModule]) {
+          BLOCKING_ERROR(`Module ${module.code}: references non-existent module "${targetModule}"`);
+        }
+        sharedEntities.push({
+          entity: targetEntity,
+          definedIn: targetModule,
+          referencedBy: module.code,
+          referenceType: rel.type
+        });
+      }
+    }
+  }
+}
+```
+
+**2c. Detect Circular Dependencies**
+
+```javascript
+const cycles = detectCycles(dependencyGraph);
+if (cycles.length > 0) {
+  BLOCKING_ERROR("Circular dependencies detected:");
+  for (const cycle of cycles) {
+    ERROR(`  ${cycle.join(" → ")}`);
+  }
+  ACTIONS: Review dependencies, move shared entities to Core module, or use event-driven communication
+  STOP - DO NOT PROCEED
+}
+```
+
+**2d. Display Cross-Module Interaction Map**
+
+```
+═══════════════════════════════════════════════════════════════
+  CROSS-MODULE INTERACTIONS VALIDATED
+═══════════════════════════════════════════════════════════════
+
+| Source Module | Target | Type | Status |
+|---------------|--------|------|--------|
+| Orders        | Customers.Customer | FK (N:1) | ✓ RESOLVED |
+| Invoices      | Customers.Customer | FK (N:1) | ✓ RESOLVED |
+
+Total: {count} cross-module references
+Shared entities: {count}
+═══════════════════════════════════════════════════════════════
+```
+
+### 3. Permission Coherence Check
+
+Load permissions from all modules and validate:
+
+```javascript
+const allRoles = {};
+const permissionPaths = [];
+
+for (const module of completedModules) {
+  for (const perm of module.permissions) {
+    // Verify path format: {app}.{module}.{action} or {app}.{module}.{section}.{action}
+    if (!perm.path.match(/^[A-Za-z]+\.[A-Za-z]+\.[A-Za-z]+(\.[A-Za-z]+)?$/)) {
+      ERROR(`Invalid permission path: "${perm.path}"`);
+    }
+
+    // Verify role exists in cadrage.applicationRoles
+    if (!cadrage.applicationRoles.find(r => r.role === perm.role)) {
+      WARNING(`Permission assigned to undefined role: ${perm.role}`);
+    }
+
+    permissionPaths.push(perm);
+  }
+}
+
+// Verify role hierarchy: Admin ⊃ Manager ⊃ Contributor ⊃ Viewer
+const hierarchy = ["Admin", "Manager", "Contributor", "Viewer"];
+// For each admin permission, verify manager/contributor/viewer exist with same path
+```
+
+**3a. Role Consistency** — All modules use same applicationRoles ✓
+
+**3b. Permission Path Format** — 3-segment or 4-segment patterns ✓
+
+**3c. Role Hierarchy Coherence** — Admin ⊃ Manager ⊃ Contributor ⊃ Viewer ✓
+
+**3d. Permission Conflicts** — Present to user via AskUserQuestion if Manager can approve in one module but not another
+
+**3e. Permission-Role Coherence** — Verify pattern consistency across modules (store as WARNING if intentional)
+
+### 4. Semantic Validation (MANDATORY)
+
+Execute 13 semantic checks per module:
+
+```javascript
+const semanticChecks = [
+  { check: "permission-orpheline", severity: "WARNING" },
+  { check: "uc-sans-fr", severity: "WARNING" },
+  { check: "entity-sans-endpoint", severity: "WARNING" },
+  { check: "uc-sans-scenario", severity: "WARNING" },
+  { check: "role-sans-permissions", severity: "WARNING" },
+  { check: "navigation-sans-traduction", severity: "ERROR" },
+  { check: "lifecycle-terminal", severity: "WARNING" },
+  { check: "schema-conformity", severity: "ERROR" },
+  { check: "wireframe-coverage", severity: "ERROR" },
+  { check: "entity-doublon", severity: "ERROR" },
+  { check: "permission-fantome", severity: "ERROR" },
+  { check: "dashboard-coverage", severity: "WARNING" },
+  { check: "permission-uc-alignment", severity: "WARNING" }
+];
+
+for (const module of completedModules) {
+  for (const check of semanticChecks) {
+    const result = executeSemanticCheck(module, check);
+    if (result.status === "ERROR") {
+      errors.push({module: module.code, check: check.check, details: result.details});
+    } else if (result.status === "WARNING") {
+      warnings.push({module: module.code, check: check.check, details: result.details});
+    }
+  }
+}
+
+// Blocking rule: 0 ERROR → PASS, ≥1 ERROR → BLOCK (ask user for each)
+if (errors.length > 0) {
+  BLOCKING_ERROR("Semantic validation failed");
+  for (const error of errors) {
+    ERROR(`  [${error.module}] ${error.check}: ${error.details}`);
+  }
+  STOP - User must fix before proceeding
+}
+```
+
+### 5. Data Model Consolidation
+
+Generate global entity relationship diagram:
+
+```javascript
+const globalEntities = [];
+const globalRelationships = [];
+
+for (const module of completedModules) {
+  for (const entity of module.entities) {
+    globalEntities.push({
+      name: entity.name,
+      module: module.code,
+      attributes: entity.attributes.length,
+      pk: entity.pk || "Id"
+    });
+
+    for (const rel of entity.relationships || []) {
+      globalRelationships.push({
+        sourceEntity: entity.name,
+        sourceModule: module.code,
+        targetEntity: rel.target.split(".")[1] || rel.target,
+        targetModule: rel.target.split(".")[0] || module.code,
+        cardinality: rel.cardinality || "N:1",
+        cascadeDelete: rel.cascadeDelete || false
+      });
+    }
+  }
+}
+
+// Display ERD summary
+Display("Global Entity Count: {count}")
+Display("Global Relationships: {count}")
+```
+
+### 6. E2E Flow Validation
+
+Identify business processes spanning multiple modules:
+
+```javascript
+const e2eFlows = [
+  {
+    name: "Order to Invoice",
+    modules: ["Orders", "Customers", "Invoices"],
+    steps: [
+      { module: "Orders", action: "Create order", permission: "sales.orders.create", dataFlow: "Customer → Order" },
+      { module: "Invoices", action: "Generate invoice", permission: "sales.invoices.create", dataFlow: "Order → Invoice" }
+    ]
+  }
+];
+
+for (const flow of e2eFlows) {
+  // Verify all permissions exist
+  // Verify entities in dataFlow are defined
+  // Verify module sequence respects dependency graph
+}
+```
+
+Display E2E flows and actors involved.
+
+### 7. Global Risk Assessment
+
+Evaluate application-level risks:
+
+```javascript
+const riskMetrics = {
+  totalEntities: globalEntities.length,
+  totalBRs: completedModules.reduce((sum, m) => sum + (m.rules?.length || 0), 0),
+  crossModuleDependencies: dependencyGraph.edges.length,
+  sharedEntities: sharedEntities.length,
+  maxE2EFlowLength: Math.max(...e2eFlows.map(f => f.steps.length)),
+  permissionPaths: permissionPaths.length
+};
+
+const risks = [
+  riskMetrics.totalEntities > 20 ? {risk: "High entity count", severity: "medium"} : null,
+  riskMetrics.totalBRs > 50 ? {risk: "High BR count", severity: "medium"} : null,
+  riskMetrics.crossModuleDependencies > 10 ? {risk: "Complex module coupling", severity: "high"} : null,
+  riskMetrics.sharedEntities > 5 ? {risk: "Many shared entities", severity: "medium"} : null,
+  riskMetrics.maxE2EFlowLength > 8 ? {risk: "Long E2E flow", severity: "medium"} : null
+].filter(r => r !== null);
+```
+
+### 8. Consolidation Summary Display
+
+```
+═══════════════════════════════════════════════════════════════
+  CONSOLIDATION SUMMARY - {application_name}
+═══════════════════════════════════════════════════════════════
+
+MODULES ({count})
+| Module | Entities | BRs | UCs | Status |
+|--------|----------|-----|-----|--------|
+{for each module}
+
+INTERACTIONS
+- Cross-module references: {count}
+- Shared entities: {count}
+- E2E flows: {count}
+- Circular dependencies: {count}
+
+PERMISSIONS
+- Roles: {count} (coherent: ✓)
+- Total paths: {count}
+- Conflicts: {count} (resolved)
+
+SEMANTIC CHECKS
+- Errors: {count}
+- Warnings: {count}
+- Pass rate: {percent}%
+
+RISKS
+{risk table}
+
+═══════════════════════════════════════════════════════════════
+```
+
+### 9. Client Approval (BLOCKING)
+
+**Single-Module Mode:** Auto-approve (no cross-module concerns)
+
+```
+IF completedModules.length === 1:
+  Display: "Module unique - consolidation automatique ✓"
+  approval = { approved: true, reason: "Single module", approvedAt: now() }
+  SKIP to section 10
+```
+
+**Multi-Module Mode:** Ask via AskUserQuestion:
+
+```
+question: "La consolidation est complète. Validez-vous l'ensemble ?"
+header: "Approbation Finale"
+options:
+  - label: "Approuvé"
+    description: "Passer au handoff pour la phase d'implémentation"
+  - label: "Réviser un module"
+    description: "Retourner à la spécification d'un module spécifique"
+  - label: "Modifier les interactions"
+    description: "Ajuster les interactions cross-module"
+
+IF "Réviser un module":
+  Ask which module → set currentModuleIndex → load step-03-specify.md
+
+IF "Modifier les interactions":
+  RESTART consolidation (section 2-4)
+```
+
+### 10. Write Consolidation Data
+
+```javascript
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "consolidation",
+  data: {
+    crossModuleInteractions: globalRelationships.map(rel => ({
+      fromModule: rel.sourceModule,
+      toModule: rel.targetModule,
+      interactionType: "FK-reference|event|shared-lookup",
+      description: `${rel.sourceEntity} → ${rel.targetEntity} (${rel.cardinality})`,
+      entities: [`${rel.sourceEntity}→${rel.targetEntity}`]
+    })),
+    sharedEntities: sharedEntities.map(se => ({
+      entity: se.entity,
+      ownerModule: se.definedIn,
+      referencedBy: [se.referencedBy],
+      sharedFields: []
+    })),
+    permissionCoherence: {
+      rolesConsistent: true,
+      pathFormatConsistent: true,
+      hierarchyRespected: true,
+      conflicts: [],
+      warnings: []
+    },
+    e2eFlows: e2eFlows,
+    globalRiskAssessment: risks,
+    semanticChecks: [
+      { check: "permission-orpheline", status: "PASS|WARNING", details: "..." }
+    ],
+    decision: {
+      approved: approval.approved,
+      reason: approval.reason,
+      approvedBy: "Client",
+      approvedAt: approval.approvedAt
+    }
+  }
+});
+
+// Add changelog entry
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "metadata.changelog",
+  data: {
+    step: "step-04-consolidate",
+    timestamp: now(),
+    changes: [
+      `Cross-module interactions: ${globalRelationships.length} FK references`,
+      `Permission coherence: validated (${permissionPaths.length} paths)`,
+      `E2E flows: ${e2eFlows.length} identified`,
+      `Global risk: ${risks.length > 0 ? 'MEDIUM' : 'LOW'}`,
+      `Semantic checks: PASSED`,
+      `Client approval: APPROVED`
+    ]
+  }
+});
+
+// Update status
+ba-writer.updateStatus({feature_id}, "consolidated");
+
+// Save workflow state for resume support
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "metadata.workflow",
+  data: {
+    lastCompletedStep: "step-04-consolidate",
+    readyForHandoff: true
+  }
+});
+```
+
+### 11. Summary & Proceed
+
+Display final summary:
+
+```
+✓ Consolidation completed
+✓ All validations passed
+✓ Client approval obtained
+✓ Status: consolidated
+→ Proceeding to step-05-deploy.md
+```
+
+---
+
+## CONTEXT MANAGEMENT
+
+| Loaded | Not Loaded |
+|--------|------------|
+| _shared.md | Full module JSON files |
+| Module summaries | Questionnaires |
+| cadrage.json | Templates |
+| Granular JSON files via index.json | React viewer files |
+| dependencyGraph | |
+
+---
+
+## SUCCESS CRITERIA
+
+- ✓ All cross-module references resolved
+- ✓ No circular dependencies
+- ✓ Permission coherence validated
+- ✓ Semantic checks: 0 errors
+- ✓ Client approval obtained (or auto-approved for single module)
+- ✓ Consolidation section written to validation.json
+- ✓ Status updated to "consolidated"
+- ✓ Workflow state saved for resume support
+
+---
+
+## NEXT STEP
+
+Load: `./step-05-deploy.md`