@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/validate-feature/steps/step-05-db-validation.md

@@ -1,149 +1,149 @@
----
-name: step-05-db-validation
-description: Validate database schema, migrations, seed data, and multi-tenant isolation against real SQL Server
-prev_step: steps/step-04-api-smoke.md
-next_step: null
----
-
-# Step 5: Database Validation (SQL Server LocalDB)
-
-> **Purpose:** Verify migrations apply correctly, seed data inserts, LINQ queries execute on SQL Server, multi-tenant isolation works on REAL SQL Server (not SQLite).
-
-See `references/db-validation-checks.md` for detailed checks, error classification, and fixes.
-
----
-
-## Procedure
-
-### Check 1: LocalDB Available?
-
-```bash
-sqllocaldb info MSSQLLocalDB
-```
-
-If NOT available → Skip DB validation, set `DB_VALIDATION = SKIPPED`
-
-### Check 2: Pending Model Changes?
-
-```bash
-dotnet ef migrations has-pending-model-changes --project "$INFRA_PROJECT" --startup-project "$API_PROJECT"
-```
-
-If exit code != 0 → Create missing migration:
-```bash
-dotnet ef migrations add {SuggestedName} --project {InfraProject} --startup-project {ApiProject} -o Persistence/Migrations
-```
-
-### Check 3: Apply Migrations on Temp DB
-
-```bash
-DB_NAME="SmartStack_Validate_$(date +%s)"
-CONN_STRING="Server=(localdb)\\MSSQLLocalDB;Database=$DB_NAME;Integrated Security=true;TrustServerCertificate=true;Connect Timeout=120;"
-
-dotnet ef database update --connection "$CONN_STRING" --project "$INFRA_PROJECT" --startup-project "$API_PROJECT"
-```
-
-If FAIL → Check for: migration ordering, duplicate migration, seed data conflict (see reference)
-
-### Check 4: Integration Tests (SQL Server)
-
-```bash
-TEST_PROJECT=$(ls tests/*Tests.Integration*/*.csproj 2>/dev/null | head -1)
-dotnet test "$TEST_PROJECT" --no-build --verbosity normal
-```
-
-Validates: LINQ→SQL, multi-tenant isolation, soft delete, EF configs, repositories on real SQL Server
-
-### Check 5: Dev Seeding Enabled?
-
-```bash
-APPSETTINGS=$(ls appsettings.Development.json 2>/dev/null || ls appsettings.json 2>/dev/null)
-PROGRAM_CS=$(find . -name "Program.cs" -path "*/Api/*" 2>/dev/null | head -1)
-
-# Check for Program.cs override or appsettings EnableDevSeeding = true
-```
-
-If not enabled → Add to Program.cs:
-```csharp
-options.EnableDevSeeding = builder.Environment.IsDevelopment();
-```
-
-### Check 6: DefaultTenantId FK Validation
-
-```bash
-SEED_CONSTANTS=$(find . -path "*/SeedConstants.cs" 2>/dev/null | head -1)
-TENANT_GUID=$(grep -oP 'DefaultTenantId\s*=\s*Guid\.Parse\("([^"]+)"\)' "$SEED_CONSTANTS" | grep -oP '"[^"]+"' | tr -d '"')
-
-sqlcmd -S "(localdb)\MSSQLLocalDB" -d "$DB_NAME" -Q "
-  SET NOCOUNT ON;
-  SELECT COUNT(*) FROM core.tenant_Tenants WHERE Id = '$TENANT_GUID'
-"
-```
-
-If COUNT = 0 → Use a TenantId seeded by `InitializeSmartStackAsync()`
-
-### Check 7: Seed Data Accessible?
-
-```bash
-dotnet run --project "$API_PROJECT" --urls "http://localhost:5097" \
-  -- --ConnectionStrings:DefaultConnection="$CONN_STRING" &
-
-# Verify seed data via API endpoint
-# (See reference for full commands)
-```
-
-### Check 8: Cleanup
-
-```bash
-sqlcmd -S "(localdb)\MSSQLLocalDB" -Q "
-  IF DB_ID('$DB_NAME') IS NOT NULL
-  BEGIN
-    ALTER DATABASE [$DB_NAME] SET SINGLE_USER WITH ROLLBACK IMMEDIATE;
-    DROP DATABASE [$DB_NAME];
-  END
-"
-```
-
----
-
-## Validation Summary
-
-```
-## DB Validation: {EntityName}
-
-| Check | Result | Details |
-|-------|--------|---------|
-| LocalDB available | PASS/SKIP | sqllocaldb info MSSQLLocalDB |
-| Pending model changes | PASS/FAIL | dotnet ef migrations has-pending |
-| Migrations apply cleanly | PASS/FAIL | dotnet ef database update on temp DB |
-| Integration tests (SQL Server) | PASS/FAIL | dotnet test --filter Integration |
-| EnableDevSeeding active | PASS/WARN | Program.cs override or appsettings |
-| DefaultTenantId FK valid | PASS/FAIL | SeedConstants GUID exists in tenant_Tenants |
-| Seed data accessible | PASS/WARN | API endpoints return seeded data |
-| Temp DB cleanup | PASS/WARN | Database dropped |
-
-DB Validation Result: {PASS / FAIL / SKIPPED}
-```
-
-**Interpretation:**
-- **PASS** — All checks covered: migrations, SQL Server, LINQ→SQL, isolation, seeding config
-- **FAIL** — Fix before committing
-- **SKIPPED** — LocalDB unavailable; tests ran on SQLite only (partial coverage)
-
----
-
-## Error Reference
-
-See `references/db-validation-checks.md` for complete error classification and fixes including:
-- Migration ordering issues
-- Seed data conflicts
-- ForeignKey constraint violations
-- LocalDB connectivity
-- EnableDevSeeding configuration
-- DefaultTenantId phantom FK
-
----
-
-## NEXT STEP:
-
-DB validation complete. Review all step results and generate final report.
+---
+name: step-05-db-validation
+description: Validate database schema, migrations, seed data, and multi-tenant isolation against real SQL Server
+prev_step: steps/step-04-api-smoke.md
+next_step: null
+---
+
+# Step 5: Database Validation (SQL Server LocalDB)
+
+> **Purpose:** Verify migrations apply correctly, seed data inserts, LINQ queries execute on SQL Server, multi-tenant isolation works on REAL SQL Server (not SQLite).
+
+See `references/db-validation-checks.md` for detailed checks, error classification, and fixes.
+
+---
+
+## Procedure
+
+### Check 1: LocalDB Available?
+
+```bash
+sqllocaldb info MSSQLLocalDB
+```
+
+If NOT available → Skip DB validation, set `DB_VALIDATION = SKIPPED`
+
+### Check 2: Pending Model Changes?
+
+```bash
+dotnet ef migrations has-pending-model-changes --project "$INFRA_PROJECT" --startup-project "$API_PROJECT"
+```
+
+If exit code != 0 → Create missing migration:
+```bash
+dotnet ef migrations add {SuggestedName} --project {InfraProject} --startup-project {ApiProject} -o Persistence/Migrations
+```
+
+### Check 3: Apply Migrations on Temp DB
+
+```bash
+DB_NAME="SmartStack_Validate_$(date +%s)"
+CONN_STRING="Server=(localdb)\\MSSQLLocalDB;Database=$DB_NAME;Integrated Security=true;TrustServerCertificate=true;Connect Timeout=120;"
+
+dotnet ef database update --connection "$CONN_STRING" --project "$INFRA_PROJECT" --startup-project "$API_PROJECT"
+```
+
+If FAIL → Check for: migration ordering, duplicate migration, seed data conflict (see reference)
+
+### Check 4: Integration Tests (SQL Server)
+
+```bash
+TEST_PROJECT=$(ls tests/*Tests.Integration*/*.csproj 2>/dev/null | head -1)
+dotnet test "$TEST_PROJECT" --no-build --verbosity normal
+```
+
+Validates: LINQ→SQL, multi-tenant isolation, soft delete, EF configs, repositories on real SQL Server
+
+### Check 5: Dev Seeding Enabled?
+
+```bash
+APPSETTINGS=$(ls appsettings.Development.json 2>/dev/null || ls appsettings.json 2>/dev/null)
+PROGRAM_CS=$(find . -name "Program.cs" -path "*/Api/*" 2>/dev/null | head -1)
+
+# Check for Program.cs override or appsettings EnableDevSeeding = true
+```
+
+If not enabled → Add to Program.cs:
+```csharp
+options.EnableDevSeeding = builder.Environment.IsDevelopment();
+```
+
+### Check 6: DefaultTenantId FK Validation
+
+```bash
+SEED_CONSTANTS=$(find . -path "*/SeedConstants.cs" 2>/dev/null | head -1)
+TENANT_GUID=$(grep -oP 'DefaultTenantId\s*=\s*Guid\.Parse\("([^"]+)"\)' "$SEED_CONSTANTS" | grep -oP '"[^"]+"' | tr -d '"')
+
+sqlcmd -S "(localdb)\MSSQLLocalDB" -d "$DB_NAME" -Q "
+  SET NOCOUNT ON;
+  SELECT COUNT(*) FROM core.tenant_Tenants WHERE Id = '$TENANT_GUID'
+"
+```
+
+If COUNT = 0 → Use a TenantId seeded by `InitializeSmartStackAsync()`
+
+### Check 7: Seed Data Accessible?
+
+```bash
+dotnet run --project "$API_PROJECT" --urls "http://localhost:5097" \
+  -- --ConnectionStrings:DefaultConnection="$CONN_STRING" &
+
+# Verify seed data via API endpoint
+# (See reference for full commands)
+```
+
+### Check 8: Cleanup
+
+```bash
+sqlcmd -S "(localdb)\MSSQLLocalDB" -Q "
+  IF DB_ID('$DB_NAME') IS NOT NULL
+  BEGIN
+    ALTER DATABASE [$DB_NAME] SET SINGLE_USER WITH ROLLBACK IMMEDIATE;
+    DROP DATABASE [$DB_NAME];
+  END
+"
+```
+
+---
+
+## Validation Summary
+
+```
+## DB Validation: {EntityName}
+
+| Check | Result | Details |
+|-------|--------|---------|
+| LocalDB available | PASS/SKIP | sqllocaldb info MSSQLLocalDB |
+| Pending model changes | PASS/FAIL | dotnet ef migrations has-pending |
+| Migrations apply cleanly | PASS/FAIL | dotnet ef database update on temp DB |
+| Integration tests (SQL Server) | PASS/FAIL | dotnet test --filter Integration |
+| EnableDevSeeding active | PASS/WARN | Program.cs override or appsettings |
+| DefaultTenantId FK valid | PASS/FAIL | SeedConstants GUID exists in tenant_Tenants |
+| Seed data accessible | PASS/WARN | API endpoints return seeded data |
+| Temp DB cleanup | PASS/WARN | Database dropped |
+
+DB Validation Result: {PASS / FAIL / SKIPPED}
+```
+
+**Interpretation:**
+- **PASS** — All checks covered: migrations, SQL Server, LINQ→SQL, isolation, seeding config
+- **FAIL** — Fix before committing
+- **SKIPPED** — LocalDB unavailable; tests ran on SQLite only (partial coverage)
+
+---
+
+## Error Reference
+
+See `references/db-validation-checks.md` for complete error classification and fixes including:
+- Migration ordering issues
+- Seed data conflicts
+- ForeignKey constraint violations
+- LocalDB connectivity
+- EnableDevSeeding configuration
+- DefaultTenantId phantom FK
+
+---
+
+## NEXT STEP:
+
+DB validation complete. Review all step results and generate final report.

