@atlashub/smartstack-cli 3.5.0 → 3.6.0

package/templates/skills/business-analyse/steps/step-05d-html.md

@@ -0,0 +1,326 @@
+---
+name: step-05d-html
+description: Deploy ba-interactive.html pre-populated with all analysis data
+model: sonnet
+next_step: null
+---
+
+> **Context files:** `_shared.md`
+
+# Step 5d: Deploy Interactive HTML
+
+## MANDATORY EXECUTION RULES
+
+- **ALWAYS** deploy ba-interactive.html PRE-POPULATED with all data
+- **ALWAYS** follow references/html-data-mapping.md EXACTLY for FEATURE_DATA and EMBEDDED_ARTIFACTS mapping
+- **FEATURE_DATA.moduleSpecs MUST be populated for EACH module** — 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.vibeCoding must be set** from master.metadata.vibeCoding (controls section visibility)
+- **NEVER leave FEATURE_DATA or EMBEDDED_ARTIFACTS empty or partial**
+
+## YOUR TASK
+
+Deploy the interactive HTML document pre-populated with ALL analysis data. This is the final step of the business analysis workflow. The HTML is the client-facing deliverable for review and can be edited, enriched, and re-imported.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Read Source Data
+
+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)
+
+> **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.**cadrage.scope** must use HTML keys (vital/important/optional/excluded) NOT feature.json keys (mustHave/shouldHave/couldHave/outOfScope)
+- FEATURE_DATA.**metadata.vibeCoding** must be set from `master.metadata.vibeCoding` (controls section visibility)
+- 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
+
+---
+
+### 2. Build FEATURE_DATA Object
+
+Reference `references/html-data-mapping.md` EXACTLY. The FEATURE_DATA object must contain:
+
+**Structure:**
+```javascript
+const FEATURE_DATA = {
+  metadata: {
+    applicationName: master.application_name,
+    applicationId: master.feature_id,
+    version: master.version,
+    createdAt: ISO_TIMESTAMP,
+    vibeCoding: master.metadata.vibeCoding // "enabled" or "disabled" — controls UI section visibility
+  },
+  cadrage: {
+    goal: master.cadrage.goal,
+    vision: master.cadrage.vision,
+    success_criteria: master.cadrage.success_criteria,
+    scope: {
+      // CONVERT feature.json keys to HTML keys:
+      // mustHave → vital
+      // shouldHave → important
+      // couldHave → optional
+      // outOfScope → excluded
+      vital: master.globalScope.mustHave || [],
+      important: master.globalScope.shouldHave || [],
+      optional: master.globalScope.couldHave || [],
+      excluded: master.globalScope.outOfScope || []
+    },
+    constraints: master.cadrage.constraints || [],
+    risks: master.cadrage.risks || [],
+    stakeholders: master.stakeholders || []
+  },
+  modules: [
+    {
+      moduleCode: module.code,
+      moduleName: module.name,
+      moduleDescription: module.description || "",
+      // ... per-module fields from feature.json
+    }
+  ],
+  moduleSpecs: {
+    // CRITICAL: Must have ONE entry per module with ALL module data
+    // Each entry keyed by moduleCode:
+    "{moduleCode}": {
+      useCases: module.specification.useCases || [],
+      businessRules: module.analysis.businessRules || [],
+      entities: module.analysis.entities || [],
+      permissions: module.specification.permissions || [],
+      apiEndpoints: module.specification.apiEndpoints || []
+    }
+  },
+  consolidation: {
+    // Cross-module analysis
+    integrations: master.consolidation.integrations || [],
+    sharedEntities: master.consolidation.sharedEntities || [],
+    sequenceDiagrams: master.consolidation.e2eFlows || []
+  },
+  handoff: {
+    // From feature.json handoff section
+    complexity: master.handoff.complexity,
+    implementationStrategy: master.handoff.implementationStrategy,
+    moduleOrder: master.handoff.moduleOrder,
+    filesToCreate: master.handoff.filesToCreate,
+    brToCodeMapping: master.handoff.brToCodeMapping,
+    apiEndpointSummary: master.handoff.apiEndpointSummary
+  }
+};
+```
+
+**Build process:**
+1. Extract metadata from master feature.json
+2. Extract cadrage from master feature.json (CONVERT scope keys)
+3. Extract stakeholders from master.stakeholders
+4. Iterate ALL modules and populate moduleSpecs (THIS IS CRITICAL — empty moduleSpecs = BUG)
+5. For EACH module, extract:
+   - Use cases from specification.useCases
+   - Business rules from analysis.businessRules
+   - Entities from analysis.entities
+   - Permissions from specification.permissions
+   - API endpoints from specification.apiEndpoints
+6. Extract consolidation data (integrations, shared entities, E2E flows)
+7. Extract handoff section (complexity, strategy, module order, file counts)
+
+---
+
+### 3. Build EMBEDDED_ARTIFACTS Object
+
+Extract visual artifacts and diagrams from the analysis:
+
+```javascript
+const EMBEDDED_ARTIFACTS = {
+  wireframes: [
+    // Extract from each module's specification.uiWireframes
+    {
+      moduleCode: "{moduleCode}",
+      screen: wireframe.screen,
+      description: wireframe.description,
+      layout: wireframe.layout || "responsive",
+      components: wireframe.components || []
+    }
+  ],
+  e2eFlows: [
+    // Extract from master consolidation.e2eFlows
+    {
+      flowName: flow.name,
+      description: flow.description,
+      sequence: flow.sequence || [],
+      modules: flow.modules || []
+    }
+  ],
+  dependencyGraph: {
+    // From master consolidation.dependencyGraph
+    nodes: master.consolidation.dependencyGraph?.nodes || [],
+    edges: master.consolidation.dependencyGraph?.edges || []
+  }
+};
+```
+
+**Artifact gathering:**
+1. Read each module's `specification.uiWireframes[]` and add to wireframes array
+2. Read master's `consolidation.e2eFlows[]` and add to e2eFlows array
+3. Read master's `consolidation.dependencyGraph` and include as-is
+4. Serialize as JSON with 2-space indentation
+
+---
+
+### 4. Replace Placeholders in Template
+
+1. Serialize the FEATURE_DATA object as JSON (with 2-space indentation)
+2. Serialize the EMBEDDED_ARTIFACTS object as JSON (with 2-space indentation)
+3. Replace `{{FEATURE_DATA}}` with the serialized FEATURE_DATA JSON
+4. Replace `{{EMBEDDED_ARTIFACTS}}` with the serialized EMBEDDED_ARTIFACTS JSON
+5. Replace `{{APPLICATION_NAME}}` with `{application_name}`
+6. Replace `{{APPLICATION_ID}}` with `{feature_id}`
+7. Replace `{{VERSION}}` with `{version}`
+8. Replace `{{CREATED_AT}}` with `{ISO timestamp}`
+
+**Verification during replacement:**
+- Ensure FEATURE_DATA JSON is valid (no trailing commas, proper nesting)
+- Ensure EMBEDDED_ARTIFACTS JSON is valid
+- Verify placeholders are completely replaced (grep for `{{` to confirm)
+
+---
+
+### 5. Write and Verify
+
+1. Write the populated HTML to the output directory: `docs/business/{app}/business-analyse/v{version}/ba-interactive.html`
+2. Display deployment confirmation:
+
+```
+[OK] Interactive HTML deployed:
+  Path: docs/business/{app}/business-analyse/v{version}/ba-interactive.html
+  Pre-populated with: {stakeholder_count} stakeholders, {module_count} modules,
+    {total_uc} use cases, {total_br} business rules, {total_entity} entities
+  Visual artifacts: {total_wireframes} wireframes, {e2e_flow_count} E2E diagrams
+  Open in browser to review and edit the business analysis.
+  Export JSON and re-import with: /business-analyse -x <exported-json-path>
+```
+
+---
+
+## POST-CHECK (BLOCKING)
+
+After writing the HTML file, verify:
+
+1. **File size > 100KB** (indicates pre-populated, not empty template)
+   ```bash
+   file_size=$(stat --format=%s "{output_path}/ba-interactive.html")
+   if [ $file_size -lt 100000 ]; then
+     BLOCKING_ERROR("ba-interactive.html is only ${file_size} bytes — not pre-populated")
+   fi
+   ```
+
+2. **Grep for "moduleSpecs"** — MUST be present in generated HTML
+   ```bash
+   if ! grep -q '"moduleSpecs"' "{output_path}/ba-interactive.html"; then
+     BLOCKING_ERROR("moduleSpecs not found in HTML — FEATURE_DATA not serialized correctly")
+   fi
+   ```
+
+3. **moduleSpecs must have entries for ALL modules** (not empty object `{}`)
+   ```bash
+   # Count moduleSpecs entries — should equal module count
+   moduleSpec_count=$(grep -o '"moduleCode"' "{output_path}/ba-interactive.html" | wc -l)
+   if [ $moduleSpec_count -lt {module_count} ]; then
+     BLOCKING_ERROR("moduleSpecs has only ${moduleSpec_count} entries but need {module_count}")
+   fi
+   ```
+
+4. **cadrage.scope must use HTML keys** (vital/important/optional/excluded)
+   ```bash
+   if grep -q '"mustHave"' "{output_path}/ba-interactive.html"; then
+     BLOCKING_ERROR("cadrage.scope still has feature.json keys (mustHave) — must convert to HTML keys (vital)")
+   fi
+   ```
+
+**IF ANY CHECK FAILS → DO NOT PROCEED. Fix the data mapping and regenerate.**
+
+---
+
+## SELF-VERIFICATION (FINAL)
+
+Before completion, verify:
+
+1. **ba-interactive.html exists** at `docs/business/{app}/business-analyse/v{version}/` and file size > 100KB
+2. **FEATURE_DATA contains moduleSpecs** with entries for ALL modules (grep for `"moduleSpecs"` — if absent, the specification tabs will be broken)
+3. **cadrage.scope uses HTML keys** (vital/important/optional/excluded) — NOT feature.json keys
+4. **EMBEDDED_ARTIFACTS contains wireframes** for all modules with screen names and descriptions
+5. **All 5 metadata fields populated:** applicationName, applicationId, version, createdAt, vibeCoding
+
+**IF any check fails → REGENERATE the HTML immediately.**
+
+---
+
+## WHY A FINAL HTML DEPLOYMENT AT HANDOFF?
+
+- Step 03 already deploys the HTML incrementally after each module (partial data)
+- This final deployment adds the COMPLETE data: all modules + consolidation + handoff info
+- The client sees the FULL analysis pre-populated — including cross-module interactions and E2E flows
+- The client can review, edit, and enrich directly in the browser
+- Any client modifications can be re-imported via `-x` extraction mode
+- The HTML is standalone (no server required) with localStorage persistence
+- On first open: pre-populated data displays. After client edits: localStorage overrides
+- **NOTE:** This overwrites the incremental HTML from step-03 with the complete version
+
+---
+
+## OUTPUT
+
+The final deliverable:
+
+- **ba-interactive.html** (deployed to docs/business/{app}/business-analyse/v{version}/)
+  - Standalone interactive HTML document for client review
+  - Pre-populated with ALL analysis data (metadata, cadrage, modules, wireframes, E2E flows)
+  - FEATURE_DATA and EMBEDDED_ARTIFACTS fully serialized as JSON variables
+  - Client can edit, add use cases, modify scope, and export JSON
+  - Re-importable via `/business-analyse -x <exported-json-path>`
+
+---
+
+## TROUBLESHOOTING
+
+| Issue | Resolution |
+|-------|-----------|
+| ba-interactive.html is too small (< 100KB) | FEATURE_DATA not serialized correctly. Verify JSON structure. Re-run FEATURE_DATA build. |
+| moduleSpecs missing from HTML | FEATURE_DATA.moduleSpecs is empty or not included in JSON. Verify each module is iterated and populated. |
+| Scope keys still show "mustHave" instead of "vital" | Conversion from feature.json keys to HTML keys failed. Check cadrage.scope conversion logic. |
+| Wireframes array is empty | Verify each module has specification.uiWireframes. If missing, add wireframe stubs. |
+| dependencyGraph missing | Verify master feature.json has consolidation.dependencyGraph. If missing, create empty nodes/edges arrays. |
+| HTML opens but data blank (localStorage issue) | Clear browser localStorage. HTML will load pre-populated FEATURE_DATA on first load. |
+| Export/re-import fails | Verify exported JSON matches original feature.json schema. Validate with `/business-analyse -x --validate`. |
+
+---
+
+## FINAL COMPLETION
+
+```
+═══════════════════════════════════════════════════════════════
+  BUSINESS ANALYSE COMPLETE
+═══════════════════════════════════════════════════════════════
+
+All artifacts deployed:
+  ✓ feature.json (master + per-module)
+  ✓ prd.json (module-level task breakdown)
+  ✓ progress.txt (development tracker)
+  ✓ ba-interactive.html (client-facing review document)
+
+Next steps:
+  1. Share ba-interactive.html with stakeholders
+  2. Gather feedback and edits
+  3. Export modified JSON from HTML
+  4. Re-import with: /business-analyse -x <exported-json-path>
+  5. Launch development: /ralph-loop -r
+
+═══════════════════════════════════════════════════════════════
+```
+
+**Business analysis is now complete. The HTML document is ready for client review.**

