@atlashub/smartstack-cli 1.33.0 → 1.35.0

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

@@ -1,25 +1,21 @@
 ---
 name: step-05-handoff
 description: Handoff phase - Generate autonomous development prompt
-model: opus
-prev_step: steps/step-04-validate.md
 next_step: steps/step-06-doc-html.md
 ---
 
-<objective>
-Generate a complete, autonomous development prompt for `/implement`.
+## YOUR TASK:
+
+Generate a complete, autonomous development prompt with Ralph Loop task breakdown for iterative implementation.
 The handoff must be zero-ambiguity: a developer (or Claude) can implement without questions.
-</objective>
 
-<ultrathink>
-ULTRATHINK MODE - Handoff Generation:
-- Every implementation detail must be explicit
-- File paths must be exact
-- Patterns must reference existing code
-- No assumptions about "obvious" behavior
-</ultrathink>
+> **ULTRATHINK MODE:**
+> - Every implementation detail must be explicit
+> - File paths must be exact
+> - Patterns must reference existing code
+> - No assumptions about "obvious" behavior
 
-## EXECUTION SEQUENCE
+## EXECUTION SEQUENCE:
 
 ### 1. Read Current State
 
@@ -29,6 +25,10 @@ Read specs: `{output_dir}/3-functional-specification.md`
 
 Update progress: `05-handoff` -> "In Progress"
 
+**Read digest from previous step:**
+Read `{output_dir}/digest-04.md` for compressed context from previous step.
+**DO NOT read full output files** unless in resume mode (`-r`).
+
 ---
 
 ### 2. Verify Validation Passed
@@ -45,7 +45,7 @@ END IF
 ### 3. Load Handoff Template
 
 ```
-Read: templates/frd-handoff.md    # ~100 lines
+Read: templates/tpl-handoff.md    # ~100 lines
 ```
 
 ---
@@ -217,14 +217,25 @@ For each file, provide explicit instructions:
 > **Module:** business/{application_name}/{module_name}
 > **Version:** 1.0
 > **Validated Specs:** FRD v1.0 (validation.json: APPROVED)
-> **Implementation:** `/implement {feature_id}`
+> **Implementation:** `/ralph-loop -r` (iterative) | `/feature-full business/{application_name}/{module_name}` (one-shot)
 
 ## DEVELOPER INSTRUCTIONS
 
-This document is a standalone prompt for Claude Code. Execute:
+Ce document est un prompt autonome pour Claude Code.
+
+**Option 1 - Itératif (recommandé) :**
 ```
-/implement {feature_id}
+/ralph-loop -r
 ```
+> Le fichier `.ralph/prd.json` a été pré-généré avec le découpage en tâches atomiques.
+> Ralph Loop exécute chaque tâche avec validation MCP entre chaque itération.
+
+**Option 2 - One-shot :**
+```
+/feature-full business/{application_name}/{module_name}
+```
+> Génère l'implémentation full-stack complète en une seule passe
+> (Domain → Application → Infrastructure → API → Web + Notifications + Workflows + AI).
 
 ---
 
@@ -268,19 +279,63 @@ This document is a standalone prompt for Claude Code. Execute:
 - [ ] Permissions in PermissionConfiguration.cs
 - [ ] i18n complete (FR, EN, IT, DE)
 - [ ] Documentation: `/business-analyse:6-doc-html {feature_id}`
+- [ ] Documentation manifest updated: `docs-manifest.json`
 
 ---
 
 ## EXECUTION
 
