@atlashub/smartstack-cli 3.35.0 → 3.36.0

package/package.json

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

package/templates/skills/apex/SKILL.md

@@ -39,6 +39,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | `-r` | Resume: continue from previous state |
 | `-pr` | PR mode: create pull request at end |
 | `-d {path}` | Delegate mode: read context from PRD file at `{path}`. Implies `-a -e`. Used by `/ralph-loop`. |
+| `--foundation` | Foundation mode: generate ONLY entities + EF configs + migration. No services/controllers/frontend. Used by ralph-loop Phase 0. |
 
 </parameters>
 
@@ -55,6 +56,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | `{pr_mode}` | boolean | Create PR at end |
 | `{delegate_mode}` | boolean | Delegated by `/ralph-loop` via `-d` flag |
 | `{delegate_prd_path}` | string? | Path to PRD file (`.ralph/prd.json` or `.ralph/prd-{module}.json`) |
+| `{foundation_mode}` | boolean | Foundation mode: entities-only (no services/controllers/frontend). Used by ralph-loop Phase 0. |
 | `{context_code}` | string | "business", "platform", "personal" |
 | `{app_name}` | string | Application name |
 | `{module_code}` | string | Module code |
@@ -131,6 +133,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 - **Save outputs** if `{save_mode}` = true
 - **Commits per layer** - Atomic commits after each execution layer
 - **Delegate mode** (`-d`): Read PRD context, skip challenge questions, auto+economy mode implied. Used when `/ralph-loop` delegates code generation to `/apex`.
+- **Foundation mode** (`--foundation`): Generate ONLY entities + EF configs + migration (domain + infrastructure layers). Skip application/api/frontend/tests. Used by ralph-loop Phase 0 to create database foundation before spawning parallel teammates.
 
 </execution_rules>
 

package/templates/skills/apex/steps/step-00-init.md

@@ -28,7 +28,7 @@ Extract flags from the raw input:
 ```
 Input: "{raw_input}"
 
-Flags to detect: -a, -x, -s, -e, -r, -pr, -d {path}
+Flags to detect: -a, -x, -s, -e, -r, -pr, -d {path}, --foundation
 Remaining text after flag removal = {task_description}
 ```
 
@@ -43,10 +43,13 @@ pr_mode: false
 resume_mode: false
 delegate_mode: false
 delegate_prd_path: null