package/templates/skills/business-analyse/templates/tpl-frd.md

@@ -1,7 +1,7 @@
 # Template Functional Requirements Document
 
 > **Usage:** Template for 3-functional-specification.md
-> **Loaded in:** step-03a-specify.md
+> **Loaded in:** step-03a-data.md
 
 ---
 

package/templates/skills/business-analyse/templates/tpl-launch-displays.md

@@ -1,6 +1,6 @@
 # Skill Launch Display Templates (templates/tpl-launch-displays.md)
 
-> **Used by:** step-05b-deploy (section 5: Completion Summary)
+> **Used by:** step-05c-deploy (section 5: Completion Summary)
 > **Purpose:** User-facing display templates for BA completion
 > **Note:** No emojis - uses text markers per Claude Code conventions
 

package/templates/skills/business-analyse/templates/tpl-progress.md

@@ -1,6 +1,6 @@
 # Progress Tracker Template (templates/tpl-progress.md)
 
-> **Used by:** step-05b-deploy (section 2: Initialize Progress Tracker)
+> **Used by:** step-05c-deploy (section 2: Initialize Progress Tracker)
 > **Purpose:** Template structure for .ralph/progress.txt - populate with module-specific data
 
 ## Template

package/templates/skills/controller/steps/step-03-generate.md