+**Itératif (recommandé) :**
+```bash
+/ralph-loop -r
+```
+
+**One-shot :**
 ```bash
-/implement {feature_id}
+/feature-full business/{application_name}/{module_name}
 ```
 ```
 
 ---
 
-### 12. Save Output
+### 12. Generate Context Digest
+
+**Write digest to:** `{output_dir}/digest-05.md`
+
+```markdown
+# Digest: Step 05 - Handoff
+
+## Changes
+- {output_dir}/4-development-handoff.md: Handoff document created
+- .ralph/prd.json: Ralph Loop task breakdown created
+- .ralph/progress.txt: Progress file initialized
+
+## Decisions
+- Implementation mode: iterative (Ralph Loop) or one-shot (feature-full)
+- Task count: {tasks_total} atomic tasks
+- Complexity: {Simple/Medium/Complex}
+
+## Findings
+- Backend files to create: {count}
+- Frontend files to create: {count}
+- Test files to create: {count}
+
+## State Updates
+| Variable | New Value |
+|----------|-----------|
+| tasks_total | {count} |
+| ralph_prd_created | true |
+| handoff_ready | true |
+
+## For Next Step
+- Documentation generation ready (step-06)
+- FRD data extraction needed for React components
+- i18n: 4 languages to create
+```
+
+---
+
+### 12a. Save Output
 
 Write to: `{output_dir}/4-development-handoff.md`
 
@@ -289,19 +344,148 @@ Update `00-context.md`:
 
 ---
 
-### 13. Display Summary and Offer Next Step
+### 12b. Generate Ralph Loop Task Breakdown
 
-**Display:**
+**Purpose:** Generate `.ralph/prd.json` and `.ralph/progress.txt` so the implementation can be executed via `/ralph-loop -r`.
+
+#### 12bis.1 Create .ralph/ directory structure
+
+```bash
+mkdir -p .ralph/logs
+mkdir -p .ralph/reports
+```
+
+#### 12bis.2 Derive Task List from Handoff
+
+**ULTRATHINK about task decomposition:**
+- Each task must be atomic (implementable in one Ralph iteration)
+- Tasks follow the SmartStack layer order: Domain → Application → Infrastructure → API → Frontend → Tests → Validation
+- Conditionally include tasks based on feature scope (skip layers not present in the handoff document)
+
+**Conditional Task Generation Rules:**
+
+For each layer, generate tasks ONLY if the handoff document contains specifications for that layer.
+
+```
+LAYER 1 - DOMAIN (if entities defined in handoff section 3/4):
+  Task: "Create {Entity} entity in SmartStack.Domain/Entities/Business/ with properties: {property_list}"
+  Task: "Create {Entity}Status enum if status workflow defined"
+  (One task per entity)
+
+LAYER 2 - APPLICATION (if CQRS handlers defined in handoff section 3/4):
+  Task: "Create CQRS Commands for {Entity}: {Create/Update/Delete}Command + Handler + Validator"
+  Task: "Create CQRS Queries for {Entity}: GetAll{Entity}Query, Get{Entity}ByIdQuery + Handlers"
+  Task: "Create DTOs for {Entity}: {Entity}Dto, Create{Entity}Request, Update{Entity}Request"
+  Task: "Register permissions in Permissions.cs and PermissionConfiguration.cs for business.{app}.{module}"
+
+LAYER 3 - INFRASTRUCTURE (if EF Core config or services in handoff):
+  Task: "Create EF Core configuration for {Entity} with HasData seed and migration"
+  Task: "Register {Entity} DbSet in ApplicationDbContext"
+  Task: "Create {Entity}Service implementing I{Entity}Service with DI registration" (if services needed)
+
+LAYER 4 - API (if endpoints defined in handoff section 8):
+  Task: "Create {Module}Controller with CRUD endpoints: GET, POST, GET/{id}, PUT/{id}, DELETE/{id}"
+
+LAYER 5 - FRONTEND (if frontend files in handoff section 5):
+  Task: "Create {module}Api.ts API service with Axios calls"
+  Task: "Create use{Module}.ts hook with React Query + SignalR"
+  Task: "Create {Module}Page.tsx list page with EntityCard"
+  Task: "Create {Module}Form.tsx create/edit form"
+  Task: "Add routes in App.tsx for business/{app}/{module}"
+
+LAYER 6 - I18N (if i18n keys in handoff section 10):
+  Task: "Create i18n translation files for {module} in 4 languages (fr, en, it, de)"
+
+LAYER 7 - TESTS (always included):
+  Task: "Create unit tests: {Entity}ValidatorTests + {Entity}Tests"
+  Task: "Create integration tests: {Module}ControllerTests with 200, 201, 400, 403, 404 scenarios"
+
+LAYER 8 - VALIDATION (always included):
+  Task: "Run dotnet build, pnpm build, dotnet test - fix any failures"
+  Task: "Run MCP validate_conventions to verify all naming conventions"
+```
+
+**Sizing rules:**
+- Simple feature (1 entity, CRUD only): ~8-12 tasks
+- Medium feature (2-3 entities, business rules): ~15-20 tasks
+- Complex feature (multiple entities, integrations): ~20-30 tasks
+
+#### 12bis.3 Write prd.json
+
+Write to: `.ralph/prd.json`
+
+```json
+{
+  "feature": "{feature_id} - {feature_description}",
+  "created": "{ISO 8601 timestamp}",
+  "max_iterations": 30,
+  "completion_promise": "IMPLEMENTATION COMPLETE",
+  "current_iteration": 1,
+  "source": "{output_dir}/4-development-handoff.md",
+  "tasks": [
+    { "id": 1, "description": "...", "passes": false },
+    { "id": 2, "description": "...", "passes": false }
+  ]
+}
 ```
-HANDOFF - {feature_id}
-├── Status: Complete
-├── Files to create: {file count}
-├── Tests to write: {test count}
-├── Output: {output_dir}/4-development-handoff.md
-├── Execute: /implement {feature_id}
-└── Optional: step-06-doc-html (React documentation)
+
+> **Note:** The `source` field links back to the handoff document for reference. It is not read by Ralph's execution engine and is backward-compatible.
+
+#### 12bis.4 Initialize progress.txt
+
+Write to: `.ralph/progress.txt`
+
+```markdown
+# Ralph Loop Progress
+
+## Task: {feature_id} - {feature_description}
+## Source: {output_dir}/4-development-handoff.md
+## Started: {timestamp}
+## Generated by: Business Analysis skill (step-05-handoff)
+
+---
+
+## Handoff Reference
+
+The detailed specifications for this implementation are in:
+- **Handoff document:** `{output_dir}/4-development-handoff.md`
+- **Functional Specification:** `{output_dir}/3-functional-specification.md`
+- **Business Requirements:** `{output_dir}/2-business-requirements.md`
+- **Validation:** `{output_dir}/validation.json`
+
+Consult these documents for entity properties, business rules, API endpoints, and test requirements.
+
+---
+
+## Iteration 1
+
+### Context
+Starting fresh implementation from BA handoff.
+Task breakdown generated from business analysis with {tasks_total} tasks.
+
+### Learnings
+(To be updated after each iteration)
 ```
 
+---
+
+### 12c. Display Summary and Offer Next Step
+
+**Display:**
+
+| Field | Value |
+|-------|-------|
+| Step | HANDOFF |
+| Feature | {feature_id} |
+| Status | Complete |
+| Files to create | {file count} |
+| Tests to write | {test count} |
+| Output | {output_dir}/4-development-handoff.md |
+| Ralph Loop | .ralph/prd.json ({tasks_total} tasks) |
+| Execute (iterative) | /ralph-loop -r |
+| Execute (one-shot) | /feature-full business/{application_name}/{module_name} |
+| Optional | step-06-doc-html (React documentation) |
+
 **Ask user:**
 ```json
 {
@@ -310,9 +494,10 @@ HANDOFF - {feature_id}
       "question": "What would you like to do now?",
       "header": "Next",
       "options": [
-        {"label": "Generate HTML documentation", "description": "Create the React documentation page"},
-        {"label": "Launch implementation", "description": "Execute /implement {feature_id}"},
-        {"label": "End BA", "description": "Stop here, implement later"}
+        {"label": "Ralph Loop (itératif)", "description": "Exécuter /ralph-loop -r — recommandé pour les features complexes ({tasks_total} tâches atomiques)"},
+        {"label": "Feature Full (one-shot)", "description": "Exécuter /feature-full business/{application_name}/{module_name} — pour les features simples"},
+        {"label": "Generate HTML documentation", "description": "Créer la page de documentation React d'abord"},
+        {"label": "End BA", "description": "Terminer ici, implémenter plus tard"}
       ],
       "multiSelect": false
     }
