@atlashub/smartstack-cli 3.32.0 → 3.34.0

package/.documentation/test-web.html

@@ -12,7 +12,7 @@
         <header class="global-header">
             <div class="logo">SS</div>
             <span class="site-title">SmartStack CLI</span>
-            <span class="version-badge">v3.0.0</span>
+            <span class="version-badge">v3.34.0</span>
             <div class="header-divider"></div>
             <span class="page-title">Test Web</span>
             <nav class="breadcrumb">
@@ -90,6 +90,10 @@
                         <span class="icon">&#128260;</span>
                         <span class="nav-text">Ralph Loop</span>
                     </a>
+                    <a href="apex.html" class="nav-item">
+                        <span class="icon">&#9881;</span>
+                        <span class="nav-text">APEX</span>
+                    </a>
                 </div>
 
                 <div class="nav-section">

package/package.json

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

package/templates/agents/ba-writer.md

@@ -10,11 +10,14 @@ You are a business analysis writer agent specialized in managing feature.json fi
 
 ## Mission
 
-Write and update feature.json files for both application-level (master) and module-level documents. Handle progressive enrichment of features as they move through analysis phases, manage versioning for refactoring, and enforce schema consistency.
+Write and update feature.json files for project-level (multi-app), application-level (master), and module-level documents. Handle progressive enrichment of features as they move through analysis phases, manage versioning for refactoring, and enforce schema consistency.
 
-**Directory structure:**
-- Application-level: `docs/business/{app}/business-analyse/v{X.Y}/feature.json`
-- Module-level: `docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`
+**Directory structure (3-tier hierarchy):**
+- Project-level (multi-app only): `docs/business-analyse/v{X.Y}/feature.json`
+- Application-level: `docs/{context}/{app}/business-analyse/v{X.Y}/feature.json`
+- Module-level: `docs/{context}/{app}/{module}/business-analyse/v{X.Y}/feature.json`
+
+> **Backward compatibility:** If only 1 application, the project level is NOT created. The application-level feature.json remains the master.
 
 ## Core Operations
 
@@ -23,16 +26,19 @@ Create an initial feature.json with metadata and draft status.
 
 **Input:**
 - metadata: object with app, module, language, featureDescription, featureType, useCase
-- scope: "application" or "module" (default: "module")
+- scope: "project", "application", or "module" (default: "module")
 - Optional: applicationRef (FEAT-NNN of master, required when scope = "module" in app mode)
+- Optional: projectRef (PROJ-NNN of project master, required when scope = "application" in project mode)
+- Optional: context (default: "business", allows "platform" or "personal" in project mode)
 - Optional: initialSections for pre-populated content
 
 **Process:**
-1. Read `.business-analyse/config.json` to get lastFeatureId
-2. Increment FEAT-NNN identifier
+1. Read `.business-analyse/config.json` to get lastFeatureId (or lastProjectId for scope = "project")
+2. Increment FEAT-NNN (or PROJ-NNN) identifier
 3. Create directory structure based on scope:
-   - If scope = "application": `docs/business/{app}/business-analyse/v1.0/`
-   - If scope = "module": `docs/business/{app}/{module}/business-analyse/v1.0/`
+   - If scope = "project": `docs/business-analyse/v1.0/`
+   - If scope = "application": `docs/{context}/{app}/business-analyse/v1.0/`
+   - If scope = "module": `docs/{context}/{app}/{module}/business-analyse/v1.0/`
 4. Generate initial feature.json with:
    - **`$schema`**: relative path to the deployed schema file (MANDATORY — see $schema rules below)
    - id: FEAT-NNN (from config)
@@ -40,6 +46,7 @@ Create an initial feature.json with metadata and draft status.
    - status: "draft"
    - scope: "application" or "module"
    - metadata: createdAt, updatedAt, createdBy, updatedBy, previousVersion: null, scope, applicationRef
