@atlashub/smartstack-cli 3.10.0 → 3.12.0

package/templates/skills/business-analyse/steps/step-04c-decide.md

@@ -0,0 +1,186 @@
+---
+name: step-04c-decide
+description: Final client approval, write consolidation, proceed to handoff
+model: opus
+next_step: steps/step-05a-handoff.md
+---
+
+> **Context files:** `_shared.md`
+
+# Step 4c: Decide - Final Approval & Consolidation Write
+
+## MANDATORY EXECUTION RULES
+- Final client approval is BLOCKING before handoff
+- ALWAYS write consolidation section before proceeding
+- ALWAYS update workflow state for resume support
+
+## YOUR TASK
+Obtain final client approval for the complete application specification, write the consolidation section to feature.json, and prepare for handoff.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 8. Final Client Approval (BLOCKING)
+
+Ask via AskUserQuestion:
+```
+question: "La spécification complète de l'application est prête. Validez-vous l'ensemble ?"
+header: "Approbation"
+options:
+  - label: "Approuvé"
+    description: "Passer au handoff pour la phase d'implémentation"
+  - label: "Réviser un module"
+    description: "Retourner à la spécification d'un module spécifique"
+  - label: "Modifier les interactions"
+    description: "Ajuster les interactions cross-module"
+```
+
+IF "Réviser un module":
+  Ask which module → set currentModuleIndex to that module → load step-03a-data.md
+
+IF "Modifier les interactions":
+  Re-enter step-04a-collect.md (sections 2-4)
+
+### 9. Write Consolidation
+
+> **STRUCTURE CARD: consolidation** — Must match `application-schema.json`. Follow this structure exactly.
+
+```
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "consolidation",
+  data: {
+    crossModuleInteractions: [
+      {
+        "fromModule": "Orders",
+        "toModule": "Customers",
+        "interactionType": "FK-reference|event-publish|event-subscribe|shared-lookup|cascade-delete|cascade-update",
+        "description": "Order references customer via FK",
+        "entities": ["Order→Customer"]
+      }
+    ],
+    sharedEntities: [
+      {
+        "entity": "Customer",
+        "ownerModule": "Customers",
+        "referencedBy": ["Orders", "Invoices"],
+        "sharedFields": ["code", "name"]
+      }
+    ],
+    permissionCoherence: {
+      "rolesConsistent": true,
+      "pathFormatConsistent": true,
+      "hierarchyRespected": true,
+      "conflicts": [],
+      "warnings": []
+    },
+    e2eFlows: [
+      {
+        "name": "Order to Invoice",
+        "modules": ["Customers", "Orders", "Invoices"],
+        "steps": [
+          { "module": "Orders", "action": "Create order", "permission": "business.sales.orders.create", "dataFlow": "Customer → Order" }
+        ]
+      }
+    ],
+    globalRiskAssessment: [
+      {
+        "risk": "Cross-module coupling complexity",
+        "category": "coupling|complexity|dependency-chain|security|scope",
+        "severity": "critical|high|medium|low",
+        "mitigation": "Event-driven communication instead of direct FK"
+      }
+    ],
+    semanticChecks: [
+      { "check": "permission-orpheline", "status": "PASS|WARNING|ERROR", "details": "..." },
+      { "check": "uc-sans-fr", "status": "PASS|WARNING|ERROR", "details": "..." },
+      { "check": "wireframe-coverage", "status": "PASS|WARNING|ERROR", "details": "..." }
+    ],
+    decision: {
+      "approved": true,
+      "reason": "All cross-module validations passed",
+      "approvedBy": "Client",
+      "approvedAt": "{ISO timestamp}"
+    }
+  }
+})
+
+ba-writer.updateStatus({feature_id}, "consolidated")
+```
+
+> **STRUCTURE DIFFERENCES FROM OLD FORMAT:**
+> - `crossModuleInteractions` is a FLAT ARRAY (not `{fkReferences, sharedEntities, events}` nested object)
+> - `sharedEntities` is TOP-LEVEL (not nested inside crossModuleInteractions)
+> - `decision` is an OBJECT with `approved`, `reason`, `approvedBy`, `approvedAt` (not `clientApproval` string)
+> - `globalRiskAssessment` is an ARRAY of risk objects (not `{totalEntities: {value, threshold}}`)
+
+Add changelog entry:
+```json
+{
+  "step": "step-04-consolidation",
+  "timestamp": "...",
+  "changes": [
+    "Cross-module interactions: X FK, Y events, Z shared entities",
+    "Permission coherence: validated ({count} paths, {conflicts} conflicts resolved)",
+    "E2E flows: {count} identified",
+    "Global risk: {level}",
+    "Client approval: APPROVED"
+  ]
+}
+```
+
+### 10. Workflow State Save (for resume support)
+
+After consolidation approval, update workflow state to enable resume if context is exhausted during handoff steps:
+
+```
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "metadata.workflow",
+  data: {
+    lastCompletedStep: "step-04-consolidation",
+    readyForHandoff: true
+  }
+})
+```
+
+> **Why:** Steps 05a-05b arrive late in the conversation when context may be near exhaustion.
+> If BA is interrupted during handoff, the user can resume with `/business-analyse` which will
+> detect `lastCompletedStep: "step-04-consolidation"` and resume directly at step-05a.
+
+---
+
+## SINGLE-MODULE MODE
+
+When only 1 module:
+1. Auto-approve (no cross-module concerns)
+2. Write minimal consolidation section
+3. Display: "Module unique - consolidation automatique ✓"
+4. Proceed to step-05a-handoff.md
+
+---
+
+## CONTEXT MANAGEMENT
+
+| Loaded | Not Loaded |
+|--------|------------|
+| _shared.md | Full module feature.json files |
+| consolidation data (from steps 04a-04b) | Questionnaires |
+| Master feature.json | Templates |
+
+---
+
+## SUCCESS CRITERIA
+
+- Client approval obtained (or auto-approved for single module)
+- Consolidation section written to master feature.json
+- Status updated to "consolidated"
+- Workflow state saved for resume support
+- Ready to proceed to handoff phase
+
+---
+
+## NEXT STEP
+
+Load: `./step-05a-handoff.md`

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

