@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/efcore/references/zero-downtime-patterns.md

@@ -1,229 +0,0 @@
-<overview>
-Zero-downtime migration patterns for EF Core. Use when a migration contains destructive operations (column rename, type change, column drop) that could cause downtime during deployment.
-
-These patterns apply to production deployments where the application runs continuously. For development environments, standard migrations are sufficient.
-
-> **Exception to "no raw SQL" rule:** `migrationBuilder.Sql(...)` is authorized ONLY for data backfill operations within zero-downtime migration patterns (e.g., `UPDATE ... SET NewCol = OldCol`). Never use it for DDL (CREATE/ALTER/DROP) — those must go through EF Core Fluent API or `SqlObjects/`.
-</overview>
-
-<when_to_use>
-## When These Patterns Apply
-
-**Destructive operations requiring zero-downtime strategy:**
-- `RenameColumn` / `RenameTable`
-- `DropColumn` / `DropTable`
-- `AlterColumn` (type change, nullability change)
-
-**Safe operations (no special handling needed):**
-- `AddColumn` (nullable or with default value)
-- `CreateTable`
-- `CreateIndex`
-- `AddForeignKey`
-</when_to_use>
-
-<column_rename>
-## Pattern 1: Column Rename (5 phases)
-
-A column rename cannot be done atomically without downtime. Use a phased approach across multiple deployments.
-
-### Phase 1 - Add New Column (Migration 1)
-```csharp
-protected override void Up(MigrationBuilder migrationBuilder)
-{
-    migrationBuilder.AddColumn<string>(
-        name: "FullName",
-        table: "auth_users",
-        schema: "core",
-        type: "nvarchar(256)",
-        nullable: true); // Must be nullable initially
-
-    // Backfill existing data
-    migrationBuilder.Sql(
-        "UPDATE core.auth_users SET FullName = DisplayName WHERE FullName IS NULL");
-}
-
-protected override void Down(MigrationBuilder migrationBuilder)
-{
-    migrationBuilder.DropColumn(name: "FullName", table: "auth_users", schema: "core");
-}
-```
-
-### Phase 2 - Dual-Write Code (Application deployment)
-```csharp
-// Entity writes to BOTH columns during transition
-public void UpdateName(string name)
-{
-    DisplayName = name;  // Old column
-    FullName = name;     // New column
-}
-```
-
-### Phase 3 - Backfill Remaining Data (Migration 2, optional)
-```csharp
-protected override void Up(MigrationBuilder migrationBuilder)
-{
-    // Catch any rows missed during dual-write transition
-    migrationBuilder.Sql(
-        "UPDATE core.auth_users SET FullName = DisplayName WHERE FullName IS NULL");
-
-    // Make new column non-nullable
-    migrationBuilder.AlterColumn<string>(
-        name: "FullName",
-        table: "auth_users",
-        schema: "core",
-        type: "nvarchar(256)",
-        nullable: false,
-        defaultValue: "");
-}
-```
-
-### Phase 4 - Switch Reads (Application deployment)
-```csharp
-// Entity now reads from new column only
-public string Name => FullName;
-```
-
-### Phase 5 - Drop Old Column (Migration 3)
-```csharp
-protected override void Up(MigrationBuilder migrationBuilder)
-{
-    migrationBuilder.DropColumn(name: "DisplayName", table: "auth_users", schema: "core");
-}
-
-protected override void Down(MigrationBuilder migrationBuilder)
-{
-    migrationBuilder.AddColumn<string>(
-        name: "DisplayName",
-        table: "auth_users",
-        schema: "core",
-        type: "nvarchar(256)",
-        nullable: false,
-        defaultValue: "");
-
-    migrationBuilder.Sql(
-        "UPDATE core.auth_users SET DisplayName = FullName");
-}
-```
-</column_rename>
-
-<column_type_change>
-## Pattern 2: Column Type Change (4 phases)
-
-Changing a column type (e.g., `int` to `string`, `string` to `decimal`) follows the same dual-column approach.
-
-### Phase 1 - Add New Typed Column
-```csharp
-protected override void Up(MigrationBuilder migrationBuilder)
-{
-    migrationBuilder.AddColumn<decimal>(
-        name: "PriceDecimal",
-        table: "extensions_products",
-        schema: "extensions",
-        type: "decimal(18,2)",
-        nullable: true);
-
-    migrationBuilder.Sql(
-        "UPDATE extensions.extensions_products SET PriceDecimal = CAST(Price AS decimal(18,2))");
-}
-```
-
-### Phase 2 - Dual-Write in Code
-### Phase 3 - Make Non-Nullable + Switch Reads
-### Phase 4 - Drop Old Column
-
-Same phased pattern as column rename.
-</column_type_change>
-
-<large_table_operations>
-## Pattern 3: Large Table Backfill
-
-For tables with millions of rows, batch the backfill to avoid lock escalation.
-
-```csharp
-protected override void Up(MigrationBuilder migrationBuilder)
-{
-    migrationBuilder.AddColumn<string>(
-        name: "NormalizedEmail",
-        table: "auth_users",
-        schema: "core",
-        type: "nvarchar(256)",
-        nullable: true);
-
-    // Batched backfill to avoid table locks
-    migrationBuilder.Sql(@"
-        DECLARE @BatchSize INT = 5000;
-        DECLARE @RowsAffected INT = 1;
-
-        WHILE @RowsAffected > 0
-        BEGIN
-            UPDATE TOP (@BatchSize) core.auth_users
-            SET NormalizedEmail = UPPER(Email)
-            WHERE NormalizedEmail IS NULL;
-
-            SET @RowsAffected = @@ROWCOUNT;
-        END
-    ");
-}
-```
-
-**Rules:**
-- Batch size: 1,000-10,000 rows depending on table width
-- Always include a `WHERE` clause to avoid re-processing
-- Monitor transaction log growth during execution
-- Run during low-traffic windows if possible
-</large_table_operations>
-
-<rollback_strategy>
-## Rollback Strategies
-
-### Migration Down() Method
-Every migration MUST have a functional `Down()` method for rollback:
-
-```csharp
-protected override void Down(MigrationBuilder migrationBuilder)
-{
-    // Reverse the operation
-    migrationBuilder.DropColumn(name: "NewColumn", table: "auth_users", schema: "core");
-}
-```
-
-### Rollback Command
-```bash
-# Rollback to specific migration
-dotnet ef database update {PreviousMigrationName} \
-  --context $DBCONTEXT \
-  --project $INFRA_PROJECT \
-  --startup-project $STARTUP_PROJECT
-```
-
-### Pre-Deployment Checklist
-- [ ] `Down()` method tested locally
-- [ ] Database backup taken before deployment
-- [ ] Application compatible with both old and new schema (dual-write phase)
-- [ ] Rollback procedure documented in deployment notes
-- [ ] Monitoring alerts configured for error spike
-</rollback_strategy>
-
-<decision_guide>
-## Decision Guide
-
-| Operation | Risk | Strategy |
-|-----------|------|----------|
-| Add nullable column | Low | Standard migration |
-| Add column with default | Low | Standard migration |
-| Create table | Low | Standard migration |
-| Create index | Medium | `CREATE INDEX CONCURRENTLY` if supported |
-| Rename column | High | 5-phase pattern |
-| Change column type | High | 4-phase pattern |
-| Drop column | High | Verify no reads, then drop |
-| Drop table | High | Verify no references, then drop |
-| Make column non-nullable | Medium | Ensure no NULL values exist first |
-
-**Rule of thumb:** If the operation would cause a `SqlException` on running code, use a phased approach.
-</decision_guide>
-
-<sources>
-- EF Core Migrations documentation
-- Zero-Downtime Deployments with EF Core (Microsoft patterns)
-- Blue-Green Deployment pattern (Martin Fowler)
-</sources>