+   - For project scope: cadrage: {}, applications: [], applicationDependencyGraph: {}, consolidation: {}, suggestions: [], changelog: []
    - For application scope: cadrage: {}, modules: [], dependencyGraph: {}, consolidation: {}, suggestions: [], changelog: []
    - For module scope: discovery: {}, analysis: {}, specification: {}, validation: {}, handoff: {}, suggestions: [], applicationContext: {}
 5. Update `.business-analyse/config.json` with new lastFeatureId
@@ -64,6 +71,83 @@ Create a master application-level feature.json. Shorthand for `create` with `sco
 2. Initialize `metadata.workflow` with mode, moduleOrder: [], currentModuleIndex: 0, completedModules: [], currentModule: null
 3. Return feature ID and path
 
+### createProjectFeature
+Create a project-level feature.json for multi-application analysis. Only used when 2+ applications are identified.
+
+**Input:**
+- metadata: object with projectName, language, featureDescription
+- cadrage: object with project-level cadrage data (problem, stakeholders, globalScope, globalRoles, risks)
+
+**Process:**
+1. Read `.business-analyse/config.json` to get lastProjectId (default: 0)
+2. Increment PROJ-NNN identifier
+3. Create directory: `docs/business-analyse/v1.0/`
+4. Generate project feature.json with:
+   - `$schema`: `"../schemas/project-schema.json"`
+   - id: PROJ-NNN
+   - version: "1.0"
+   - status: "draft"
+   - scope: "project"
+   - metadata: projectName, language, workflow: { mode: "project", applicationOrder: [], currentApplicationIndex: 0, completedApplications: [], currentApplication: null }
+   - cadrage: from input
+   - applications: []
+   - applicationDependencyGraph: {}
+   - consolidation: {}
+   - suggestions: []
+   - changelog: []
+5. Update `.business-analyse/config.json` with new lastProjectId
+6. Deploy schemas to `docs/business-analyse/schemas/` (including project-schema.json)
+7. Return project ID (PROJ-NNN) and path
+
+### enrichApplicationRegistry
+Update the applications array and dependency graph in a project-level feature.json.
+
+**Input:**
+- projectId: PROJ-NNN of the project feature.json
+- applications: array of application objects (code, name, context, tablePrefix, icon, description, applicationRoles[], scope, dependencies[], estimatedComplexity)
+- applicationDependencyGraph: object with edges[], topologicalOrder[], layers[]
+
+**Process:**
+1. Find project feature.json (verify scope = "project")
+2. Replace `applications` array entirely
+3. Replace `applicationDependencyGraph` object entirely
+4. For each application, set initial status: "pending"
+5. Set metadata.workflow.applicationOrder from applicationDependencyGraph.topologicalOrder
+6. Set metadata.workflow.currentApplication to first application in order
+7. Update metadata.updatedAt
+8. Write back
+9. Return confirmation
+
+### updateApplicationStatus
+Update the status of a specific application in the project feature.json.
+
+**Input:**
+- projectId: PROJ-NNN of the project
+- applicationCode: string (PascalCase application code)
+- status: "pending" | "in-progress" | "decomposed" | "specified" | "consolidated"
+
+**Process:**
+1. Find project feature.json
+2. Find application by code in `applications[]`
+3. Update application.status
+4. Update metadata.updatedAt
+5. Write back
+6. Return confirmation
+
+### advanceApplicationLoop
+Increment the application loop counter in the project feature.json.
+
+**Process:**
+1. Find project feature.json
+2. Read `metadata.workflow.currentApplicationIndex` and `metadata.workflow.applicationOrder`
+3. Add current application to `metadata.workflow.completedApplications`
+4. Increment `metadata.workflow.currentApplicationIndex`
+5. If new index < applicationOrder.length: set `currentApplication` to next application
+6. If new index >= applicationOrder.length: set `currentApplication` to null
+7. Update metadata.updatedAt
+8. Write back
+9. Return new index, next application code (or null), and whether loop is complete
+
 ### enrichSection
 Merge a section into an existing feature.json.
 
@@ -223,9 +307,16 @@ Transition the status through defined workflow.
 - specified → consolidated
 - consolidated → handed-off
 
+**Valid transitions (project-level):**
+- draft → framed
+- framed → decomposed
+- decomposed → specified
+- specified → consolidated
+- consolidated → handed-off
+
 **Process:**
 1. Read feature.json
-2. Detect scope (application or module) to determine valid transitions
+2. Detect scope (project, application, or module) to determine valid transitions
 3. Verify current status allows transition
 4. Update status field
 5. Update metadata.steps object with timestamp for the corresponding step
@@ -498,17 +589,23 @@ On EVERY `enrichSection()` call:
 ## Directory Structure
 
 ```
