@atlashub/smartstack-cli 4.22.0 → 4.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "4.22.0",
+  "version": "4.24.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/skills/ba-design-ui/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ba-design-ui
+description: "Design user interfaces for each module: screens, wireframes, and navigation tree from Phase 1 analysis data."
+model: opus
+user_invocable: true
+---
+
+# /ba-design-ui
+
+Design user interfaces for each module based on the business analysis data (entities, use cases, permissions) produced by `/business-analyse`.
+
+## Triggers
+
+- Explicit invocation: `/ba-design-ui <feature-id>`
+- After `/business-analyse` step-04 (consolidation complete)
+- After `/ba-review` when corrections target UI/screens
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `<feature-id>` | Yes | Feature identifier (e.g., FEAT-001) |
+| `--module` | No | Restrict to a single module (e.g., HumanResources) |
+
+## Prerequisites
+
+- `/business-analyse` must be completed (step-04 consolidated)
+- JSON files must exist: `index.json`, `entities.json`, `usecases.json`, `permissions.json` per module
+- Feature status must be `consolidated` or `reviewed`
+
+## Workflow
+
+3 progressive steps:
+
+| Step | File | Role |
+|------|------|------|
+| 01 | `steps/step-01-screens.md` | Define sections/resources with detailed specs per module |
+| 02 | `steps/step-02-wireframes.md` | Generate wireframes (ASCII/HTML) for each screen |
+| 03 | `steps/step-03-navigation.md` | Define the complete navigation tree (seedDataCore) |
+
+## Input
+
+For each module, load via ba-reader:
+- `index.json` (module metadata, anticipatedSections)
+- `entities.json` (attributes with types, relationships)
+- `usecases.json` (actor actions, scenarios)
+- `permissions.json` (role matrix, permission paths)
+
+## Output
+
+Per module:
+- `screens.json` — Detailed interface specifications (SmartTable columns, SmartForm fields, SmartDashboard KPIs)
+- Wireframes embedded in screens.json (mockupFormat, elements[], layout, componentMapping)
+
+Project-level:
+- `navigation.json` — Complete navigation tree (routes, menus, breadcrumbs)
+
+## Absolute Rules
+
+- **NEVER** invent entities or permissions not defined in Phase 1 — UI specs MUST reference existing analysis data
+- **Every screen** MUST have a `permission` field referencing a valid permission path from permissions.json
+- **Every SmartTable column** MUST reference a valid entity attribute or relationship
+- **Every SmartForm field** MUST reference a valid entity attribute
+- **screens.json** MUST have at least one section per module
+
+## Post-Design Workflow
+
+```
+/ba-design-ui completes
+    |
+    v
+/ba-generate-html (generates interactive HTML with mockups, ERD, permission matrix)
+    |
+    v
+Client reviews HTML
+    |
+    v
+/ba-review (apply corrections, route back to /business-analyse or /ba-design-ui)
+```
+
+## References
+
+| File | Content |
+|------|---------|
+| `/business-analyse` skill | Source analysis data (entities, UCs, permissions) |
+| `/ba-generate-html` skill | HTML generation consuming screens.json |
+| `ba-generate-html/references/data-mapping.md` | JSON to FEATURE_DATA field mapping |
+
+## Entry Point
+
+**FIRST ACTION:** Load `steps/step-01-screens.md`

package/templates/skills/ba-design-ui/steps/step-01-screens.md