package/templates/skills/explore/SKILL.md

@@ -1,98 +0,0 @@
----
-name: explore
-description: Deep codebase exploration to answer specific questions
-argument-hint: <question>
-context: fork
-agent: Explore
-allowed-tools: Read, Grep, Glob, WebSearch, WebFetch
----
-
-<objective>
-Answer questions about the codebase through systematic investigation using direct search tools.
-
-**Note:** This skill runs in an isolated context. Use Grep, Glob, and Read directly - do NOT launch Task agents.
-</objective>
-
-<quick_start>
-```bash
-/explore where is authentication handled?
-/explore how does the payment flow work?
-/explore what patterns are used for validation?
-```
-</quick_start>
-
-## Task
-Research the following question: $ARGUMENTS
-
-<workflow>
-
-## 1. Parse Question
-
-- Extract key terms and concepts from the question
-- Identify file types, patterns, or areas to search
-- Determine if web research is needed
-
-## 2. Search Codebase (Direct Tools)
-
-Use direct search tools **in parallel** where possible:
-
-**File discovery:**
-```
-Glob: pattern="**/*{keyword}*" to find related files
-```
-
-**Code search:**
-```
-Grep: pattern="{keyword}" to find content matches
-Grep: pattern="class {Name}" or "function {name}" for implementations
-```
-
-**Targeted reading:**
-```
-Read: the most relevant 3-5 files discovered
-```
-
-**Web research** (if external context needed):
-```
-WebSearch: "{question} best practices"
-WebFetch: documentation URLs found in the codebase
-```
-
-**CRITICAL**: Run independent searches in parallel for speed.
-
-## 3. Analyze Findings
-
-- Read relevant files found by searches
-- Trace relationships between files
-- Identify patterns and conventions
-- Note file paths with line numbers (e.g., `src/app.ts:42`)
-
-## 4. Answer Question
-
-Provide comprehensive response:
-- Direct answer to the question
-- Supporting evidence with file references
-- Code examples if relevant
-- Architectural context when useful
-
-</workflow>
-
-<execution_rules>
-
-- **PARALLEL SEARCH**: Run independent Grep/Glob searches simultaneously
-- **CITE SOURCES**: Always reference file paths and line numbers
-- **STAY FOCUSED**: Only explore what's needed to answer the question
-- **BE THOROUGH**: Don't stop at first match - gather complete context
-- **NO TASK AGENTS**: Use Grep, Glob, Read, WebSearch, WebFetch directly
-
-</execution_rules>
-
-<priority>
-Accuracy > Speed > Brevity. Provide complete answers with evidence.
-</priority>
-
-<success_criteria>
-- Question answered with supporting file references and line numbers
-- All relevant code patterns and conventions identified
-- Dependencies and connections mapped
-</success_criteria>