+foundation_mode: false
 ```
 
 **If `-d {path}` detected:** set `delegate_mode = true`, `delegate_prd_path = {path}`, force `auto_mode = true`, `economy_mode = true`.
 
+**If `--foundation` detected:** set `foundation_mode = true`, force `auto_mode = true`. Foundation mode generates ONLY entities + EF configs + migration (domain + infrastructure layers). Skip application/api/frontend/tests.
+
 ---
 
 ## 1b. Delegate Mode Fast Path (if -d)

package/templates/skills/apex/steps/step-03-execute.md

@@ -22,6 +22,28 @@ All code goes through skills (/controller, /application, /ui-components, /efcore
 
 ---
 
+## Foundation Mode Detection
+
+**IF `{foundation_mode}` == true:**
+
+This is a foundation-only execution (called by ralph-loop Phase 0). Execute ONLY:
+- Layer 0: Domain entities + EF configs + Migration
+
+**SKIP ALL OTHER LAYERS:**
+- Layer 1: Application + API + Seed Data → SKIP
+- Layer 2: Frontend → SKIP
+- Layer 3: Tests → SKIP
+
+After Layer 0 completes and builds successfully:
+- Commit with message: `chore(foundation): entities for {module_code}`
+- Jump to step-04 for POST-CHECKs (domain + infrastructure only)
+- End execution
+
+**IF `{foundation_mode}` == false:**
+Execute ALL layers normally (Layer 0 → Layer 1 → Layer 2 → Layer 3).
+
+---
+
 ## Layer 0 — Domain + Infrastructure (sequential, agent principal)
 
 ### Domain Entities

package/templates/skills/documentation/SKILL.md

@@ -81,7 +81,68 @@ Identify the specific name:
 
 ### STEP 3: EXECUTION
 
-**For NEW documentation (type = user|developer|database|testing):**
+**For NEW documentation (type = user) - AUTOMATIC MOCK UI GENERATION:**
+
+Use the automated generator script that creates complete documentation with Mock UI components:
+
+```bash
+npx tsx scripts/generate-doc-with-mock-ui.ts \
+  --module {module} \
+  --context {context} \
+  --application {application} \
+  --app-path "D:/01 - projets/SmartStack.app/02-Develop"
+```
+
+**What it does automatically:**
+
+1. **Find & Extract Entity** (e.g., users → User.cs)
+   - Locates Domain entity file
+   - Extracts all properties with types
+
+2. **Extract API Endpoints** (via `extract-api-endpoints.ts`)
+   - Scans controller for all endpoints
+   - Parses `[HttpGet]`, `[HttpPost]`, `[NavRoute]`, `[RequirePermission]`
+   - Resolves permission constants
+   - Output: JSON array of endpoints with method, path, handler, permission
+
+3. **Extract Business Rules** (via `extract-business-rules.ts`)
+   - Scans Domain entity for guard clauses and DomainExceptions
+   - Scans unit tests for edge case scenarios
+   - Auto-assigns BR-XXX IDs and categorizes rules
+   - Output: JSON array of business rules with id, name, category, statement
+
+4. **Generate Mock UI Components**
+   - **KPIs**: Automatic stats based on entity properties
+     - Total count
+     - Active/Inactive (if IsActive property)
+     - Status breakdown (if Status property)
+     - Time-based stats (if DateTime property)
+   - **Table**: Smart column selection (6 most relevant properties)
+     - Filters out: Hash, Token, *Id (FK), normalized, internal fields
+     - Prioritizes: name/title → email → status → date
+   - **Form**: Create form with intelligent field types
+     - Email → type="email" with placeholder
+     - Bool → checkbox
+     - DateTime → type="date"
+     - Description/Notes → textarea
+     - Default → type="text"
+
+5. **Generate Complete TSX File**
+   - Full React component with breadcrumb, sections, mock data
+   - Section 1: Introduction
+   - Section 2: Access (navigation path + URL)
+   - Section 3: Interface Overview (KPIs + Table Mock UI)
+   - Section 4: Create Form (generated form fields)
+   - Section 5: API Reference (endpoints table)
+
+6. **Manual Steps (Post-Generation)**
+   - Save generated TSX to `docs/business/{context}/{application}/{module}/index.tsx`
+   - Update docs-manifest.json
+   - Update App.tsx routing
+   - Update DocPanelContext.tsx mapping
+   - Generate i18n FR file (if needed)
+
+**For NEW documentation (type = developer|database|testing):**
 
 Follow the data-driven workflow from [templates.md](templates.md):
 
@@ -92,22 +153,127 @@ Follow the data-driven workflow from [templates.md](templates.md):
 4. Generate i18n FR file (source language only)
 5. Update docs-manifest.json
 6. Update App.tsx routing and parent indexes
-7. Update DocPanelContext.tsx mapping (contextual doc panel)
 ```
 
 **For UPDATE documentation (type = update):**
 
