@atlashub/smartstack-cli 2.3.0 → 2.4.0

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

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`