@atlashub/smartstack-cli 3.33.0 → 3.35.0

package/templates/skills/business-analyse/steps/step-05b-deploy.md

@@ -176,21 +176,38 @@ IF ANY category shows FAIL → **STOP AND RE-RUN `ss derive-prd`**. DO NOT proce
 **Update logic:**
 
 1. Read existing manifest at `docs/business/index.json` (or create empty `{ "version": "1.0", "updatedAt": "", "analyses": [] }`)
-2. For the APPLICATION-level feature.json:
-   - Find existing entry where `appCode == {app_code}` AND `moduleCode == null` AND `version == {version}`
-   - If found: update `status`, `updatedAt`, `featureDescription`
-   - If not found: append new entry with `moduleCode: null` and `path: "{app_code}/business-analyse/v{version}/feature.json"`
-3. For EACH MODULE-level feature.json:
-   - Find existing entry where `appCode == {app_code}` AND `moduleCode == {module_code}` AND `version == {version}`
-   - If found: update `status`, `updatedAt`, `featureDescription`
-   - If not found: append new entry with `moduleCode: "{module_code}"` and `path: "{app_code}/{module_code}/business-analyse/v{version}/feature.json"`
+
+2. **PROJECT MODE (`workflow.mode === "project"`):**
+   a. Add/update PROJECT-level entry:
+      - Find existing entry where `projectId == {project_id}` AND `scope == "project"`
+      - If found: update `status`, `updatedAt`
+      - If not found: append new entry with `scope: "project"`, `projectId: "{project_id}"`, `path: "business-analyse/v{version}/feature.json"`
+   b. For EACH APPLICATION:
+      - Find existing entry where `appCode == {app_code}` AND `moduleCode == null` AND `version == {version}`
+      - If found: update `status`, `updatedAt`, `featureDescription`
+      - If not found: append new entry with `moduleCode: null`, `context: "{app.context}"`, and `path: "{context}/{app_code}/business-analyse/v{version}/feature.json"`
+   c. For EACH MODULE within each application:
+      - Find existing entry where `appCode == {app_code}` AND `moduleCode == {module_code}` AND `version == {version}`
+      - If found: update `status`, `updatedAt`, `featureDescription`
+      - If not found: append new entry with `path: "{context}/{app_code}/{module_code}/business-analyse/v{version}/feature.json"`
+
+3. **SINGLE-APP MODE (default):**
+   a. For the APPLICATION-level feature.json:
+      - Find existing entry where `appCode == {app_code}` AND `moduleCode == null` AND `version == {version}`
+      - If found: update `status`, `updatedAt`, `featureDescription`
+      - If not found: append new entry with `moduleCode: null` and `path: "{app_code}/business-analyse/v{version}/feature.json"`
+   b. For EACH MODULE-level feature.json:
+      - Find existing entry where `appCode == {app_code}` AND `moduleCode == {module_code}` AND `version == {version}`
+      - If found: update `status`, `updatedAt`, `featureDescription`
+      - If not found: append new entry with `moduleCode: "{module_code}"` and `path: "{app_code}/{module_code}/business-analyse/v{version}/feature.json"`
+
 4. Update root `updatedAt` to current timestamp
 5. Write manifest back to `docs/business/index.json`
 
 **Display confirmation:**
 ```
 ✓ BA manifest updated: docs/business/index.json
-  Entries: {total_count} ({app_count} applications, {module_count} modules)
+  Entries: {total_count} ({project_count} projects, {app_count} applications, {module_count} modules)
   Web viewer: /system/docs/ba
 ```
 
@@ -205,20 +222,28 @@ IF ANY category shows FAIL → **STOP AND RE-RUN `ss derive-prd`**. DO NOT proce
 ### 4. Read Source Data for HTML
 
 1. Read the HTML template from skill directory: `html/ba-interactive.html` (relative to `~/.claude/skills/business-analyse/`)
-2. Read the master feature.json (application level)
-3. Read EACH module feature.json (module level)
+2. **SINGLE-APP MODE:** Read the master feature.json (application level)
+3. **PROJECT MODE:** Read the project feature.json + ALL application feature.json files
+4. Read EACH module feature.json (module level, across all applications in project mode)
 
 > **Reference:** Read `references/html-data-mapping.md` for the complete FEATURE_DATA and EMBEDDED_ARTIFACTS mapping specification.
 
 **Key requirements:**
 - FEATURE_DATA must be pre-populated with ALL analysis data (empty data = BUG)