package/templates/skills/feature-full/SKILL.md

@@ -1,111 +0,0 @@
----
-name: feature-full
-description: |
-  Creates a complete SmartStack feature with all integrations.
-  Use this skill when:
-  - User wants to create a complete feature from A to Z
-  - User mentions "oneshot", "complete feature", "full-stack"
-  - Creating a module with notifications, workflows and/or AI
-  - Need for complete user experience
-  Scope: Domain -> Application -> Infrastructure -> API -> Web + Notifications + Workflows + AI
-disable-model-invocation: true
----
-
-# Skill Feature Full SmartStack
-
-> **OneShot Development:** Orchestrates all skills for a complete feature.
-
-**Reference:** [_shared.md](../_shared.md) for architecture, permissions, i18n
-
-## When This Skill Activates
-
-| Trigger | Example |
-|---------|---------|
-| Complete feature | "Create a product management module" |
-| Full-stack | "Create the backend and frontend for..." |
-| Integration | "With notifications and automated emails" |
-
-## Complete Flow
-
-```
-DOMAIN -> APPLICATION -> INFRASTRUCTURE -> API -> WEB
-                      + NOTIFICATIONS + WORKFLOWS + AI
-```
-
-## Phase 1: Analysis
-
-```
-- Module/functionality?
-- Entities? CRUD operations? Business rules?
-- Notifications required? Automated emails? AI?
-- Display: Cards/Table/Kanban? Permissions?
-```
-
-## Phases 2-7: Implementation
-
-Start with [steps/step-00-init.md](steps/step-00-init.md) to analyze requirements and existing patterns, then proceed to [steps/step-01-implementation.md](steps/step-01-implementation.md) for detailed code templates covering:
-- Phase 2: Domain (Entity + Factory + Behaviors + Enum)
-- Phase 3: Application (Interface + DTOs + Permissions)
-- Phase 4: Infrastructure (EF Config + Service + DI)
-- Phase 5: API (Controller + Authorize + RequirePermission)
-- Phase 6: Frontend (API + Hook + Page + Routes)
-- Phase 7: Integrations (Notifications + Workflows + AI)
-
-## Complete Checklist
-
-### Backend
-```
-- Domain: Entity + Factory + Behaviors + Enum + IAuditableEntity
-- Application: Interface + DTOs + Permissions (2 files!)
-- Infrastructure: EF Config + Service + DI + DbSet + Migration
-- API: Controller + Authorize + RequirePermission + ProducesResponseType
-```
-
-### Frontend
-```
-- {module}Api.ts + use{Module}.ts (with SignalR) + {Module}Page.tsx + {Module}Form.tsx
-- i18n: fr, en, it, de
-- Nested routes in App.tsx
-```
-
-### Integrations
-```
-- Notifications: NotificationType + SendNotificationAsync + useSignalR
-- Workflows: Trigger + Workflow + TriggerAsync
-- AI: Prompt + OutputSchema + ExecutePromptAsync
-```
-
-### Validation
-```
-- dotnet build + npm run build + npm run lint OK
-```
-
-## Orchestrated Skills
-
-| Skill | Phase |
-|-------|-------|
-| `/application` | 2-6 |
-| `/controller` | 5 |
-| `/notification` | 7.1 |
-| `/workflow` | 7.2 |
-| `/ai-prompt` | 7.3 |
-| `/ui-components` | 6 |
-| `/efcore migration` | 4 |
-
-## Absolute Rules
-
-| DO | DON'T |
-|----|-------|
-| Layered architecture | Direct frontend DB access |
-| Entity Factory Methods | Hardcoded permission strings |
-| Permissions 2 files | Flat routes |
-| SignalR hooks | Skip i18n 4 languages |
-| ProducesResponseType | Skip logging |
-
-<success_criteria>
-- All layers created: Domain, Infrastructure, Application, API, Frontend
-- Navigation, permissions, and roles seed data generated via MCP
-- EF Core migration created and applied
-- Tests pass (unit + integration)
-- i18n translations in 4 languages
-</success_criteria>

