@atlashub/smartstack-cli 1.34.0 → 1.35.0

package/templates/skills/documentation/SKILL.md

@@ -8,14 +8,17 @@ description: |
   - User wants to document a module, table, tool, or test
   - After implementing a feature to generate its documentation
   Types: user module, developer tools, database ERD, testing tools
+argument-hint: "<module-name> [--type user|developer|database|testing|update]"
 ---
 
-# Skill Documentation SmartStack
-
-> **Note:** This skill works in synergy with the `/documentation:module` command.
+<objective>
+Generate and maintain technical documentation integrated into SmartStack web app.
+Works in synergy with the `/documentation:module` command.
 
 **Reference:** [_shared.md](../_shared.md) for architecture, i18n
+</objective>
 
+<quick_start>
 ## WHEN THIS SKILL ACTIVATES
 
 Claude automatically invokes this skill when it detects:
@@ -27,9 +30,33 @@ Claude automatically invokes this skill when it detects:
 | After implementation | "The feature is done, generate the doc" |
 | Structure question | "How is the documentation organized?" |
 | Keywords | "ERD", "schema", "diagram", "document" |
+| **Update request** | "Update the doc", "refresh documentation", "doc is outdated" |
+| **Drift detected** | "The SLA documentation is stale" |
+</quick_start>
 
----
+<parameters>
+## DOCUMENTATION TYPES
+
+| Type | Description | Output |
+|------|-------------|--------|
+| `user` | User module (data-driven) | `docs/business/{app}/{module}/frd-data.ts` + `index.tsx` |
+| `developer` | Development tool guide | `docs/developer/tools/{Tool}Page.tsx` |
+| `database` | Schema with ERD diagram | `docs/developer/database/{Schema}SchemaPage.tsx` |
+| `testing` | Testing tool | `docs/developer/testing/{Tool}TestingPage.tsx` |
+| `update` | Update existing documentation | Updates `frd-data.ts` + i18n FR |
+
+### Available Developer tools
+
+| Category | Tools |
+|----------|-------|
+| Local Environment | Docker Compose, MailDev, VS Code, Environment variables |
+| API Testing | Postman, REST Client, Swagger/OpenAPI |
+| E2E Testing | Microsoft Playwright, Inspector, Trace Viewer |
+| Load Testing | NBomber (.NET), k6, Azure Load Testing |
+| Security Testing | OWASP ZAP, Security Code Scan, Snyk, OWASP ASVS |
+</parameters>
 
+<workflow>
 ## AUTOMATIC WORKFLOW
 
 ### STEP 1: TYPE DETECTION
@@ -53,40 +80,35 @@ Identify the specific name:
 
 ### STEP 3: EXECUTION
 
-Follow the workflow of the `/documentation:module` command:
+**For NEW documentation (type = user|developer|database|testing):**
 