-- FEATURE_DATA.**moduleSpecs** MUST be populated for EACH module (use cases, business rules, entities, permissions) — empty moduleSpecs = BROKEN specification tabs
+- FEATURE_DATA.**moduleSpecs** MUST be populated for EACH module across ALL applications (use cases, business rules, entities, permissions) — empty moduleSpecs = BROKEN specification tabs
 - FEATURE_DATA.**cadrage.scope** must use HTML keys (vital/important/optional/excluded) NOT feature.json keys (mustHave/shouldHave/couldHave/outOfScope)
 - FEATURE_DATA.**metadata.analysisMode** must be set from `master.metadata.analysisMode` (always "interactive")
 - EMBEDDED_ARTIFACTS contains wireframes, E2E diagrams, dependency graph
 - Both objects are serialized as JSON with 2-space indentation
 - All data mapped from master and module feature.json files — follow `html-data-mapping.md` EXACTLY
 
+**PROJECT MODE additions to FEATURE_DATA:**
+- `FEATURE_DATA.project` — project-level metadata (name, applicationCount, applicationOrder)
+- `FEATURE_DATA.applications` — array of application summaries with their modules
+- `FEATURE_DATA.modules` — flattened list of ALL modules across ALL applications (each with `applicationCode` field)
+- `FEATURE_DATA.consolidation.crossApplicationInteractions` — from project feature.json
+- FEATURE_DATA.**metadata.workflowMode** must be `"project"` (enables multi-app tabs in HTML)
+
 ---
 
 ### 5-7. Build FEATURE_DATA, EMBEDDED_ARTIFACTS & Replace Placeholders
@@ -426,9 +451,13 @@ Display completion using the template from `templates/tpl-launch-displays.md`:
 
 ```
 ═══════════════════════════════════════════════════════════════
-  [OK] BUSINESS ANALYSE TERMINEE - {application_name}
+  [OK] BUSINESS ANALYSE TERMINEE - {application_name OR project_name}
 ═══════════════════════════════════════════════════════════════
 
+{IF workflow.mode === "project":}
+Project:   {project_name}
+Apps:      {app_count} ({app_names})
+{ENDIF}
 Modules:   {count} ({names})
 Strategy:  {strategy}
 Files:     {total files across all modules}
@@ -437,8 +466,11 @@ Complexity: {complexity}
 Effort:    {total_days} days ({total_hours} hours)
 
 [DIR] Artefacts générés:
-  ✓ feature.json (master + per-module) - spécification complète
+  ✓ feature.json ({IF project: "project + " ENDIF}master + per-module) - spécification complète
   ✓ .ralph/prd-{module}.json - task breakdown per module
+  {IF workflow.mode === "project":}
+  ✓ .ralph/prd-CrossApplication.json - cross-application integration tests
+  {ENDIF}
   ✓ .ralph/progress.txt - tracker de progression
   ✓ ba-interactive.html - document de revue interactif
 

package/templates/skills/documentation/SKILL.md

@@ -88,10 +88,11 @@ Follow the data-driven workflow from [templates.md](templates.md):
 ```
 1. Read source data (feature.json, code patterns)
 2. Generate doc-data.ts (data file, ~50 lines)
-3. Generate index.tsx (page wrapper, ~10 lines)
+3. Generate index.tsx (page wrapper, ~10 lines) with i18nNamespace prop
 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):**
@@ -118,16 +119,20 @@ Follow the data-driven workflow from [templates.md](templates.md):
 4. **ALWAYS** confirm before creating
 5. **ALWAYS** update App.tsx and parent indexes
 6. **ALWAYS** add module in `UserIndexPage.tsx` (IF type == `user`)
+7. **ALWAYS** update `DocPanelContext.tsx` mapping (IF type == `user`)
+8. **ALWAYS** pass `i18nNamespace` prop to DocRenderer in index.tsx
 </execution_rules>
 
 ---
 
 <success_criteria>
 - Documentation page renders correctly in React app
-- i18n files created for all 4 languages (FR, EN, IT, DE)
+- i18n FR file created (EN/IT/DE deferred to translation pipeline)
 - Route registered in App.tsx
 - docs-manifest.json updated
 - Module appears in UserIndexPage (if type = user)
+- DocPanelContext.tsx mapping updated (if type = user)
+- BookOpen edge button opens correct doc for the module's routes
 </success_criteria>
 
 ---
