@atlashub/smartstack-cli 2.2.0 → 2.4.0

package/templates/skills/business-analyse/steps/step-01-cadrage.md

@@ -0,0 +1,259 @@
+---
+name: step-01-cadrage
+description: Application/module framing - context, problem, stakeholders, scope, application roles
+model: opus
+next_step: steps/step-02-decomposition.md
+---
+
+# Step 1: Cadrage (Framing)
+
+## MANDATORY EXECUTION RULES
+
+- ALWAYS use ULTRATHINK mode for this step
+- ALWAYS apply the 5 Elicitation Techniques from `_shared.md`
+- NEVER accept vague answers — probe deeper
+- NEVER define entities or business rules here — that's per-module in step-03
+- ALL questions via AskUserQuestion tool (NEVER as text dumps)
+- ALL communication in `{language}` (from feature.json.metadata.language)
+
+## YOUR TASK
+
+Frame the analysis scope at the **application level**: understand the problem, stakeholders, scope, and define application-level roles. This step works for both multi-module applications and single modules.
+
+**Key difference from old step-01-analyse:** This step does NOT define entities, business rules, or process flows. Those are per-module and handled in step-03.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Read Current State
+
+```
+ba-reader.findFeature({feature_id})
+→ Read metadata: application, language, workflow.mode, useCase
+→ Read cadrage section (if resuming)
+```
+
+IF cadrage already completed (status = "framed"):
+  Display: "Cadrage already completed. Loading next step."
+  Load: steps/step-02-decomposition.md
+  STOP
+
+### 2. Codebase Pre-Research
+
+> **Same pattern as previous step-01-analyse.** Understand what already exists.
+
+**Phase 2a: MCP Tools (if available)**
+```
+IF mcp_available:
+  Call: mcp__smartstack__analyze_extension_points
+  → Discover existing modules, entities, services
+
+  Call: mcp__smartstack__api_docs
+  → Existing API documentation
+
+  Call: mcp__smartstack__validate_conventions
+  → Validate application/module naming
+
+  Store findings in {codebase_context}
+```
+
+**Phase 2b: Parallel Agents (unless economy_mode)**
+```
+IF NOT economy_mode:
+  Launch 3 agents in parallel:
+    Agent 1: Search for existing domain entities (Glob: **/Domain/**/*.cs)
+    Agent 2: Search for existing services/integrations (Grep: IService, IRepository)
+    Agent 3: Search for existing page patterns (Glob: **/pages/business/**/*.tsx)
+
+  Merge findings into {codebase_context}
+```
+
+**Phase 2c: Economy Mode**
+```
+IF economy_mode:
+  Use Glob/Grep directly (no subagents)
+  Quick scan of Domain/, Application/, pages/ directories
+```
+
+### 3. Application-Level Questionnaire (application mode)
+
+> **Only loaded when workflow.mode = "application"**
+
+Load: `questionnaire/00-application.md`
+
+Ask questions in batches of max 4 via AskUserQuestion:
+
+**Batch 1 (Q0.1-Q0.2): Application Identity**
+- Application name (PascalCase)
+- Application purpose (1-2 sentences)
+
+**Batch 2 (Q0.3-Q0.4): Module Landscape**
+- How many modules envisioned
+- Which are must-have for first release
+
+**Batch 3 (Q0.5-Q0.6): Application Roles**
+- Standard 4-tier roles or customize
+- Module-specific role restrictions
+
+**Batch 4 (Q0.7-Q0.8): Cross-Module**
+- Business processes spanning modules
+- Default role for new users
+
+After each batch: Apply ULTRATHINK + Elicitation Techniques.
+
+### 4. Core Questionnaires (always)
+
+Load these categories in order:
+
+**Category 01 - Context** (`questionnaire/01-context.md`)
+- Q1.1-Q1.4: Problem, AS-IS, TO-BE, trigger
+- 1 AskUserQuestion batch
+
+**Category 02 - Stakeholders** (`questionnaire/02-stakeholders.md`)
+- Q2.1-Q2.8: Roles, tasks, frequency, pain points
+- 2 AskUserQuestion batches
+- ULTRATHINK: Map stakeholders to application roles
+
+**Category 03 - Scope** (`questionnaire/03-scope.md`)
+- Q3.1-Q3.8: MoSCoW prioritization, flows, errors
+- 2 AskUserQuestion batches
+- ULTRATHINK: Ensure scope items map to modules
+
+### 5. Conditional Questionnaires
+
+Based on feature description analysis, load additional categories:
+
+| Condition | Category | Questionnaire |
+|-----------|----------|---------------|
+| Security concerns mentioned | 06 | `questionnaire/06-security.md` |
+| Integration with external systems | 05 | `questionnaire/05-integrations.md` |
+| Performance requirements | 08 | `questionnaire/08-performance.md` |
+| Technical constraints | 09 | `questionnaire/09-constraints.md` |
+| Documentation requirements | 10 | `questionnaire/10-documentation.md` |
+
+> **Categories 04 (data), 07 (ui), 11 (data-lifecycle), 12 (migration), 13 (cross-module) are per-module and loaded in step-03.**
+
+### 6. Application Roles Definition
+
+> **Define roles at the APPLICATION level, not per-module.**
+
+IF application mode AND roles not yet defined from Q0.5:
+  Propose the standard 4-tier roles:
+
+```
+Application Roles for {application_name}:
+
+| Role | Level | Default Permissions |
+|------|-------|-------------------|
+| {App} Admin | admin | business.{app}.* (wildcard) |
+| {App} Manager | manager | read, create, update, assign |
+| {App} Contributor | contributor | read, create, update |
+| {App} Viewer | viewer | read only |
+```
+
+Ask via AskUserQuestion:
+```
+question: "Ces 4 rôles conviennent-ils pour {application_name} ?"
+header: "Rôles"
+options:
+  - label: "Oui, parfait"
+    description: "Utiliser les 4 rôles standards tels quels"
+  - label: "Renommer"
+    description: "Garder 4 niveaux mais personnaliser les noms"
+  - label: "Personnaliser"
+    description: "Modifier le nombre ou les permissions des rôles"
+```
+
+IF single-module mode:
+  Same role definition but inferred from stakeholders
+
+### 7. Proactive Suggestions
+
+> **Same pattern as previous step-01.** Load suggestion catalog.
+
+Load: `patterns/suggestion-catalog.md`
+
+1. Analyze scope items and stakeholder needs
+2. Match against catalog patterns
+3. Present top 3-4 suggestions via AskUserQuestion (multiSelect: true)
+4. Store accepted suggestions in `suggestions[]`
+
+### 8. Risk Analysis
+
+Ask via AskUserQuestion:
+```
+question: "Quels sont les principaux risques pour ce projet ?"
+header: "Risques"
+multiSelect: true
+options:
+  - label: "Adoption utilisateur"
+    description: "Risque que les utilisateurs n'adoptent pas le système"
+  - label: "Qualité des données"
+    description: "Données existantes incomplètes ou incohérentes à migrer"
+  - label: "Dépendances techniques"
+    description: "Dépendance à des systèmes externes ou des APIs"
+  - label: "Complexité fonctionnelle"
+    description: "Règles métier complexes ou mal documentées"
+```
+
+Classify per probability/impact:
+- High/High → Critical (mitigation required)
+- High/Low or Low/High → Medium (monitor)
+- Low/Low → Low (accept)
+
+### 9. Write Cadrage to Feature.json
+
+Use ba-writer to enrich master feature.json:
+
+```
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "cadrage",
+  data: {
+    problem: {Q1.1 answer},
+    asIs: {Q1.2 answer},
+    toBe: {Q1.3 answer},
+    trigger: {Q1.4 answer},
+    stakeholders: [{mapped from Q2.x answers}],
+    globalScope: {
+      mustHave: [{from Q3.x}],
+      shouldHave: [{from Q3.x}],
+      couldHave: [{from Q3.x}],
+      outOfScope: [{from Q3.x}]
+    },
+    applicationRoles: [{from section 6}],
+    risks: [{from section 8}],
+    acceptanceCriteria: [{derived from scope}],
+    codebaseContext: {codebase_context}
+  }
+})
+
+ba-writer.updateStatus({feature_id}, "framed")
+```
+
+### 10. Display Summary
+
+```
+## Cadrage Complete - {feature_id}
+
+| Aspect | Count |
+|--------|-------|
+| Stakeholders | {count} |
+| Must-have scope items | {count} |
+| Application roles | {count} |
+| Risks identified | {count} |
+| Suggestions accepted | {count} |
+
+### Application Roles
+{table of roles with permission levels}
+
+### Next Step
+→ Module decomposition (step-02-decomposition.md)
+```
+
+---
+
+## NEXT STEP
+
+Load: `./step-02-decomposition.md`