@@ -33,8 +33,9 @@ Read: templates/templates.md
 
 **Target path:**
 ```
-src/SmartStack.Api/Controllers/{area}/{module}Controller.cs
+src/SmartStack.Api/Controllers/{ContextShort}/{Application}/{entity}Controller.cs
 ```
+> Context mapping: `business` → `Business`, `platform` → `Admin`, `personal` → `User`
 
 **Apply template with variables:**
 

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

@@ -311,6 +311,12 @@ Before ANY work, verify MCP servers:
 | 04 | `steps/step-04-check.md` | Check completion, decide next action |
 | 05 | `steps/step-05-report.md` | Generate final report |
 
+**Reference files (loaded conditionally):**
+
+| Ref | File | Loaded when |
+|-----|------|-------------|
+| - | `references/core-seed-data.md` | Infrastructure task involves seed data or IClientSeedDataProvider |
+
 </step_files>
 
 <file_structure>
@@ -402,14 +408,23 @@ Before ANY work, verify MCP servers:
 
 <execution_rules>
 
+- **NEVER DELEGATE THE LOOP** - The Ralph loop MUST execute in the MAIN agent context. NEVER use the Task tool to spawn a sub-agent for loop execution. Sub-agents lose ALL skill context (step files, COMPACT LOOP logic, MCP requirements, SmartStack conventions) and WILL stop prematurely. This is FORBIDDEN. The only acceptable use of Task is for isolated read-only research (e.g., looking up documentation via Context7).
 - **Load step files ONCE** - Step files are read only on FIRST iteration. After that, use the COMPACT LOOP in step-04 section 5.
 - **VERIFY MCP FIRST** - Never skip MCP validation at init
 - **BATCH same-category tasks** - Execute up to 5 tasks of the same category per iteration (reduces loop iterations from 30+ to ~8)
 - **COMMIT AFTER EACH BATCH** - One commit per batch, not per individual task
 - **UPDATE progress.txt** - Persist learnings
 - **NEVER fake completion** - Only output promise when truly done