package/templates/skills/workflow/SKILL.md

@@ -1,127 +1,127 @@
----
-name: workflow
-description: |
-  Creates and configures automated SmartStack workflows.
-  Use this skill when:
-  - User wants to automate actions (emails, webhooks)
-  - User mentions "workflow", "automation", "trigger"
-  - Creating a business process with steps
-  - Integrating transactional emails
-  Types: SendEmail, Wait, Condition, Webhook
----
-
-# Skill Workflow SmartStack
-
-> **Architecture:** Trigger -> Steps -> Actions (Email/Wait/Condition/Webhook)
-
-**Reference:** [_shared.md](../_shared.md) for common services
-
-## When This Skill Activates
-
-| Trigger | Example |
-|---------|---------|
-| Explicit request | "Create a workflow for registration" |
-| Automatic email | "Send an email when a ticket is created" |
-| Chaining | "After 24h without response, send a reminder" |
-| Keywords | "workflow", "trigger", "automation", "email template" |
-
-## Flow
-
-```
-EVENT -> WorkflowTrigger("user.registered")
-    |
-IWorkflowService.TriggerAsync(code, variables)
-    |
-Workflow Steps: SendEmail -> Wait -> Condition -> Webhook
-```
-
-## Available Triggers
-
-### User Events
-| Trigger | Variables |
-|---------|-----------|
-| `user.registered` | userId, email, displayName, confirmUrl |
-| `user.email-confirmed` | userId, email, displayName |
-| `user.password-reset-requested` | userId, email, resetUrl |
-| `user.account-locked/unlocked` | userId, email, lockReason |
-
-### Ticket Events
-| Trigger | Variables |
-|---------|-----------|
-| `ticket.created` | ticketId, ticketNumber, title, creatorEmail |
-| `ticket.resolved/assigned` | ticketId, ticketNumber, assigneeName |
-| `ticket.sla-warning/breached` | ticketId, deadline, remainingMinutes |
-
-### Add a Trigger
-```csharp
-// WorkflowTriggerConfiguration.cs - GetSeedData()
-new { Id = Guid.Parse("..."), Code = "entity.event", Name = "Entity Event",
-    AvailableVariablesJson = JsonSerializer.Serialize(new[]{ ... }), ... }
-
-// Trigger
-await _workflowService.TriggerAsync("entity.event", new Dictionary<string, object>{...}, language: "en");
-```
-
-## Implementation
-
-Start with [steps/step-00-init.md](steps/step-00-init.md) to identify workflow triggers and requirements, then proceed to [steps/step-01-implementation.md](steps/step-01-implementation.md) for:
-- Step types (SendEmail, Wait, Condition, Webhook) with code templates
-- Workflow creation and seed data
-- Triggering from services
-- Email templates (Handlebars syntax)
-- Frontend API
-
-## Relation with Domain Events
-
-Workflow triggers (`TriggerAsync`) are the **primary mechanism** for cross-process automation (emails, webhooks, multi-step flows).
-
-**Domain Events** (MediatR `INotificationHandler<T>`) are complementary for **in-process** side effects (audit logging, cache invalidation, read-model updates).
-
-| Scenario | Mechanism |
-|----------|-----------|
-| Send email after entity creation | Workflow Trigger |
-| Invalidate cache after entity update | Domain Event |
-| Log audit trail | Domain Event |
-| Multi-step business process with delays | Workflow Trigger |
-| Notify multiple services of same change | Domain Event -> Workflow Trigger |
-
-See `review-code/references/smartstack-conventions.md` (Domain Events section) for full pattern.
-
-## Checklist
-
-```
-- Trigger identified (existing or new in WorkflowTriggerConfiguration.cs)
-- Workflow created: Unique code, Linked trigger, Priority (10=standard, 20+=priority)
-- Steps: SendEmail+templateId, Wait+delayMinutes, Condition+expression, Webhook+url
-- Email templates created (if SendEmail)
-- Trigger added to source code
-- Tests: trigger, emails, variables
-```
-
-## Absolute Rules
-
-| DO | DON'T |
-|----|-------|
-| IWorkflowService.TriggerAsync | Direct execution |
-| All trigger variables | Hardcoded URLs in templates |
-| Specify language for emails | Secrets in variables |
-| Unique kebab-case codes | Infinite loops (A->B->A) |
-| Log executions | Forget email templates |
-
-## Key Files
-
-| File | Role |
-|------|------|
-| `Domain/Communications/Workflow.cs` | Workflow entity |
-| `Domain/Communications/WorkflowStep.cs` | Step entity |
-| `Domain/Communications/WorkflowTrigger.cs` | Trigger entity |
-| `Application/Common/Interfaces/IWorkflowService.cs` | Interface |
-| `Infrastructure/Services/Workflow/WorkflowExecutionService.cs` | Implementation |
-| `Infrastructure/.../WorkflowConfiguration.cs` | EF Config + Seed |
-
-<success_criteria>
-- Workflow entity, steps, and triggers created following SmartStack patterns
-- EF Core configuration and seed data generated
-- IWorkflowService integration wired correctly
-- Email templates created with i18n support (4 languages)
-</success_criteria>
+---
+name: workflow
+description: |
+  Creates and configures automated SmartStack workflows.
+  Use this skill when:
+  - User wants to automate actions (emails, webhooks)
+  - User mentions "workflow", "automation", "trigger"
+  - Creating a business process with steps
+  - Integrating transactional emails
+  Types: SendEmail, Wait, Condition, Webhook
+---
+
+# Skill Workflow SmartStack
+
+> **Architecture:** Trigger -> Steps -> Actions (Email/Wait/Condition/Webhook)
+
+**Reference:** [_shared.md](../_shared.md) for common services
+
+## When This Skill Activates
+
+| Trigger | Example |
+|---------|---------|
+| Explicit request | "Create a workflow for registration" |
+| Automatic email | "Send an email when a ticket is created" |
+| Chaining | "After 24h without response, send a reminder" |
+| Keywords | "workflow", "trigger", "automation", "email template" |
+
+## Flow
+
+```
+EVENT -> WorkflowTrigger("user.registered")
+    |
+IWorkflowService.TriggerAsync(code, variables)
+    |
+Workflow Steps: SendEmail -> Wait -> Condition -> Webhook
+```
+
+## Available Triggers
+
+### User Events
+| Trigger | Variables |
+|---------|-----------|
+| `user.registered` | userId, email, displayName, confirmUrl |
+| `user.email-confirmed` | userId, email, displayName |
+| `user.password-reset-requested` | userId, email, resetUrl |
+| `user.account-locked/unlocked` | userId, email, lockReason |
+
+### Ticket Events
+| Trigger | Variables |
+|---------|-----------|
+| `ticket.created` | ticketId, ticketNumber, title, creatorEmail |
+| `ticket.resolved/assigned` | ticketId, ticketNumber, assigneeName |
+| `ticket.sla-warning/breached` | ticketId, deadline, remainingMinutes |
+
+### Add a Trigger
+```csharp
+// WorkflowTriggerConfiguration.cs - GetSeedData()
+new { Id = Guid.Parse("..."), Code = "entity.event", Name = "Entity Event",
+    AvailableVariablesJson = JsonSerializer.Serialize(new[]{ ... }), ... }
+
+// Trigger
+await _workflowService.TriggerAsync("entity.event", new Dictionary<string, object>{...}, language: "en");
+```
+
+## Implementation
+
+Start with [steps/step-00-init.md](steps/step-00-init.md) to identify workflow triggers and requirements, then proceed to [steps/step-01-implementation.md](steps/step-01-implementation.md) for:
+- Step types (SendEmail, Wait, Condition, Webhook) with code templates
+- Workflow creation and seed data
+- Triggering from services
+- Email templates (Handlebars syntax)
+- Frontend API
+
+## Relation with Domain Events
+
+Workflow triggers (`TriggerAsync`) are the **primary mechanism** for cross-process automation (emails, webhooks, multi-step flows).
+
+**Domain Events** (MediatR `INotificationHandler<T>`) are complementary for **in-process** side effects (audit logging, cache invalidation, read-model updates).
+
+| Scenario | Mechanism |
+|----------|-----------|
+| Send email after entity creation | Workflow Trigger |
+| Invalidate cache after entity update | Domain Event |
+| Log audit trail | Domain Event |
+| Multi-step business process with delays | Workflow Trigger |
+| Notify multiple services of same change | Domain Event -> Workflow Trigger |
+
+See `review-code/references/smartstack-conventions.md` (Domain Events section) for full pattern.
+
+## Checklist
+
+```
+- Trigger identified (existing or new in WorkflowTriggerConfiguration.cs)
+- Workflow created: Unique code, Linked trigger, Priority (10=standard, 20+=priority)
+- Steps: SendEmail+templateId, Wait+delayMinutes, Condition+expression, Webhook+url
+- Email templates created (if SendEmail)
+- Trigger added to source code
+- Tests: trigger, emails, variables
+```
+
+## Absolute Rules
+
+| DO | DON'T |
+|----|-------|
+| IWorkflowService.TriggerAsync | Direct execution |
+| All trigger variables | Hardcoded URLs in templates |
+| Specify language for emails | Secrets in variables |
+| Unique kebab-case codes | Infinite loops (A->B->A) |
+| Log executions | Forget email templates |
+
+## Key Files
+
+| File | Role |
+|------|------|
+| `Domain/Communications/Workflow.cs` | Workflow entity |
+| `Domain/Communications/WorkflowStep.cs` | Step entity |
+| `Domain/Communications/WorkflowTrigger.cs` | Trigger entity |
+| `Application/Common/Interfaces/IWorkflowService.cs` | Interface |
+| `Infrastructure/Services/Workflow/WorkflowExecutionService.cs` | Implementation |
+| `Infrastructure/.../WorkflowConfiguration.cs` | EF Config + Seed |
+
+<success_criteria>
+- Workflow entity, steps, and triggers created following SmartStack patterns
+- EF Core configuration and seed data generated
+- IWorkflowService integration wired correctly
+- Email templates created with i18n support (4 languages)
+</success_criteria>