+Re-run the generator script to refresh automatically extracted data:
+
 ```
-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 doc-data.ts with new/modified data
-6. Update i18n FR file if labels changed
-7. Update docs-manifest.json timestamps
+1. Run generate-doc-with-mock-ui.ts → regenerates with latest API/rules
+2. Update i18n FR file if labels changed
+3. 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é.
+
+---
+
+## EXTRACTION SCRIPTS REFERENCE
+
+### extract-api-endpoints.ts
+
+**Purpose:** Extract all API endpoints from SmartStack controllers
+
+**Input:**
+- `--module {module}` - Module name (e.g., users, tenants)
+- `--app-path {path}` - Path to SmartStack.app
+
+**What it extracts:**
+- Controller file path (e.g., `UsersController.cs`)
+- HTTP method (`[HttpGet]`, `[HttpPost]`, `[HttpPut]`, `[HttpDelete]`, `[HttpPatch]`)
+- Route suffix (e.g., `{id:guid}`, `activate`)
+- Base path from `[NavRoute("platform.administration.users")]`
+- Permission from `[RequirePermission(Permissions.Admin.Users.View)]`
+- Handler method name
+
+**Output:** JSON array
+```json
+[
+  {
+    "method": "GET",
+    "path": "/api/platform/administration/users",
+    "handler": "GetUsers",
+    "permission": "platform.administration.users.read"
+  }
+]
+```
+
+**Permission resolution:**
+- Loads `Permissions.cs` constants
+- Maps `Permissions.Admin.Users.View` → `"platform.administration.users.read"`
+
+---
+
+### extract-business-rules.ts
+
+**Purpose:** Extract business rules from Domain entities and unit tests
+
+**Input:**
+- `--module {module}` - Module name (e.g., users, tenants)
+- `--app-path {path}` - Path to SmartStack.app
+
+**Phase 1: Domain Entity Extraction**
+- Scans Domain entity (e.g., `User.cs`)
+- Looks for guard clauses: `if (...) throw new DomainException("...")`
+- Looks for validation in Create/Update methods
+- Extracts exception messages and context
+
+**Phase 2: Unit Tests Extraction**
+- Scans unit test file (e.g., `UserTests.cs`)
+- Looks for test methods with `[Fact]` attribute
+- Extracts test names and scenarios (edge cases)
+- Maps to business rule statements
+
+**Output:** JSON array
+```json
+[
+  {
+    "id": "BR-001",
+    "name": "Email requis",
+    "category": "Validation",
+    "statement": "Un utilisateur doit avoir une adresse email valide et non vide"
+  }
+]
+```
+
+**Auto-categorization:**
+- Validation: Required fields, format checks
+- Security: Password rules, access control
+- Business Logic: State transitions, calculations
+
+---
+
+### generate-doc-with-mock-ui.ts
+
+**Purpose:** Main generator - creates complete documentation TSX with Mock UI
+
+**Input:**
+- `--module {module}` - Module name (e.g., users)
+- `--context {context}` - Context (e.g., platform)
+- `--application {application}` - Application (e.g., administration)
+- `--app-path {path}` - Path to SmartStack.app
+
+**Workflow:**
+1. Find Domain entity file (users → User.cs via singularize)
+2. Extract entity properties (name, type, nullable, required)
+3. Call `extract-api-endpoints.ts`
+4. Call `extract-business-rules.ts`
+5. Generate mock data (5 sample records with realistic values)
+6. Generate KPI stats (Total, Active/Inactive, Status breakdown)
+7. Generate table UI (smart column selection - 6 most relevant)
+8. Generate form UI (intelligent field types based on property)
+9. Output complete TSX file to stdout
+
+**Smart Features:**
+- **Singularize**: users → User.cs, tenants → Tenant.cs
+- **Property filtering**: Excludes hash, token, *Id, normalized, internal
+- **Priority selection**: name/title > email > status > date
+- **Field type detection**: email → email input, bool → checkbox
+- **Mock value generation**: Realistic emails, names, dates, GUIDs
+
+**Output:** Complete React TSX component (400-500 lines)
+
 </workflow>
 
 <execution_rules>

package/templates/skills/efcore/steps/squash/step-03-create.md

@@ -55,10 +55,11 @@ echo "DbContext Type: $DBCONTEXT_TYPE"
 
 const result = await mcp__smartstack__suggest_migration({
   description: DESCRIPTION,
-  context: DBCONTEXT_TYPE    // NEVER hardcode!
+  context: DBCONTEXT_TYPE,   // NEVER hardcode!
+  squash: true               // Squash format: {context}_v{version} (no sequence/description)
 });
 
-// Result example: core_v1.9.0_001_MultitenantConsolidated
+// Result example: core_v1.9.0 (squash — just version, no _001_Description)
 MIGRATION_NAME = result.migrationName;
 ```
 
@@ -66,11 +67,12 @@ MIGRATION_NAME = result.migrationName;
 - Calculating name manually
 - Hardcoding context as "core"
 - Using underscores instead of dots in version
+- Adding sequence/description to squash migrations
 
 ### 3. Create Migration with EF Core
 
 ```bash
-# MIGRATION_NAME = result from MCP (e.g., core_v1.9.0_001_MultitenantConsolidated)
+# MIGRATION_NAME = result from MCP (e.g., core_v1.9.0)
 # DBCONTEXT = CoreDbContext or ExtensionsDbContext (from detect_dbcontext)
 
 echo ""
@@ -211,7 +213,7 @@ After step-03-create:
 
 | Variable | Description |
 |----------|-------------|
-| `{migration_name}` | Name from MCP (e.g., core_v1.9.0_001_...) |
+| `{migration_name}` | Name from MCP (e.g., core_v1.9.0) |
 | `{migration_file}` | Full path to .cs file |
 | `{designer_file}` | Full path to .Designer.cs file |
 

package/templates/skills/gitflow/_shared.md

@@ -462,7 +462,9 @@ GitFlow configuration JSON template v2.1.0 (aligned with `templates/config.json`
     "enabled": true,
     "validateOnCommit": true,
     "blockDestructive": true,
-    "migrationNaming": "{context}_v{version}_{sequence}_{Description}"
+    "migrationNaming": "{context}_v{version}_{sequence}_{Description}",
+    "migrationNamingSquash": "{context}_v{version}",
+    "squashBeforePR": true
   },
   "workflow": {
     "push": {

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

@@ -122,6 +122,40 @@ else
 fi
 ```
 
