@atlashub/smartstack-cli 2.0.0 → 2.2.0

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

@@ -0,0 +1,690 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "feature.json",
+  "title": "SmartStack Business Analysis Feature",
+  "description": "Single JSON file enriched progressively by each BA step. Published to docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json",
+  "type": "object",
+  "required": ["id", "version", "status", "metadata"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^FEAT-\\d{3,}$",
+      "description": "Unique feature identifier (e.g., FEAT-001)"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Document version (e.g., 1.0, 1.1)"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "analysed", "specified", "approved", "handed-off"],
+      "description": "Current lifecycle status, enriched by each step"
+    },
+
+    "metadata": {
+      "type": "object",
+      "required": ["createdAt", "updatedAt", "application", "module", "context", "language", "featureDescription"],
+      "properties": {
+        "createdAt": { "type": "string", "format": "date-time" },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "application": { "type": "string", "description": "Application name (PascalCase)" },
+        "module": { "type": "string", "description": "Module name (PascalCase)" },
+        "context": { "type": "string", "const": "business" },
+        "language": { "type": "string", "enum": ["fr", "en", "it", "de"] },
+        "featureDescription": { "type": "string" },
+        "featureType": {
+          "type": "string",
+          "enum": ["data-centric", "integration", "ui-centric", "workflow", "reporting", "full-module", "micro"],
+          "description": "Auto-classified from feature description"
+        },
+        "useCase": {
+          "type": "string",
+          "enum": ["new", "refactoring", "micro"],
+          "description": "Which use case triggered this analysis"
+        },
+        "permissionBase": {
+          "type": "string",
+          "description": "e.g., business.sales.orders"
+        },
+        "previousVersion": {
+          "type": ["string", "null"],
+          "description": "Reference to previous version (for refactoring)"
+        },
+        "changeReason": {
+          "type": ["string", "null"],
+          "description": "Why this version was created (refactoring delta)"
+        },
+        "mcpAvailable": { "type": "boolean" },
+        "economyMode": { "type": "boolean" },
+        "steps": {
+          "type": "object",
+          "description": "Progress tracking per step",
+          "properties": {
+            "init": { "$ref": "#/$defs/stepStatus" },
+            "analyse": { "$ref": "#/$defs/stepStatus" },
+            "specify": { "$ref": "#/$defs/stepStatus" },
+            "validate": { "$ref": "#/$defs/stepStatus" },
+            "handoff": { "$ref": "#/$defs/stepStatus" }
+          }
+        }
+      }
+    },
+
+    "discovery": {
+      "type": "object",
+      "description": "Enriched by step-01-analyse (discovery part)",
+      "properties": {
+        "problem": { "type": "string", "description": "Q1.1 - Business problem to solve" },
+        "asIs": { "type": "string", "description": "Q1.2 - Current situation" },
+        "toBe": { "type": "string", "description": "Q1.3 - Target situation" },
+        "trigger": { "type": "string", "description": "Q1.4 - What triggered this need" },
+        "stakeholders": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["role"],
+            "properties": {
+              "role": { "type": "string" },
+              "function": { "type": "string" },
+              "involvement": { "type": "string", "enum": ["approver", "decision-maker", "consulted", "informed", "end-user"] },
+              "tasks": { "type": "array", "items": { "type": "string" } },
+              "frequency": { "type": "string" },
+              "painPoints": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        },
+        "scope": {
+          "type": "object",
+          "properties": {
+            "mustHave": { "type": "array", "items": { "type": "string" } },
+            "shouldHave": { "type": "array", "items": { "type": "string" } },
+            "couldHave": { "type": "array", "items": { "type": "string" } },
+            "outOfScope": { "type": "array", "items": { "type": "string" } },
+            "mainFlow": { "type": "string" },
+            "decisionPoints": { "type": "array", "items": { "type": "string" } },
+            "alternativeFlows": { "type": "array", "items": { "type": "string" } },
+            "errorCases": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "risks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "type", "description"],
+            "properties": {
+              "id": { "type": "string", "pattern": "^RISK-\\d{3}$" },
+              "type": { "type": "string", "enum": ["business", "technical", "organizational"] },
+              "description": { "type": "string" },
+              "probability": { "type": "string", "enum": ["high", "medium", "low"] },
+              "impact": { "type": "string", "enum": ["high", "medium", "low"] },
+              "priority": { "type": "string", "enum": ["critical", "medium", "low"] },
+              "mitigation": { "type": "string" }
+            }
+          }
+        },
+        "acceptanceCriteria": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "criterion"],
+            "properties": {
+              "id": { "type": "string", "pattern": "^AC-\\d{3}$" },
+              "criterion": { "type": "string" },
+              "validated": { "type": "boolean", "default": false }
+            }
+          }
+        },
+        "codebaseContext": {
+          "type": "string",
+          "description": "Summary of existing modules/patterns found during pre-research"
+        },
+        "openQuestions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": { "type": "string" },
+              "question": { "type": "string" },
+              "answer": { "type": ["string", "null"] },
+              "status": { "type": "string", "enum": ["pending", "answered", "deferred"] }
+            }
+          }
+        }
+      }
+    },
+
+    "analysis": {
+      "type": "object",
+      "description": "Enriched by step-01-analyse (analysis part, merged from old BRD step)",
+      "properties": {
+        "objectives": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "objective"],
+            "properties": {
+              "id": { "type": "string", "pattern": "^OBJ-\\d{3}$" },
+              "objective": { "type": "string" },
+              "metric": { "type": "string" },
+              "target": { "type": "string" }
+            }
+          }
+        },
+        "businessRules": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "name", "category", "statement"],
+            "properties": {
+              "id": { "type": "string", "pattern": "^BR-(VAL|CALC|WF|SEC|DATA)-\\d{3}$" },
+              "name": { "type": "string" },
+              "category": { "type": "string", "enum": ["validation", "calculation", "workflow", "security", "data"] },
+              "statement": { "type": "string", "description": "IF ... THEN ... ELSE ..." },
+              "priority": { "type": "string", "enum": ["must", "should", "could"] },
+              "conditions": { "type": "array", "items": { "type": "string" } },
+              "examples": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "input": { "type": "string" },
+                    "expected": { "type": "string" }
+                  }
+                }
+              },
+              "testability": { "type": "string" }
+            }
+          }
+        },
+        "entities": {
+          "type": "array",
+          "description": "Business-view entities only. NO technical fields (Id, TenantId, CreatedBy, etc.)",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string", "description": "PascalCase entity name" },
+              "description": { "type": "string" },
+              "attributes": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["name"],
+                  "properties": {
+                    "name": { "type": "string" },
+                    "description": { "type": "string" },
+                    "required": { "type": "boolean", "default": false },
+                    "unique": { "type": "boolean", "default": false },
+                    "validation": { "type": "string" }
+                  }
+                }
+              },
+              "relationships": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["target", "type"],
+                  "properties": {
+                    "target": { "type": "string" },
+                    "type": { "type": "string", "enum": ["1:1", "1:N", "N:M"] },
+                    "description": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "processFlow": {
+          "type": "object",
+          "properties": {
+            "entryPoints": { "type": "array", "items": { "type": "string" } },
+            "mainFlow": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "step": { "type": "integer" },
+                  "actor": { "type": "string" },
+                  "action": { "type": "string" },
+                  "system": { "type": "string" }
+                }
+              }
+            },
+            "decisionPoints": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "condition": { "type": "string" },
+                  "ifTrue": { "type": "string" },
+                  "ifFalse": { "type": "string" },
+                  "rule": { "type": "string", "description": "Reference to BR-XXX" }
+                }
+              }
+            },
+            "alternativeFlows": { "type": "array", "items": { "type": "object" } }
+          }
+        },
+        "integrations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "system": { "type": "string" },
+              "direction": { "type": "string", "enum": ["in", "out", "bidirectional"] },
+              "data": { "type": "string" },
+              "frequency": { "type": "string" },
+              "errorStrategy": { "type": "string" }
+            }
+          }
+        },
+        "dataLifecycle": {
+          "type": "object",
+          "properties": {
+            "retentionPeriod": { "type": "string" },
+            "archiveStrategy": { "type": "string" },
+            "gdprCompliance": { "type": "string" },
+            "states": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "name": { "type": "string" },
+                  "transitions": { "type": "array", "items": { "type": "string" } }
+                }
+              }
+            }
+          }
+        },
+        "crossModuleImpact": {
+          "type": "object",
+          "properties": {
+            "existingModules": { "type": "array", "items": { "type": "string" } },
+            "sharedData": { "type": "array", "items": { "type": "string" } },
+            "events": { "type": "array", "items": { "type": "string" } },
+            "modifications": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      }
+    },
+
+    "specification": {
+      "type": "object",
+      "description": "Enriched by step-02-specify",
+      "properties": {
+        "actors": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["role", "permissions"],
+            "properties": {
+              "role": { "type": "string" },
+              "description": { "type": "string" },
+              "permissions": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        },
+        "useCases": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "name", "primaryActor", "permission"],
+            "properties": {
+              "id": { "type": "string", "pattern": "^UC-\\d{3}$" },
+              "name": { "type": "string" },
+              "primaryActor": { "type": "string" },
+              "permission": { "type": "string", "description": "business.{app}.{module}.{action}" },
+              "preconditions": { "type": "array", "items": { "type": "string" } },
+              "postconditions": { "type": "array", "items": { "type": "string" } },
+              "mainScenario": { "type": "array", "items": { "type": "string" } },
+              "alternativeScenarios": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "name": { "type": "string" },
+                    "steps": { "type": "array", "items": { "type": "string" } }
+                  }
+                }
+              },
+              "errorScenarios": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "name": { "type": "string" },
+                    "steps": { "type": "array", "items": { "type": "string" } }
+                  }
+                }
+              },
+              "linkedRules": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Cross-references to BR-XXX in analysis.businessRules"
+              }
+            }
+          }
+        },
+        "functionalRequirements": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "statement", "priority"],
+            "properties": {
+              "id": { "type": "string", "pattern": "^FR-\\d{3}$" },
+              "statement": { "type": "string", "description": "System MUST/SHOULD/COULD ..." },
+              "priority": { "type": "string", "enum": ["must", "should", "could"] },
+              "linkedRules": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Cross-references to BR-XXX"
+              },
+              "linkedUseCases": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Cross-references to UC-XXX"
+              },
+              "acceptanceCriteria": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        },
+        "permissionMatrix": {
+          "type": "object",
+          "properties": {
+            "permissions": {
+              "type": "array",
+              "description": "All permissions for this module",
+              "items": {
+                "type": "object",
+                "required": ["path", "action"],
+                "properties": {
+                  "path": { "type": "string", "description": "business.{app}.{module}.{action}" },
+                  "action": { "type": "string", "enum": ["read", "create", "update", "delete", "export", "import", "admin", "*"] },
+                  "description": { "type": "string" }
+                }
+              }
+            },
+            "roleAssignments": {
+              "type": "array",
+              "description": "Role-to-permission mapping (SeedData source)",
+              "items": {
+                "type": "object",
+                "required": ["role", "permissions"],
+                "properties": {
+                  "role": { "type": "string" },
+                  "permissions": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Permission paths assigned to this role"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "navigation": {
+          "type": "object",
+          "description": "Navigation hierarchy for SeedData generation",
+          "properties": {
+            "entries": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["level", "code", "route"],
+                "properties": {
+                  "level": { "type": "string", "enum": ["context", "application", "module", "section", "resource"] },
+                  "code": { "type": "string" },
+                  "labels": {
+                    "type": "object",
+                    "properties": {
+                      "fr": { "type": "string" },
+                      "en": { "type": "string" },
+                      "it": { "type": "string" },
+                      "de": { "type": "string" }
+                    }
+                  },
+                  "route": { "type": "string" },
+                  "icon": { "type": "string" },
+                  "isNew": { "type": "boolean" }
+                }
+              }
+            }
+          }
+        },
+        "gherkinScenarios": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "feature": { "type": "string" },
+              "scenarios": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "name": { "type": "string" },
+                    "tags": { "type": "array", "items": { "type": "string" } },
+                    "given": { "type": "array", "items": { "type": "string" } },
+                    "when": { "type": "array", "items": { "type": "string" } },
+                    "then": { "type": "array", "items": { "type": "string" } }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "validations": {
+          "type": "array",
+          "description": "Field-level validations for entities",
+          "items": {
+            "type": "object",
+            "properties": {
+              "entity": { "type": "string" },
+              "field": { "type": "string" },
+              "rules": { "type": "array", "items": { "type": "string" } },
+              "errorMessageKey": { "type": "string" }
+            }
+          }
+        },
+        "apiEndpoints": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "method": { "type": "string", "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"] },
+              "path": { "type": "string" },
+              "permission": { "type": "string" },
+              "requestDto": { "type": "string" },
+              "responseDto": { "type": "string" },
+              "description": { "type": "string" }
+            }
+          }
+        },
+        "i18nKeys": {
+          "type": "object",
+          "description": "Translation keys organized by section",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          }
+        },
+        "uiWireframes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "screen": { "type": "string" },
+              "description": { "type": "string" },
+              "elements": { "type": "array", "items": { "type": "string" } },
+              "actions": { "type": "array", "items": { "type": "string" } },
+              "permissionsRequired": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    },
+
+    "validation": {
+      "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" } }
+          }
+        },
+        "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" } }
+          }
+        },
+        "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" } }
+          }
+        },
+        "issues": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "severity": { "type": "string", "enum": ["critical", "warning", "info"] },
+              "category": { "type": "string" },
+              "description": { "type": "string" },
+              "suggestion": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+
+    "handoff": {
+      "type": "object",
+      "description": "Enriched by step-04-handoff",
+      "properties": {
+        "complexity": { "type": "string", "enum": ["simple", "medium", "complex"] },
+        "filesToCreate": {
+          "type": "object",
+          "properties": {
+            "domain": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } },
+            "application": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } },
+            "infrastructure": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } },
+            "api": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } },
+            "frontend": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } },
+            "seedData": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } },
+            "tests": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } }
+          }
+        },
+        "brToCodeMapping": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "ruleId": { "type": "string" },
+              "implementationFile": { "type": "string" },
+              "pattern": { "type": "string" }
+            }
+          }
+        },
+        "ralphPrd": {
+          "type": "object",
+          "description": "Embedded Ralph Loop task breakdown (also exported to .ralph/prd.json)",
+          "properties": {
+            "tasks": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": { "type": "integer" },
+                  "description": { "type": "string" },
+                  "category": { "type": "string", "enum": ["domain", "application", "infrastructure", "api", "frontend", "i18n", "test", "validation"] },
+                  "dependencies": { "type": "array", "items": { "type": "integer" } },
+                  "acceptanceCriteria": { "type": "string" }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+
+    "suggestions": {
+      "type": "array",
+      "description": "Proactive AI suggestions for complementary modules/sections",
+      "items": {
+        "type": "object",
+        "required": ["type", "code", "reason"],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["module", "section", "integration", "enhancement"]
+          },
+          "code": { "type": "string", "description": "Suggested module/section code (PascalCase)" },
+          "title": { "type": "string" },
+          "reason": { "type": "string", "description": "Why this is suggested based on the current analysis" },
+          "accepted": {
+            "type": ["boolean", "null"],
+            "description": "null = not yet answered, true = accepted, false = rejected"
+          }
+        }
+      }
+    },
+
+    "changelog": {
+      "type": "array",
+      "description": "Version history and change tracking",
+      "items": {
+        "type": "object",
+        "required": ["version", "timestamp", "changes"],
+        "properties": {
+          "version": { "type": "string" },
+          "timestamp": { "type": "string", "format": "date-time" },
+          "author": { "type": "string" },
+          "changes": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    }
+  },
+
+  "$defs": {
+    "stepStatus": {
+      "type": "object",
+      "properties": {
+        "status": { "type": "string", "enum": ["pending", "in-progress", "completed", "skipped"] },
+        "startedAt": { "type": ["string", "null"], "format": "date-time" },
+        "completedAt": { "type": ["string", "null"], "format": "date-time" }
+      }
+    },
+    "fileSpec": {
+      "type": "object",
+      "properties": {
+        "path": { "type": "string", "description": "Relative file path" },
+        "description": { "type": "string" },
+        "pattern": { "type": "string", "description": "Reference pattern from existing codebase" },
+        "instructions": { "type": "string" }
+      }
+    }
+  }
+}