@@ -0,0 +1,177 @@
+---
+name: step-01-screens
+description: Define sections and resources with detailed UI specs per module
+model: opus
+next_step: steps/step-02-wireframes.md
+---
+
+# Step 01 — Screens (Define Sections & Resources)
+
+## Objective
+
+For each module, define all sections and resources with detailed interface specifications: SmartTable columns, SmartForm fields with types, SmartDashboard KPIs, SmartKanban columns.
+
+## Prerequisites
+
+- `/business-analyse` completed (entities, usecases, permissions exist)
+- Module index.json accessible via ba-reader
+
+## Execution
+
+### 1. Load Analysis Data
+
+For each module (in dependency order from index.json):
+
+```
+Load via ba-reader:
+  - entities.json → entity attributes with types, relationships
+  - usecases.json → actor actions, CRUD operations
+  - permissions.json → role matrix, permission paths
+  - index.json → anticipatedSections from step-02
+```
+
+### 2. Define Sections & Resources
+
+For each module, transform anticipatedSections into detailed screen specs.
+
+**SmartTable resource:**
+```json
+{
+  "code": "{entity-plural}-grid",
+  "type": "SmartTable",
+  "label": "Grille des {entity-plural}",
+  "columns": [
+    { "field": "code", "label": "Code", "type": "text", "sortable": true, "width": "100px" },
+    { "field": "fullName", "label": "Nom", "type": "text", "sortable": true },
+    { "field": "department.name", "label": "Departement", "type": "lookup", "filterable": true },
+    { "field": "status", "label": "Statut", "type": "badge", "filterable": true, "options": ["Active", "Inactive"] }
+  ],
+  "actions": ["create", "edit", "delete", "export"],
+  "filters": [
+    { "field": "department", "type": "select", "label": "Departement" },
+    { "field": "status", "type": "select", "label": "Statut" }
+  ],
+  "permission": "{AppCode}.{ModuleCode}.Read",
+  "rowActions": ["edit", "view-detail"],
+  "defaultSort": { "field": "code", "direction": "asc" },
+  "pageSize": 25
+}
+```
+
+**SmartForm resource:**
+```json
+{
+  "code": "{entity}-form",
+  "type": "SmartForm",
+  "label": "Fiche {entity}",
+  "tabs": [
+    {
+      "label": "Informations",
+      "fields": [
+        { "field": "firstName", "label": "Prenom", "type": "text", "required": true, "col": 6 },
+        { "field": "lastName", "label": "Nom", "type": "text", "required": true, "col": 6 },
+        { "field": "email", "label": "Email", "type": "email", "required": true, "validation": "unique" },
+        { "field": "department", "label": "Departement", "type": "lookup", "entity": "Department", "required": true },
+        { "field": "status", "label": "Statut", "type": "select", "options": ["Active", "Inactive"], "readonly": "onCreate" }
+      ]
+    },
+    {
+      "label": "Contrats",
+      "type": "subtable",
+      "entity": "Contract",
+      "columns": ["contractType", "startDate", "endDate", "status"]
+    }
+  ],
+  "permission": "{AppCode}.{ModuleCode}.Update"
+}
+```
+
+**SmartDashboard resource:**
+```json
+{
+  "code": "{module}-dashboard",
+  "type": "SmartDashboard",
+  "label": "Tableau de bord {module}",
+  "kpis": [
+    { "label": "Total actifs", "value": "count(status=Active)", "icon": "users", "color": "primary" },
+    { "label": "En conge", "value": "count(status=OnLeave)", "icon": "calendar", "color": "warning" }
+  ],
+  "charts": [
+    { "type": "pie", "label": "Repartition par departement", "dataSource": "employees", "groupBy": "department" },
+    { "type": "bar", "label": "Evolution des effectifs", "dataSource": "employees", "groupBy": "hireDate.year" }
+  ],
+  "permission": "{AppCode}.{ModuleCode}.Read"
+}
+```
+
+**SmartKanban resource:**
+```json
+{
+  "code": "{entity}-kanban",
+  "type": "SmartKanban",
+  "label": "Kanban {entity}",
+  "statusField": "status",
+  "columns": [
+    { "value": "Draft", "label": "Brouillon", "color": "gray" },
+    { "value": "Submitted", "label": "Soumis", "color": "blue" },
+    { "value": "Approved", "label": "Approuve", "color": "green" }
+  ],
+  "cardFields": ["code", "assignee", "dueDate"],
+  "permission": "{AppCode}.{ModuleCode}.Read"
+}
+```
+
+### 3. Column/Field Type Mapping
+
+Map entity attribute types to UI component types:
+
+| Entity type | SmartTable type | SmartForm type |
+|-------------|----------------|----------------|
+| `string` | `text` | `text` |
+| `int`, `decimal` | `number` | `number` |
+| `date` | `date` | `datepicker` |
+| `datetime` | `datetime` | `datetimepicker` |
+| `bool` | `boolean` | `checkbox` |
+| `enum` | `badge` | `select` |
+| `guid` (FK) | `lookup` | `lookup` |
+| `text` (long) | `text` (truncated) | `textarea` |
+
+### 4. Write screens.json
+
+For each module, write via ba-writer:
+
+```json
+{
+  "sections": [
+    {
+      "sectionCode": "list",
+      "sectionLabel": "Liste des employes",
+      "resources": [ /* SmartTable, filters */ ]
+    },
+    {
+      "sectionCode": "form",
+      "sectionLabel": "Fiche employe",
+      "resources": [ /* SmartForm with tabs */ ]
+    },
+    {
+      "sectionCode": "dashboard",
+      "sectionLabel": "Tableau de bord",
+      "resources": [ /* SmartDashboard */ ]
+    }
+  ]
+}
+```
+
+Update `index.json` with screens.json hash and status.
+
+## Validation
+
+- [ ] Every resource has a valid `permission` referencing permissions.json
+- [ ] Every SmartTable column references a valid entity attribute
+- [ ] Every SmartForm field references a valid entity attribute
+- [ ] Every section has at least one resource
+- [ ] Every module has at least one section
+
+## Transition
+
+-> Step 02 (wireframes) — Generate visual mockups for each screen