@@ -305,6 +305,27 @@ After writing the HTML file, verify:
    fi
    ```
 
+5. **EMBEDDED_ARTIFACTS wireframes must use renamed fields** (`format`/`content`, NOT `mockupFormat`/`mockup`)
+   ```bash
+   # Check that wireframe field rename was applied (mockup → content, mockupFormat → format)
+   if grep -q '"mockupFormat"' "{output_path}/ba-interactive.html"; then
+     BLOCKING_ERROR("EMBEDDED_ARTIFACTS wireframes still use 'mockupFormat' — must rename to 'format'")
+     BLOCKING_ERROR("See references/html-data-mapping.md for correct field mapping")
+   fi
+   if grep -q '"mockup":' "{output_path}/ba-interactive.html" | grep -v '"mockupNotes"'; then
+     # Note: "mockup" in EMBEDDED_ARTIFACTS = wrong, must be "content"
+     BLOCKING_ERROR("EMBEDDED_ARTIFACTS wireframes still use 'mockup' — must rename to 'content'")
+   fi
+   ```
+
+6. **EMBEDDED_ARTIFACTS wireframes must exist for ALL modules** (not empty `{}`)
+   ```bash
+   # Each module should have at least one wireframe with "format" and "content"
+   if ! grep -q '"format"' "{output_path}/ba-interactive.html"; then
+     BLOCKING_ERROR("No wireframe 'format' field found — EMBEDDED_ARTIFACTS wireframes not populated")
+   fi
+   ```
+
 **IF ANY CHECK FAILS → DO NOT PROCEED. Fix the data mapping and regenerate.**
 
 ---

package/templates/skills/business-analyse/steps/step-05c-ralph-readiness.md

@@ -81,47 +81,39 @@ Validating business analysis completeness before development...
    a. Locate expected PRD file: .ralph/prd-{moduleCode}.json
    b. Verify file exists
    c. Read PRD file
-   d. Verify structure (see validation rules below)
+   d. Verify structure (see [references/prd-generation.md](../references/prd-generation.md))
    ```
 
 2. **PRD Structure Validation:**