@@ -151,6 +156,87 @@ Follow the data-driven workflow from [templates.md](templates.md):
 
 ---
 
+## DocPanelContext Integration (TYPE: user)
+
+**MANDATORY** for `user` modules: Update the contextual documentation panel mapping.
+
+### How it works
+
+When a user clicks the BookOpen icon (edge button) on any application page, the `DocPanelContext` resolves the current route to the matching documentation URL and opens it in an iframe panel.
+
+### File to update
+
+`web/smartstack-web/src/contexts/DocPanelContext.tsx`
+
+### What to add
+
+For each module, add entries in the `docMapping` object for ALL the module's routes:
+
+```typescript
+const docMapping: Record<string, string> = {
+  // Platform > Administration > {Module}
+  '{module}': '/docs/business/platform/administration/{module}',
+  '{module}/list': '/docs/business/platform/administration/{module}',
+  '{module}/create': '/docs/business/platform/administration/{module}',
+  '{module}/dashboard': '/docs/business/platform/administration/{module}',
+  // ... add ALL sub-routes that exist for the module
+};
+```
+
+### Key resolution logic
+
+The `getDocUrlForPath()` function extracts segments from the pathname:
+- `/platform/administration/users/list` → tries `users/list`, then `users`
+- `/platform/support/tickets/123` → tries `tickets/123`, then `tickets`
+
+**Also update `appDocMapping`** if the module is the "default" for its application:
+
+```typescript
+const appDocMapping: Record<string, string> = {
+  'administration': '/docs/business/platform/administration/users',  // default for admin
+};
+```
+
+### index.tsx must pass i18nNamespace
+
+Each doc page wrapper MUST pass the correct i18n namespace to DocRenderer:
+
+```tsx
+import { DocRenderer } from '@/components/docs';
+import { docData } from './doc-data';
+
+export default function {Module}DocPage() {
+  return (
+    <DocRenderer
+      data={docData}
+      backPath="/docs/business/platform"
+      backLabel="nav.backToAdministration"
+      i18nNamespace="docsAdministration{Module}"
+    />
+  );
+}
+```
+
+### i18n namespace naming convention
+
+| Module | Namespace | File |
+|--------|-----------|------|
+| users | `docsAdministrationUsers` | `docs-administration-users.json` |
+| permissions | `docsAdministrationPermissions` | `docs-administration-permissions.json` |
+| tenants | `docsAdministrationTenants` | `docs-administration-tenants.json` |
+
+The JSON file root key MUST match the namespace: `{ "docsAdministration{Module}": { ... } }`
+
+### i18n config update
+
+Add the new namespace to `web/smartstack-web/src/i18n/config.ts`:
+1. Add to the destructured imports in `loadLanguageResources`
+2. Add the dynamic import with `.catch(() => ({ default: {} }))`
+3. Add to the return object
+4. Add to the `ns` array in `i18n.init()`
+
+---
+
 ## DATA SOURCES
 
 | Data | Source |
@@ -168,5 +254,9 @@ Follow the data-driven workflow from [templates.md](templates.md):
 - **Data Schema:** [data-schema.md](data-schema.md)
 - **DocRenderer:** `web/smartstack-web/src/components/docs/DocRenderer.tsx`
 - **Types:** `web/smartstack-web/src/components/docs/types.ts`
+- **DocPanelContext:** `web/smartstack-web/src/contexts/DocPanelContext.tsx`
+- **DocEdgeButton:** `web/smartstack-web/src/components/ui/DocEdgeButton.tsx`
+- **DocPanel:** `web/smartstack-web/src/components/ui/DocPanel.tsx`
+- **i18n Config:** `web/smartstack-web/src/i18n/config.ts`
 - **Manifest Schema:** `_resources/docs-manifest-schema.md`
 - **Complete Command:** `.claude/commands/documentation-module.md`

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

@@ -5,7 +5,9 @@ argument-hint: "[-m N] [-c TEXT] [-v] <task description>"
 ---
 
 <objective>
-Execute the Ralph Weegund technique — iterative development where the same prompt is fed repeatedly until completion. Uses progressive step loading with MCP validation, progress persistence, and Agent Teams for multi-module parallelization.
+Execute the Ralph Weegund technique — iterative module orchestration. Ralph reads PRDs from `/business-analyse`, resolves task dependencies, and delegates all code generation to `/apex -d`. Uses progress persistence and Agent Teams for multi-module parallelization.
+
+**Key principle:** Ralph ORCHESTRATES (task selection, module sequencing, PRD state, reporting). All code generation is delegated to `/apex`.
 </objective>
 
 <quick_start>