package/templates/skills/workflow/steps/step-00-init.md

@@ -1,57 +1,57 @@
-# Step 0: Initialization
-
-## YOUR TASK
-Gather workflow requirements and identify triggers before implementing automated processes.
-
-## EXECUTION SEQUENCE
-
-### 1. Identify Workflow Type
-- What event triggers this workflow? (user.registered, entity.created, status.changed, time-based)
-- What business process should be automated? (email sequence, multi-step approval, notification chain)
-- What is the primary action? (SendEmail, Webhook, Condition logic, Wait/delay)
-- Is this a new trigger or does it use an existing one? (check WorkflowTriggerConfiguration.cs)
-
-### 2. Define Workflow Variables
-- What variables are available from the trigger event?
-  - Example: `user.registered` provides userId, email, displayName, confirmUrl
-  - Example: `ticket.created` provides ticketId, ticketNumber, title, creatorEmail
-- What variables are needed in steps? (recipients, delays, conditions, webhook payloads)
-- Map all {{variable}} placeholders to available data
-
-### 3. Plan Workflow Steps
-- Step 1: SendEmail? Webhook? Condition? Wait/Delay?
-- Step 2: Follow-up action after first step
-- Step 3+: Conditional branches or multi-step sequences
-- Error handling: what happens if a step fails? (retry, fallback, notify)
-- Timeout: should the workflow have a maximum duration?
-
-### 4. Design Email Templates (if SendEmail steps)
-- Email subject and body templates
-- Handlebars syntax for variable interpolation: `{{userId}}`, `{{confirmUrl}}`
-- HTML and plain text versions if needed
-- i18n translations: French, English, Italian, German
-- Template registration in EmailTemplateConfiguration.cs
-
-### 5. Check Trigger Configuration
-- Does the trigger exist in WorkflowTriggerConfiguration.cs?
-- If new trigger:
-  - Define available variables (JSON serialized array)
-  - Add trigger seed data with unique code (kebab-case)
-  - Plan where in code to call `IWorkflowService.TriggerAsync(code, variables)`
-
-### 6. Define Logging & Monitoring
-- What execution events should be logged?
-- How to track workflow success/failure metrics?
-- What observability is needed for debugging?
-
-## SUCCESS METRICS
-- Workflow trigger identified or new trigger planned
-- Available variables from trigger documented
-- Workflow steps sequenced (SendEmail -> Wait -> Condition -> Webhook, etc.)
-- Email templates designed with i18n
-- Trigger configuration understood (existing or new)
-- Integration point in code identified (where TriggerAsync is called)
-- Error handling strategy defined
-
-## NEXT STEP
-Proceed to `./step-01-implementation.md` to implement workflow entity, steps, trigger configuration, email templates, and integration into services with IWorkflowService.
+# Step 0: Initialization
+
+## YOUR TASK
+Gather workflow requirements and identify triggers before implementing automated processes.
+
+## EXECUTION SEQUENCE
+
+### 1. Identify Workflow Type
+- What event triggers this workflow? (user.registered, entity.created, status.changed, time-based)
+- What business process should be automated? (email sequence, multi-step approval, notification chain)
+- What is the primary action? (SendEmail, Webhook, Condition logic, Wait/delay)
+- Is this a new trigger or does it use an existing one? (check WorkflowTriggerConfiguration.cs)
+
+### 2. Define Workflow Variables
+- What variables are available from the trigger event?
+  - Example: `user.registered` provides userId, email, displayName, confirmUrl
+  - Example: `ticket.created` provides ticketId, ticketNumber, title, creatorEmail
+- What variables are needed in steps? (recipients, delays, conditions, webhook payloads)
+- Map all {{variable}} placeholders to available data
+
+### 3. Plan Workflow Steps
+- Step 1: SendEmail? Webhook? Condition? Wait/Delay?
+- Step 2: Follow-up action after first step
+- Step 3+: Conditional branches or multi-step sequences
+- Error handling: what happens if a step fails? (retry, fallback, notify)
+- Timeout: should the workflow have a maximum duration?
+
+### 4. Design Email Templates (if SendEmail steps)
+- Email subject and body templates
+- Handlebars syntax for variable interpolation: `{{userId}}`, `{{confirmUrl}}`
+- HTML and plain text versions if needed
+- i18n translations: French, English, Italian, German
+- Template registration in EmailTemplateConfiguration.cs
+
+### 5. Check Trigger Configuration
+- Does the trigger exist in WorkflowTriggerConfiguration.cs?
+- If new trigger:
+  - Define available variables (JSON serialized array)
+  - Add trigger seed data with unique code (kebab-case)
+  - Plan where in code to call `IWorkflowService.TriggerAsync(code, variables)`
+
+### 6. Define Logging & Monitoring
+- What execution events should be logged?
+- How to track workflow success/failure metrics?
+- What observability is needed for debugging?
+
+## SUCCESS METRICS
+- Workflow trigger identified or new trigger planned
+- Available variables from trigger documented
+- Workflow steps sequenced (SendEmail -> Wait -> Condition -> Webhook, etc.)
+- Email templates designed with i18n
+- Trigger configuration understood (existing or new)
+- Integration point in code identified (where TriggerAsync is called)
+- Error handling strategy defined
+
+## NEXT STEP
+Proceed to `./step-01-implementation.md` to implement workflow entity, steps, trigger configuration, email templates, and integration into services with IWorkflowService.