@atlashub/smartstack-cli 2.2.0 → 2.4.0

package/templates/skills/business-analyse/schemas/feature-schema.json

@@ -18,9 +18,15 @@
     },
     "status": {
       "type": "string",
-      "enum": ["draft", "analysed", "specified", "approved", "handed-off"],
+      "enum": ["draft", "framed", "analysed", "specified", "approved", "consolidated", "handed-off"],
       "description": "Current lifecycle status, enriched by each step"
     },
+    "scope": {
+      "type": "string",
+      "enum": ["application", "module"],
+      "default": "module",
+      "description": "Scope of this feature.json: application (master) or module (detailed)"
+    },
 
     "metadata": {
       "type": "object",
@@ -57,12 +63,35 @@
         },
         "mcpAvailable": { "type": "boolean" },
         "economyMode": { "type": "boolean" },
+        "scope": {
+          "type": "string",
+          "enum": ["application", "module"],
+          "default": "module",
+          "description": "Explicitly marks this as module-scope"
+        },
+        "applicationRef": {
+          "type": ["string", "null"],
+          "description": "Reference to parent application feature ID (FEAT-XXX) when part of multi-module analysis"
+        },
+        "applicationPath": {
+          "type": ["string", "null"],
+          "description": "Path to the parent application-level feature.json"
+        },
+        "moduleIndex": {
+          "type": ["integer", "null"],
+          "description": "Position in topological order within the application (0-based)"
+        },
+        "inheritsRoles": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether roles are inherited from application-level (true for multi-module)"
+        },
         "steps": {
           "type": "object",
           "description": "Progress tracking per step",
           "properties": {
             "init": { "$ref": "#/$defs/stepStatus" },
-            "analyse": { "$ref": "#/$defs/stepStatus" },
+            "cadrage": { "$ref": "#/$defs/stepStatus" },
             "specify": { "$ref": "#/$defs/stepStatus" },
             "validate": { "$ref": "#/$defs/stepStatus" },
             "handoff": { "$ref": "#/$defs/stepStatus" }
@@ -71,6 +100,35 @@
       }
     },
 
+    "applicationContext": {
+      "type": "object",
+      "description": "Inherited from parent application feature.json when part of multi-module analysis",
+      "properties": {
+        "applicationRoles": {
+          "type": "array",
+          "description": "Copied from master feature.json for reference",
+          "items": {
+            "type": "object",
+            "properties": {
+              "role": { "type": "string" },
+              "description": { "type": "string" },
+              "level": { "type": "string", "enum": ["admin", "manager", "contributor", "viewer"] },
+              "permissionPattern": { "type": "string" }
+            }
+          }
+        },
+        "permissionBase": {
+          "type": "string",
+          "description": "Application-level permission base (e.g., business.sales)"
+        },
+        "relatedModules": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Other modules in the same application"
+        }
+      }
+    },
+
     "discovery": {
       "type": "object",
       "description": "Enriched by step-01-analyse (discovery part)",
@@ -227,7 +285,7 @@
                   "required": ["target", "type"],
                   "properties": {
                     "target": { "type": "string" },
-                    "type": { "type": "string", "enum": ["1:1", "1:N", "N:M"] },
+                    "type": { "type": "string", "enum": ["1:1", "1:N", "N:1", "N:M"] },
                     "description": { "type": "string" }
                   }
                 }
@@ -518,7 +576,132 @@
               "description": { "type": "string" },
               "elements": { "type": "array", "items": { "type": "string" } },
               "actions": { "type": "array", "items": { "type": "string" } },