@@ -63,8 +65,7 @@ Execute the Ralph Weegund technique — iterative development where the same pro
 
 **Task execution cycle:**
 ```
-LOAD → GENERATE → COMPILE → TEST → [FAIL?] → FIX → RE-TEST → [PASS!] → COMMIT → NEXT
-                                       ↑___________________________|
+LOAD → DELEGATE TO /apex -d → VERIFY PRD STATE → COMMIT PRD → NEXT MODULE
 ```
 
 </workflow>
@@ -78,6 +79,8 @@ LOAD → GENERATE → COMPILE → TEST → [FAIL?] → FIX → RE-TEST → [PASS
 | `{current_iteration}` | number | Current iteration |
 | `{current_module}` | string\|null | Current module (multi-module) |
 | `{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) |
 </state_variables>
 
 <mcp_requirements>
@@ -85,14 +88,7 @@ LOAD → GENERATE → COMPILE → TEST → [FAIL?] → FIX → RE-TEST → [PASS
 1. `mcp__smartstack__validate_conventions` — verify connectivity
 2. `mcp__context7__resolve-library-id` — verify connectivity
 
-**During work:**
-- `validate_conventions` — before commits
-- `check_migrations` — before EF Core changes
-- `suggest_migration` — migration naming
-- `generate_permissions` — RBAC seed data
-- `scaffold_api_client` — frontend API client
-- `scaffold_routes` — frontend routing
-- `scaffold_tests` — test generation
+**During work:** All MCP tool calls are handled by `/apex` during delegation. Ralph only uses `validate_conventions` for initial connectivity check.
 </mcp_requirements>
 
 <execution_guarantee>
@@ -116,7 +112,7 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 - Ask the user to choose between supervised/autonomous mode
 - Ask the user to choose a completion promise
 - Wait for user input between iterations
-- Delegate the loop to sub-agents (except team mode)
+- Delegate the loop to sub-agents (except team mode and /apex delegation)
 
 **The ONLY valid stop conditions are:**
 - ALL tasks completed (→ step-05 report)
@@ -137,7 +133,7 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 |------|------|---------|-------------|
 | 00 | `steps/step-00-init.md` | Parse args, verify MCP, init state, team setup | ~150 |
 | 01 | `steps/step-01-task.md` | Load/create tasks from prd.json | ~365 |
-| 02 | `steps/step-02-execute.md` | Execute ONE task (first iteration) | ~140 |
+| 02 | `steps/step-02-execute.md` | Delegate module to /apex -d | ~120 |
 | 03 | `steps/step-03-commit.md` | Commit, update prd.json/progress.txt | ~135 |
 | 04 | `steps/step-04-check.md` | Check completion, compact loop entry | ~185 |
 | 05 | `steps/step-05-report.md` | Generate final report | ~150 |
@@ -145,10 +141,9 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 **Reference files (loaded conditionally):**
 | File | Loaded when |
 |------|-------------|
-| `references/category-rules.md` | Step-02 and compact loop (execution rules per category) |
-| `references/compact-loop.md` | Step-04 section 5 (inline execution after first iteration) |
-| `references/core-seed-data.md` | Infrastructure task with seed data keywords |
-| `references/error-classification.md` | Build failure in compact loop or validation (error diagnosis) |
+| `references/category-rules.md` | Step-01 and compact loop (category ordering and dependency rules) |
+| `references/compact-loop.md` | Step-04 section 5 (module loop with /apex delegation) |
+| `references/section-splitting.md` | Step-01 section 4c when module has >4 entities + >1 section |
 | `references/team-orchestration.md` | Step-00 when multi-module detected (2+ PRDs) |
 </step_files>
 
@@ -159,6 +154,8 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 ├── progress.txt          # Persistent memory
 ├── modules-queue.json    # Multi-module tracking (if applicable)
 ├── prd-{module}.json     # Per-module PRDs (from ss derive-prd, unified v3 format)
+├── prd-{module}-phase0.json         # Section split: Foundation (domain+infra+migration)
+├── prd-{module}-section-{code}.json # Section split: Per-section (app+api+seed+frontend+tests)
 ├── logs/
 └── reports/
     └── {feature}.md