@atlashub/smartstack-cli 3.4.1 → 3.6.0

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

@@ -1,432 +0,0 @@
----
-name: step-05b-deploy
-description: Generate prd.json, progress.txt, deploy ba-interactive.html, manifest, user choice
-model: sonnet
-next_step: null
----
-
-> **Context files:** `_shared.md`
-
-# Step 5b: Handoff - Deploy Artifacts
-
-## MANDATORY EXECUTION RULES
-
-- **ALWAYS** verify all module handoffs are complete before generating artifacts
-- **ALWAYS** derive prd.json from feature.json (NEVER independently)
-- **NEVER** invent entities/FRs/BRs not in feature.json
-- **ALWAYS** deploy ba-interactive.html PRE-POPULATED with all data
-- **ALWAYS** update BA manifest at docs/business/index.json
-
-## YOUR TASK
-
-Generate deployment artifacts from the handoff data written in step-05a: prd.json (per module), progress.txt, interactive HTML document, BA manifest, and present development approach choice to the user.
-
----
-
-## EXECUTION SEQUENCE
-
-### 0. Pre-flight Verification
-
-Before generating ANY artifact, verify step-05a completed successfully:
-
-```
-FOR each module in modules[]:
-  Read module feature.json
-  IF module.handoff === {} OR module.status !== "handed-off":
-    → BLOCKING ERROR: Module {module.code} has no handoff data
-    → Return to step-05a-handoff.md
-```
-
-IF all modules have valid handoff → proceed.
-
----
-
-### 1. Generate prd.json (PROGRAMMATIC)
-
-> **RULE:** prd.json is extracted by CLI code, **NEVER** generated by LLM.
-> The `ss derive-prd` command performs a deterministic data transformation from feature.json.
-
-**For each module:**
-
-```
-Execute: ss derive-prd --feature {moduleFeaturePath} --output .ralph/prd-{moduleCode}.json
-```
-
-**For consolidated view (multi-module, optional):**
-
-```
-Execute: ss derive-prd --application {masterFeaturePath}
-→ Generates .ralph/prd-{moduleCode}.json for each module
-```
-
-**Verification:** After execution, read the generated prd.json and display summary:
-
-```
-prd.json generated for module {moduleCode}:
-  - Use cases: {count}
-  - Functional requirements: {count}
-  - Business rules: {count}
-  - API endpoints: {count}
-  - Sections: {count}
-  - Files to create: {count}
-  - BR-to-code mappings: {count}
-```
-
-**Key guarantees:**
-- Source MUST reference feature.json path (traceability)
-- All data is EXACT COPY from feature.json (no transformation, no invention)
-- prd.json version: "2.0.0"
-- source.type: "ba-handoff-programmatic"
-
----
-
-### 2. Initialize Progress Tracker
-
-> **Template:** Read `templates/tpl-progress.md` for the complete progress tracker template structure.
-> Populate the template with module-specific data from feature.json handoff sections.
-
-**Progress Tracker Rules:**
-- One section per module, in topological order (dependencies first)
-- CORE SeedData ALWAYS 5 entries (mandatory)
-- Business SeedData varies by module
-- Hierarchical task structure (module -> layer -> tasks)
-- Each task is independent, assignable checkbox
-- Effort estimate per module (simple/medium/complex)
-- Summary with totals across all modules
-- Cross-module tasks only if multi-module
-
----
-
-### 3. Deploy Interactive HTML Document (MANDATORY)
-
-> **The interactive HTML document is deployed to the project PRE-POPULATED with ALL analysis data.**
-> The client opens it in a browser and sees the complete analysis (cadrage, modules, entities, UCs, BRs, wireframes, permissions, consolidation).
-> The client can then review, edit, enrich, and export modifications as JSON.
-> That JSON can be re-imported via `/business-analyse -x` to update the feature.json.
-
-**Source:** `html/ba-interactive.html` (relative to skill root = `~/.claude/skills/business-analyse/html/`)
-
-**Destination:** `docs/business/{app}/business-analyse/v{version}/ba-interactive.html`
-
-**Deployment steps:**
-
-#### Step 1: Read source data
-
-1. Read the HTML template from skill directory
-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)
-- 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
-
-#### Step 3: Replace placeholders in template
-
-1. Serialize the FEATURE_DATA object as JSON (with 2-space indentation for readability)
-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}}` → `{application_name}` (still used in `<title>` and header)
-6. Replace `{{APPLICATION_ID}}` → `{feature_id}` (still used in `APP_KEY`)
-7. Replace `{{VERSION}}` → `{version}`
-8. Replace `{{CREATED_AT}}` → `{ISO timestamp}`
-
-> **NOTE:** `{{APPLICATION_NAME}}`, `{{APPLICATION_ID}}`, `{{VERSION}}`, `{{CREATED_AT}}` still appear
-> in the HTML body (`<title>`, header, `APP_KEY`). They MUST be replaced separately from FEATURE_DATA.
-
-> **NEW:** `{{EMBEDDED_ARTIFACTS}}` is a separate JavaScript variable in the HTML that stores all visual artifacts (wireframes, E2E diagrams, dependency graph) for client-side rendering and export.
-
-#### Step 4: Write and confirm
-
-1. Write the populated HTML to the output directory
-2. Display deployment confirmation:
-
-```
-✓ 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>
-```
-
-**Why a FINAL 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
-
----
-
-### 4. Update BA Manifest (MANDATORY)
-
-> **The BA manifest enables the SmartStack web app to discover and display all available business analyses.**
-> It is a JSON index file at `docs/business/index.json` that lists all feature.json files.
-
-**Path:** `docs/business/index.json` (project root relative)
-
-**Schema:**
-```json
-{
-  "version": "1.0",
-  "updatedAt": "{ISO timestamp}",
-  "analyses": [
-    {
-      "appCode": "{app_code}",
-      "appName": "{application_name}",
-      "moduleCode": null | "{module_code}",
-      "moduleName": "{module_name}",
-      "version": "{version}",
-      "status": "handed-off",
-      "featureDescription": "{feature_description}",
-      "path": "{app_code}/business-analyse/v{version}/feature.json",
-      "updatedAt": "{ISO timestamp}"
-    }
-  ]
-}
-```
-
-**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"`
-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)
-  Web viewer: /system/docs/ba
-```
-
-**Why a manifest?**
-- The web app needs to discover available BAs without scanning the filesystem
-- Static file serving (no backend API needed)
-- Incremental updates: each handoff adds/updates only its entries
-- Consumed by the SmartStack web app BA viewer at `/system/docs/ba`
-
----
-
-### 5. Completion Summary
-
-Display the completion summary after successful handoff:
-
-> **Reference:** Read `templates/tpl-launch-displays.md` for user-facing display templates.
-
-```
-═══════════════════════════════════════════════════════════════
-  [OK] BUSINESS ANALYSE TERMINEE - {application_name}
-═══════════════════════════════════════════════════════════════
-
-Modules:   {count} ({names})
-Strategy:  {strategy}
-Files:     {total files across all modules}
-Tasks:     {total tasks} ({core_count} CORE + {biz_count} business + {dev_count} development)
-Complexity: {complexity}
-Effort:    {total_days} days ({total_hours} hours)
-
-[DIR] Artefacts generés:
-  ✓ feature.json (master + per-module) - spécification complète
-  ✓ .ralph/prd.json or .ralph/prd-{module}.json - task breakdown
-  ✓ .ralph/progress.txt - tracker de progression
-  ✓ ba-interactive.html - document de revue interactif
-
-[TARGET] Prochaines étapes:
-  1. Ouvrir ba-interactive.html dans le navigateur
-  2. Partager avec les stakeholders pour validation
-  3. Si retours --> relancer /business-analyse pour une nouvelle itération
-  4. Une fois validé, lancer le développement:
-
-     /ralph-loop -r
-
-═══════════════════════════════════════════════════════════════
-```
-
-**No AskUserQuestion here.** The BA ends after displaying the summary. The user will manually launch `/ralph-loop -r` when ready (typically after stakeholder validation).
-
----
-
-## SELF-VERIFICATION (FINAL)
-
-Before presenting completion summary, VERIFY:
-
-1. **`.ralph/prd-{module}.json`** exists for ALL modules (file size > 100 bytes each)
-2. **`.ralph/progress.txt`** exists (file size > 500 bytes)
-3. **`ba-interactive.html`** exists at `docs/business/{app}/business-analyse/v{version}/` and file size > 100KB (pre-populated, not empty template)
-4. **`docs/business/index.json`** exists with correct entry count (1 app + N modules)
-
-**IF any check fails → GENERATE the missing artifact before presenting completion summary.**
-
----
-
-## MODE SUPPORT
-
-### Standard Mode
-
-Full handoff with all implementation details:
-- All 7 file categories
-- Complete BR-to-code mapping
-- Full API endpoint summary
-- Detailed prd.json
-- Comprehensive progress tracker
-
-### Micro Mode (use_case = micro)
-
-Simplified handoff with minimal scope:
-- Only essential CRUD entity + controller
-- 3 core SeedData entries (omit some optional ones)
-- Basic prd.json with simplified sections
-- Lightweight progress.txt
-- Display `/ralph-loop -r` command for later use
-
-### Delta Mode (use_case = refactoring)
-
-Focused handoff for changes:
-- Only affected modules listed
-- Reuse existing implementation patterns
-- Highlight what changed vs baseline
-- Update only affected prd.json sections
-- Progress tracker shows only delta tasks
-
----
-
-## OUTPUT
-
-> **FORBIDDEN:** Do NOT generate separate JSON files (specification.json, analysis.json, etc.).
-> **ONLY:** feature.json is the mandatory JSON deliverable.
-> **PLUS:** prd.json and progress.txt are additional working files.
-
-This step enriches **feature.json** (master + per-module) with:
-- **handoff** section: complexity, implementationStrategy, moduleOrder, filesToCreate (7 categories), brToCodeMapping, apiEndpointSummary, prdFiles
-- **status:** "handed-off"
-
-Also generates working files and updates the manifest:
-
-- **ba-interactive.html** (deployed to docs/business/{app}/business-analyse/v{version}/)
-  - Standalone interactive HTML document for client review
-  - Pre-populated with application name, ID, version
-  - Client can edit, add use cases, modify scope, and export JSON
-  - Re-importable via `/business-analyse -x <exported-json-path>`
-
-- **.ralph/prd.json** (or .ralph/prd-{module}.json per module structure)
-  - Derived entirely from feature.json
-  - Single source of truth for development team
-  - Includes all entities, use cases, business rules, API endpoints
-  - Task breakdown and implementation sequence
-
-- **.ralph/progress.txt**
-  - Main development task tracker
-  - Hierarchical structure (module → layer → tasks)
-  - Checkboxes for progress tracking
-  - Effort estimates per module
-  - Cross-module integration tasks (if multi-module)
-
-Completion: Display summary with `/ralph-loop -r` command for later execution after stakeholder validation.
-
----
-
-## EXAMPLES & TEMPLATES
-
-### Example: Simple Single Module (Orders)
-
-**Feature:** Order Management
-**Module:** Orders (1 entity, 2 use cases, 3 BRs)
-
-**Output:**
-- feature.json with handoff section
-- .ralph/prd.json (single consolidated file)
-- .ralph/progress.txt (~150 lines, 20-30 tasks)
-
-Strategy: Module by module (only 1 module)
-
-### Example: Medium Multi-Module (E-Commerce)
-
-**Feature:** E-Commerce Platform
-**Modules:** Customers (4 entities), Products (6 entities), Orders (8 entities), Invoices (3 entities)
-
-**Dependencies:**
-- Customers: Foundation (no deps)
-- Products: Foundation (no deps)
-- Orders: Depends on Customers + Products
-- Invoices: Depends on Orders
-
-**Output:**
-- feature.json (master + 4 module features) with handoff sections
-- User chooses: per-module prd (.ralph/prd-customers.json, .ralph/prd-products.json, etc.) or consolidated (.ralph/prd.json)
-- .ralph/progress.txt (~400 lines, 100+ tasks)
-- Module order: Customers, Products → Orders → Invoices (topological)
-
-Strategy options: Module by module (recommended), Layer by layer, Hybrid
-
-### Example: Complex Multi-Module (ERP)
-
-**Feature:** Enterprise Resource Planning
-**Modules:** Accounting, Sales, Purchasing, Inventory, HR, Finance (20+ entities total, 50+ use cases, 100+ BRs)
-
-**Output:**
-- feature.json (master + 6 module features) with handoff sections
-- Per-module prd.json (recommended for complexity management)
-- .ralph/progress.txt (~800+ lines, 200+ tasks)
-
-Complexity: Complex (highest across all modules)
-Strategy: Hybrid recommended (Foundation modules layer-by-layer, then dependent modules module-by-module)
-
----
-
-## VALIDATION CHECKLIST
-
-Before presenting handoff to user:
-
-- [ ] Status verified: "consolidated"
-- [ ] Implementation strategy selected or defaulted
-- [ ] Complexity calculated for each module and overall
-- [ ] filesToCreate: 7 categories complete, no free text
-- [ ] **WIREFRAME TRACEABILITY:** Every frontend Page/DashboardPage has `linkedWireframes[]` referencing specification.uiWireframes[].screen
-- [ ] **WIREFRAME ACCEPTANCE:** Every frontend Page/DashboardPage has `wireframeAcceptanceCriteria` describing expected layout
-- [ ] brToCodeMapping: All business rules from analysis.businessRules[] mapped
-- [ ] apiEndpointSummary: Exact copy from specification.apiEndpoints[]
-- [ ] prd.json: Derived from feature.json, not independently generated
-- [ ] prd.json: Includes all UCs, FRs, BRs, entities, API endpoints from source
-- [ ] progress.txt: Hierarchical, all modules in topological order, 5 CORE SeedData per module
-- [ ] progress.txt: Frontend tasks reference wireframe identifiers [wireframe: {screen}]
-- [ ] Module order: Follows topological dependency graph
-- [ ] feature.json updated: handoff section + status "handed-off"
-- [ ] All paths use project namespace from .smartstack/config.json
-- [ ] No invented requirements (everything traced to feature.json)
-- [ ] ba-interactive.html deployed PRE-POPULATED with all analysis data (not empty)
-- [ ] BA manifest (docs/business/index.json) updated with current analysis entries
-- [ ] User ready for next agent selection
-
----
-
-## TROUBLESHOOTING
-
-| Issue | Resolution |
-|-------|-----------|
-| All modules missing handoff data | Return to step-05a-handoff.md. Handoff MUST be written to each module feature.json. |
-| prd.json generation failed | Verify ss derive-prd command is installed and feature.json path is correct. |
-| progress.txt incomplete | Ensure all 5 CORE SeedData entries are present per module. Check topological order. |
-| ba-interactive.html deployment failed | Verify output directory exists. Check file permissions. Ensure HTML template is readable. |
-| BA manifest not found | Create docs/business/index.json if missing. Use schema provided in section 4. |
-| HTML pre-populated but empty | Verify FEATURE_DATA and EMBEDDED_ARTIFACTS objects are serialized correctly. Check JSON syntax. |
-
----
-
-END OF STEP 5b: DEPLOY ARTIFACTS