+
+   Perform the 4 mandatory PRD structure checks:
+   - **Check 1:** Version must be "3.0.0"
+   - **Check 2:** filesToCreate must be under `implementation` (NOT root level)
+   - **Check 3:** All 7 categories present (domain, application, infrastructure, api, frontend, seedData, tests)
+   - **Check 4:** File counts match feature.json handoff counts
+
    ```javascript
-   const prd = readJSON(`.ralph/prd-${moduleCode}.json`);
-
-   // Check 1: Version must be 3.0.0
-   if (prd.$version !== "3.0.0") {
-     BLOCKING_ERROR("PRD version must be 3.0.0, got: " + prd.$version);
-   }
-
-   // Check 2: filesToCreate must be under implementation (NOT root)
-   if (prd.filesToCreate && !prd.implementation?.filesToCreate) {
-     BLOCKING_ERROR("filesToCreate is at ROOT level (wrong structure)");
-     BLOCKING_ERROR("Re-run: ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json");
-   }
-
-   // Check 3: All 7 categories present in implementation.filesToCreate
-   const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests'];
-   const missingCategories = [];
-   for (const cat of categories) {
-     if (!prd.implementation.filesToCreate[cat]) {
-       missingCategories.push(cat);
-     }
-   }
-   if (missingCategories.length > 0) {
-     BLOCKING_ERROR(`Missing categories: ${missingCategories.join(', ')}`);
-   }
-
-   // Check 4: File counts match feature.json handoff
-   const featureHandoff = moduleFeature.handoff.filesToCreate;
-   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 has ${prdCount} files but feature.json has ${featureCount}`);
-     }
-   }
+   const prdErrors = validateAllPRDs(modules);
+
+   IF prdErrors.length > 0:
+     // CONDITIONAL LOAD: Only load PRD reference on validation failure
+     Read references/prd-generation.md
+     Display:
+       - PRD v3.0 structure requirements
+       - Detailed validation logic for failed checks
+       - Common errors & fix commands for each failure
+       - Generation command reference
+
+     BLOCKING ERROR: {prdErrors.length} PRD file(s) invalid
+     → Fix all PRD errors before proceeding
+
+   ELSE:
+     All PRD files valid ✓
+     → Continue to dependency graph validation
    ```
 
+   **Optimization:** The detailed 300-line prd-generation.md is loaded **only when PRD validation fails** (saves ~12,000 tokens on success path).
+
 3. Display PRD validation table:
 
 ```

package/templates/skills/debug/SKILL.md

@@ -10,6 +10,7 @@ $ARGUMENTS
 
 <objective>
 Follow an ultra-deep analysis workflow to identify, understand, and resolve bugs.
+Uses **Agent Teamwork** for parallel investigation with real-time collaboration.
 **ULTRA THINK** at each phase transition.
 </objective>
 
@@ -23,95 +24,194 @@ Follow an ultra-deep analysis workflow to identify, understand, and resolve bugs
 
 <workflow>
 
-## 1. ANALYZE: Deep Log/Error Analysis
+## 1. ANALYZE: Deep Log/Error Analysis (inline)
 
 - Parse the provided log/error message carefully
 - Extract key error patterns, stack traces, and symptoms
 - Identify error types: runtime, compile-time, logic, performance
 - **CRITICAL**: Document exact error context and reproduction steps
+- Determine investigation scope (see decision matrix below)
 
-## 2. EXPLORE: Targeted Codebase Investigation
+### Decision Matrix — Team vs. Inline
 
-Launch **parallel subagents** to search for error-related code:
+| Condition | Action |
+|-----------|--------|
+| Simple error, obvious from stack trace | NO team — investigate inline |
+| Error involves code + data | Team: `code-investigator` + `data-inspector` |
+| Error involves unknown library | Team: `code-investigator` + `doc-researcher` |
+| Complex bug, multiple suspects | Full team: all 3 agents |
+| Performance issue (no error) | `code-investigator` only (profiling inline) |
 