@@ -320,17 +505,55 @@ HANDOFF - {feature_id}
 }
 ```
 
+If "Ralph Loop (itératif)":
+```
+DISPLAY: "Execute: /ralph-loop -r"
+DISPLAY: "Le prd.json a été pré-généré avec {tasks_total} tâches."
+```
+
+If "Feature Full (one-shot)":
+```
+DISPLAY: "Execute: /feature-full business/{application_name}/{module_name}"
+```
+
 If "Generate HTML documentation":
 ```
 Read and execute: steps/step-06-doc-html.md
 ```
 
+If "End BA":
+```
+DISPLAY: "BA terminé. Pour implémenter plus tard :"
+DISPLAY: "  Itératif : /ralph-loop -r"
+DISPLAY: "  One-shot : /feature-full business/{application_name}/{module_name}"
+```
+
 ---
 
-## OUTPUT
+## OUTPUT FORMAT:
 
 This step produces:
 - `{output_dir}/4-development-handoff.md` (created)
 - `{output_dir}/00-context.md` (updated)
+- `.ralph/prd.json` (created - Ralph Loop task breakdown)
+- `.ralph/progress.txt` (created - with BA references)
+
+Handoff is ready for:
+- **Iterative:** `/ralph-loop -r`
+- **One-shot:** `/feature-full business/{application_name}/{module_name}`
+
+## ERROR HANDLING:
+
+**If pattern exploration fails:**
+1. Use minimal handoff template without code references
+2. Mark as "Patterns not validated - manual review required"
+3. Reduce task count in prd.json (simpler breakdown)
+
+**If .ralph/ directory already exists:**
+1. Warn user: "Existing Ralph Loop data found"
+2. Ask: "Overwrite / Append / Cancel"
+3. If append: add new tasks after existing ones
+
+## NEXT STEP:
 
-Handoff is ready for `/implement {feature_id}`.
+After completion, proceed to `steps/step-06-doc-html.md`

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

@@ -1,15 +1,13 @@
 ---
 name: step-06-doc-html
 description: Documentation phase - Generate React documentation page
-model: sonnet
-prev_step: steps/step-05-handoff.md
 next_step: null
 ---
 
-<objective>
+## YOUR TASK:
+
 Generate React documentation page integrated into SmartStack web app.
 Create i18n translations in 4 languages (FR, EN, IT, DE).
-</objective>
 
 <context7>
 CONTEXT7 REQUIRED for React generation:
@@ -26,7 +24,7 @@ Libraries to reference:
 - /lucide-icons/lucide-react - Icons
 </context7>
 
-## EXECUTION SEQUENCE
+## EXECUTION SEQUENCE:
 
 ### 1. Read Current State
 
@@ -35,6 +33,10 @@ Read FRD: `{output_dir}/3-functional-specification.md`
 
 Update progress: `06-doc-html` -> "In Progress"
 
+**Read digest from previous step:**
+Read `{output_dir}/digest-05.md` for compressed context from previous step.
+**DO NOT read full output files** unless in resume mode (`-r`).
+
 ---
 
 ### 2. Load React Templates (Progressive)
@@ -223,39 +225,96 @@ Update `00-context.md`:
 
 ### 9. Display Final Summary
 
-```
-DOCUMENTATION - {feature_id}
-├── Status: Complete
-├── React page: FrdDocPage.tsx
-├── i18n: 4 languages created
-├── Route: /docs/business/{app}/{module}
-└── BA WORKFLOW COMPLETE
-
-Summary:
-├── Discovery: {output_dir}/1-discovery.md
-├── BRD: {output_dir}/2-business-requirements.md
-├── FRD: {output_dir}/3-functional-specification.md
-├── Validation: {output_dir}/validation.json (APPROVED)
-├── Handoff: {output_dir}/4-development-handoff.md
-└── Documentation: web/.../FrdDocPage.tsx
-
-Next steps:
+**Step Summary:**
+
+| Field | Value |
+|-------|-------|
+| Step | DOCUMENTATION |
+| Feature | {feature_id} |
+| Status | Complete |
+| React page | FrdDocPage.tsx |
+| i18n | 4 languages created |
+| Route | /docs/business/{app}/{module} |
+| Status | BA WORKFLOW COMPLETE |
+
+**Artifacts Summary:**
+
+| Document | Location | Status |
+|----------|----------|--------|
+| Discovery | {output_dir}/1-discovery.md | Complete |
+| BRD | {output_dir}/2-business-requirements.md | Complete |
+| FRD | {output_dir}/3-functional-specification.md | Complete |
+| Validation | {output_dir}/validation.json | APPROVED |
+| Handoff | {output_dir}/4-development-handoff.md | Complete |
+| Documentation | web/.../FrdDocPage.tsx | Complete |
+
+**Next steps:**
 1. Review generated documentation at /docs/business/{app}/{module}
