@atlashub/smartstack-cli 3.8.0 → 3.10.0

package/templates/skills/business-analyse/steps/step-06-review.md

@@ -0,0 +1,277 @@
+---
+name: step-06-review
+description: Apply review corrections from ba-review.json, create new version, regenerate all artifacts
+model: opus
+---
+
+> **Context files:** `_shared.md`, `references/review-data-mapping.md`, `references/html-data-mapping.md`
+
+# Step 06: Apply Review Corrections
+
+Apply corrections exported from the interactive HTML review (`ba-review.json`) to create a new version of the business analysis with all downstream artifacts regenerated.
+
+## Prerequisites
+
+- `workflow_type = "review"` (set by step-00)
+- `review_json_path` points to a valid `ba-review.json` file
+- `application_name` and `docs_dir` are set
+
+## Flow
+
+1. Read and validate ba-review.json
+2. Read existing master feature.json
+3. Create new version
+4. Apply cadrage corrections (reverse mapping)
+5. Apply module corrections
+6. Apply consolidation corrections
+7. Preserve review comments
+8. Regenerate PRD
+9. Regenerate progress.txt
+10. Update manifest
+11. Regenerate HTML
+12. Display completion summary
+
+---
+
+## Step 1: Read and Validate ba-review.json
+
+```
+1. Read file at {review_json_path}
+2. Parse JSON
+3. Validate required structure:
+   - _reviewMeta: { sourceVersion, sourceApplicationId, exportedAt }
+   - metadata: { applicationId, version }
+   - cadrage: { ... }
+   - modules: [ ... ]
+   - moduleSpecifications: { ... }
+4. If validation fails → display error with missing fields, STOP
+5. Display: "Review file valid: {_reviewMeta.changeSummary}"
+```
+
+**Store:**
+```yaml
+review_data: parsed ba-review.json object
+source_version: _reviewMeta.sourceVersion
+change_summary: _reviewMeta.changeSummary
+```
+
+## Step 2: Read Existing Master Feature.json
+
+```
+1. Locate master feature.json from docs_dir
+2. Read and parse
+3. Verify metadata.application matches _reviewMeta.sourceApplicationId
+4. Store as existing_master
+```
+
+## Step 3: Create New Version
+
+Determine version bump based on changes:
+
+```
+IF change_summary.modulesAdded.length > 0 OR change_summary.modulesRemoved.length > 0:
+  version_type = "major"  (v1.0 → v2.0)
+ELSE:
+  version_type = "minor"  (v1.0 → v1.1)
+
+Call ba-writer.createVersion(existing_master.id, "Review corrections applied from v{source_version}")
+```
+
+**Store:**
+```yaml
+new_version: string (e.g., "1.1" or "2.0")
+new_docs_dir: path to new version directory
+new_master_path: path to new master feature.json
+```
+
+## Step 4: Apply Cadrage Corrections
+
+> **Reference:** `references/review-data-mapping.md` for exact field mapping
+
+Read the new master feature.json and apply reverse mapping from review data:
+
+```
+1. Scope mapping (review → feature.json):
+   - cadrage.scope.vital[] → cadrage.globalScope.mustHave[]
+   - cadrage.scope.important[] → cadrage.globalScope.shouldHave[]
+   - cadrage.scope.optional[] → cadrage.globalScope.couldHave[]
+   - cadrage.scope.excluded[] → cadrage.globalScope.outOfScope[]
+   (Extract name from {name, description} objects)
+
+2. Stakeholders mapping:
+   - For each review stakeholder:
+     - role → role (preserved)
+     - function → function
+     - tasks → tasks
+     - access → involvement (reverse: admin→decision-maker, manager→consulted, contributor→end-user, viewer→informed)
+     - frequency → frequency (reverse: daily→Quotidien, weekly→Hebdomadaire, monthly→Mensuel, occasional→Occasionnel)
+     - frustrations → painPoints (split by newline)
+
+3. Problem/Vision mapping:
+   - cadrage.problem.description → cadrage.problem
+   - cadrage.problem.trigger → cadrage.trigger
+   - cadrage.vision.changes → cadrage.toBe
+   - cadrage.current.tools → cadrage.asIs
+
+4. Risks mapping:
+   - For each review risk → cadrage.risks[] (direct mapping, generate RISK-NNN IDs if missing)
+
+5. Acceptance criteria:
+   - cadrage.success.definition → cadrage.acceptanceCriteria[] (split by newline, generate AC-NNN IDs)
+
+Call ba-writer.enrichSection(new_master.id, "cadrage", updated_cadrage)
+```
+
+## Step 5: Apply Module Corrections
+
+```
+FOR EACH moduleCode in review_data.moduleSpecifications:
+  1. Check if module exists in current master.modules[]
+     - If NEW module (in change_summary.modulesAdded):
+       a. Add to master.modules[] with metadata from review
+       b. Create module directory and feature.json via ba-writer.create(scope:"module")
+     - If REMOVED module (in change_summary.modulesRemoved):
+       a. Mark module status as "removed" in master (do NOT delete files)
+     - If EXISTING module:
+       a. Read module feature.json
+
+  2. Reverse-map module specification data:
+     - review.useCases[] → specification.useCases[]
+       (name→name, actor→primaryActor, steps→mainScenario (split by \n), alternative→alternativeScenarios)
+     - review.businessRules[] → analysis.businessRules[]
+       (name→name, category→category, statement→statement, example→examples[])
+     - review.entities[] → analysis.entities[]
+       (name→name, description→description, attributes→attributes, relationships→relationships)
+     - review.permissions[] → specification.permissionMatrix
+       (reverse "Role|Action" format → {permissions[], roleAssignments[]})
+
+  3. Write updated module feature.json via ba-writer.enrichSection()
+```
+
+## Step 6: Apply Consolidation Corrections
+
+```
+IF review_data.consolidation exists:
+  1. Reverse-map interactions:
+     - consolidation.interactions[] → consolidation.crossModuleInteractions[]
+       (from→fromModule, to→toModule, description→description)
+
+  2. Reverse-map E2E flows:
+     - consolidation.e2eFlows[] → consolidation.e2eFlows[]
+       (name→name, steps→steps, actors preserved)
+
+  Call ba-writer.enrichSection(new_master.id, "consolidation", updated_consolidation)
+```
+
+## Step 7: Preserve Review Comments
+
+Store all review feedback in a new `review` section of the master feature.json:
+
+```
+review_section = {
+  appliedAt: new Date().toISOString(),
+  sourceVersion: source_version,
+  comments: review_data.comments || [],          // inline structured comments
+  specComments: review_data.specComments || {},   // textarea comments per spec item
+  wireframeComments: review_data.wireframeComments || {},  // wireframe feedback
+  changeSummary: change_summary
+}
+
+Call ba-writer.enrichSection(new_master.id, "review", review_section)
+```
+
+## Step 8: Regenerate PRD
+
+```
+FOR EACH module in master.modules[] WHERE status != "removed":
+  Run: ss derive-prd --application {new_master_path} --module {moduleCode}
+  Verify: .ralph/prd-{moduleCode}.json exists and has filesToCreate
+```
+
+> `ss derive-prd` is a deterministic CLI command (no LLM), safe for regeneration.
+
+## Step 9: Regenerate progress.txt
+
+```
+Write .ralph/progress.txt with:
+- Link to new master feature.json
+- Link to each module feature.json
+- Link to ba-interactive.html (new version)
+- Summary of review changes applied
+```
+
+## Step 10: Update Manifest
+
+```
+1. Read docs/business/index.json
+2. Find entry for this application
+3. Update version, lastModified, status
+4. If entry doesn't exist, create it
+5. Write docs/business/index.json
+```
+
+## Step 11: Regenerate Interactive HTML
+
+> **Reference:** `references/html-data-mapping.md` for FEATURE_DATA and EMBEDDED_ARTIFACTS mapping
+
+```
+1. Read ba-interactive.html template from skill templates
+2. Build FEATURE_DATA from NEW master + module feature.json files
+   (follow exact mapping from html-data-mapping.md)
+3. Build EMBEDDED_ARTIFACTS from NEW module feature.json files
+   (wireframes, e2eFlows, dependencyGraph)
+4. Replace placeholders:
+   - {{FEATURE_DATA}} → serialized FEATURE_DATA JSON
+   - {{EMBEDDED_ARTIFACTS}} → serialized EMBEDDED_ARTIFACTS JSON
+   - {{APPLICATION_NAME}} → application_name
+   - {{APPLICATION_ID}} → feature_id
+5. Write to new version directory: {new_docs_dir}/ba-interactive.html
+```
+
+## Step 12: Display Completion Summary
+
+```
+═══════════════════════════════════════════════════════════════
+  REVIEW CORRECTIONS APPLIED SUCCESSFULLY
+═══════════════════════════════════════════════════════════════
+
+| Field                | Value                                |
+|----------------------|--------------------------------------|
+| Application          | {application_name}                   |
+| Previous version     | v{source_version}                    |
+| New version          | v{new_version}                       |
+| Version type         | {major/minor}                        |
+
+Changes applied:
+| Change               | Count                                |
+|----------------------|--------------------------------------|
+| Cadrage modified     | {yes/no}                             |
+| Modules added        | {count} ({list})                     |
+| Modules removed      | {count} ({list})                     |
+| Modules modified     | {count} ({list})                     |
+| Comments preserved   | {count}                              |
+
+Artifacts regenerated:
+| Artifact             | Path                                 |
+|----------------------|--------------------------------------|
+| Master feature.json  | {new_master_path}                    |
+| ba-interactive.html  | {new_docs_dir}/ba-interactive.html   |
+| PRD files            | .ralph/prd-*.json                    |
+| progress.txt         | .ralph/progress.txt                  |
+| Manifest             | docs/business/index.json             |
+
+NEXT STEPS:
+1. Open the new ba-interactive.html to verify corrections
+2. Run /ralph-loop -r to start development from the updated analysis
+═══════════════════════════════════════════════════════════════
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| ba-review.json malformed | Display structure errors, STOP |
+| Source version mismatch | Warn but continue (corrections may still apply) |
+| Module not found for update | Skip module, warn user |
+| PRD generation fails | Warn but continue (can be re-run manually) |
+| Manifest update fails | Warn but continue |

package/templates/skills/cc-agent/references/agent-behavior-patterns.md

@@ -0,0 +1,95 @@
+# Agent Behavior Pattern Templates
+
+> Referenced from `steps/step-02-generate.md` — System prompt templates for each agent behavior pattern.
+
+---
+
+## Explorer Pattern
+
+```markdown
+You are a specialized exploration agent for {purpose}.
+
+## Workflow
+
+1. **Search**: Use Grep and Glob to find relevant files
+2. **Read**: Load and analyze discovered files
+3. **Analyze**: Identify patterns, dependencies, and relationships
+4. **Report**: Present findings in structured format
+
+## Execution Rules
+
+- Run independent searches in parallel
+- Always cite file paths and line numbers
+- Focus only on what's relevant to the request
+- Present findings as tables or structured lists
+
+## Output Format
+
+List findings with file references:
+```
+- path/to/file.ext:line - Description of finding
+```
+```
+
+---
+
+## Modifier Pattern
+
+```markdown
+You are a code modification specialist for {purpose}.
+
+## Workflow
+
+1. **Read**: Load all specified files with Read tool
+2. **Analyze**: Understand current structure and patterns
+3. **Edit**: Apply requested changes using Edit tool
+4. **Validate**: Verify changes are correct
+5. **Report**: List what was modified
+
+## Execution Rules
+
+- Follow existing code style exactly
+- Preserve all formatting and indentation
+- Make minimal changes to achieve the goal
+- Never add comments unless requested
+
+## Output Format
+
+```
+- path/to/file.ext: [Description of change]
+```
+```
+
+---
+
+## Validator Pattern
+
+```markdown
+You are a validation specialist for {purpose}.
+
+## Workflow
+
+1. **Scan**: Find all files to validate
+2. **Check**: Apply validation rules to each file
+3. **Report**: Present issues with severity and recommendations
+
+## Execution Rules
+
+- Check ALL files in scope, not just a sample
+- Every issue must have a clear recommendation
+- Use severity levels: ERROR, WARN, INFO
+- Present results as tables
+
+## Output Format
+
+| File | Severity | Issue | Recommendation |
+|------|----------|-------|----------------|
+| path | ERROR | ... | ... |
+```
+
+---
+
+## Custom Pattern
+
+Use the user's description from Step 1 to generate appropriate sections.
+Include Workflow, Execution Rules, and Output Format sections tailored to the specific purpose.

package/templates/skills/cc-agent/steps/step-02-generate.md

@@ -79,84 +79,11 @@ Close frontmatter:
 
 Based on the behavior pattern chosen in Step 1:
 
-**Explorer pattern:**
-```markdown
-You are a specialized exploration agent for {purpose}.
-
-## Workflow
-
-1. **Search**: Use Grep and Glob to find relevant files
-2. **Read**: Load and analyze discovered files
-3. **Analyze**: Identify patterns, dependencies, and relationships
-4. **Report**: Present findings in structured format
-
-## Execution Rules
-
-- Run independent searches in parallel
-- Always cite file paths and line numbers
-- Focus only on what's relevant to the request
-- Present findings as tables or structured lists
-
-## Output Format
-
-List findings with file references:
-```
-- path/to/file.ext:line - Description of finding
-```
-```
-
-**Modifier pattern:**
-```markdown
-You are a code modification specialist for {purpose}.
-
-## Workflow
-
-1. **Read**: Load all specified files with Read tool
-2. **Analyze**: Understand current structure and patterns
-3. **Edit**: Apply requested changes using Edit tool
-4. **Validate**: Verify changes are correct
-5. **Report**: List what was modified
-
-## Execution Rules
-
-- Follow existing code style exactly
-- Preserve all formatting and indentation
-- Make minimal changes to achieve the goal
-- Never add comments unless requested
-
-## Output Format
-
-```
-- path/to/file.ext: [Description of change]
-```
-```
-
-**Validator pattern:**
-```markdown
-You are a validation specialist for {purpose}.
-
-## Workflow
-
-1. **Scan**: Find all files to validate
-2. **Check**: Apply validation rules to each file
-3. **Report**: Present issues with severity and recommendations
-
-## Execution Rules
-
-- Check ALL files in scope, not just a sample
-- Every issue must have a clear recommendation
-- Use severity levels: ERROR, WARN, INFO
-- Present results as tables
-
-## Output Format
-
-| File | Severity | Issue | Recommendation |
-|------|----------|-------|----------------|
-| path | ERROR | ... | ... |
-```
-
-**Custom pattern:**
-Use the user's description from Step 1 to generate appropriate sections.
+See [references/agent-behavior-patterns.md](../references/agent-behavior-patterns.md) for the 4 behavior pattern templates:
+- **Explorer**: Search → Read → Analyze → Report (with file references)
+- **Modifier**: Read → Analyze → Edit → Validate → Report
+- **Validator**: Scan → Check → Report (with severity table: ERROR/WARN/INFO)
+- **Custom**: User-driven from Step 1 description
 
 ### 5. Write Agent File
 

package/templates/skills/check-version/SKILL.md

@@ -187,3 +187,10 @@ If mismatches detected during release finish:
 | 1 | Mismatches detected (blocking for releases) |
 
 </exit_codes>
+
+<success_criteria>
+- All version references compared against package.json version
+- Mismatches clearly listed with file path and current vs expected values
+- Exit code 0 when aligned, exit code 1 when mismatched
+- Fix subcommand updates all references successfully
+</success_criteria>

package/templates/skills/controller/references/controller-code-templates.md

@@ -0,0 +1,159 @@
+# Controller & DTO Code Templates
+
+> Referenced from `steps/step-03-generate.md` — C# templates for controller, DTOs, and security patterns.
+
+---
+
+## Controller Template
+
+**Target path:** `src/SmartStack.Api/Controllers/{ContextShort}/{Application}/{entity}Controller.cs`
+
+> Context mapping: `business` → `Business`, `platform` → `Admin`, `personal` → `User`
+
+```csharp
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Http;
+using SmartStack.Application.Common.Authorization;
+using SmartStack.Application.Common.Interfaces;
+using SmartStack.Domain.Entities;
+
+namespace SmartStack.Api.Controllers.{area};
+
+[ApiController]
+[Route("api/{area_lowercase}/[controller]")]
+[Authorize]
+public class {module}Controller : ControllerBase
+{
+    private readonly IApplicationDbContext _context;
+    private readonly ICurrentUserService _currentUser;
+    private readonly ILogger<{module}Controller> _logger;
+
+    public {module}Controller(
+        IApplicationDbContext context,
+        ICurrentUserService currentUser,
+        ILogger<{module}Controller> logger)
+    {
+        _context = context;
+        _currentUser = currentUser;
+        _logger = logger;
+    }
+
+    // Endpoints generated based on plan...
+}
+```
+
+---
+
+## GET Endpoint Example
+
+```csharp
+[HttpGet]
+[RequirePermission(Permissions.{module}.View)]
+[ProducesResponseType(typeof(PagedResult<{entity}ResponseDto>), StatusCodes.Status200OK)]
+[ProducesResponseType(StatusCodes.Status401Unauthorized)]
+[ProducesResponseType(StatusCodes.Status403Forbidden)]
+public async Task<IActionResult> GetAll(
+    [FromQuery] int page = 1,
+    [FromQuery] int pageSize = 20,
+    CancellationToken ct = default)
+{
+    var query = _context.{module}
+        .AsNoTracking()
+        .OrderByDescending(x => x.CreatedAt);
+
+    var total = await query.CountAsync(ct);
+    var items = await query
+        .Skip((page - 1) * pageSize)
+        .Take(pageSize)
+        .Select(x => new {entity}ResponseDto(x))
+        .ToListAsync(ct);
+
+    return Ok(new PagedResult<{entity}ResponseDto>(items, total, page, pageSize));
+}
+```
+
+**Endpoint attributes to include:**
+1. `[HttpGet]`, `[HttpPost]`, etc.
+2. `[RequirePermission(Permissions.{module}.View)]`
+3. `[ProducesResponseType(typeof(...), StatusCodes.Status200OK)]`
+4. `[ProducesResponseType(StatusCodes.Status401Unauthorized)]`
+5. `[ProducesResponseType(StatusCodes.Status403Forbidden)]`
+
+---
+
+## DTO Templates
+
+**Target paths:**
+```
+src/SmartStack.Application/DTOs/{module}/{entity}CreateDto.cs
+src/SmartStack.Application/DTOs/{module}/{entity}UpdateDto.cs
+src/SmartStack.Application/DTOs/{module}/{entity}ResponseDto.cs
+```
+
+**CreateDto:**
+```csharp
+public record {entity}CreateDto(
+    string Name,
+    // ... required properties
+);
+```
+
+**UpdateDto:**
+```csharp
+public record {entity}UpdateDto(
+    string? Name,
+    // ... optional properties
+);
+```
+
+**ResponseDto:**
+```csharp
+public record {entity}ResponseDto(
+    Guid Id,
+    string Name,
+    // ... all public properties
+    DateTime CreatedAt,
+    DateTime? UpdatedAt
+)
+{
+    public {entity}ResponseDto({entity} entity) : this(
+        entity.Id,
+        entity.Name,
+        // ... mapping
+        entity.CreatedAt,
+        entity.UpdatedAt
+    ) { }
+}
+```
+
+---
+
+## Security Logging Templates
+
+```csharp
+// Create
+_logger.LogInformation("User {User} created {entity} {Id}",
+    _currentUser.Email, entity.Id);
+
+// Update
+_logger.LogInformation("User {User} updated {entity} {Id}",
+    _currentUser.Email, entity.Id);
+
+// Delete (Warning level)
+_logger.LogWarning("User {User} deleted {entity} {Id} ({Name})",
+    _currentUser.Email, id, entity.Name);
+```
+
+---
+
+## System Account Protection
+
+```csharp
+// Before modify/delete operations
+if (entity.UserType == UserType.System || entity.UserType == UserType.LocalAdmin)
+{
+    _logger.LogWarning("Attempt to modify system account {Id} by {User}",
+        entity.Id, _currentUser.Email);
+    return BadRequest(new { message = "Cannot modify system accounts" });
+}
+```