-**Agent 1: Codebase Search** (`explore-codebase`)
+**If team NOT needed** → skip to phase 3 (ULTRA-THINK) with inline investigation.
+**If team needed** → proceed to phase 2.
+
+## 2. EXPLORE: Team Investigation
+
+> **Reference:** Load `references/team-protocol.md` for full protocol details.
+
+### 2.1 Create Team
+
+```yaml
+TeamCreate:
+  team_name: "debug-investigate"
+  description: "Parallel bug investigation"
+```
+
+### 2.2 Spawn Teammates (single message, parallel Task calls)
+
+Spawn all relevant teammates simultaneously:
+
+**code-investigator** (`general-purpose`, haiku)
 ```
-Find code related to this error: {error_description}
-Search for:
-- Error source location from stack trace
-- Related error handling patterns
-- Similar code that works correctly
-Report file paths with line numbers.
+You are a code investigator on the debug team.
+
+## Bug Context
+Error: {error_description}
+Stack trace: {stack_trace}
+
+## Mission
+1. Locate the error source in code (from stack trace)
+2. Find related error handling patterns
+3. Identify similar code that works correctly (for comparison)
+4. Check recent commits on affected files (git log, git blame)
+5. Search for similar error patterns elsewhere in codebase
+
+## Communication
+- Send FINDING messages to team-lead for each significant discovery:
+  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description with file:line}", summary: "Found {short}")
+- When done:
+  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "Code investigation done")
+- If team-lead sends a LEAD_HINT, follow that direction
+
+## Rules
+- Bash ONLY for: git log, git blame, git diff (NEVER modify code)
+- Report file paths with line numbers
+- Be precise and factual
 ```
 
-**Agent 2: Documentation** (`explore-docs`)
+**doc-researcher** (`general-purpose`, haiku)
 ```
-Research documentation for: {libraries_in_stacktrace}
-Find:
-- Known issues or breaking changes
-- Correct usage patterns
-- Migration guides if version issues
+You are a documentation researcher on the debug team.
+
+## Bug Context
+Error: {error_description}
+Libraries: {libraries_in_stacktrace}
+
+## Mission
+1. Research documentation for libraries in the stack trace
+2. Find known issues or breaking changes
+3. Find correct usage patterns
+4. Search for similar issues reported online
+5. Look for migration guides if version issues suspected
+
+## Communication
+- Send FINDING messages to team-lead for each discovery:
+  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Found {short}")
+- When done:
+  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "Doc research done")
+- If team-lead sends a LEAD_HINT, follow that direction
 ```
 
-**Agent 3: Web Research** (`websearch`)
+**data-inspector** (`general-purpose`, haiku) — *only if bug involves data/persistence/DB*
 ```
-Search for: {error_message}
-Find:
-- Similar issues reported by others
-- Solutions and workarounds
-- Root cause explanations
+You are a READ-ONLY database inspector on the debug team.
+
+## Bug Context
+Error: {error_description}
+
+## ABSOLUTE RESTRICTIONS
+YOU MUST NEVER EXECUTE: INSERT, UPDATE, DELETE, MERGE, TRUNCATE, DROP, ALTER, CREATE, EXEC, dotnet ef database update, dotnet ef migrations
+YOU MAY ONLY EXECUTE: SELECT, INFORMATION_SCHEMA, sys.* views, sp_help
+
+## Mission
+1. Find connection string (appsettings.json, appsettings.Development.json)
+2. Check record existence and field values for affected entities
+3. Verify FK integrity (orphaned records)
+4. Check tenant isolation (TenantId on all records)
+5. Verify soft delete and audit field consistency
+6. Compare schema vs expected EF Core model
+
+## Communication
+- Send FINDING messages to team-lead for each data anomaly:
+  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Data issue {short}")
+- When done:
+  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "DB inspection done")
+- If team-lead sends a LEAD_HINT, follow that direction
+
+## Rules
+- Bash ONLY for SELECT queries (NEVER modify data)
+- If a fix is needed, DESCRIBE it — NEVER execute it
+- Mask sensitive data (passwords, tokens, PII)
+- Limit results with TOP/LIMIT
 ```
 
-Additional investigation:
-- Search for similar error patterns in codebase using Grep
-- Find all files related to the failing component/module
-- Examine recent changes that might have introduced the bug
-- **ULTRA THINK**: Connect error symptoms to potential root causes
+### 2.3 Orchestrate — Lead Actions During Investigation
 
-## 3. ULTRA-THINK: Deep Root Cause Analysis
+While teammates investigate in parallel:
 
-**THINK DEEPLY** about the error chain: symptoms -> immediate cause -> root cause
+- **Monitor** incoming `FINDING` messages from agents
+- **Cross-reference** findings between agents (code ↔ data ↔ docs)
+- **Send `LEAD_HINT`** when one agent's finding informs another:
+  ```yaml
+  SendMessage:
+    type: "message"
+    recipient: "data-inspector"
+    content: "LEAD_HINT: code-investigator found null FK at OrderService.cs:45 — check if Customer records exist for affected OrderIds"
+    summary: "Investigate FK from code finding"
+  ```
+- **Additional inline investigation**: Grep for error patterns, check related files, examine recent commits
 