package/templates/skills/ba-design-ui/steps/step-02-wireframes.md

@@ -0,0 +1,140 @@
+---
+name: step-02-wireframes
+description: Generate wireframes (ASCII/HTML mockups) for each screen defined in step-01
+model: opus
+next_step: steps/step-03-navigation.md
+---
+
+# Step 02 — Wireframes (Generate Mockups)
+
+## Objective
+
+Generate visual wireframes for each screen defined in screens.json. Each wireframe provides a concrete representation of the UI layout, component placement, and user interactions.
+
+## Prerequisites
+
+- Step 01 (screens) completed
+- screens.json exists for each module with detailed section/resource specs
+
+## Execution
+
+### 1. Load Screen Specs
+
+For each module, read screens.json via ba-reader.
+
+### 2. Generate Wireframes per Resource
+
+For each resource in each section, generate a wireframe object:
+
+**SmartTable wireframe:**
+```json
+{
+  "screen": "{sectionCode}-{resourceCode}",
+  "section": "{sectionCode}",
+  "mockupFormat": "ascii",
+  "mockup": "+----------------------------------------------------------+\n| [Departement v] [Statut v]        [+ Nouveau employe]    |\n+------+----------------+---------------+--------+---------+\n| Code | Nom complet    | Departement   | Statut | Actions |\n+------+----------------+---------------+--------+---------+\n| E001 | Dupont Marie   | RH            | Actif  | [E] [S] |\n| E002 | Martin Pierre  | IT            | Conge  | [E] [S] |\n+------+----------------+---------------+--------+---------+\n| << 1 2 3 ... 10 >>                           25 par page |\n+----------------------------------------------------------+",
+  "elements": ["FilterBar", "DataGrid", "Pagination", "ActionButtons"],
+  "actions": ["filter", "sort", "create", "edit", "delete", "export"],
+  "componentMapping": [
+    { "wireframeElement": "FilterBar", "reactComponent": "SmartFilter" },
+    { "wireframeElement": "DataGrid", "reactComponent": "SmartTable" },
+    { "wireframeElement": "Pagination", "reactComponent": "SmartPagination" },
+    { "wireframeElement": "ActionButtons", "reactComponent": "SmartToolbar" }
+  ],
+  "layout": {
+    "type": "vertical",
+    "regions": ["filters", "grid", "pagination"]
+  },
+  "permissionsRequired": ["{AppCode}.{ModuleCode}.Read"]
+}
+```
+
+**SmartForm wireframe:**
+```json
+{
+  "screen": "{sectionCode}-{resourceCode}",
+  "section": "{sectionCode}",
+  "mockupFormat": "ascii",
+  "mockup": "+----------------------------------------------------------+\n| Fiche Employe                              [Sauvegarder] |\n+----------------------------------------------------------+\n| [Informations] [Contrats] [Documents]                    |\n+----------------------------------------------------------+\n| Prenom:      [_______________]  Nom: [_______________]   |\n| Email:       [_______________]  Tel: [_______________]   |\n| Departement: [Selectionnez v ]  Poste: [_____________]   |\n| Date embauche: [__ /__ /____]   Statut: [Actif      v]  |\n+----------------------------------------------------------+",
+  "elements": ["TabBar", "FormFields", "SaveButton"],
+  "actions": ["save", "cancel", "tab-switch"],
+  "componentMapping": [
+    { "wireframeElement": "TabBar", "reactComponent": "SmartTabs" },
+    { "wireframeElement": "FormFields", "reactComponent": "SmartForm" },
+    { "wireframeElement": "SaveButton", "reactComponent": "SmartButton" }
+  ],
+  "layout": {
+    "type": "vertical",
+    "regions": ["header", "tabs", "form-body", "actions"]
+  },
+  "permissionsRequired": ["{AppCode}.{ModuleCode}.Update"]
+}
+```
+
+**SmartDashboard wireframe:**
+```json
+{
+  "screen": "{sectionCode}-{resourceCode}",
+  "section": "{sectionCode}",
+  "mockupFormat": "ascii",
+  "mockup": "+----------------------------------------------------------+\n| Tableau de bord RH                                       |\n+-------------+-------------+-------------+----------------+\n| Total actifs| En conge    | Nouveaux    | Taux rotation  |\n|    156      |     12      |      8      |    3.2%        |\n+-------------+-------------+-------------+----------------+\n| [Repartition par dept (pie)]  [Evolution effectifs (bar)]|\n+----------------------------------------------------------+",
+  "elements": ["KPICards", "PieChart", "BarChart"],
+  "actions": ["filter-period", "export-report"],
+  "componentMapping": [
+    { "wireframeElement": "KPICards", "reactComponent": "SmartKPI" },
+    { "wireframeElement": "PieChart", "reactComponent": "SmartChart" },
+    { "wireframeElement": "BarChart", "reactComponent": "SmartChart" }
+  ],
+  "layout": {
+    "type": "grid",
+    "regions": ["kpi-row", "charts-row"]
+  },
+  "permissionsRequired": ["{AppCode}.{ModuleCode}.Read"]
+}
+```
+
+### 3. Enrich screens.json with Wireframes
+
+For each module, update screens.json to embed wireframes at the resource level:
+
+```json
+{
+  "sections": [
+    {
+      "sectionCode": "list",
+      "sectionLabel": "Liste des employes",
+      "resources": [
+        {
+          "code": "employees-grid",
+          "type": "SmartTable",
+          "columns": [ /* ... */ ],
+          "wireframe": {
+            "screen": "list-employees-grid",
+            "mockupFormat": "ascii",
+            "mockup": "...",
+            "elements": [...],
+            "componentMapping": [...],
+            "layout": {...}
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 4. Write Updated screens.json
+
+Write via ba-writer for each module. Update index.json hashes.
+
+## Validation
+
+- [ ] Every resource has a wireframe object
+- [ ] Every wireframe has a non-empty `mockup` field
+- [ ] Every wireframe has `elements[]` and `componentMapping[]`
+- [ ] Wireframe `permissionsRequired` references valid permission paths
+- [ ] All wireframes have `mockupFormat` set ("ascii" or "html")
+
+## Transition
+
+-> Step 03 (navigation) — Define the complete navigation tree

package/templates/skills/ba-design-ui/steps/step-03-navigation.md

@@ -0,0 +1,134 @@
+---
+name: step-03-navigation
+description: Define the complete navigation tree (routes, menus, breadcrumbs)
+model: opus
+---
+
+# Step 03 — Navigation (Navigation Tree)
+
+## Objective
+
+Define the complete navigation tree for the application: routes, menus, breadcrumbs, and seedDataCore entries. This ensures consistent navigation across all modules.
+
+## Prerequisites
+
+- Step 01 (screens) and Step 02 (wireframes) completed
+- screens.json exists for each module with sections and resources
+
+## Execution
+
+### 1. Load All Screens
+
+Read screens.json for every module via ba-reader. Collect all sections and resources.
+
+### 2. Build Navigation Tree
+
+Build the navigation hierarchy following SmartStack conventions:
+
+```
+Application
+  |-- Module 1
+  |   |-- Section 1 (e.g., "Liste")
+  |   |   |-- Resource 1 (e.g., "employees-grid")
+  |   |-- Section 2 (e.g., "Fiche")
+  |   |   |-- Resource 1 (e.g., "employee-form")
+  |   |-- Section 3 (e.g., "Dashboard")
+  |       |-- Resource 1 (e.g., "hr-dashboard")
+  |-- Module 2
+      |-- ...
+```
+
+### 3. Generate navigation.json
+
+```json
+{
+  "application": {
+    "code": "{AppCode}",
+    "name": "{AppName}",
+    "icon": "app-icon"
+  },
+  "modules": [
+    {
+      "code": "{ModuleCode}",
+      "name": "{ModuleName}",
+      "icon": "module-icon",
+      "route": "/{app-code}/{module-code}",
+      "permission": "{AppCode}.{ModuleCode}.Read",
+      "sections": [
+        {
+          "code": "{sectionCode}",
+          "label": "{sectionLabel}",
+          "route": "/{app-code}/{module-code}/{section-code}",
+          "icon": "section-icon",
+          "resources": [
+            {
+              "code": "{resourceCode}",
+              "type": "{SmartTable|SmartForm|SmartDashboard|SmartKanban}",
+              "route": "/{app-code}/{module-code}/{section-code}/{resource-code}",
+              "permission": "{AppCode}.{ModuleCode}.{Action}"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "menuItems": [
+    {
+      "label": "{ModuleName}",
+      "icon": "module-icon",
+      "route": "/{app-code}/{module-code}",
+      "permission": "{AppCode}.{ModuleCode}.Read",
+      "children": [
+        {
+          "label": "{sectionLabel}",
+          "route": "/{app-code}/{module-code}/{section-code}",
+          "permission": "{AppCode}.{ModuleCode}.Read"
+        }
+      ]
+    }
+  ],
+  "breadcrumbs": {
+    "/{app-code}/{module-code}/{section-code}": [
+      { "label": "{AppName}", "route": "/{app-code}" },
+      { "label": "{ModuleName}", "route": "/{app-code}/{module-code}" },
+      { "label": "{sectionLabel}", "route": "" }
+    ]
+  }
+}
+```
+
+### 4. Write navigation.json
+
+Write via ba-writer at project level (alongside master index.json). Update index.json with navigation.json reference.
+
+## Validation
+
+- [ ] Every module in index.json has a corresponding navigation entry
+- [ ] Every section in screens.json has a corresponding menu item
+- [ ] Every route is unique
+- [ ] Every menu item has a valid permission reference
+- [ ] Breadcrumbs cover all routes
+
+## Completion Summary
+
+```
+================================================================
+  UI DESIGN COMPLETE
+================================================================
+
+| Module          | Sections | Resources | Wireframes |
+|-----------------|----------|-----------|------------|
+| {moduleCode}    | {count}  | {count}   | {count}    |
+| ...             | ...      | ...       | ...        |
+
+| Artifact        | Path                              |
+|-----------------|-----------------------------------|
+| screens.json    | {module-path}/screens.json        |
+| navigation.json | {project-path}/navigation.json    |
+
+NEXT STEPS:
+1. Run /ba-generate-html to produce the interactive HTML with mockups
+2. Client reviews the HTML (mockups, ERD, permission matrix)
+3. Run /ba-review to apply corrections
+================================================================
+```

package/templates/skills/ba-generate-html/SKILL.md

@@ -25,7 +25,6 @@ Generate the interactive HTML document of the business analysis from the JSON an
 ## Prerequisites
 
 - JSON analysis files must exist (at minimum `index.json` + `cadrage.json`)
-- PRD files must exist (`.ralph/prd-{moduleCode}.json`) — run `/derive-prd` first
 - Feature status must be `consolidated`
 
 ## Workflow