-2. Execute /implement {feature_id} to start development
+2. Execute /ralph-loop -r (iterative) or /feature-full (one-shot) to start development
 3. Run tests after implementation
 
 Thank you for using Business Analysis skill!
 Contact: support@atlshub.ch
-```
 
 ---
 
-## OUTPUT
+### 10. Update Documentation Manifest
+
+**Update `docs-manifest.json` at project root:**
+
+1. Read existing `docs-manifest.json` (create if absent with `version: "1.0"`)
+2. Add or update the module entry:
+   ```json
+   {
+     "business/{application_name}/{module_name}": {
+       "featureId": "{feature_id}",
+       "displayName": "{module_name}",
+       "codeFiles": [/* from handoff section 3 */],
+       "docFiles": [
+         "web/.../pages/docs/business/{app}/{module}/frd-data.ts",
+         "web/.../i18n/locales/fr/docs-{app}-{module}.json"
+       ],
+       "baOutputs": ["{output_dir}"],
+       "screenshots": {/* from frd-data screenshots field */},
+       "lastCodeChange": "{current_timestamp}",
+       "lastDocUpdate": "{current_timestamp}",
+       "gitCommitCode": "",
+       "gitCommitDoc": "",
+       "status": "synced"
+     }
+   }
+   ```
+3. Update `lastUpdated` at manifest root level
+4. Write updated manifest
+
+> **Schema reference:** See `_resources/docs-manifest-schema.md` for full schema documentation.
+
+---
+
+## OUTPUT FORMAT:
 
 This step produces:
 - React documentation page
 - 4 i18n translation files
 - Updated routing
+- Updated documentation manifest
 - Final BA summary
 
 **BA Workflow Complete.**
+
+## ERROR HANDLING:
+
+**If React component generation fails:**
+1. Save FRD data structure to `{output_dir}/frd-data-draft.json`
+2. Skip React page generation
+3. Mark step as "Partial - data extracted, page generation failed"
+4. Suggest: "Run `/documentation {module}` manually to retry"
+
+**If i18n translation fails for non-FR language:**
+1. Generate FR (source language) first
+2. Mark other languages as "[TODO - translation pending]"
+3. Log: "EN/IT/DE translations deferred to translation pipeline"
+
+## NEXT STEP:
+
+After completion, the Business Analysis workflow is finalized. Implementation proceeds via `/ralph-loop -r` or `/feature-full`.

package/templates/skills/business-analyse/templates/{frd-handoff.md → tpl-handoff.md}

@@ -11,13 +11,21 @@
 > **Module:** business/{application}/{module}
 > **Version:** 1.0
 > **Validated Specs:** FRD v1.0 (validation.json)
-> **Implementation:** `/implement {FEAT-XXX}`
+> **Implementation:** `/ralph-loop -r` (iterative) | `/feature-full business/{app}/{module}` (one-shot)
 
 ## DEVELOPER INSTRUCTIONS
 
-This document is a self-contained prompt for Claude Code. Execute:
+This document is a self-contained prompt for Claude Code.
+
+**Option 1 - Iterative (recommended):**
+```
+/ralph-loop -r
+```
+> Pre-generated `.ralph/prd.json` with atomic task breakdown.
+
+**Option 2 - One-shot:**
 ```