package/templates/skills/business-analyse/steps/step-02-decomposition.md

@@ -0,0 +1,282 @@
+---
+name: step-02-decomposition
+description: Module decomposition - identify modules, dependency graph, topological sort, client checkpoint
+model: sonnet
+next_step: steps/step-03-specify.md
+---
+
+# Step 2: Decomposition
+
+## MANDATORY EXECUTION RULES
+
+- ALWAYS present the module structure to the client for validation (BLOCKING checkpoint)
+- NEVER proceed to specification without client approval of module structure
+- ALWAYS sort modules by dependency (foundations first)
+- ALWAYS detect dependency cycles (ERROR if found)
+- This step runs for BOTH application mode and single-module mode (trivial for single)
+
+## YOUR TASK
+
+Decompose the application scope into ordered modules. Identify dependencies between modules and determine the processing order for iterative specification.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Read Cadrage Results
+
+```
+ba-reader.findFeature({feature_id})
+→ Read cadrage.globalScope (mustHave, shouldHave, couldHave)
+→ Read cadrage.stakeholders (roles, tasks, pain points)
+→ Read cadrage.applicationRoles
+→ Read cadrage.codebaseContext (existing modules found)
+→ Read metadata.workflow.mode
+```
+
+IF status already "decomposed":
+  Display: "Decomposition already completed. Loading next step."
+  Load: steps/step-03-specify.md
+  STOP
+
+### 2. Module Identification
+
+**From the scope items and stakeholder needs, identify distinct modules:**
+
+For each mustHave/shouldHave scope item:
+- Group related items into cohesive functional units
+- Each module should be independently deployable
+- Each module maps to a navigation entry at Level 3 (Module)
+
+**ULTRATHINK Challenge:**
+- "Is this one module or two? Could a user need only half of it?"
+- "Are there hidden modules not mentioned in scope? (e.g., Notifications, Dashboard)"
+- "Does the codebase already have modules that should be extended vs. created new?"
+
+**For each module, determine:**
+```json
+{
+  "code": "PascalCase module name",
+  "description": "1-2 sentence description",
+  "featureType": "data-centric | integration | ui-centric | workflow | reporting | full-module",
+  "entities": ["Anticipated entity names"],
+  "priority": "must | should | could",
+  "estimatedComplexity": "simple | medium | complex"
+}
+```
+
+**Complexity estimation rules:**
+| Criteria | Simple | Medium | Complex |
+|----------|--------|--------|---------|
+| Entities | ≤2 | 3-5 | >5 |
+| Expected UCs | ≤4 | 5-10 | >10 |
+| Integrations | 0 | 1-2 | >2 |
+| Workflows | None | Simple | Multi-step with approvals |
+
+### 3. Present Module List to Client
+
+Display the identified modules as markdown:
+
+```
+## Modules identifiés pour {application_name}
+
+| # | Module | Type | Priorité | Complexité | Entités pressenties |
+|---|--------|------|----------|------------|---------------------|
+| 1 | Customers | data-centric | must | medium | Customer, Address, Contact |
+| 2 | Products | data-centric | must | simple | Product, Category |
+| 3 | Orders | workflow | must | complex | Order, OrderLine |
+| 4 | Invoices | workflow | should | medium | Invoice, InvoiceLine, Payment |
+```
+
+Ask via AskUserQuestion:
+```
+question: "Ces modules correspondent-ils à votre vision de l'application ?"
+header: "Modules"
+options:
+  - label: "Validé"
+    description: "La liste des modules est correcte, on peut continuer"
+  - label: "Ajouter un module"
+    description: "Il manque un module dans la liste"
+  - label: "Retirer un module"
+    description: "Un module est en trop ou hors périmètre"
+  - label: "Modifier un module"
+    description: "Renommer, fusionner ou découper un module"
+```
+
+IF modifications requested:
+  Apply changes and re-present the list
+  Loop until "Validé"
+
+### 4. Dependency Analysis
+
+For each pair of modules, determine dependencies:
+
+**Dependency types:**
+| Type | Signal | Example |
+|------|--------|---------|
+| FK | Module A references entity from module B | Order.CustomerId → Customer |
+| Event | Module A produces event consumed by module B | Order.Created → Invoice.AutoGenerate |
+| Shared-entity | Both modules operate on same entity | Both Orders and Invoices reference Customer |
+| Lookup | Module A uses reference data from module B | Products.CategoryId → Categories (if separate module) |
+
+**For each dependency found:**
+```json
+{
+  "from": "Orders",
+  "to": "Customers",
+  "type": "FK",
+  "description": "Order references Customer via CustomerId"
+}
+```
+
+### 5. Topological Sort
+
+Sort modules so dependencies are processed first:
+
+**Algorithm:**
+1. Build adjacency list from dependency edges
+2. Compute in-degree for each module (number of dependencies)
+3. Start with modules having in-degree 0 (no dependencies)
+4. Process in BFS order: remove processed modules, reduce in-degrees
+5. Group into layers (modules with same depth can be processed in parallel)
+
+**Cycle detection:**
+IF a cycle is detected:
+  Display ERROR:
+  ```
+  ⚠ Dépendance circulaire détectée : {Module A} → {Module B} → {Module A}
+  Les modules ne peuvent pas dépendre mutuellement.
+  ```
+  Ask user to resolve: remove one direction of the dependency
+
+**Result:**
+```json
+{
+  "topologicalOrder": ["Customers", "Products", "Orders", "Invoices"],
+  "layers": [
+    { "layer": 0, "modules": ["Customers", "Products"] },
+    { "layer": 1, "modules": ["Orders"] },
+    { "layer": 2, "modules": ["Invoices"] }
+  ]
+}
+```
+
+### 6. Client Checkpoint (BLOCKING)
+
+Display the complete decomposition as markdown:
+
+```
+## Structure de l'application {application_name}
+
+### Graphe de dépendances
+
+```
+Customers ──┐
+            ├──→ Orders ──→ Invoices
+Products ───┘
+```
+
+### Ordre de traitement
+
+| Ordre | Module | Dépend de | Complexité |
+|-------|--------|-----------|------------|
+| 1 | Customers | (aucune) | medium |
+| 2 | Products | (aucune) | simple |
+| 3 | Orders | Customers, Products | complex |
+| 4 | Invoices | Orders, Customers | medium |
+
+> Les modules seront spécifiés dans cet ordre. Chaque module sera
+> détaillé avec ses sections, entités, permissions et maquettes,
+> puis validé avant de passer au suivant.
+```
+
+Ask via AskUserQuestion:
+```
+question: "Validez-vous cette structure et cet ordre de traitement ?"
+header: "Validation"
+options:
+  - label: "Validé, on commence"
+    description: "Commencer la spécification par {first_module}"
+  - label: "Modifier l'ordre"
+    description: "Changer la priorité de traitement des modules"
+  - label: "Revenir aux modules"
+    description: "Modifier la liste des modules"
+```
+
+IF "Revenir aux modules": Go back to step 3
+IF "Modifier l'ordre": Re-sort and re-present
+
+### 7. Write Module Registry
+
+Use ba-writer to update master feature.json:
+
+```
+ba-writer.enrichModuleRegistry({
+  featureId: {feature_id},
+  modules: [{module objects with all fields}],
+  dependencyGraph: {
+    edges: [{dependency edges}],
+    topologicalOrder: [{sorted module codes}],
+    layers: [{layer groups}]
+  }
+})
+
+// Initialize workflow loop state
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "metadata.workflow",
+  data: {
+    moduleOrder: [{topological order}],
+    currentModuleIndex: 0,
+    completedModules: [],
+    currentModule: {first module code}
+  }
+})
+
+ba-writer.updateStatus({feature_id}, "decomposed")
+```
+
+### 8. Create Module Directories
+
+For each module in moduleOrder:
+```
+Create: docs/business/{app}/{module_code}/business-analyse/v1.0/
+```
+
+> Module feature.json files will be created by step-03 when each module is processed.
+
+### 9. Display Summary
+
+```
+## Decomposition Complete - {feature_id}
+
+| Aspect | Value |
+|--------|-------|
+| Modules identified | {count} |
+| Dependencies | {edge count} |
+| Dependency layers | {layer count} |
+| First module | {first module name} |
+
+### Processing Order
+{numbered list of modules}
+
+→ Starting iterative specification with {first_module}...
+```
+
+---
+
+## SINGLE-MODULE MODE
+
+When `workflow.mode = "module"` or only 1 scope item identified:
+
+1. Create a single module entry with code = `{module_name}` from init
+2. No dependency analysis needed
+3. **Simplified checkpoint:** Quick confirmation instead of full validation
+4. Set moduleOrder = [{single module code}]
+5. Proceed to step-03
+
+---
+
+## NEXT STEP
+
+Load: `./step-03-specify.md`