package/templates/skills/feature-full/steps/step-00-init.md

@@ -1,57 +0,0 @@
-# Step 0: Initialization
-
-## YOUR TASK
-Gather requirements and analyze existing code patterns before implementing a complete full-stack feature.
-
-## EXECUTION SEQUENCE
-
-### 1. Identify Feature Scope
-- What is the main entity/aggregate? (e.g., Product, Invoice, Support Ticket)
-- What are the CRUD operations required? (Create, Read, Update, Delete, Archive)
-- What business rules apply? (validations, state transitions, constraints)
-- What user permissions are needed? (who can create/edit/delete/view)
-- What notifications/workflows are required? (emails, webhooks, automation)
-- Does AI play a role? (content generation, analysis, validation)
-
-### 2. Analyze Existing Code Patterns
-- Review `Domain/` for similar entity structures, factories, and behaviors
-- Check `Application/` for existing service interfaces and DTOs
-- Examine `Infrastructure/` for EF Core configurations and patterns
-- Look at `API/Controllers/` for authorization and RequirePermission attributes
-- Study `web/` for similar pages, forms, and i18n implementations
-- Identify reusable components and patterns to follow
-
-### 3. Define Data Model
-- Entity properties and types
-- Enums for status, types, and classifications
-- Relationships (OneToMany, ManyToMany, etc.)
-- Audit requirements (CreatedAt, CreatedBy, ModifiedAt, ModifiedBy)
-- Soft delete or permanent delete?
-
-### 4. Plan Implementation Phases
-- **Phase 2:** Domain entity, factory method, behaviors, enums, IAuditableEntity
-- **Phase 3:** Application service interface, DTOs, permissions (create + assign permissions files)
-- **Phase 4:** Infrastructure (EF Config, concrete service, DI registration, DbSet, migration)
-- **Phase 5:** API controller with Authorize, RequirePermission, ProducesResponseType
-- **Phase 6:** Frontend (API client, custom hook with SignalR, page, form, routing, i18n for 4 languages)
-- **Phase 7:** Integrations (notifications, workflows, AI if applicable)
-
-### 5. Validate Against Architecture Rules
-- Confirm layered architecture is followed (no frontend-to-DB shortcuts)
-- Verify entity factory methods are used (no direct constructors in services)
-- Check permissions split across 2 files (Create/List/Read/Update/Delete vs Assign)
-- Plan SignalR hooks for real-time updates
-- Define ProducesResponseType for all endpoints
-- Plan i18n for English, French, Italian, German
-
-## SUCCESS METRICS
-- Feature scope clearly defined and bounded
-- All required CRUD operations identified
-- Business rules documented
-- Permissions mapped to roles
-- Implementation plan with all 7 phases outlined
-- Existing code patterns understood and will be followed
-- Data model defined with relationships and audit requirements
-
-## NEXT STEP
-Proceed to `./step-01-implementation.md` to execute all phases (Domain, Application, Infrastructure, API, Frontend, Integrations) with code templates and orchestration of child skills.