-/implement {FEAT-XXX}
+/feature-full business/{app}/{module}
 ```
 
 ---
@@ -112,7 +120,13 @@ FRONTEND:
 
 ## EXECUTION
 
+**Iterative (recommended):**
+```bash
+/ralph-loop -r
+```
+
+**One-shot:**
 ```bash
-/implement {FEAT-XXX}
+/feature-full business/{app}/{module}
 ```
 ```

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

@@ -353,13 +353,21 @@ Feature: {FEAT-XXX} {Feature Name}
 > **Module:** business/{application}/{module}
 > **Version:** 1.0
 > **Validated Specs:** FRD v1.0 (validation.json)
-> **Implementation:** `/implement FEAT-XXX`
+> **Implementation:** `/ralph-loop -r` (iterative) | `/feature-full business/{app}/{module}` (one-shot)
 
 ## DEVELOPER INSTRUCTIONS
 
-This document is a self-contained prompt for Claude Code. Execute:
+This document is a self-contained prompt for Claude Code.
+
+**Option 1 - Iterative (recommended):**
+```
+/ralph-loop -r
+```
+> Pre-generated `.ralph/prd.json` with atomic task breakdown.
+
+**Option 2 - One-shot:**
 ```
-/implement FEAT-XXX
+/feature-full business/{app}/{module}
 ```
 
 ---