-```
-TYPE = detected type (user|developer|database|testing)
-TARGET = extracted target
+Follow the data-driven workflow from [templates.md](templates.md):
 
-→ Execute the complete /documentation:module workflow
+```
+1. Read source data (FRD, BRD, code patterns)
+2. Generate frd-data.ts (data file, ~50 lines)
+3. Generate index.tsx (page wrapper, ~10 lines)
+4. Generate i18n FR file (source language only)
+5. Update docs-manifest.json
+6. Update App.tsx routing and parent indexes
 ```
 
----
-
-## QUICK REFERENCE
-
-### Documentation types
-
-| Type | Description | Output |
-|------|-------------|--------|
-| `user` | User module with UI mockups | `docs/user/{context}/{Module}DocPage.tsx` |
-| `developer` | Development tool guide | `docs/developer/tools/{Tool}Page.tsx` |
-| `database` | Schema with ERD diagram | `docs/developer/database/{Schema}SchemaPage.tsx` |
-| `testing` | Testing tool | `docs/developer/testing/{Tool}TestingPage.tsx` |
-
-### Available Developer tools
+**For UPDATE documentation (type = update):**
 
-| Category | Tools |
-|----------|-------|
-| Local Environment | Docker Compose, MailDev, VS Code, Environment variables |
-| API Testing | Postman, REST Client, Swagger/OpenAPI |
-| E2E Testing | Microsoft Playwright, Inspector, Trace Viewer |
-| Load Testing | NBomber (.NET), k6, Azure Load Testing |
-| Security Testing | OWASP ZAP, Security Code Scan, Snyk, OWASP ASVS |
+```
+1. Read docs-manifest.json → find target module
+2. Invoke docs-context-reader agent → get current doc state
+3. Identify code changes since last doc update (git diff)
+4. Map changes to documentation sections (see data-schema.md)
+5. Update frd-data.ts with new/modified data
+6. Update i18n FR file if labels changed
+7. Update docs-manifest.json timestamps
+```
 
----
+> **i18n simplifié:** Seul FR (source) est généré. EN/IT/DE sont déférés à un pipeline de traduction séparé.
+</workflow>
 
+<execution_rules>
 ## ABSOLUTE RULES
 
 1. **NEVER** hardcoded text → `useTranslation('docs')`
@@ -95,6 +117,17 @@ TARGET = extracted target
 4. **ALWAYS** confirm before creating
 5. **ALWAYS** update App.tsx and parent indexes
 6. **ALWAYS** add module in `UserIndexPage.tsx` (IF type == `user`)
+</execution_rules>
+
+---
+
+<success_criteria>
+- Documentation page renders correctly in React app
+- i18n files created for all 4 languages (FR, EN, IT, DE)
+- Route registered in App.tsx
+- docs-manifest.json updated
+- Module appears in UserIndexPage (if type = user)
+</success_criteria>
 
 ---
 
@@ -131,4 +164,8 @@ TARGET = extracted target
 ## ASSOCIATED FILES
 
 - **React Templates:** [templates.md](templates.md)
+- **Data Schema:** [data-schema.md](data-schema.md)
+- **FrdDocRenderer:** `web/smartstack-web/src/components/docs/FrdDocRenderer.tsx`
+- **Types:** `web/smartstack-web/src/components/docs/types.ts`
+- **Manifest Schema:** `_resources/docs-manifest-schema.md`
 - **Complete Command:** `.claude/commands/documentation-module.md`

package/templates/skills/documentation/data-schema.md

@@ -0,0 +1,198 @@
+# Documentation Data Schema
+
+## Purpose
+
+This file describes how to generate `frd-data.ts` files for the `FrdDocRenderer` shared component.
+Instead of generating full TSX components (~250 lines) per module, generate only the data (~50 lines).
+
+## FrdData Interface Reference
+
+The full TypeScript interface is in `web/smartstack-web/src/components/docs/types.ts`.
+
+## Data Extraction Mapping
+
+### From FRD (3-functional-specification.md)
+
+| FRD Section | FrdData Field | Extraction |
+|-------------|---------------|------------|
+| Section 1: Overview | `overview.objective` | Functional objective text |
+| Section 1: Overview | `overview.problem` | Problem statement |
+| Section 1: Overview | `overview.solution` | Solution statement |
+| Section 2: Use Cases | `useCases[]` | UC-XXX entries (id, name, actor, description, permission, priority) |
+| Section 3: Functional Requirements | `features[]` | FR-XXX entries grouped as features |
+| Section 5: Permission Matrix | `permissions[]` | Role-permission entries |
+| Section 6: Gherkin Scenarios | (used for test data, not doc) | - |
+| Section 7: Validations | `businessRules[]` | BR-XXX from BRD cross-referenced |
+
+### From BRD (2-business-requirements.md)
+
+| BRD Section | FrdData Field | Extraction |
+|-------------|---------------|------------|
+| Section 2: Business Objectives | `overview.stats` | Count objectives |
+| Section 3: Business Rules | `businessRules[]` | BR-XXX entries (id, name, category, statement) |
+| Section 6: Integrations | `technicalRef` | Integration notes |
+
+### From Handoff (4-development-handoff.md)
+
+| Handoff Section | FrdData Field | Extraction |
+|-----------------|---------------|------------|
+| Section 3: Files to Create | `technicalRef.entityNames` | Entity names |
+| Section 6: API Endpoints | `apiEndpoints[]` | Endpoint entries |
+| Section 1: Quick Context | `technicalRef.permissionBase` | Permission base path |
+| Section 1: Quick Context | `technicalRef.controllerRoute` | Controller route |
+
+### Generated/Inferred Fields
+
+| Field | Source |
+|-------|--------|
+| `featureId` | From 00-context.md state |
+| `moduleName` | From 00-context.md state |
+| `applicationName` | From 00-context.md state |
+| `version` | "1.0" (initial) |
+| `benefits[]` | Inferred from BRD objectives or i18n |
+| `beforeAfter` | Inferred from discovery problem/solution |
+| `steps[]` | Inferred from use cases main scenario |
+| `faq[]` | Inferred from discovery open questions |
+| `screenshots` | Convention: `/assets/docs/{module}/step-{N}.png` |
+
+## Generated File Structure
+
+### frd-data.ts (per module, ~50-80 lines)
+
+```typescript
+// web/smartstack-web/src/pages/docs/business/{app}/{module}/frd-data.ts
+import type { FrdData } from '@/components/docs';
+
+export const frdData: FrdData = {
+  featureId: 'FEAT-001',
+  moduleName: 'Sla',
+  applicationName: 'Support',
+  version: '1.0',
+
+  overview: {
+    objective: 'docs.support.sla.overview.objective',
+    problem: 'docs.support.sla.overview.problem',
+    solution: 'docs.support.sla.overview.solution',
+    stats: { useCases: 4, businessRules: 6, permissions: 5, endpoints: 5 },
+  },
+
+  useCases: [
+    { id: 'UC-001', name: 'Create SLA', actor: 'Admin', description: '...', permission: 'business.support.sla.create', priority: 'Must' },
+    // ...
+  ],
+
+  benefits: [
+    { icon: 'time', titleKey: 'docs.support.sla.benefits.time.title', value: '-70%', descriptionKey: 'docs.support.sla.benefits.time.description' },
+    { icon: 'quality', titleKey: 'docs.support.sla.benefits.quality.title', value: '+95%', descriptionKey: 'docs.support.sla.benefits.quality.description' },
+    { icon: 'roi', titleKey: 'docs.support.sla.benefits.roi.title', value: '3x', descriptionKey: 'docs.support.sla.benefits.roi.description' },
+  ],
+
+  beforeAfter: {
+    beforeItems: ['Manual SLA tracking', 'No escalation alerts', 'No compliance visibility', 'Scattered data'],
+    afterItems: ['Automated SLA monitoring', 'Real-time escalation', 'Compliance dashboard', 'Centralized metrics'],
+  },
+
+  features: [
+    { id: 'F-001', title: 'SLA Configuration', description: '...', example: '...' },
+    // ...
+  ],
+
+  steps: [
+    { number: 1, title: 'Navigate to SLA module', description: '...', screenshotKey: 'step1' },
+    { number: 2, title: 'Create SLA policy', description: '...', screenshotKey: 'step2' },
+    // ...
+  ],
+
+  faq: [
+    { questionKey: 'docs.support.sla.faq.1.question', answerKey: 'docs.support.sla.faq.1.answer' },
+    // ...
+  ],
+
+  businessRules: [
+    { id: 'BR-001', name: 'SLA Time Calculation', category: 'Calculation', statement: '...' },
+    // ...
+  ],
+
+  permissions: [
+    { path: 'business.support.sla.read', description: 'View SLA policies', roles: ['Admin', 'Manager', 'User', 'ReadOnly'] },
+    { path: 'business.support.sla.create', description: 'Create SLA policies', roles: ['Admin', 'Manager'] },
+    // ...
+  ],
+
+  apiEndpoints: [
+    { method: 'GET', path: '/api/business/sla', handler: 'GetAllSlaQuery', permission: '.read' },
+    { method: 'POST', path: '/api/business/sla', handler: 'CreateSlaCommand', permission: '.create' },
+    // ...
+  ],
+
+  screenshots: {
+    step1: '/assets/docs/sla/step-1.png',
+    step2: '/assets/docs/sla/step-2.png',
+  },
+
+  technicalRef: {
+    permissionBase: 'business.support.sla',
+    controllerRoute: 'business.support.sla',
+    entityNames: ['Sla', 'SlaPolicy', 'SlaEscalation'],
+  },
+};
+```
+
+### Page wrapper (per module, ~10 lines)
+
+```typescript
+// web/smartstack-web/src/pages/docs/business/{app}/{module}/index.tsx
+import { FrdDocRenderer } from '@/components/docs';
+import { frdData } from './frd-data';
+
+export default function {Module}DocPage() {
+  return (
+    <FrdDocRenderer
+      data={frdData}
+      backPath="/docs/business/{app}"
+      backLabel="nav.backToApp"
+    />
+  );
+}
+```
+
+### i18n file (FR source, ~30 lines)
+
+```json
+// web/smartstack-web/src/i18n/locales/fr/docs-{app}-{module}.json
+{
+  "support": {
+    "sla": {
+      "overview": {
+        "objective": "Gestion des niveaux de service (SLA)",
+        "problem": "Les engagements de service ne sont pas suivis, les escalades sont manuelles",
+        "solution": "Monitoring automatique des SLA avec alertes et escalades configurables"
+      },
+      "benefits": {
+        "time": { "title": "Temps économisé", "description": "Réduction de 70% du temps de suivi manuel" },
+        "quality": { "title": "Fiabilité", "description": "95% des SLA respectés grâce au monitoring" },
+        "roi": { "title": "ROI", "description": "Retour sur investissement en 3 mois" }
+      },
+      "faq": {
+        "1": {
+          "question": "Dois-je configurer chaque SLA manuellement ?",
+          "answer": "Non, des templates prédéfinis sont disponibles pour les cas courants."
+        }
+      }
+    }
+  }
+}
+```
+
+> **Note:** Seul FR est généré. EN/IT/DE sont marqués comme "deferred" et générés par un pipeline de traduction séparé.
+
+## Screenshot Convention
+
+| Key | Path | Description |
+|-----|------|-------------|
+| `step{N}` | `/assets/docs/{module}/step-{N}.png` | Step-by-step guide screenshots |
+| `overview` | `/assets/docs/{module}/overview.png` | Module overview screenshot |
+| `dashboard` | `/assets/docs/{module}/dashboard.png` | Dashboard view |
+
+Screenshots are added manually or via Playwright E2E tests.
+The `FrdDocRenderer` shows a "Screenshot à venir" placeholder when the image file is not found.

package/templates/skills/documentation/templates.md

@@ -22,7 +22,36 @@ Chaque documentation de module DOIT inclure ces sections dans cet ordre:
 
 ---
 
-## Template User Module (Business-First)
+## Data-Driven Approach (Recommended)
+
+> **Principe:** Au lieu de générer un composant TSX complet (~250 lignes) par module,
+> générer uniquement un fichier de DONNÉES (`frd-data.ts`, ~50 lignes) + un wrapper minimal.
+> Le rendu est assuré par le composant partagé `FrdDocRenderer` dans `web/.../components/docs/`.
+
+### Fichiers à générer par module
+
+**1. Data file** (`frd-data.ts`) : Voir [data-schema.md](data-schema.md) pour le mapping complet.
+
+**2. Page wrapper** (`index.tsx`, ~10 lignes) :
+```tsx
+import { FrdDocRenderer } from '@/components/docs';
+import { frdData } from './frd-data';
+
+export default function {ModuleName}DocPage() {
+  return <FrdDocRenderer data={frdData} backPath="/docs/business/{app}" />;
+}
+```
+
+**3. i18n FR uniquement** : Générer la langue source (FR). EN/IT/DE sont déférés.
+
+> **Screenshots:** Chemins conventionnels `/assets/docs/{module}/step-{N}.png`.
+> Le renderer affiche un placeholder "Screenshot à venir" si l'image n'existe pas.
+
+---
+
+## Legacy: Template TSX Complet (référence)
+
+> **Déprécié:** Conservé pour référence. Utilisez l'approche data-driven ci-dessus.
 
 ```tsx
 // web/smartstack-web/src/pages/docs/user/{ModuleName}DocPage.tsx