-docs/business/{app}/business-analyse/
+docs/business-analyse/
+  v1.0/
+    feature.json                          ← PROJECT (multi-app master, only if 2+ apps)
+
+docs/{context}/{app}/business-analyse/
   v1.0/
     feature.json                          ← APPLICATION (master)
 
-docs/business/{app}/{module}/business-analyse/
+docs/{context}/{app}/{module}/business-analyse/
   v1.0/
     feature.json                          ← MODULE (detailed)
   v1.1/
     feature.json
 ```
 
+> **{context}** = "business" (default) | "platform" | "personal" — determined per application in project mode.
+
 Versions are stored as separate files in versioned directories. Always store feature.json at the root of each version folder.
 
 ## Config Management
@@ -519,6 +616,7 @@ Versions are stored as separate files in versioned directories. Always store fea
 ```json
 {
   "lastFeatureId": 42,
+  "lastProjectId": 1,
   "lastMigrationId": 15,
   "schema": "1.0"
 }
@@ -670,8 +768,9 @@ If a module feature.json exceeds 500KB despite incremental operations:
 
 | Scope | Feature.json location | $schema value |
 |-------|----------------------|---------------|
-| application | `docs/business/{app}/business-analyse/v1.0/feature.json` | `"../schemas/application-schema.json"` |
-| module | `docs/business/{app}/{module}/business-analyse/v1.0/feature.json` | `"../../../business-analyse/schemas/feature-schema.json"` |
+| project | `docs/business-analyse/v1.0/feature.json` | `"../schemas/project-schema.json"` |
+| application | `docs/{context}/{app}/business-analyse/v1.0/feature.json` | `"../schemas/application-schema.json"` |
+| module | `docs/{context}/{app}/{module}/business-analyse/v1.0/feature.json` | `"../../../business-analyse/schemas/feature-schema.json"` |
 
 **Rules:**
 - `$schema` is ALWAYS the FIRST field in feature.json (before `id`)
@@ -726,7 +825,7 @@ If a module feature.json exceeds 500KB despite incremental operations:
   "version": "1.0",
   "status": "draft",
   "scope": "application",
-  "metadata": { "..." },
+  "metadata": { "...", "projectRef": "PROJ-001" },
   "cadrage": {},
   "modules": [],
   "dependencyGraph": {},