@@ -454,11 +462,17 @@ FRONTEND:
 
 ## EXECUTION
 
+**Iterative (recommended):**
+```bash
+/ralph-loop -r
+```
+
+**One-shot:**
 ```bash
-/implement FEAT-XXX
+/feature-full business/{app}/{module}
 ```
 
-Options:
+Options (one-shot only):
 - `--phase=1` : Backend only
 - `--phase=2` : Frontend only
 - `--phase=3` : Tests only

package/templates/skills/business-analyse/tracking/change-template.md

@@ -0,0 +1,30 @@
+# Change Tracking Template
+
+## CHANGE-NNN: {description}
+
+**Feature:** {feature_id}
+**Date:** {timestamp}
+**Type:** requirement-change | scope-change | bug-fix | enhancement
+**Impact:** {modules affected}
+**Doc sync required:** Yes | No
+
+## Changes
+
+- {what changed and why}
+
+## Documentation Impact
+
+| Section | Impact | Action Required |
+|---------|--------|-----------------|
+| Business Rules | Modified BR-XXX | Update frd-data.ts |
+| Permissions | New permission added | Update frd-data.ts + PermissionConfiguration.cs |
+| API Endpoints | New endpoint | Update frd-data.ts |
+| Use Cases | Modified UC-XXX | Update frd-data.ts + i18n FR |
+
+## Validation
+
+- [ ] Code changes implemented
+- [ ] Documentation updated (frd-data.ts)
+- [ ] i18n FR updated
+- [ ] docs-manifest.json updated
+- [ ] Tests passing