package/templates/skills/gitflow/steps/step-init.md

@@ -265,7 +265,127 @@ AskUserQuestion:
     multiSelect: false
 ```
 
-The user will type the actual name via "Other". Use it as `{PROJECT_NAME}`.
+The user will type the actual name via "Other". Use this raw input for step 6b.
+
+### 6b. Normalize Project Name (INTELLIGENT)
+
+**⛔ ALWAYS normalize, even if user chose the detected name.**
+
+**Step 1: Parse input into words**
+
+Split the raw input on any separator: spaces, hyphens, underscores, dots, camelCase boundaries.
+
+| Raw input | Parsed words |
+|-----------|-------------|
+| `mon super projet` | `["mon", "super", "projet"]` |
+| `gestion-des-stocks` | `["gestion", "des", "stocks"]` |
+| `my_awesome_app` | `["my", "awesome", "app"]` |
+| `SmartStack.App` | `["Smart", "Stack", "App"]` |
+| `userManagement` | `["user", "Management"]` |
+
+**Step 2: Language detection and spell check**
+
+For EACH word, you MUST:
+1. **Detect the language** (French, English, or technical/proper noun)
+2. **Check spelling** - flag obvious typos
+3. **Suggest corrections** if misspelled
+
+| Word | Language | Spelling | Suggestion |
+|------|----------|----------|------------|
+| `gestion` | FR | ✅ | - |
+| `gestoin` | FR | ❌ typo | → `gestion` |
+| `managment` | EN | ❌ typo | → `management` |
+| `SmartStack` | Proper noun | ✅ | - |
+| `auth` | EN (abbreviation) | ✅ | - |
+
+**If typos detected**, ask the user BEFORE generating variants:
+
+```yaml
+AskUserQuestion:
+  - header: "Spelling"
+    question: "Corrections detected. Accept?"
+    options:
+      - label: "Accept corrections (Recommended)"
+        description: "'gestoin' → 'gestion', 'managment' → 'management'"
+      - label: "Keep original"
+        description: "Use the name as typed"
+    multiSelect: false
+```
+
+**Step 3: Generate all name variants**
+
+From the cleaned words, generate ALL variants:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  PROJECT NAME VARIANTS                                       │
+│  Input: "gestion des stocks"                                 │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  A) PascalCase.Dot    →  Gestion.Des.Stocks                 │
+│     Best for: .NET namespace, C# project, folder name        │
+│                                                              │
+│  B) PascalCase        →  GestionDesStocks                    │
+│     Best for: Class name, assembly name                      │
+│                                                              │
+│  C) kebab-case        →  gestion-des-stocks                  │
+│     Best for: Git repo, npm package, URL slug                │
+│                                                              │
+│  D) snake_case        →  gestion_des_stocks                  │
+│     Best for: Database, Python, file system                  │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Step 4: Ask user to choose the PRIMARY format**
+
+```yaml
+AskUserQuestion:
+  - header: "Format"
+    question: "Which format for the project name?"
+    options:
+      - label: "PascalCase.Dot (Recommended)"
+        description: "{PascalCase.Dot variant} - .NET convention"
+      - label: "PascalCase"
+        description: "{PascalCase variant} - single word"
+      - label: "kebab-case"
+        description: "{kebab-case variant} - git/npm convention"
+      - label: "snake_case"
+        description: "{snake_case variant} - database/python convention"
+    multiSelect: false
+```
+
+**Step 5: Store all derived names**
+
+Regardless of the chosen primary format, ALL variants are generated and stored:
+
+```json
+{
+  "PROJECT_NAME": "{chosen format}",
+  "PROJECT_VARIANTS": {
+    "pascalCaseDot": "Gestion.Des.Stocks",
+    "pascalCase": "GestionDesStocks",
+    "kebabCase": "gestion-des-stocks",
+    "snakeCase": "gestion_des_stocks",
+    "displayName": "Gestion Des Stocks",
+    "words": ["gestion", "des", "stocks"],
+    "language": "fr"
+  }
+}
+```
+
+These variants are available for subsequent steps (repo name, namespace, folder, etc.).
+
+**Real-world examples:**
+
+| User types | PascalCase.Dot | kebab-case | PascalCase |
+|-----------|---------------|------------|------------|
+| `smart stack app` | `SmartStack.App` | `smart-stack-app` | `SmartStackApp` |
+| `gestion-des-stocks` | `Gestion.Des.Stocks` | `gestion-des-stocks` | `GestionDesStocks` |
+| `Mon Projet V2` | `Mon.Projet.V2` | `mon-projet-v2` | `MonProjetV2` |
+| `user auth module` | `User.Auth.Module` | `user-auth-module` | `UserAuthModule` |
+| `PROJET TEST` | `Projet.Test` | `projet-test` | `ProjetTest` |
+| `e-commerce platform` | `ECommerce.Platform` | `e-commerce-platform` | `ECommercePlatform` |
 
 ### 7. Ask Worktree Mode
 
@@ -332,6 +452,13 @@ mkdir -p "$DEVELOP_PATH/.claude/gitflow/{plans,logs,cache,backup}"
   "version": "2.0.0",
   "repository": {
     "name": "{PROJECT_NAME}",
+    "nameVariants": {
+      "pascalCaseDot": "{PascalCase.Dot}",
+      "pascalCase": "{PascalCase}",
+      "kebabCase": "{kebab-case}",
+      "snakeCase": "{snake_case}",
+      "displayName": "{Display Name}"
+    },
     "rootFolder": "{ROOT_FOLDER}",
     "remoteUrl": "{REPO_URL}"
   },

package/templates/skills/gitflow/templates/config.json

@@ -2,6 +2,13 @@
   "version": "2.0.0",
   "repository": {
     "name": "",
+    "nameVariants": {
+      "pascalCaseDot": "",
+      "pascalCase": "",
+      "kebabCase": "",
+      "snakeCase": "",
+      "displayName": ""
+    },
     "defaultBranch": "main",
     "remoteUrl": ""
   },

package/templates/skills/ralph-loop/SKILL.md

@@ -194,12 +194,15 @@ Before ANY work, verify MCP servers:
   "created": "2024-01-01T00:00:00Z",
   "max_iterations": 50,
   "completion_promise": "COMPLETE",
+  "source": null,
   "tasks": [
     { "id": 1, "description": "Task 1", "passes": false },
     { "id": 2, "description": "Task 2", "passes": false }
   ]
 }
 ```
+
+> **`source` field:** Optional path to the BA handoff document that generated this task list (set by `/business-analyse` step-05). When present, Ralph Loop can reference the handoff for detailed specifications. `null` when tasks are created directly by Ralph Loop.
 </file_structure>
 
 <execution_rules>