@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/workflow/SKILL.md

@@ -1,196 +0,0 @@
----
-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 |
-
-## WorkflowVersion (R18 — v3.46+) — immutable snapshots
-
-Every time a `Workflow` definition (metadata or steps) is modified, the application creates a `WorkflowVersion` snapshot:
-
-```csharp
-class WorkflowVersion
-{
-    public Guid Id { get; }
-    public Guid WorkflowId { get; }
-    public int VersionNumber { get; }            // Monotonic per workflow, starts at 1
-    public string? ChangeDescription { get; }    // Commit-message style, optional
-    public string SnapshotJson { get; }          // { workflow: {…}, steps: [{…}] } — self-contained
-    public DateTime CreatedAt { get; }
-    public string? CreatedBy { get; }
-}
-```
-
-**Properties:**
-- **Immutable** — once created, never updated. To "revert" a workflow → create a new version derived from a historical snapshot.
-- **Self-contained JSON** — reading a snapshot is a JSON parse, not a query. Snapshots survive schema migration.
-- Stored alongside the live workflow in `wkf_WorkflowVersions`.
-
-**Use cases:**
-- Audit trail (who changed what, when, why)
-- Compare two versions side-by-side in admin UI
-- Roll back a faulty workflow change without losing history
-- Re-execute a paused execution against the version that was active when it started
-
-**DO / DON'T:**
-- DO populate `ChangeDescription` — empty descriptions blind operators
-- DO surface version history in the admin UI on each `Workflow` detail page
-- DON'T mutate or delete versions (the table should have only INSERT permissions in DB)
-- DON'T snapshot on every single field change — batch via "Save" UX action
-
-## WorkflowExecution.PausedAtStepOrder (R6 — Wait step resumption)
-
-`WorkflowExecution` exposes `PausedAtStepOrder` (nullable int) to support `Wait` step suspension:
-
-```csharp
-// Suspend on a Wait step — Hangfire job will resume later
-execution.PauseUntilResume(nextStepOrder: 5);
-// Status becomes WaitingForResume (6), PausedAtStepOrder = 5
-
-// When the Hangfire job fires :
-execution.MarkResumed();
-// Status becomes Running, PausedAtStepOrder reset to null
-// Then the resumer iterates from PausedAtStepOrder onward
-```
-
-**Status enum (with v3.46+ value 6):**
-```csharp
-enum WorkflowExecutionStatus
-{
-    Pending = 0, Running = 1, Completed = 2, Failed = 3,
-    PartiallyCompleted = 4, Cancelled = 5,
-    WaitingForResume = 6  // R6 — Wait step in progress, Hangfire scheduled
-}
-```
-
-**Implementation note:** the Hangfire job is scheduled by `WorkflowExecutionService` when a Wait step is encountered. The job's payload is the execution Id ; on fire, it loads the execution, calls `MarkResumed()`, and continues iterating from `PausedAtStepOrder`.
-
-**DO / DON'T:**
-- DO use `WaitingForResume` exclusively for Wait steps (not for other "in progress with delay" patterns)
-- DO ensure the Hangfire job is idempotent (executions may resume more than once if the job retries)
-- DON'T poll executions in `WaitingForResume` — Hangfire owns the scheduling
-- DON'T remove `PausedAtStepOrder` history from completed executions (audit trail)
-
-## Key Files
-
-| File | Role |
-|------|------|
-| `Domain/Communications/Workflow.cs` | Workflow entity |
-| `Domain/Communications/WorkflowStep.cs` | Step entity |
-| `Domain/Communications/WorkflowTrigger.cs` | Trigger entity |
-| `Domain/Communications/WorkflowVersion.cs` | Immutable snapshot (R18 — v3.46+) |
-| `Domain/Communications/WorkflowExecution.cs` | Execution + `PausedAtStepOrder` (R6 — v3.46+) |
-| `Application/Common/Interfaces/IWorkflowService.cs` | Interface |
-| `Infrastructure/Services/Workflow/WorkflowExecutionService.cs` | Implementation (Hangfire scheduling for Wait) |
-| `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 +0,0 @@
-# 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.

package/templates/skills/workflow/steps/step-01-implementation.md

@@ -1,84 +0,0 @@
-# Workflow - Implementation Details
-
-## Step Types
-
-### 1. SendEmail
-```csharp
-WorkflowStep.CreateEmailStep("Welcome Email", emailTemplateId, order: 1);
-// Config: templateId, recipientVariable, ccEmails
-```
-
-### 2. Wait
-```csharp
-WorkflowStep.CreateWaitStep("Wait 24h", delayMinutes: 1440, order: 2);
-```
-
-### 3. Condition
-```csharp
-WorkflowStep.CreateConditionStep("Check premium", JsonSerializer.Serialize(new {
-    condition = "{{userType}} == 'Premium'",
-    trueStepOrder = 3, falseStepOrder = 4
-}), order: 2);
-// Operators: ==, !=, >, <, contains, &&, ||
-```
-
-### 4. Webhook
-```csharp
-WorkflowStep.CreateWebhookStep("Notify CRM", JsonSerializer.Serialize(new {
-    url = "https://...", method = "POST",
-    headers = new { Authorization = "Bearer {{apiKey}}" },
-    body = new { eventType = "...", userId = "{{userId}}" },
-    retryCount = 3
-}), order: 3);
-```
-
-## Workflow Creation
-
-```csharp
-// 1. Create workflow
-var workflow = Workflow.Create("welcome-sequence", "Welcome Sequence", description, triggerId, null, false, 10);
-
-// 2. Add steps
-workflow.AddStep(WorkflowStep.CreateEmailStep("Welcome", templateId, 1));
-workflow.AddStep(WorkflowStep.CreateWaitStep("Wait 24h", 1440, 2));
-workflow.AddStep(WorkflowStep.CreateEmailStep("Follow-up", followUpTemplateId, 3));
-
-// 3. Seed data (WorkflowConfiguration.cs)
-builder.HasData(new { Id = ..., Code = "welcome-sequence", TriggerId = ..., IsActive = true, ... });
-```
-
-## Triggering
-
-```csharp
-// In Service or Controller
-await _workflowService.TriggerAsync("user.registered", new Dictionary<string, object>
-{
-    ["userId"] = user.Id,
-    ["email"] = user.Email,
-    ["confirmUrl"] = GenerateConfirmUrl(user.Id)
-}, language: "en", ct);
-```
-
-## Email Templates
-
-### Structure
-```csharp
-EmailTemplate: Code, Name, Category, IsActive, Translations[]
-EmailTemplateTranslation: LanguageCode, Subject, HtmlBody, TextBody
-```
-
-### Syntax (Handlebars)
-```html
-<h1>Welcome {{userName}}!</h1>
-{{#if isPremium}}<p>Thank you Premium member!</p>{{else}}<p>Premium offers...</p>{{/if}}
-{{#each items}}<li>{{this.name}}</li>{{/each}}
-```
-
-## Frontend API
-
-```typescript
-workflowsApi.getAll() / getById(id) / create(data) / update(id, data)
-workflowsApi.getTriggers()
-workflowsApi.addStep(workflowId, step) / updateStep / deleteStep / reorderSteps
-workflowsApi.execute(workflowId, variables)
-```