@atlashub/smartstack-cli 4.18.0 → 4.20.0

package/templates/skills/derive-prd/schemas/handoff-schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "handoff-schema.json",
+  "title": "SmartStack BA - Handoff",
+  "description": "Module-level handoff: file mapping (8 categories), BR-to-code mapping, API endpoint summary. Used by /derive-prd skill.",
+  "type": "object",
+  "properties": {
+    "complexity": { "type": "string", "enum": ["simple", "medium", "complex"] },
+    "filesToCreate": {
+      "type": "object",
+      "properties": {
+        "domain": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } },
+        "application": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } },
+        "infrastructure": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } },
+        "api": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } },
+        "frontend": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } },
+        "seedData": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } },
+        "tests": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } },
+        "documentation": { "type": "array", "items": { "$ref": "#/$defs/fileSpec" } }
+      },
+      "required": ["domain", "application", "infrastructure", "api", "frontend", "seedData", "tests", "documentation"]
+    },
+    "brToCodeMapping": {
+      "type": "array",
+      "description": "Maps each business rule to its implementation points across layers",
+      "items": {
+        "type": "object",
+        "required": ["ruleId", "implementationPoints"],
+        "properties": {
+          "ruleId": { "type": "string", "description": "BR-XXX identifier from analysis.businessRules" },
+          "title": { "type": "string" },
+          "implementationPoints": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["layer", "component"],
+              "properties": {
+                "layer": { "type": "string", "description": "Architecture layer (Domain, Application, Infrastructure, API, Frontend)" },
+                "component": { "type": "string", "description": "File name (e.g., Order.cs, OrdersController.cs)" },
+                "method": { "type": "string" },
+                "implementation": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "apiEndpointSummary": {
+      "type": "array",
+      "description": "Subset of specification.apiEndpoints enriched with linkedUC. MUST use EXACT same routes as specification.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "operation": { "type": "string" },
+          "method": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"] },
+          "route": { "type": "string" },
+          "linkedUC": { "type": "string" },
+          "permissions": { "type": "string" }
+        }
+      }
+    },
+    "ralphPrd": {
+      "type": "object",
+      "description": "Embedded Ralph Loop task breakdown (also exported to .ralph/prd.json by ss derive-prd)",
+      "properties": {
+        "tasks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": { "type": "integer" },
+              "description": { "type": "string" },
+              "category": { "type": "string", "enum": ["domain", "seedData", "seedDataCore", "application", "infrastructure", "api", "frontend", "i18n", "test", "validation"] },
+              "dependencies": { "type": "array", "items": { "type": "integer" } },
+              "acceptanceCriteria": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "fileSpec": {
+      "type": "object",
+      "required": ["path", "type", "module"],
+      "properties": {
+        "path": { "type": "string" },
+        "type": { "type": "string" },
+        "module": { "type": "string" },
+        "description": { "type": "string" },
+        "dependencies": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/templates/skills/derive-prd/steps/step-00-validate.md

@@ -0,0 +1,130 @@
+---
+name: step-00-validate
+description: Detect input, validate BA readiness, acceptance criteria gate
+model: sonnet
+next_step: steps/step-01-transform.md
+---
+
+> **Context files:** `references/acceptance-criteria.md` | `references/readiness-scoring.md`
+
+# Step 00: Validate BA Readiness
+
+## MANDATORY EXECUTION RULES
+
+- **ALWAYS** verify status = "consolidated" for all modules before proceeding
+- **ALWAYS** validate acceptance criteria (AC-01 to AC-17) per module
+- **BLOCKING** if any module has readiness score < 100% on blocking ACs
+- **NEVER** proceed to transform if any module fails readiness gate
+
+## YOUR TASK
+
+Detect the BA feature input, verify all modules are consolidated, validate acceptance criteria as a pre-gate, calculate readiness scores, and display the readiness table.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Detect Input
+
+```
+IF --feature <path> provided:
+  featurePath = <path>
+ELSE:
+  // Auto-detect from docs/
+  Scan docs/ for index.json files with status = "consolidated"
+  IF found exactly 1:
+    featurePath = found path
+  ELSE IF found > 1:
+    Display list and ask user to specify --feature <path>
+    STOP
+  ELSE:
+    BLOCKING ERROR: "No consolidated BA feature found. Run /business-analyse first."
+    STOP
+```
+
+### 2. Load Feature & Verify Consolidation
+
+```
+// Determine workflow mode
+IF project-level index.json exists:
+  projectFeature = ba-reader.findProjectFeature()
+  FOR each app in projectFeature.applications:
+    appFeature = ba-reader.findFeature(app.featureJsonPath)
+    IF appFeature.status !== "consolidated":
+      BLOCKING ERROR: "Application {app.code} not consolidated (status: {appFeature.status})"
+      → Run /business-analyse step-04 first
+  feature = projectFeature
+  modules = projectFeature.applications.flatMap(app => app.modules)
+ELSE:
+  feature = ba-reader.findFeature(featurePath)
+  IF feature.status !== "consolidated":
+    BLOCKING ERROR: "Feature status: {feature.status}, expected consolidated"
+    → Run /business-analyse step-04 first
+  modules = feature.modules
+```
+
+### 3. Validate Acceptance Criteria Per Module
+
+For **EACH module**, run the acceptance criteria bash script from `references/acceptance-criteria.md`:
+
+```bash
+MODULE_JSON="{module_feature_json_path}"
+node -e "
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync(process.argv[1], 'utf-8'));
+// ... (full AC-01 to AC-17 script from references/acceptance-criteria.md)
+" "$MODULE_JSON"
+```
+
+Collect results per module: PASS count, FAIL count, WARNING count.
+
+### 4. Calculate Readiness Score
+
+> **Reference:** Read `references/readiness-scoring.md` for the full algorithm.
+
+For each module:
+- Count blocking ACs passed vs total blocking ACs
+- Score = (blocking passed / blocking total) x 100
+- Non-blocking score = (non-blocking passed / non-blocking total) x 100
+
+### 5. Apply Readiness Gate
+
+```
+FOR each module:
+  IF readiness_score < 100%:
+    BLOCKING ERROR: "Module {moduleCode} readiness: {score}% — {failed_count} blocking ACs failed"
+    Display failed ACs with recovery actions
+    → Run /business-analyse to fix, then retry /derive-prd
+    STOP
+
+  IF non_blocking_score < 80%:
+    WARNING: "Module {moduleCode} non-blocking score: {score}% — consider fixing before handoff"
+```
+
+### 6. Display Readiness Table
+
+```
+══════════════════════════════════════════════════════════════
+  DERIVE-PRD — BA READINESS VALIDATION
+══════════════════════════════════════════════════════════════
+
+Feature: {feature_name}
+Applications: {app_count} (project mode only)
+Modules: {module_count}
+
+┌──────────────┬──────────┬────────────┬──────────────┬────────┐
+│ Module       │ Status   │ Blocking   │ Non-blocking │ Ready  │
+├──────────────┼──────────┼────────────┼──────────────┼────────┤
+│ {module1}    │ consol.  │ 16/16 100% │ 1/1 100%     │ YES    │
+│ {module2}    │ consol.  │ 16/16 100% │ 1/1 100%     │ YES    │
+└──────────────┴──────────┴────────────┴──────────────┴────────┘
+
+→ All modules READY — proceeding to transform...
+══════════════════════════════════════════════════════════════
+```
+
+---
+
+## NEXT STEP
+
+Load: `steps/step-01-transform.md`

package/templates/skills/derive-prd/steps/step-01-transform.md

@@ -0,0 +1,206 @@
+---
+name: step-01-transform
+description: Build handoff data per module - 8 categories with all gap fixes
+model: sonnet
+next_step: steps/step-02-export.md
+---
+
+> **Context files:** `references/handoff-file-templates.md` | `references/handoff-mappings.md` | `references/handoff-seeddata-generation.md` | `references/entity-domain-mapping.md`
+
+# Step 01: Transform (Handoff Data Generation)
+
+## MANDATORY EXECUTION RULES
+
+- **ALWAYS** process modules in topological order (dependencies first)
+- **ALWAYS** map to 8 categories (including "documentation")
+- **ALWAYS** propagate personRoleConfig verbatim from analysis.entities[]
+- **ALWAYS** separate seedData into core/business categories
+- **ALWAYS** map entity to domain file path (1:1)
+- **ALWAYS** include dependencies[] per file entry
+- **NEVER** invent entities/FRs/BRs not in module JSON files
+- **ALL** API routes from specification.apiEndpoints (exact copy)
+
+## YOUR TASK
+
+For each module in topological order, build the complete handoff data with 8 file categories, BR-to-code mapping, API endpoint summary, and write to feature.json via ba-writer.
+
+---
+
+## EXECUTION SEQUENCE
+
+For **EACH module** in topological order:
+
+### 1. Calculate Complexity
+
+```json
+{
+  "complexity": "simple|medium|complex",
+  "complexityDetails": {
+    "entities": {count},
+    "useCases": {count},
+    "businessRules": {count},
+    "calculated": "{level} (entities<=X, UCs<=Y, BRs<=Z)"
+  }
+}
+```
+
+| Criteria | Simple | Medium | Complex |
+|----------|--------|--------|---------|
+| Entities | <=3 | <=6 | >6 |
+| Use Cases | <=5 | <=12 | >12 |
+| Business Rules | <=10 | <=20 | >20 |
+
+**Global complexity** = highest across all modules.
+
+### 2. Map Specification to Files (8 Categories)
+
+> **Reference:** Read `references/handoff-file-templates.md` for complete JSON templates.
+> All backend paths MUST include `{ApplicationName}/` hierarchy.
+
+| Category | Source | Key rules |
+|----------|--------|-----------|
+| **Domain** | `analysis.entities[]` | Entities, ValueObjects, Enums |
+| **Application** | `analysis.useCases[]` | Services, DTOs, Validators |
+| **Infrastructure** | `analysis.entities[]` | EF Configurations, DbSet |
+| **API** | `specification.apiEndpoints[]` | Controllers (exact copy) |
+| **Frontend** | `specification.uiWireframes[]` | Pages, Components, Hooks; split by file (NOT monolithic) |
+| **SeedData** | `specification.seedDataCore` | CORE (2 app-level + per-module) + business |
+| **Tests** | All layers | Unit, Integration, Security tests |
+| **Documentation** | All layers | Technical docs, user guides, API specs (can be empty `[]`) |
+
+**Frontend Task Splitting (MANDATORY):**
+- Each page as separate entry (not bundled mega-task)
+- Include `linkedWireframes[]` + `wireframeAcceptanceCriteria`
+- FK fields: `"fkFields": ["EmployeeId->Employee", "DepartmentId->Department"]`
+- ALL pages use `/ui-components` skill
+- Route wiring: separate entry in `filesToCreate.frontend`
+
+**Route Convention (CRITICAL):**
+- Transform PascalCase module codes to kebab-case in NavigationModule/Section routes
+- Example: `"HumanResources"` -> `"/human-resources"` (NEVER include `/business/` prefix)
+
+**Documentation Category:**
+- Include `doc-data.ts` for documentation data export
+- Include API specification files if applicable
+- Can be empty `[]` if no documentation is planned at this stage
+- Will be populated later by `/documentation` skill after `/ralph-loop`
+
+### 3. Map Business Rules to Code
+
+> **Reference:** Read `references/handoff-mappings.md` — Section "Business Rules to Code Mapping"
+
+For each BR in `analysis.businessRules[]` of EACH module:
+- ruleId, title, module, severity (critical/high/medium/low)
+- implementationPoints: Array of {layer, component, method, implementation} across all layers
+
+### 4. Propagate personRoleConfig (GAP #2 Fix)
+
+For each entity in `analysis.entities[]`:
+- IF entity has `personRoleConfig` property:
+  - Copy verbatim into handoff entity data
+  - Ensures `/apex` and `/ralph-loop` receive person extension configuration
+  - See `references/handoff-mappings.md` — Section "Person Extension Mapping"
+
+### 5. Separate SeedData Core/Business (GAP #3 Fix)
+
+Each seedData entry MUST include a `category` field:
+
+```json
+{
+  "path": "src/Infrastructure/Persistence/Seeding/Data/NavigationApplicationSeedData.cs",
+  "type": "SeedData",
+  "category": "core",
+  "module": "shared"
+}
+```
+
+- `category: "core"` — Navigation, Permissions, Roles (mandatory infrastructure)
+- `category: "business"` — Domain-specific reference/lookup data
+
+> **Reference:** Read `references/handoff-seeddata-generation.md` for complete core seed generation.
+
+### 6. Map Entity to Domain File (GAP #4 Fix)
+
+> **Reference:** Read `references/entity-domain-mapping.md` for complete mapping rules.
+
+1:1 mapping from BA entity to Domain file:
+
+| BA Element | Domain File Path |
+|------------|-----------------|
+| Entity | `src/Domain/Entities/{App}/{Module}/{EntityName}.cs` |
+| ValueObject | `src/Domain/{Module}/ValueObjects/{VOName}.cs` |
+| Enum | `src/Domain/{Module}/Enums/{EnumName}.cs` |
+
+### 7. Add Dependencies per File Entry (GAP #7 Fix)
+
+Each file entry includes `dependencies[]` ordered by layer:
+
+| Layer | Dependencies |
+|-------|-------------|
+| domain | `[]` (no dependencies) |
+| infrastructure | `["domain"]` |
+| application | `["domain"]` |
+| api | `["application"]` |
+| seedData | `["domain", "infrastructure"]` |
+| frontend | `["api"]` |
+| tests | `["domain", "application", "infrastructure", "api"]` |
+| documentation | `[]` |
+
+### 8. API Endpoint Summary
+
+> **ABSOLUTE RULE:** Copy **EXACTLY** from `specification.apiEndpoints[]`. **NEVER** reinvent routes.
+
+For each endpoint: operation, method, route, linkedUC, linkedFR, permissions, requestSchema, responseSchema, errorCodes, module.
+
+### 9. Write Handoff to Feature.json
+
+```
+FOR i = 0 to modules.length-1:
+  1. moduleCode = modules[i].code
+  2. moduleFeature = ba-reader.findFeature(modules[i].featureJsonPath)
+  3. Build handoff payload:
+     - complexity (from step 1)
+     - filesToCreate (full 8-category structure, filtered for this module)
+     - brToCodeMapping (from step 3)
+     - apiEndpointSummary (from step 8)
+     - prdFile: ".ralph/prd-{moduleCode}.json"
+     - totalFiles: count from filesToCreate
+     - totalTasks: estimated from complexity
+     - handedOffAt: ISO timestamp
+  4. Write via ba-writer.enrichModuleHandoff({ moduleFeatureId, handoffData })
+  5. Display: "handoff {i+1}/{N}: {moduleCode} ({fileCount} files)"
+```
+
+### 10. POST-CHECK Per Module (BLOCKING)
+
+For each module, verify:
+
+```javascript
+const handoff = moduleFeature.handoff;
+
+// 1. Handoff not empty
+if (!handoff || Object.keys(handoff).length === 0) {
+  BLOCKING_ERROR("Module {moduleCode}: handoff is empty");
+}
+
+// 2. All 8 categories present
+const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests', 'documentation'];
+const missing = categories.filter(cat => !handoff.filesToCreate[cat]);
+if (missing.length > 0) {
+  BLOCKING_ERROR("Module {moduleCode}: missing categories: " + missing.join(', '));
+}
+
+// 3. BR-to-code mapping non-empty
+if (!handoff.brToCodeMapping || handoff.brToCodeMapping.length === 0) {
+  BLOCKING_ERROR("Module {moduleCode}: brToCodeMapping is empty");
+}
+
+// 4. Display pass
+console.log("POST-CHECK PASS: {moduleCode} — 8 categories, {brCount} BRs mapped");
+```
+
+---
+
+## NEXT STEP
+
+Load: `steps/step-02-export.md`

package/templates/skills/derive-prd/steps/step-02-export.md

@@ -0,0 +1,181 @@
+---
+name: step-02-export
+description: Generate PRD files, verify integrity, output progress tracker and manifest
+model: sonnet
+---
+
+> **Context files:** `references/prd-generation.md` | `templates/tpl-progress.md`
+
+# Step 02: Export (PRD + Verification)
+
+## MANDATORY EXECUTION RULES
+
+- **ALWAYS** generate PRD via `ss derive-prd` CLI command (deterministic, never LLM)
+- **ALWAYS** verify PRD structure: $version=3.0.0, implementation.filesToCreate, 8 categories
+- **ALWAYS** verify file counts match between PRD and handoff
+- **ALWAYS** generate progress.txt from template
+- **ALWAYS** update BA manifest (docs/index.json)
+- **NEVER** skip POST-CHECK validation
+
+## YOUR TASK
+
+For each module, generate PRD files via CLI, verify integrity, create progress tracker, update manifest, and display completion summary.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Generate PRD Files
+
+For EACH module:
+
+```bash
+ss derive-prd --feature {moduleFeaturePath} --output .ralph/prd-{moduleCode}.json
+```
+
+### 2. POST-CHECK PRD (BLOCKING)
+
+> **Reference:** Read `references/prd-generation.md` for complete validation rules.
+
+```javascript
+const prd = readJSON(`.ralph/prd-${moduleCode}.json`);
+const featureHandoff = moduleFeature.handoff.filesToCreate;
+
+// Check 1: Version
+if (prd.$version !== "3.0.0") {
+  BLOCKING_ERROR("PRD version must be 3.0.0, got: " + prd.$version);
+}
+
+// Check 2: filesToCreate under implementation (not root)
+if (prd.filesToCreate && !prd.implementation?.filesToCreate) {
+  BLOCKING_ERROR("prd.json has filesToCreate at ROOT — not from ss derive-prd");
+  STOP;
+}
+
+// Check 3: All 8 categories present
+const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests', 'documentation'];
+const missingCategories = categories.filter(cat => !prd.implementation.filesToCreate[cat]);
+if (missingCategories.length > 0) {
+  BLOCKING_ERROR("Missing categories: " + missingCategories.join(', '));
+}
+
+// Check 4: File counts match
+for (const cat of categories) {
+  const prdCount = prd.implementation.filesToCreate[cat]?.length ?? 0;
+  const featureCount = featureHandoff[cat]?.length ?? 0;
+  if (prdCount !== featureCount) {
+    BLOCKING_ERROR(`${cat}: prd=${prdCount} but feature=${featureCount}`);
+  }
+}
+```
+
+Display verification table showing all 8 categories match between module JSON files and prd.json.
+
+### 3. Generate modules-queue.json (if 2+ modules)
+
+```json
+{
+  "queue": [
+    { "moduleCode": "{code}", "order": 1, "dependencies": [], "complexity": "simple" },
+    { "moduleCode": "{code}", "order": 2, "dependencies": ["{dep}"], "complexity": "medium" }
+  ],
+  "totalModules": {count},
+  "strategy": "topological"
+}
+```
+
+Write to: `.ralph/modules-queue.json`
+
+### 4. Generate progress.txt
+
+> **Template:** Read `templates/tpl-progress.md` for complete structure.
+> **Data source:** Populate with module-specific data from index.json.
+
+- One section per module in topological order
+- CORE SeedData: 5 entries (mandatory)
+- Business SeedData: per module (varies)
+- Hierarchical task structure (module -> layer -> tasks)
+- Each task: checkbox, description, effort, dependencies
+- Summary with totals across all modules
+- Cross-module tasks IF multi-module
+
+Write to: `.ralph/progress.txt`
+
+### 5. Update BA Manifest (docs/index.json)
+
+**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": "{description}",
+      "path": "{app_code}/business-analyse/v{version}/index.json",
+      "updatedAt": "{ISO timestamp}"
+    }
+  ]
+}
+```
+
+**Update logic:**
+
+1. Read existing manifest (or create empty)
+2. **PROJECT MODE:** Add/update project entry + all app entries + all module entries per app
+3. **SINGLE-APP MODE:** Update app entry + module entries for this app
+4. Write manifest back with updated timestamp
+5. Display: "BA manifest updated: docs/index.json ({total} entries)"
+
+### 6. Display Completion Summary
+
+```
+══════════════════════════════════════════════════════════════
+  DERIVE-PRD COMPLETE — {application_name}
+══════════════════════════════════════════════════════════════
+
+Modules: {count} ({names})
+Complexity: {simple|medium|complex}
+Files: {total across all modules}
+Tasks: {total}
+
+Readiness Scores:
+┌──────────────┬────────────┬──────────────┐
+│ Module       │ Blocking   │ Files        │
+├──────────────┼────────────┼──────────────┤
+│ {module1}    │ 100%       │ {count}      │
+│ {module2}    │ 100%       │ {count}      │
+└──────────────┴────────────┴──────────────┘
+
+Artifacts generated:
+  .ralph/prd-{module}.json      — Task breakdown per module
+  .ralph/progress.txt           — Progression tracker
+  .ralph/modules-queue.json     — Module execution order (if multi-module)
+  docs/index.json               — BA manifest (status: handed-off)
+
+[NEXT] Development:
+  1. Run /ralph-loop to begin implementation
+  2. Modules will be processed in topological order
+  3. Each module PRD contains {total_files} files across 8 categories
+
+══════════════════════════════════════════════════════════════
+```
+
+---
+
+## SELF-VERIFICATION (BEFORE COMPLETION)
+
+1. `.ralph/prd-{module}.json` exists for ALL modules (>100 bytes each)
+2. `.ralph/progress.txt` exists (>500 bytes)
+3. `.ralph/modules-queue.json` exists (if 2+ modules)
+4. `docs/index.json` updated with correct entry count and status "handed-off"
+5. All PRD files have $version=3.0.0, implementation.filesToCreate, 8 categories
+6. File counts match between PRD and handoff for all categories
+
+**IF any check fails -> fix before completing.**