-              "permissionsRequired": { "type": "array", "items": { "type": "string" } }
+              "permissionsRequired": { "type": "array", "items": { "type": "string" } },
+              "mockupFormat": {
+                "type": "string",
+                "enum": ["ascii", "svg"],
+                "description": "Format of the mockup: ascii (rendered in <pre>) or svg (rendered as inline SVG)"
+              },
+              "mockup": {
+                "type": "string",
+                "description": "ASCII art or SVG markup of the wireframe"
+              },
+              "section": {
+                "type": "string",
+                "description": "Navigation section this wireframe belongs to (e.g., list, detail, create)"
+              }
+            }
+          }
+        },
+        "messages": {
+          "type": "array",
+          "description": "Business messages (success, error, warning, info) with i18n keys. MANDATORY: ≥4 messages.",
+          "items": {
+            "type": "object",
+            "required": ["code", "type", "i18nKey"],
+            "properties": {
+              "code": { "type": "string", "description": "SCREAMING_SNAKE_CASE identifier (e.g., VEHICLE_CREATED_SUCCESS)" },
+              "type": { "type": "string", "enum": ["success", "error", "warning", "info"] },
+              "title": { "type": "string" },
+              "message": { "type": "string", "description": "User-facing message with {placeholders}" },
+              "i18nKey": { "type": "string", "description": "Dot-separated i18n key (e.g., freebike.messages.vehicleCreated)" }
+            }
+          }
+        },
+        "lifeCycles": {
+          "type": "array",
+          "description": "Per-entity state machines for entities with Status fields. MANDATORY: ≥1 entity.",
+          "items": {
+            "type": "object",
+            "required": ["entity", "states"],
+            "properties": {
+              "entity": { "type": "string", "description": "PascalCase entity name" },
+              "states": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["id", "allowedTransitions"],
+                  "properties": {
+                    "id": { "type": "string", "description": "State code (e.g., Draft, Active, Completed)" },
+                    "displayName": { "type": "string" },
+                    "description": { "type": "string" },
+                    "allowedTransitions": { "type": "array", "items": { "type": "string" } },
+                    "isTerminal": { "type": "boolean", "default": false }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "seedDataCore": {
+          "type": "object",
+          "description": "5 mandatory SmartStack core SeedData definitions derived from navigation + permissionMatrix. CRITICAL: without these, module is invisible (403).",
+          "properties": {
+            "navigationModules": {
+              "type": "array",
+              "description": "Entries for nav_Modules table (HasData). Derived from navigation.entries.",
+              "items": {
+                "type": "object",
+                "required": ["code", "label", "icon", "route"],
+                "properties": {
+                  "code": { "type": "string" },
+                  "label": { "type": "string" },
+                  "icon": { "type": "string" },
+                  "route": { "type": "string" },
+                  "parentCode": { "type": ["string", "null"] },
+                  "sort": { "type": "integer" }
+                }
+              }
+            },
+            "navigationTranslations": {
+              "type": "array",
+              "description": "Translations for nav_Translations table (HasData). One entry per module per language.",
+              "items": {
+                "type": "object",
+                "required": ["moduleCode", "language", "label"],
+                "properties": {
+                  "moduleCode": { "type": "string" },
+                  "language": { "type": "string", "enum": ["fr", "en", "it", "de"] },
+                  "label": { "type": "string" }
+                }
+              }
+            },
+            "permissions": {
+              "type": "array",
+              "description": "Entries for nav_Permissions table (HasData). Full paths from permissionMatrix.permissions.",
+              "items": {
+                "type": "object",
+                "required": ["path", "action"],
+                "properties": {
+                  "path": { "type": "string", "description": "Full permission path (business.{app}.{module}.{resource}.{action})" },
+                  "action": { "type": "string" },
+                  "description": { "type": "string" }
+                }
+              }
+            },
+            "rolePermissions": {
+              "type": "array",
+              "description": "Entries for auth_RolePermissions table (HasData). Derived from permissionMatrix.roleAssignments.",
+              "items": {
+                "type": "object",
+                "required": ["role", "permissionPath"],
+                "properties": {
+                  "role": { "type": "string" },
+                  "permissionPath": { "type": "string", "description": "Full permission path (must match permissions[].path)" }
+                }
+              }
+            },
+            "permissionConstants": {
+              "type": "array",
+              "description": "Compile-time constants for Permissions.cs (Application layer). Used in [RequirePermission] attributes.",
+              "items": {
+                "type": "object",
+                "required": ["constantName", "path"],
+                "properties": {
+                  "constantName": { "type": "string", "description": "PascalCase constant (e.g., VehiclesRead)" },
+                  "path": { "type": "string", "description": "Matching permission path" }
+                }
+              }
             }
           }
         }
@@ -529,53 +712,74 @@
       "type": "object",
       "description": "Enriched by step-03-validate",
       "properties": {
-        "decision": { "type": "string", "enum": ["approved", "rejected", "pending"] },
         "validatedAt": { "type": ["string", "null"], "format": "date-time" },
-        "completeness": {
-          "type": "object",
-          "properties": {
-            "discovery": { "type": "boolean" },
-            "analysis": { "type": "boolean" },
-            "specification": { "type": "boolean" },
-            "score": { "type": "integer" },
-            "total": { "type": "integer" },
-            "details": { "type": "array", "items": { "type": "string" } }
+        "completenessChecks": {
+          "type": "array",
+          "description": "Per-section completeness verification",
+          "items": {
+            "type": "object",
+            "properties": {
+              "section": { "type": "string" },
+              "count": { "type": "integer" },
+              "minimum": { "type": "integer" },
+              "status": { "type": "string", "enum": ["PASS", "FAIL", "WARNING"] }
+            }
           }
         },
-        "consistency": {
-          "type": "object",
-          "description": "Cross-reference validation results",
-          "properties": {
-            "rulesToRequirements": { "type": "boolean", "description": "All BR mapped to FR" },
-            "useCasesToActors": { "type": "boolean", "description": "All UC have valid actors" },
-            "requirementsToRules": { "type": "boolean", "description": "All FR trace to BR" },
-            "entitiesToEndpoints": { "type": "boolean", "description": "All entities have CRUD endpoints" },
-            "details": { "type": "array", "items": { "type": "string" } }
+        "consistencyChecks": {
+          "type": "array",
+          "description": "Cross-reference consistency checks (UC↔FR, FR↔BR, Actor↔Matrix, etc.)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "check": { "type": "string" },
+              "passed": { "type": "integer" },
+              "warnings": { "type": "integer" },
+              "errors": { "type": "integer" },
+              "status": { "type": "string", "enum": ["PASS", "FAIL", "WARNING"] }
+            }
           }
         },
-        "conventions": {
-          "type": "object",
-          "description": "SmartStack convention validation",
-          "properties": {
-            "permissionPaths": { "type": "boolean" },
-            "navRoutes": { "type": "boolean" },
-            "entityNaming": { "type": "boolean" },
-            "folderStructure": { "type": "boolean" },
-            "seedDataComplete": { "type": "boolean" },
-            "details": { "type": "array", "items": { "type": "string" } }
+        "conventionChecks": {
+          "type": "array",
+          "description": "SmartStack convention validation (naming, permissions, routes, etc.)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "check": { "type": "string" },
+              "status": { "type": "string", "enum": ["PASS", "FAIL", "WARNING"] },
+              "details": { "type": "string" }
+            }
           }
         },
-        "issues": {
+        "riskAssessments": {
           "type": "array",
+          "description": "Scope and complexity risk evaluation",
           "items": {
             "type": "object",
             "properties": {
-              "severity": { "type": "string", "enum": ["critical", "warning", "info"] },
-              "category": { "type": "string" },
-              "description": { "type": "string" },
-              "suggestion": { "type": "string" }
+              "risk": { "type": "string" },
+              "value": { "type": "integer" },
+              "threshold": { "type": "integer" },
+              "status": { "type": "string", "enum": ["ACCEPTABLE", "WARNING", "CRITICAL", "MONITORED"] }
             }
           }
+        },
+        "warnings": {
+          "type": "array",
+          "description": "Non-blocking warnings and observations",
+          "items": { "type": "string" }
+        },
+        "decision": {
+          "type": "object",
+          "description": "Final approval decision",
+          "properties": {
+            "approved": { "type": "boolean" },
+            "reason": { "type": "string" },
+            "approvalMode": { "type": "string", "enum": ["standard", "micro", "delta", "force"] },
+            "approvedBy": { "type": "string" },
+            "approvedAt": { "type": "string", "format": "date-time" }
+          }
         }
       }
     },
@@ -599,12 +803,40 @@
         },
         "brToCodeMapping": {
           "type": "array",
+          "description": "Maps each business rule to its implementation points across layers. Derived from analysis.businessRules[].",
+          "items": {
+            "type": "object",
+            "required": ["ruleId", "implementationPoints"],
+            "properties": {
+              "ruleId": { "type": "string", "description": "BR-XXX identifier from analysis.businessRules" },
+              "title": { "type": "string", "description": "Business rule title" },
+              "implementationPoints": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["layer", "component"],
+                  "properties": {
+                    "layer": { "type": "string", "description": "Architecture layer (Domain, Application, Infrastructure, API, Frontend)" },
+                    "component": { "type": "string", "description": "File name (e.g., Order.cs, OrdersController.cs)" },
+                    "method": { "type": "string", "description": "Method or attribute (e.g., Validate(), [Authorize])" },
+                    "implementation": { "type": "string", "description": "How the rule is enforced" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "apiEndpointSummary": {
+          "type": "array",
+          "description": "Subset of specification.apiEndpoints enriched with linkedUC. MUST use EXACT same routes as specification.",
           "items": {
             "type": "object",
             "properties": {
-              "ruleId": { "type": "string" },
-              "implementationFile": { "type": "string" },
-              "pattern": { "type": "string" }
+              "operation": { "type": "string" },
+              "method": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"] },
+              "route": { "type": "string", "description": "MUST match specification.apiEndpoints[].path exactly" },
+              "linkedUC": { "type": "string" },
+              "permissions": { "type": "string" }
             }
           }
         },
@@ -619,7 +851,7 @@
                 "properties": {
                   "id": { "type": "integer" },
                   "description": { "type": "string" },
-                  "category": { "type": "string", "enum": ["domain", "application", "infrastructure", "api", "frontend", "i18n", "test", "validation"] },
+                  "category": { "type": "string", "enum": ["domain", "seedData", "seedDataCore", "application", "infrastructure", "api", "frontend", "i18n", "test", "validation"] },
                   "dependencies": { "type": "array", "items": { "type": "integer" } },
                   "acceptanceCriteria": { "type": "string" }
                 }
@@ -654,15 +886,18 @@
 
     "changelog": {
       "type": "array",
-      "description": "Version history and change tracking",
+      "description": "Version history and change tracking. Each step adds an entry.",
       "items": {
         "type": "object",
-        "required": ["version", "timestamp", "changes"],
+        "required": ["timestamp", "changes"],
         "properties": {
-          "version": { "type": "string" },
+          "step": { "type": "string", "description": "Step identifier (e.g., step-01-analyse, step-02-specify, step-03-validate, step-04-handoff)" },
+          "version": { "type": "string", "description": "Feature version at this point" },
           "timestamp": { "type": "string", "format": "date-time" },
           "author": { "type": "string" },
-          "changes": { "type": "array", "items": { "type": "string" } }
+          "changes": { "type": "array", "items": { "type": "string" } },
+          "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-blocking warnings from this step" },
+          "decision": { "type": "string", "description": "Step decision outcome (e.g., approved, rejected)" }
         }
       }
     }
@@ -679,8 +914,14 @@
     },
     "fileSpec": {
       "type": "object",
+      "required": ["path", "type"],
       "properties": {
         "path": { "type": "string", "description": "Relative file path" },
+        "type": { "type": "string", "description": "File type (Entity, Service, DTO, Repository, Migration, HasData, Constants, ApiController, Page, Component, ApiClient, ReduxSlice, UnitTests, IntegrationTests, Enum)" },
+        "linkedFRs": { "type": "array", "items": { "type": "string" }, "description": "Linked functional requirement IDs (FR-XXX)" },
+        "linkedUCs": { "type": "array", "items": { "type": "string" }, "description": "Linked use case IDs (UC-XXX)" },
+        "category": { "type": "string", "enum": ["core", "business"], "description": "SeedData category: core (navigation/permissions) or business (lookup tables)" },
+        "source": { "type": "string", "description": "Source path in feature.json for derivation (e.g., specification.seedDataCore.permissions)" },
         "description": { "type": "string" },
         "pattern": { "type": "string", "description": "Reference pattern from existing codebase" },
         "instructions": { "type": "string" }

package/templates/skills/business-analyse/steps/step-00-init.md

@@ -1,7 +1,7 @@
 ---
 name: step-00-init
 description: Initialize Business Analysis - Parse flags, route use case, create feature.json
-next_step: steps/step-01-analyse.md
+next_step: steps/step-01-cadrage.md
 ---
 
 # Step 00: Initialize Business Analysis
@@ -37,6 +37,7 @@ question_mode: false
 refactor_mode: false
 micro_mode: false
 interactive_mode: false
+application_mode: false    # Multi-module application analysis
 ```
 
 ### Flag Parsing Rules
@@ -51,6 +52,7 @@ interactive_mode: false
 | `-r` | `--refactor` | Refactoring mode | next arg = FEAT-ID, remaining = change description |
 | `-m` | `--micro` | Micro feature mode | none |
 | `-i` | `--interactive` | Interactive mode | none |
+| `-app` | `--application` | Application mode: multi-module analysis | none |
 
 **Remaining arguments after flag removal = feature_description**
 
@@ -135,33 +137,79 @@ ba -m "Add email notification on approval"
 ba "Create order management system"
 ```
 
-## Step 3: MCP Health Check
+## Step 2B: Application Mode Detection
 
-Verify MCP availability (non-blocking).
+**IF `-app` flag is set:**
+- Set `{workflow_mode}` = "application"
+- Set `{use_case}` = "application"
 
-**Check file:** `.claude/mcp-status.json`
+**ELSE IF no explicit mode flag:**
+- Analyze `{feature_description}` for multi-module signals:
+  - Keywords: "application", "system", "platform", "suite", "complet", "ensemble"
+  - Multiple module mentions (3+ distinct functional areas)
+  - Scope description spanning multiple domains
+- IF multi-module signals detected:
+  ```
+  AskUserQuestion:
+    question: "Votre description semble couvrir plusieurs modules. Voulez-vous une analyse multi-module (application complète) ?"
+    header: "Mode"
+    options:
+      - label: "Oui, analyse application"
+        description: "Identifier les modules, les analyser un par un avec validation client"
+      - label: "Non, module unique"
+        description: "Traiter comme un seul module"
+  ```
+- IF user confirms multi-module: Set `{workflow_mode}` = "application"
+- ELSE: Set `{workflow_mode}` = "module"
 
-| Condition | Action |
-|-----------|--------|
-| File missing | Perform full health check |
-| > 7 days old | Perform full health check |
-| ≤ 7 days old | Quick connectivity test |
-| Error status | Display warning, continue |
+## Step 3: MCP Prerequisite Check (BLOCKING)
 
-**Full health check:**
-1. Call `mcp__smartstack__validate_conventions`
-2. Verify installed version
-3. List available tools
-4. Update `.claude/mcp-status.json`
+Verify MCP availability. **This check is BLOCKING** - the skill cannot proceed without MCP.
 
-**Quick test:**
-- Bash only, no LLM call
-- Check if `.claude/mcp/` exists and has recent files
+> See `_shared.md` → "MCP Prerequisite Guard (BLOCKING)" for the full pattern.
 
-**Display result:**
-- Success: "MCP available: yes"
-- Warning: "MCP check skipped (cache expired)"
-- Error: "MCP unavailable: using fallback (slower analysis)"
+**Detection:** Call MCP with minimal parameters:
+
+```
+mcp__smartstack__validate_conventions({ checks: ["tables"] })
+```
+
+**Decision matrix:**
+
+| Result | Action |
+|--------|--------|
+| Success response | Set `mcp_available = true`, continue to Step 4 |
+| Connection error / tool not found | **STOP EXECUTION** - display error below |
+
+**On success:**
+- Set `mcp_available = true`
+- Update `.claude/mcp-status.json` cache
+- Continue workflow
+
+**On failure (STOP):**
+
+```
+═══════════════════════════════════════════════════════════════
+  MCP SMARTSTACK NOT AVAILABLE - SKILL BLOCKED
+═══════════════════════════════════════════════════════════════
+
+  The SmartStack MCP server is required for business-analyse
+  but could not be reached.
+
+  To install:
+    claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
+
+  To verify:
+    /mcp:healthcheck
+
+  After installation, restart Claude Code and retry.
+
+═══════════════════════════════════════════════════════════════
+```
+
+**DO NOT** offer fallback modes, economy mode workarounds, or degraded execution.
+**DO NOT** continue to Step 4 or any subsequent step.
+**STOP the skill immediately.**
 
 ## Step 4: Interactive Mode
 
@@ -301,25 +349,43 @@ docs_dir: "docs/business/{app}/{module}/business-analyse/v{version}"
 output_dir: same as docs_dir
 ```
 
-## Step 10: Create Initial feature.json
-
-Create the main feature document using ba-writer agent.
-
-**Call ba-writer:**
-```
-ba-writer.createFeature({
-  id: feature_id,
-  application: application_name,
-  module: module_name,
-  featureDescription: feature_description,
-  language: language,
-  useCase: use_case,
-  featureType: feature_type OR null,
-  economyMode: economy_mode,
-  mcpAvailable: mcp_available
+## Step 10: Create Master feature.json
+
+Create the master feature document using ba-writer agent.
+
+**Use ba-writer agent:**
+
+```
+ba-writer.createApplicationFeature({
+  id: {feature_id},
+  version: "1.0",
+  scope: "application",
+  status: "draft",
+  metadata: {
+    application: {application_name},
+    context: "business",
+    language: {language},
+    featureDescription: {feature_description},
+    useCase: {use_case},
+    mcpAvailable: {mcp_available},
+    economyMode: {economy_mode},
+    workflow: {
+      mode: {workflow_mode},
+      moduleOrder: [],
+      currentModuleIndex: 0,
+      completedModules: [],
+      currentModule: null
+    }
+  }
 })
 ```
 
+**Output path:**
+- Application mode: `docs/business/{app}/business-analyse/v1.0/feature.json`
+- Module mode: `docs/business/{app}/business-analyse/v1.0/feature.json` (same - always create master first)
+
+> **Note:** Even in single-module mode, we create the master feature.json. The decomposition step will trivially identify one module.
+
 **Result structure:**
 ```json
 {
@@ -443,18 +509,17 @@ NEXT STEP: step-01-analyse ({use_case} mode)
 
 ## Step 13: Load Next Step
 
-Execute the next step in the workflow.
+**All modes except question (-q) and micro (-m):**
+After showing initialization summary, proceed to `./step-01-cadrage.md`
 
-**Read file:**
-```
-steps/step-01-analyse.md
-```
+**Question mode (-q):** EXIT after ba-reader answers the question.
+**Micro mode (-m):** Load `./step-05-handoff.md` directly.
 
 **Pass context variables:**
 ```yaml
 feature_id: string
 feature_description: string
-use_case: "new" | "question" | "refactoring" | "micro"
+use_case: "new" | "question" | "refactoring" | "micro" | "application"
 application_name: string
 module_name: string
 language: string
@@ -463,6 +528,7 @@ auto_mode: boolean
 economy_mode: boolean
 interactive_mode: boolean
 mcp_available: boolean
+workflow_mode: string
 ```
 
 ## Error Handling