-- **NEVER STOP THE LOOP** - The loop is AUTONOMOUS. DO NOT pause between iterations. DO NOT wait for user input. Only stop on: completion, max iterations, dead-end, or explicit user interruption. Stopping for any other reason wastes context and causes re-reads.
-- **COMPACT OUTPUT** - During loop iterations, use 1-2 lines per task. Save verbose output for the final report.
+- **NEVER STOP THE LOOP** - The loop is AUTONOMOUS. Stopping is a BUG. Specifically FORBIDDEN:
+  - DO NOT pause between iterations
+  - DO NOT wait for user input
+  - DO NOT output a summary and stop ("I'll continue later")
+  - DO NOT decide to stop because "quality over quantity" or "this is enough for now"
+  - DO NOT stop after completing one module when others remain in the queue
+  - DO NOT reduce scope autonomously ("I'll skip frontend/tests to save time")
+  - The ONLY valid stop reasons: ALL tasks complete, max iterations reached, dead-end (all remaining blocked/failed), or explicit user interruption via Ctrl+C
+- **CONTEXT BUDGET** - Keep ALL output COMPACT during loop iterations. Verbose reasoning wastes context tokens and causes premature termination. Use 1-2 lines per task during the loop. Save detailed output for the final report ONLY. During init, skip verbose MCP output and keep summaries minimal.
+- **MODULE COMPLETENESS** - A module is NOT complete unless ALL expected layers have completed tasks: domain, infrastructure, application, api, frontend, i18n, test. If any layer is missing, inject guardrail tasks before advancing to the next module.
 </execution_rules>
 
 <success_criteria>