-Consider all possible causes:
+### 2.4 Aggregate & Shutdown
+
+Wait for all `INVESTIGATION_COMPLETE` messages, then:
+
+1. Collect all `FINDING` messages from each agent
+2. Cross-reference: code issues ↔ data anomalies ↔ documentation
+3. Shutdown teammates:
+   ```yaml
+   SendMessage:
+     type: "shutdown_request"
+     recipient: "{each-teammate}"
+     content: "Investigation complete"
+   # Wait for shutdown_response, then:
+   TeamDelete
+   ```
+
+## 3. ULTRA-THINK: Deep Root Cause Analysis (inline)
+
+**THINK DEEPLY** about the error chain: symptoms → immediate cause → root cause
+
+Aggregate all team findings and consider:
 - Code logic errors
 - Configuration issues
+- Data integrity problems (from data-inspector findings)
 - Environment problems
 - Race conditions
 - Memory issues
 - Network problems
 
 **CRITICAL**: Map the complete failure path from root cause to visible symptom
-Validate hypotheses against the evidence
+Validate hypotheses against evidence from ALL agents
 
 ### WHY Technique
 
 Ask "why" at least 5 times:
-1. Why did the error occur? -> X happened
-2. Why did X happen? -> Y was in invalid state
-3. Why was Y invalid? -> Z didn't initialize properly
-4. Why didn't Z initialize? -> A dependency was missing
-5. Why was dependency missing? -> Configuration error
-
-## 4. RESEARCH: Solution Investigation
+1. Why did the error occur? → X happened
+2. Why did X happen? → Y was in invalid state
+3. Why was Y invalid? → Z didn't initialize properly
+4. Why didn't Z initialize? → A dependency was missing
+5. Why was dependency missing? → Configuration error
 
-Launch **parallel subagents** for solution research:
+## 4. RESEARCH: Solution Investigation (inline or websearch)
 
-**Agent: Solution Search** (`websearch`)
-```
-Search for solutions to: {root_cause}
-Find:
-- Recommended fixes
-- Best practices
-- Workarounds if fix is complex
-```
+If root cause needs further research:
 
-Evaluate solutions:
-- Search for similar issues and solutions online
+- Use `WebSearch` inline for targeted solution search
 - Check documentation for affected libraries/frameworks
 - Look for known bugs, workarounds, and best practices
 - **THINK**: Evaluate solution approaches for this specific context
 
-## 5. IMPLEMENT: Systematic Resolution
+## 5. IMPLEMENT: Systematic Resolution (inline, lead only)
 
 - Choose the most appropriate solution based on analysis
 - Follow existing codebase patterns and conventions
@@ -119,7 +219,7 @@ Evaluate solutions:
 - **STAY IN SCOPE**: Fix only what's needed for this specific bug
 - Add defensive programming where appropriate
 
-## 6. VERIFY: Comprehensive Testing
+## 6. VERIFY: Comprehensive Testing (inline)
 
 - Test the specific scenario that was failing
 - Run related tests to ensure no regressions
@@ -146,17 +246,19 @@ Evaluate solutions:
 - Consider environmental factors
 - Check for timing/concurrency issues
 - Validate assumptions about data/state
+- Cross-reference team findings (code ↔ data ↔ docs)
 
 </analysis_techniques>
 
 <execution_rules>
 
 - **ULTRA THINK** at each phase transition
-- Use parallel agents for comprehensive investigation
+- Use **Agent Teamwork** for parallel investigation (see decision matrix)
 - Document findings and reasoning at each step
-- **NEVER guess** - validate all hypotheses with evidence
+- **NEVER guess** — validate all hypotheses with evidence
 - **MINIMAL CHANGES**: Fix root cause, not symptoms
 - Test thoroughly before declaring resolution complete
+- **ALWAYS cleanup**: shutdown teammates + TeamDelete after investigation
 
 </execution_rules>
 
@@ -169,4 +271,5 @@ Understanding > Speed > Completeness. Every bug must be fully understood before
 - Fix implemented with minimal, targeted changes
 - Original error no longer reproducible
 - Related tests pass without regressions
+- Team properly shut down (no orphan agents)
 </success_criteria>