package/templates/skills/feature-full/steps/step-01-implementation.md

@@ -1,133 +0,0 @@
-# Feature Full - Implementation Phases
-
-## Phase 2: Domain
-
-```csharp
-// {Entity}.cs - Factory Method + Behaviors
-public class {Entity} : BaseEntity, IAuditableEntity
-{
-    public string Name { get; private set; }
-    public {Entity}Status Status { get; private set; }
-    private {Entity}() { }
-    public static {Entity} Create(string name, Guid createdById) =>
-        new { Id = Guid.NewGuid(), Name = name, Status = {Entity}Status.Active, ... };
-    public void Update(string name) => Name = name ?? throw new DomainException("Name required");
-}
-
-// {Entity}Status.cs
-public enum {Entity}Status { Active = 0, Inactive = 1, Archived = 2 }
-```
-
-## Phase 3: Application
-
-```csharp
-// I{Entity}Service.cs
-Task<PaginatedResult<{Entity}Dto>> GetAllAsync(...);
-Task<{Entity}Dto> CreateAsync(Create{Entity}Request request, CancellationToken ct);
-
-// DTOs
-public record {Entity}Dto(Guid Id, string Name, string Status, DateTime CreatedAt);
-public record Create{Entity}Request(string Name, string? Description);
-
-// Permissions.cs + PermissionConfiguration.cs (2 files!)
-public const string View = "{area}.{module}.read";
-```
-
-## Phase 4: Infrastructure
-
-```csharp
-// {Entity}Configuration.cs
-builder.ToTable("{Entity}s", "{schema}");
-builder.Property(x => x.Name).HasMaxLength(200).IsRequired();
-
-// {Entity}Service.cs with Notifications
-public async Task<{Entity}Dto> CreateAsync(...) {
-    var entity = {Entity}.Create(request.Name, _currentUser.Id);
-    _context.{Entity}s.Add(entity);
-    await _context.SaveChangesAsync(ct);
-    await _notificationService.SendNotificationAsync(_currentUser.Id,
-        NotificationType.{Entity}Created, "Created", $"{entity.Name} created",
-        relatedEntityType: nameof({Entity}), relatedEntityId: entity.Id, ct);
-    return MapToDto(entity);
-}
-
-// DependencyInjection.cs
-services.AddScoped<I{Entity}Service, {Entity}Service>();
-```
-
-## Phase 5: API
-
-```csharp
-[ApiController]
-[NavRoute("{area}.{module}")]
-[Microsoft.AspNetCore.Authorization.Authorize]
-[Produces("application/json")]
-[Tags("{EntityPlural}")]
-public class {Entity}Controller : ControllerBase
-{
-    private readonly ISender _mediator;
-
-    [HttpGet]
-    [RequirePermission(Permissions.{Area}.{Module}.View)]
-    [ProducesResponseType(typeof(PaginatedResult<{Entity}Dto>), StatusCodes.Status200OK)]
-    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
-    [ProducesResponseType(StatusCodes.Status403Forbidden)]
-    public async Task<ActionResult<PaginatedResult<{Entity}Dto>>> GetAll(...);
-
-    [HttpPost]
-    [RequirePermission(Permissions.{Area}.{Module}.Create)]
-    [ProducesResponseType(typeof({Entity}Dto), StatusCodes.Status201Created)]
-    [ProducesResponseType(StatusCodes.Status400BadRequest)]
-    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
-    [ProducesResponseType(StatusCodes.Status403Forbidden)]
-    public async Task<ActionResult<{Entity}Dto>> Create([FromBody] request, CancellationToken ct);
-}
-```
-
-## Phase 6: Frontend
-
-```typescript
-// {module}Api.ts
-export const {module}Api = {
-  getAll: (page, pageSize, search?) => apiClient.get<PaginatedResult<{Entity}Dto>>('/{area}/{module}', { params }),
-  create: (data) => apiClient.post<{Entity}Dto>('/{area}/{module}', data),
-};
-
-// use{Module}.ts with SignalR
-export function use{Module}() {
-  const queryClient = useQueryClient();
-  useSignalR({ onNotification: (n) => {
-    if (n.relatedEntityType === '{Entity}') queryClient.invalidateQueries(['{module}']);
-  }});
-  const createMutation = useMutation({ mutationFn: {module}Api.create, onSuccess: () => ... });
-  return { create: createMutation.mutate, ... };
-}
-
-// {Module}Page.tsx with EntityCard
-<EntityCard title={item.name} actions={[{ label: 'View', onClick: () => navigate(...) }]} />
-
-// Routes (nested mandatory)
-<Route path="{area}"><Route path="{module}"><Route index element={<{Module}Page />} /></Route></Route>
-```
-
-## Phase 7: Integrations
-
-### Notifications
-```csharp
-await _notificationService.SendNotificationAsync(userId, NotificationType.{Entity}Created,
-    title, message, relatedEntityType: nameof({Entity}), relatedEntityId: entity.Id, actionUrl);
-```
-
-### Workflow Email
-```csharp
-// 1. WorkflowTriggerConfiguration.cs: new { Code = "{entity}.created", ... }
-// 2. WorkflowConfiguration.cs: new { TriggerId = ..., ... }
-// 3. Service:
-await _workflowService.TriggerAsync("{entity}.created", new Dictionary<string, object>{...});
-```
-
-### AI
-```csharp
-var result = await _aiCompletionService.ExecutePromptByCodeWithValidationAsync<{Entity}AnalysisResult>(
-    "{entity}-analyzer", new Dictionary<string, object>{ ["name"] = entity.Name }, ct);
-```