@atlashub/smartstack-cli 2.0.0 → 2.2.0

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

@@ -1,658 +0,0 @@
----
-name: step-05-handoff
-description: Handoff phase - Generate autonomous development prompt
-next_step: steps/step-06-doc-html.md
----
-
-## 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.
-
-> **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:
-
-### 1. Read Current State
-
-Read `{output_dir}/00-context.md` for state variables.
-Read validation: `{output_dir}/validation.json`
-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
-
-```
-IF validation.decision != "APPROVED" THEN
-  DISPLAY ERROR: "Validation must pass before handoff"
-  EXIT to step-04-validate
-END IF
-```
-
----
-
-### 3. Load Handoff Template
-
-```
-Read: templates/tpl-handoff.md    # ~100 lines
-```
-
----
-
-### 4. Explore Existing Patterns
-
-**CRITICAL: Handoff must reference ACTUAL code patterns!**
-
-If `{economy_mode}` = false, launch parallel agents:
-
-```
-Agent 1: Backend patterns
-  "Explore src/SmartStack.Domain/Entities/ and
-   src/SmartStack.Application/Features/ to document:
-   - Entity naming pattern
-   - CQRS handler pattern
-   - Validation pattern
-   - Repository pattern"
-
-Agent 2: Frontend patterns
-  "Explore web/smartstack-web/src/pages/business/ to document:
-   - Page component structure
-   - API service pattern
-   - i18n usage pattern
-   - Form handling pattern"
-
-Agent 3: Infrastructure patterns
-  "Explore src/SmartStack.Infrastructure/ to document:
-   - EF Core configuration pattern
-   - DbContext registration
-   - Migration naming convention"
-```
-
-If `{economy_mode}` = true:
-- Use Glob/Grep to find similar modules
-- Read 2-3 reference files directly
-
----
-
-### 5. Map Specifications to Files
-
-**Backend files to create:**
-
-| Layer | File | Template/Pattern |
-|-------|------|------------------|
-| Domain | `src/SmartStack.Domain/Entities/Business/{Entity}.cs` | Standard entity |
-| Application | `src/SmartStack.Application/Features/{Module}/Commands/` | CQRS pattern |
-| Application | `src/SmartStack.Application/Features/{Module}/Queries/` | CQRS pattern |
-| Application | `src/SmartStack.Application/Features/{Module}/DTOs/` | Request/Response DTOs |
-| Application | `src/SmartStack.Application/Features/{Module}/Validators/` | FluentValidation |
-| Infrastructure | `src/SmartStack.Infrastructure/Persistence/Configurations/` | EF Core config |
-| API | `src/SmartStack.Api/Controllers/Business/{Module}Controller.cs` | NavRoute controller |
-
-**Frontend files to create:**
-
-| Layer | File | Pattern |
-|-------|------|---------|
-| Pages | `web/smartstack-web/src/pages/business/{app}/{module}/` | Page components |
-| Services | `web/smartstack-web/src/services/api/{module}Api.ts` | Axios service |
-| i18n | `web/smartstack-web/src/i18n/locales/{lang}/{module}.json` | 4 languages |
-
----
-
-### 6. Generate Implementation Instructions
-
-For each file, provide explicit instructions:
-
-```markdown
-### Backend: {Entity}.cs
-
-**Path:** `src/SmartStack.Domain/Entities/Business/{Entity}.cs`
-
-**Reference:** Copy pattern from `src/SmartStack.Domain/Entities/Business/[ExistingEntity].cs`
-
-**Properties to add:**
-| Property | Type | Attributes | From BR |
-|----------|------|------------|---------|
-| Id | Guid | [Key] | - |
-| {attr1} | string | [Required, MaxLength(100)] | BR-001 |
-| {attr2} | decimal | [Precision(18,2)] | BR-002 |
-| TenantId | Guid | [Required] | Multi-tenant |
-| CreatedAt | DateTime | Audit | - |
-| UpdatedAt | DateTime | Audit | - |
-
-**Business rules to implement:**
-- BR-001: {rule} -> Implement in Validator
-- BR-002: {rule} -> Implement in Entity method
-```
-
----
-
-### 7. Map Business Rules to Code
-
-| BR-ID | Rule | Implementation Location | Code Pattern |
-|-------|------|------------------------|--------------|
-| BR-001 | {rule} | `{Entity}Validator.cs` | `.RuleFor(x => x.Field).NotEmpty()` |
-| BR-002 | {rule} | `{Entity}.cs` method | `public bool CanXXX() { ... }` |
-| BR-003 | {rule} | `{Handler}.cs` | `if (!entity.CanXXX()) throw` |
-
----
-
-### 8. Define API Endpoints
-
-| Endpoint | Method | Handler | Permission | Request DTO | Response DTO |
-|----------|--------|---------|------------|-------------|--------------|
-| `/api/business/{module}` | GET | `GetAll{Entity}Query` | `.read` | - | `{Entity}ListResponse` |
-| `/api/business/{module}` | POST | `Create{Entity}Command` | `.create` | `Create{Entity}Request` | `{Entity}Response` |
-| `/api/business/{module}/{id}` | GET | `Get{Entity}ByIdQuery` | `.read` | - | `{Entity}Response` |
-| `/api/business/{module}/{id}` | PUT | `Update{Entity}Command` | `.update` | `Update{Entity}Request` | `{Entity}Response` |
-| `/api/business/{module}/{id}` | DELETE | `Delete{Entity}Command` | `.delete` | - | `204` |
-
----
-
-### 9. Generate Test Requirements
-
-**Unit tests:**
-- [ ] `{Entity}ValidatorTests.cs` - Validation rules
-- [ ] `{Entity}Tests.cs` - Entity methods
-
-**Integration tests:**
-- [ ] `{Module}ControllerTests.cs` - All endpoints
-- [ ] Permission tests - 403 for unauthorized
-- [ ] Validation tests - 400 for invalid data
-
-**Gherkin reference:** Copy scenarios from FRD section 7
-
----
-
-### 10. Generate i18n Keys
-
-**Keys to create:**
-
-```json
-{
-  "{module}": {
-    "title": "{Module display name}",
-    "fields": {
-      "{field1}": "{Label}",
-      "{field2}": "{Label}"
-    },
-    "messages": {
-      "created": "{Entity} created successfully",
-      "updated": "{Entity} updated successfully",
-      "deleted": "{Entity} deleted successfully"
-    },
-    "errors": {
-      "{field1}Required": "{Field1} is required",
-      "notFound": "{Entity} not found",
-      "permissionDenied": "You don't have permission to perform this action"
-    },
-    "buttons": {
-      "create": "Create {Entity}",
-      "edit": "Edit",
-      "delete": "Delete",
-      "save": "Save",
-      "cancel": "Cancel"
-    }
-  }
-}
-```
-
----
-
-### 11. Compile Handoff Document
-
-```markdown
-# Development Handoff - {feature_id} {feature_description}
-
-> **Module:** business/{application_name}/{module_name}
-> **Version:** 1.0
-> **Validated Specs:** FRD v1.0 (validation.json: APPROVED)
-> **Implementation:** `/ralph-loop -r` (iterative) | `/feature-full business/{application_name}/{module_name}` (one-shot)
-
-## DEVELOPER INSTRUCTIONS
-
-Ce document est un prompt autonome pour Claude Code.
-
-**Option 1 - Itératif (recommandé) :**
-```
-/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).
-
----
-
-## 1. QUICK CONTEXT
-
-| Attribute | Value |
-|-----------|-------|
-| Feature ID | {feature_id} |
-| Module | business/{application_name}/{module_name} |
-| Permission base | `business.{app}.{module}` |
-| Complexity | {Simple/Medium/Complex} |
-| Entities | {entity count} |
-| Endpoints | {endpoint count} |
-
-## 2. [EXPLORE] EXISTING PATTERNS
-
-{Patterns discovered in step 4}
-
-## 3. FILES TO CREATE
-
-{File mapping table}
-
-## 4. DETAILED SPECIFICATIONS
-
-{Per-file instructions}
-
-## 5. BUSINESS RULES → CODE
-
-{BR to code mapping}
-
-## 6. REQUIRED TESTS
-
-{Test checklist}
-
-## 7. POST-IMPLEMENTATION CHECKLIST
-
-- [ ] Build backend OK (`dotnet build`)
-- [ ] Build frontend OK (`pnpm build`)
-- [ ] Tests pass (`dotnet test`)
-- [ ] EF Core migration created
-- [ ] 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
-/feature-full business/{application_name}/{module_name}
-```
-```
-
----
-
-### 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`
-
-Update `00-context.md`:
-- Progress: `05-handoff` -> "Complete"
-
----
-
-### 12b. Generate Ralph Loop Task Breakdown
-
-**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 → i18n → Tests → Validation
-- Conditionally include tasks based on feature scope (skip layers not present in the handoff document)
-- Each task MUST include `category`, `dependencies`, and `acceptance_criteria` (schema v2)
-
-**Granularity Rules:**
-- 1 task per entity (domain, EF config, unit tests)
-- 1 task per entity for CQRS (commands + queries + DTOs grouped per entity)
-- 1 task per controller (API)
-- 1 task per page (frontend)
-- Max 1 entity per task — do NOT group multiple entities into a single task
-- Enums and shared value objects can be grouped in 1 task if they belong to the same module
-
-**Conditional Task Generation Rules (v2 schema):**
-
-For each layer, generate tasks ONLY if the handoff document contains specifications for that layer.
-Each task must have: `id`, `description`, `status: "pending"`, `category`, `dependencies`, `acceptance_criteria`.
-
-```
-LAYER 1 - DOMAIN (if entities defined in handoff section 3/4):
-  Task per entity:
-    description: "Create {Entity} entity in Domain/Entities/Business/ with properties: {property_list}"
-    category: "domain"
-    dependencies: []
-    acceptance_criteria: "Entity compiles, properties match handoff spec, correct base class (SoftDeletableEntity/AuditableEntity)"
-  Task (if enums needed):
-    description: "Create domain enums for {Module}: {EnumList} in Domain/Enums/{Module}/"
-    category: "domain"
-    dependencies: []
-    acceptance_criteria: "Enums compile, values match handoff spec"
-
-LAYER 2 - APPLICATION (if CQRS handlers defined in handoff section 3/4):
-  Task per entity:
-    description: "Create CQRS for {Entity}: Commands ({Create/Update/Delete}Command + Handlers), Queries (GetAll/GetById + Handlers), DTOs ({Entity}Dto, Create/UpdateRequest), Validator"
-    category: "application"
-    dependencies: [ID of corresponding DOMAIN task for this entity]
-    acceptance_criteria: "Handlers compile, validators defined with business rules, DTOs match handoff properties"
-  Task (once per module):
-    description: "Register permissions in Permissions.cs and PermissionConfiguration.cs for business.{app}.{module}"
-    category: "application"
-    dependencies: [IDs of ALL application tasks for this module]
-    acceptance_criteria: "Permissions compile, HasData seed includes all permissions from handoff"
-
-LAYER 3 - INFRASTRUCTURE (if EF Core config or services in handoff):
-  Task per entity:
-    description: "Create EF Core configuration for {Entity} with indexes, relationships, and schema"
-    category: "infrastructure"
-    dependencies: [ID of corresponding DOMAIN task for this entity]
-    acceptance_criteria: "Configuration compiles, DbSet registered in DbContext, indexes match handoff"
-  Task (once per module):
-    description: "Create EF Core migration for {Module} entities"
-    category: "infrastructure"
-    dependencies: [IDs of ALL EF Core configuration tasks]
-    acceptance_criteria: "Migration applies without errors, 3 files present (Migration.cs, Designer.cs, ModelSnapshot.cs)"
-  Task per service (if services needed):
-    description: "Create {Service} implementing I{Service} with DI registration"
-    category: "infrastructure"
-    dependencies: [IDs of relevant DOMAIN + APPLICATION tasks]
-    acceptance_criteria: "Service compiles, registered in DI, follows existing patterns"
-
-LAYER 4 - API (if endpoints defined in handoff section 8):
-  Task per controller:
-    description: "Create {Entity}Controller with endpoints: {endpoint list} and [NavRoute] + [Authorize] attributes"
-    category: "api"
-    dependencies: [IDs of APPLICATION tasks for this entity + INFRASTRUCTURE migration task]
-    acceptance_criteria: "Controller compiles, endpoints respond, Swagger displays all routes"
-
-LAYER 5 - FRONTEND (if frontend files in handoff section 5):
-  Task (API service):
-    description: "Create {module}Api.ts API service with Axios calls for all endpoints"
-    category: "frontend"
-    dependencies: [IDs of ALL API controller tasks]
-    acceptance_criteria: "API service compiles, all endpoints covered, types match DTOs"
-  Task per page:
-    description: "Create {PageName}.tsx with {description of page content}"
-    category: "frontend"
-    dependencies: [ID of frontend API service task]
-    acceptance_criteria: "Page renders, API calls work, navigation functional"
-  Task (routes):
-    description: "Add routes in App.tsx for business/{app}/{module} and register in navigation"
-    category: "frontend"
-    dependencies: [IDs of ALL frontend page tasks]
-    acceptance_criteria: "Routes resolve, navigation links appear in menu"
-
-LAYER 6 - I18N (if i18n keys in handoff section 10):
-  Task:
-    description: "Create i18n translation files for {module} in 4 languages (fr, en, it, de)"
-    category: "i18n"
-    dependencies: [IDs of frontend page tasks]
-    acceptance_criteria: "4 language files created, all keys from handoff present, no missing translations"
-
-LAYER 7 - TESTS (always included):
-  Task per entity:
-    description: "Create unit tests for {Entity}: {Entity}ValidatorTests + {Entity}Tests (entity methods)"
-    category: "test"
-    dependencies: [ID of APPLICATION task for this entity]
-    acceptance_criteria: "Tests pass, validator rules covered, entity methods tested"
-  Task per controller:
-    description: "Create integration tests for {Entity}Controller: 200, 201, 400, 403, 404 scenarios"
-    category: "test"
-    dependencies: [ID of API task for this controller]
-    acceptance_criteria: "Tests pass, all status codes covered, permission denial tested"
-
-LAYER 8 - VALIDATION (always included):
-  Task 1:
-    description: "Run dotnet build + dotnet test - fix any build errors or test failures"
-    category: "validation"
-    dependencies: [IDs of ALL test tasks]
-    acceptance_criteria: "Build succeeds, all tests pass"
-  Task 2:
-    description: "Run MCP validate_conventions to verify all naming and structural conventions"
-    category: "validation"
-    dependencies: [ID of validation task 1]
-    acceptance_criteria: "MCP validation clean, no convention violations"
-```
-
-**Sizing rules:**
-- Simple feature (1 entity, CRUD only): ~10-15 tasks
-- Medium feature (2-3 entities, business rules): ~18-25 tasks
-- Complex feature (multiple entities, integrations): ~25-35 tasks
-
-#### 12bis.3 Write prd.json
-
-Write to: `.ralph/prd.json`
-
-```json
-{
-  "$version": "2.0.0",
-  "feature": "{feature_id} - {feature_description}",
-  "status": "pending",
-  "created": "{ISO 8601 timestamp}",
-  "updated_at": "{ISO 8601 timestamp}",
-  "metadata": {
-    "cli_version": "{version from package.json}",
-    "branch": "{current git branch}",
-    "project_path": "{cwd}",
-    "mcp_servers": { "smartstack": true, "context7": true }
-  },
-  "config": {
-    "max_iterations": 30,
-    "completion_promise": "IMPLEMENTATION COMPLETE",
-    "current_iteration": 1
-  },
-  "source": {
-    "type": "ba-handoff",
-    "handoff_path": "{output_dir}/4-development-handoff.md",
-    "frd_path": "{output_dir}/3-functional-specification.md",
-    "brd_path": "{output_dir}/2-business-requirements.md"
-  },
-  "tasks": [
-    {
-      "id": 1,
-      "description": "Create {Entity} entity in Domain layer with properties: {list}",
-      "status": "pending",
-      "category": "domain",
-      "dependencies": [],
-      "acceptance_criteria": "Entity compiles, properties match handoff spec",
-      "started_at": null,
-      "completed_at": null,
-      "iteration": null,
-      "commit_hash": null,
-      "files_changed": { "created": [], "modified": [] },
-      "validation": null,
-      "error": null
-    }
-  ],
-  "history": []
-}
-```
-
-> **Schema v2.0.0** — Compatible avec ralph-loop step-01 sans migration. Chaque tache inclut `category`, `dependencies` et `acceptance_criteria` pour un pilotage precis de l'execution.
-
-#### 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
-{
-  "questions": [
-    {
-      "question": "What would you like to do now?",
-      "header": "Next",
-      "options": [
-        {"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
-    }
-  ]
-}
-```
-
-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 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:
-
-After completion, proceed to `steps/step-06-doc-html.md`