+### 4b. Enforce Migration Squash (Feature Branches)
+
+**BLOCKING**: Feature branches must have at most 1 migration before creating a PR.
+
+```bash
+if [ "$BRANCH_TYPE" = "feature" ]; then
+  MIGRATION_DIR=$(find . -path "*/Persistence/Migrations" -type d 2>/dev/null | head -1)
+  if [ -n "$MIGRATION_DIR" ]; then
+    # Count migration .cs files added by this feature (not in target branch)
+    NEW_MIGRATIONS=$(git diff --name-only "origin/$TARGET_BRANCH...HEAD" -- "$MIGRATION_DIR" \
+      | grep -E '\.cs$' \
+      | grep -v 'Designer\|ModelSnapshot' \
+      | wc -l)
+
+    if [ "$NEW_MIGRATIONS" -gt 1 ]; then
+      echo ""
+      echo "❌ MULTIPLE MIGRATIONS DETECTED ($NEW_MIGRATIONS migrations)"
+      echo "→ Feature branches must have exactly 1 migration (squashed) before PR"
+      echo "→ Run: /efcore squash"
+      echo ""
+      echo "Migrations found:"
+      git diff --name-only "origin/$TARGET_BRANCH...HEAD" -- "$MIGRATION_DIR" \
+        | grep -E '\.cs$' \
+        | grep -v 'Designer\|ModelSnapshot'
+      STOP
+    elif [ "$NEW_MIGRATIONS" -eq 1 ]; then
+      echo "✓ Single migration detected (squashed)"
+    else
+      echo "✓ No migrations in this feature"
+    fi
+  fi
+fi
+```
+
 ### 5. Generate PR Content
 
 **Title:**

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

@@ -36,6 +36,7 @@ Execute the Ralph Weegund technique — iterative module orchestration. Ralph re
 | `-c TEXT` | `--completion-promise TEXT` | Completion signal text |
 | `-v` | `--verbose` | Detailed logging |
 | `-r` | `--resume` | Resume from previous state |
+| `-p` | `--parallel` | Teams mode: Phase 0 (entities) sequential, then spawn parallel teammates per application/module |
 </parameters>
 
 <workflow>
@@ -50,9 +51,30 @@ Execute the Ralph Weegund technique — iterative module orchestration. Ralph re
    - Find eligible → batch by category (max 5) → execute → test → commit → loop
 7. Report (step-05)
 
-**Multi-module (2+ modules, from BA handoff):**
+**Multi-module (2+ modules) with `-p` (parallel mode):**
+1. Init: detect prd-*.json, parse `-p` flag (step-00)
+2. **Phase 0 (Ralph sequential):**
+   - Ralph generates ALL entities from ALL modules via `/apex --foundation`
+   - Creates ONE migration with all entities
+   - Commits: `chore(foundation): entities for all modules`
+3. **Phase 1-N (Teams parallel):**
+   ```
+   Team Lead → TeamCreate("smartstack-{project}")
+     Spawn teammates (1 per application OR 1 per module if app > 3 modules):
+       - Task(subagent_type: "apex", name: "apex-hr")
+       - Task(subagent_type: "apex", name: "apex-crm")
+       - Task(subagent_type: "apex", name: "apex-pm")
+     Each teammate generates:
+       - Services + Controllers + Seed data + Frontend + Tests
+       - NO entities (already done in Phase 0)
+       - NO migrations (ModelSnapshot already complete)
+     → Teammates work in parallel → Ralph collects results → TeamDelete
+   ```
+4. Report with per-module aggregation (step-05)
+
+**Multi-module (2+ modules) WITHOUT `-p` (sequential mode — legacy):**
 1. Init: detect prd-*.json, read dependency layers (step-00)
-2. **IF dependency graph available:** Agent Teams (parallel)
+2. **IF dependency graph available:** Agent Teams (parallel, legacy)
    ```
    Team Lead → TeamCreate("ralph-{app}")
      Layer 0: Spawn "mod-employees" (foundation) → wait LAYER_READY
@@ -81,6 +103,8 @@ LOAD → DELEGATE TO /apex -d → VERIFY PRD STATE → COMMIT PRD → NEXT MODUL
 | `{modules_queue}` | object\|null | Module queue (multi-module) |
 | `{section_split_mode}` | boolean | Section splitting active for current module (>4 entities + >1 section) |
 | `{section_phases}` | SectionPhase[] | Phase execution plan (Phase 0: foundation, Phase 1..N: per-section) |
+| `{parallel_mode}` | boolean | Teams mode enabled via `-p` flag. Ralph generates Phase 0 (entities) sequentially, then spawns parallel teammates. |
+| `{team_name}` | string\|null | Team name for parallel mode (e.g., "smartstack-hr") |
 </state_variables>
 
 <mcp_requirements>