@@ -735,3 +834,31 @@ If a module feature.json exceeds 500KB despite incremental operations:
   "changelog": []
 }
 ```
+
+**Project-level (multi-app only):**
+```json
+{
+  "$schema": "../schemas/project-schema.json",
+  "id": "PROJ-001",
+  "version": "1.0",
+  "status": "draft",
+  "scope": "project",
+  "metadata": {
+    "projectName": "Enterprise HR Platform",
+    "language": "fr",
+    "workflow": {
+      "mode": "project",
+      "applicationOrder": ["HumanResources", "EmployeeSelfService"],
+      "currentApplicationIndex": 0,
+      "completedApplications": [],
+      "currentApplication": "HumanResources"
+    }
+  },
+  "cadrage": {},
+  "applications": [],
+  "applicationDependencyGraph": {},
+  "consolidation": {},
+  "suggestions": [],
+  "changelog": []
+}
+```

package/templates/skills/apex/SKILL.md

@@ -38,6 +38,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | `-e` | Economy mode: no subagents |
 | `-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`. |
 
 </parameters>
 
@@ -52,6 +53,8 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | `{save_mode}` | boolean | Save outputs to `.claude/output/apex/{task-id}/` |
 | `{economy_mode}` | boolean | No subagents |
 | `{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`) |
 | `{context_code}` | string | "business", "platform", "personal" |
 | `{app_name}` | string | Application name |
 | `{module_code}` | string | Module code |
@@ -95,7 +98,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 
 | Phase | Step | Obligatory | Description |
 |-------|------|------------|-------------|
-| *Init* | 00 | Yes | Setup, hierarchy, challenge the need |
+| *Init* | 00 | Yes | Setup, hierarchy, challenge the need (skipped in `-d` delegate mode) |
 | **A** — Analyze | 01 | Yes | Explore existing code |
 | **P** — Plan | 02 | Yes | File-by-file plan with skill/MCP mapping |
 | **E** — Execute | 03 | Yes | Orchestrate creation via skills and MCP |
@@ -112,6 +115,8 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 |------|---------|-----------|
 | `references/smartstack-api.md` | BaseEntity, interfaces, entity/config/controller patterns | step-01, step-03 |
 | `references/smartstack-layers.md` | Layer execution rules, skill/MCP mapping, seed data | step-02, step-03 |
+| `references/core-seed-data.md` | Comprehensive seed data templates (navigation, permissions, roles) | step-03 (delegate mode + seedData tasks) |
+| `references/error-classification.md` | Build error diagnosis categories A-F | step-03 (build failure), step-04 |
 | `references/agent-teams-protocol.md` | TeamCreate, coordination, shutdown protocol | step-01, step-03 |
 </reference_files>
 
@@ -125,6 +130,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 - **Agent Teams** - Parallel execution for scan (step-01) and Layer 1 (step-03), unless economy_mode
 - **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`.
 
 </execution_rules>
 

package/templates/skills/apex/_shared.md

@@ -24,6 +24,42 @@
 
 ---
 
+## Delegate Mode Context
+
+> **Active when:** `-d {path}` flag is set. Implies `-a` (auto) + `-e` (economy).
+
+When `/ralph-loop` invokes `/apex -d {prd_path}`:
+
+1. **Read PRD** from `{delegate_prd_path}` (`.ralph/prd.json` or `.ralph/prd-{module}.json`)
+2. **Extract context:**
+   - `context_code` = `prd.project.context` (e.g., "business")
+   - `app_name` = `prd.project.application` (e.g., "HumanResources")
+   - `module_code` = `prd.project.module` (e.g., "EmployeeManagement")
+   - `sections` = from `_seedDataMeta.coreSeedData.navigationSections` in infrastructure tasks
+   - `entities` = from `prd.tasks` filtered by `category == 'domain'` (entity names from description)
+   - `feature_path` = `prd.source.feature_json_path`
+3. **Read task metadata** per category:
+   - `_seedDataMeta` → seed data scope (coreSeedData, navRoute, appLabels)
+   - `_frontendMeta` → wireframes, filesToCreate, fkFields
+   - `_migrationMeta` → entities[], moduleCode
+4. **Skip:** challenge questions (step-00 §5), user checkpoints (step-01 §6, step-02 §6)
+5. **No nested teams:** `-e` implied, all execution sequential on agent principal
+
+### PRD State Update Protocol (delegate mode only)
+
+After completing each layer in step-03, update the PRD file:
+```
+Read {delegate_prd_path}
+For each task executed in this layer:
+  task.status = 'completed' (or 'failed')
+  task.completed_at = ISO timestamp
+  task.commit_hash = git rev-parse --short HEAD
+  task.files_changed = { created: [...], modified: [...] }
+Write back to {delegate_prd_path}
+```
+
+---
+
 ## MCP Tools Reference
 
 ### Mandatory (every execution)
@@ -41,9 +77,18 @@
 | Resource | `{context}.{app}.{module}.{section}.{resource}.{action}` | 5+1 segments |
 
 **Examples:**
-- Module: `business.humanresources.employees.read` (3+1)
-- Section: `business.humanresources.employees.departments.read` (4+1)
-- Resource: `business.humanresources.employees.departments.export.execute` (5+1)
+- Module: `business.human-resources.employees.read` (3+1)
+- Section: `business.human-resources.employees.departments.read` (4+1)
+- Resource: `business.human-resources.employees.departments.export.execute` (5+1)
+
+> **CRITICAL — Permission codes use the SAME kebab-case segments as NavRoute codes.**
+> Every dot-separated segment in a permission path is a navigation entity code.
+> Multi-word codes MUST be kebab-case: `human-resources`, NOT `humanresources`.
+>
+> SmartStack.app reference: `business.support-client.my-tickets.read`, `platform.administration.email-templates.read`
+>
+> **FORBIDDEN:** `business.humanresources.employees.read` (concatenated — no kebab-case)
+> **CORRECT:** `business.human-resources.employees.read` (kebab-case — matches NavRoute)
 
 ### Generation (step-03)
 
@@ -55,7 +100,7 @@
 | `scaffold_api_client` | Generate TypeScript API client | Frontend changes |
 | `scaffold_routes` | Generate React Router routes | Frontend changes |
 
-### eXamine (step-04) — 30 POST-CHECKs
+### eXamine (step-04) — 43 POST-CHECKs
 
 | Tool | Purpose | Condition |
 |------|---------|-----------|

package/templates/skills/{ralph-loop → apex}/references/core-seed-data.md

@@ -1,10 +1,11 @@
 # Core Seed Data - Execution Reference
 
-> **Loaded by:** step-02-execute and step-04 compact loop
-> **Condition:** Infrastructure task involves core seed data or IClientSeedDataProvider
+> **Loaded by:** apex step-03-execute (delegate mode + seedData tasks) and step-04-examine
+> **Condition:** Seed data generation — infrastructure or seedData category tasks
 > **Applies to:** Client projects only (seeding_strategy = "provider", ExtensionsDbContext)
 >
 > **Source of truth:** `/application` skill `templates-seed.md` (lines 608-916)
+> **Moved from:** `ralph-loop/references/core-seed-data.md` (delegation refactoring)
 
 ---
 
@@ -25,9 +26,9 @@ const permissions = coreSeedData.permissions || [];
 const rolePerms = coreSeedData.rolePermissions || [];
 
 // Derived context (from guardrail or PRD)
-const navRoute = meta.navRoute;         // e.g. "business.humanresources.projects"
+const navRoute = meta.navRoute;         // e.g. "business.human-resources.projects"
 const contextCode = meta.contextCode;   // e.g. "business"
-const appCode = meta.appCode;           // e.g. "humanresources"
+const appCode = meta.appCode;           // e.g. "human-resources"
 const moduleCode = task.module;         // e.g. "projects"
 
 // If _seedDataMeta is absent, fallback to PRD source
@@ -41,9 +42,9 @@ if (!navRoute) {
 
 | Variable | Example | Source |
 |----------|---------|--------|
-| `navRoute` | `business.humanresources.projects` | `_seedDataMeta.navRoute` |
+| `navRoute` | `business.human-resources.projects` | `_seedDataMeta.navRoute` |
 | `contextCode` | `business` | `_seedDataMeta.contextCode` |
-| `appCode` | `humanresources` | `_seedDataMeta.appCode` |
+| `appCode` | `human-resources` | `_seedDataMeta.appCode` |
 | `moduleCode` | `projects` | `task.module` |
 | `navModules[]` | `[{code, label, icon, route, translations}]` | `coreSeedData.navigationModules` |
 | `navSections[]` | `[{code, label, icon, route, parentCode, permission, sort}]` | `coreSeedData.navigationSections` |
@@ -85,7 +86,7 @@ From `seedDataCore.navigationApplications[0]` in feature.json (generated by BA s
 // Deterministic GUID for APPLICATION (not context — contexts are pre-seeded by SmartStack core)
 public static readonly Guid ApplicationId =
     GenerateDeterministicGuid("navigation-application-{contextCode}.{appCode}");
-// Example: GenerateDeterministicGuid("navigation-application-business.humanresources")
+// Example: GenerateDeterministicGuid("navigation-application-business.human-resources")
 //
 // FORBIDDEN — Context IDs must NOT be generated:
 // public static readonly Guid BusinessContextId = GenerateDeterministicGuid("nav:business"); // WRONG!
@@ -244,7 +245,7 @@ private static Guid GenerateDeterministicGuid(string seed)
 
 // Usage: GUIDs are derived from the navigation path
 public static readonly Guid ModuleId = GenerateDeterministicGuid("navigation-module-{navRoute}");
-// Example: GenerateDeterministicGuid("navigation-module-business.humanresources.projects")
+// Example: GenerateDeterministicGuid("navigation-module-business.human-resources.projects")
 ```
 
 ### Template
@@ -405,12 +406,12 @@ public class NavigationTranslationSeedEntry
 // Section GUID: deterministic from navRoute + section code
 public static readonly Guid {SectionPascal}SectionId =
     GenerateDeterministicGuid("navigation-section-{navRoute}.{sectionCode}");
-// Example: GenerateDeterministicGuid("navigation-section-business.ressourceshumaines.employees.list")
+// Example: GenerateDeterministicGuid("navigation-section-business.human-resources.employees.list")
 
 // Resource GUID: deterministic from navRoute + section code + resource code
 public static readonly Guid {ResourcePascal}ResourceId =
     GenerateDeterministicGuid("navigation-resource-{navRoute}.{sectionCode}.{resourceCode}");
-// Example: GenerateDeterministicGuid("navigation-resource-business.ressourceshumaines.employees.list.employees-grid")
+// Example: GenerateDeterministicGuid("navigation-resource-business.human-resources.employees.list.employees-grid")
 ```
 
 ### Section Methods (add to {ModulePascal}NavigationSeedData.cs)
@@ -676,15 +677,23 @@ MCP returns:
 
 ### Step B: Write Permissions.cs (Application layer)
 
+> **CRITICAL — Permission paths use the SAME kebab-case as NavRoute codes.**
+> `{navRoute}` is already kebab-case (e.g., `business.human-resources.employees`).
+> NEVER strip hyphens or derive codes from C# class names.
+> FORBIDDEN: `business.humanresources.employees.read` → CORRECT: `business.human-resources.employees.read`
+> SmartStack.app reference: `business.support-client.my-tickets.read`
+
 ```csharp
 // Add to Application/Common/Authorization/Permissions.cs
+// IMPORTANT: {navRoute} uses kebab-case segments (e.g., "business.human-resources.employees")
+// Do NOT derive permission codes from C# identifiers — use navRoute directly
 public static class {ContextPascal}
 {
     public const string Access = "{contextCode}.{appCode}";
 
     public static class {ModulePascal}
     {
-        public const string View = "{navRoute}.read";
+        public const string View = "{navRoute}.read";       // e.g., "business.human-resources.employees.read"
         public const string Create = "{navRoute}.create";
         public const string Update = "{navRoute}.update";
         public const string Delete = "{navRoute}.delete";

package/templates/skills/{ralph-loop → apex}/references/error-classification.md

@@ -1,8 +1,9 @@
 # Error Classification Reference
 
-> **Loaded by:** compact-loop.md (build failure analysis) and category-rules.md (validation section)
+> **Loaded by:** apex step-03-execute (build failure) and step-04-examine (validation)
 > **Purpose:** Classify build and runtime errors to apply the correct fix strategy.
 > **Key insight:** Not all errors are code errors. Package/config errors require different fixes than code errors.
+> **Moved from:** `ralph-loop/references/error-classification.md` (delegation refactoring)
 
 ---