@atlashub/smartstack-cli 1.37.0 → 2.1.0

package/templates/skills/cc-skill/templates/skill-progressive.md

@@ -0,0 +1,102 @@
+# Template: Progressive Step Loading Skill
+
+Use this template when creating a complex skill with multiple phases that benefit from progressive step loading.
+
+## Generated SKILL.md format:
+
+```yaml
+---
+name: {{SKILL_NAME}}
+description: |
+  {{DESCRIPTION}}
+{{#if ARGUMENT_HINT}}
+argument-hint: "{{ARGUMENT_HINT}}"
+{{/if}}
+{{#if DISABLE_MODEL_INVOCATION}}
+disable-model-invocation: true
+{{/if}}
+{{#if MODEL}}
+model: {{MODEL}}
+{{/if}}
+---
+
+<objective>
+{{OBJECTIVE}}
+</objective>
+
+<quick_start>
+
+` ` `bash
+/{{SKILL_NAME}} {{EXAMPLE_ARGS_1}}
+/{{SKILL_NAME}} {{EXAMPLE_ARGS_2}}
+` ` `
+
+</quick_start>
+
+<parameters>
+
+<flags>
+| Flag | Description |
+|------|-------------|
+| {{FLAG_SHORT}} | {{FLAG_DESCRIPTION}} |
+</flags>
+
+<examples>
+` ` `bash
+/{{SKILL_NAME}} {{EXAMPLE_1}}
+/{{SKILL_NAME}} {{EXAMPLE_2}}
+` ` `
+</examples>
+
+</parameters>
+
+<workflow>
+{{#each STEPS}}
+{{@index_plus_one}}. {{this.title}}
+{{/each}}
+</workflow>
+
+<state_variables>
+| Variable | Type | Description |
+|----------|------|-------------|
+{{#each STATE_VARS}}
+| `{ {{this.name}} }` | {{this.type}} | {{this.description}} |
+{{/each}}
+</state_variables>
+
+<entry_point>
+
+**FIRST ACTION:** Load `steps/step-00-init.md`
+
+</entry_point>
+
+<step_files>
+| Step | File | Purpose |
+|------|------|---------|
+{{#each STEPS}}
+| {{this.number}} | `steps/step-{{this.number}}-{{this.name}}.md` | {{this.description}} |
+{{/each}}
+</step_files>
+
+<execution_rules>
+- **Load one step at a time** - Progressive loading to minimize context
+- **Persist state variables** across all steps
+- **Follow next_step directive** at end of each step
+- {{RULE_1}}
+- {{RULE_2}}
+</execution_rules>
+
+<success_criteria>
+- {{CRITERIA_1}}
+- {{CRITERIA_2}}
+- {{CRITERIA_3}}
+</success_criteria>
+```
+
+## Notes:
+- Keep SKILL.md under 500 lines (detailed content goes in steps)
+- Each step should be self-contained
+- State variables persist across all steps
+- Always start with step-00-init for argument parsing
+- Always end with a validation/summary step
+- Best for: workflows, generators, multi-phase operations

package/templates/skills/cc-skill/templates/skill-simple.md

@@ -0,0 +1,75 @@
+# Template: Simple Skill
+
+Use this template when creating a skill that fits in a single SKILL.md file without progressive step loading.
+
+## Generated SKILL.md format:
+
+```yaml
+---
+name: {{SKILL_NAME}}
+description: |
+  {{DESCRIPTION}}
+{{#if ARGUMENT_HINT}}
+argument-hint: "{{ARGUMENT_HINT}}"
+{{/if}}
+{{#if DISABLE_MODEL_INVOCATION}}
+disable-model-invocation: true
+{{/if}}
+{{#if USER_INVOCABLE_FALSE}}
+user-invocable: false
+{{/if}}
+{{#if MODEL}}
+model: {{MODEL}}
+{{/if}}
+---
+
+<objective>
+{{OBJECTIVE}}
+</objective>
+
+<quick_start>
+
+` ` `bash
+/{{SKILL_NAME}} {{EXAMPLE_ARGS_1}}
+/{{SKILL_NAME}} {{EXAMPLE_ARGS_2}}
+` ` `
+
+</quick_start>
+
+## Task
+{{TASK_DESCRIPTION}}
+
+$ARGUMENTS
+
+<workflow>
+
+## 1. {{FIRST_PHASE}}
+{{FIRST_PHASE_INSTRUCTIONS}}
+
+## 2. {{SECOND_PHASE}}
+{{SECOND_PHASE_INSTRUCTIONS}}
+
+## 3. {{THIRD_PHASE}}
+{{THIRD_PHASE_INSTRUCTIONS}}
+
+</workflow>
+
+<execution_rules>
+- {{RULE_1}}
+- {{RULE_2}}
+- {{RULE_3}}
+</execution_rules>
+
+<success_criteria>
+- {{CRITERIA_1}}
+- {{CRITERIA_2}}
+- {{CRITERIA_3}}
+</success_criteria>
+```
+
+## Notes:
+- Keep total lines under 500
+- Description should include trigger keywords for auto-detection
+- Use $ARGUMENTS to reference user input
+- Workflow steps are inline (no external step files)
+- Best for: linting, simple generation, knowledge injection, quick commands

package/templates/skills/cc-skill/templates/step-template.md

@@ -0,0 +1,82 @@
+# Template: Step File
+
+Standard template for a progressive step loading step file.
+
+## Generated step file format:
+
+```yaml
+---
+name: step-{{NUMBER}}-{{NAME}}
+description: {{DESCRIPTION}}
+{{#if NEXT_STEP}}
+next_step: steps/step-{{NEXT_NUMBER}}-{{NEXT_NAME}}.md
+{{/if}}
+---
+
+# Step {{N}}: {{TITLE}}
+
+## MANDATORY EXECUTION RULES:
+- {{RULE_1}}
+- {{RULE_2}}
+- FORBIDDEN to proceed to next step until this step is complete
+
+## YOUR TASK:
+{{TASK_DESCRIPTION}}
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. {{SUBTASK_1_TITLE}}
+{{SUBTASK_1_INSTRUCTIONS}}
+
+### 2. {{SUBTASK_2_TITLE}}
+{{SUBTASK_2_INSTRUCTIONS}}
+
+### 3. Show Summary
+Display step results in compact format (table preferred).
+
+---
+
+## SUCCESS METRICS:
+- {{METRIC_1}}
+- {{METRIC_2}}
+- Output is compact and scannable
+
+## NEXT STEP:
+{{#if NEXT_STEP}}
+After showing summary, proceed directly to `./step-{{NEXT_NUMBER}}-{{NEXT_NAME}}.md`
+{{else}}
+This is the final step. Skill execution is complete.
+{{/if}}
+```
+
+## Step Types:
+
+### Init Step (step-00)
+- Parse arguments and flags
+- Validate required inputs
+- Initialize state variables
+- Show configuration summary
+
+### Analysis Step
+- Read files, search codebase
+- Extract patterns and information
+- Show findings summary
+
+### Generation Step
+- Use templates or references
+- Create/modify files
+- Show what was generated
+
+### Validation Step (usually last)
+- Check generated output
+- Verify conventions
+- Display final summary and next steps
+
+## Rules:
+- Each step MUST be self-contained (loadable independently)
+- State variables persist via conversation context
+- Always show compact summary before proceeding
+- Always reference next step at the end
+- Last step must NOT have next_step in frontmatter

package/templates/skills/check-version/SKILL.md

@@ -1,9 +1,15 @@
 ---
 name: check-version
 description: Verify version alignment between package.json and documentation
+context: fork
+agent: Explore
 model: haiku
+allowed-tools: Read, Glob, Grep, Bash
 ---
 
+## Current state (auto-injected)
+- Package version: !`node -p "require('./package.json').version" 2>/dev/null || echo "no package.json"`
+
 <objective>
 Verify that the version in `package.json` is aligned with all documentation files in `.documentation/`.
 Use before releases or as part of release process to ensure documentation is up-to-date.

package/templates/skills/controller/templates.md

@@ -1461,8 +1461,90 @@ public record BulkUpdate{Entity}Request(
   □ EF Core Migration created
   □ Migration applied
 
+□ API Versioning (if applicable)
+  □ See API Versioning section below
+
 □ Correct Permission Level
   □ Module (Level 3) - For main CRUD
   □ Section (Level 4) - If sub-pages with different permissions
   □ Resource (Level 5) - If sub-resources with distinct permissions
 ```
+
+---
+
+## API Versioning
+
+**SmartStack convention:** Header-based versioning using `Asp.Versioning.Mvc`.
+
+### Setup
+
+```csharp
+// Program.cs
+builder.Services.AddApiVersioning(options =>
+{
+    options.DefaultApiVersion = new ApiVersion(1, 0);
+    options.AssumeDefaultVersionWhenUnspecified = true;
+    options.ReportApiVersions = true; // Adds api-supported-versions header
+    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
+})
+.AddApiExplorer(options =>
+{
+    options.GroupNameFormat = "'v'VVV";
+    options.SubstituteApiVersionInUrl = true;
+});
+```
+
+### Controller Usage
+
+```csharp
+// v1 - Default (no attribute needed if only one version exists)
+[ApiController]
+[ApiVersion("1.0")]
+[NavRoute("business.crm.contacts")]
+public class ContactsController : ControllerBase
+{
+    [HttpGet]
+    [RequirePermission(Permissions.Business.Crm.Contacts.Read)]
+    public async Task<ActionResult<PagedResult<ContactDto>>> GetAll(...) { ... }
+}
+
+// v2 - Breaking changes only
+[ApiController]
+[ApiVersion("2.0")]
+[NavRoute("business.crm.contacts")]
+public class ContactsV2Controller : ControllerBase
+{
+    [HttpGet]
+    [RequirePermission(Permissions.Business.Crm.Contacts.Read)]
+    public async Task<ActionResult<PagedResult<ContactV2Dto>>> GetAll(...) { ... }
+}
+```
+
+### Deprecation
+
+```csharp
+[ApiVersion("1.0", Deprecated = true)] // Adds api-deprecated-versions header
+[ApiVersion("2.0")]
+public class ContactsController : ControllerBase
+{
+    [HttpGet]
+    [MapToApiVersion("1.0")]
+    public async Task<ActionResult<PagedResult<ContactDto>>> GetAllV1(...) { ... }
+
+    [HttpGet]
+    [MapToApiVersion("2.0")]
+    public async Task<ActionResult<PagedResult<ContactV2Dto>>> GetAllV2(...) { ... }
+}
+```
+
+### SmartStack Versioning Rules
+
+| Rule | Detail |
+|------|--------|
+| Default version | `1.0` (assumed when no header sent) |
+| Version header | `api-version: 2.0` |
+| When to version | Breaking changes only (field removal, type change, behavior change) |
+| Non-breaking changes | Add to existing version (new fields, new endpoints) |
+| Naming | `V2Controller` suffix or `[MapToApiVersion]` in same controller |
+| Deprecation | Mark old version deprecated, maintain for 2 releases minimum |
+| Documentation | Both versions documented via `[ProducesResponseType]` |

package/templates/skills/debug/SKILL.md

@@ -2,8 +2,12 @@
 name: debug
 description: Systematic bug debugging with deep analysis and resolution
 argument-hint: <log|error|problem-description>
+model: opus
 ---
 
+## Bug to investigate
+$ARGUMENTS
+
 <objective>
 Follow an ultra-deep analysis workflow to identify, understand, and resolve bugs.
 **ULTRA THINK** at each phase transition.

package/templates/skills/documentation/SKILL.md

@@ -9,6 +9,7 @@ description: |
   - After implementing a feature to generate its documentation
   Types: user module, developer tools, database ERD, testing tools
 argument-hint: "<module-name> [--type user|developer|database|testing|update]"
+model: sonnet
 ---
 
 <objective>

package/templates/skills/efcore/SKILL.md

@@ -2,8 +2,13 @@
 name: efcore
 description: EF Core Commands - Migration and database management
 argument-hint: "<command> [options]"
+disable-model-invocation: true
 ---
 
+## Current state (auto-injected)
+- Branch: !`git branch --show-current`
+- Recent migrations: !`find . -path "*/Migrations/*.cs" -not -name "*Designer*" -not -name "*Snapshot*" 2>/dev/null | sort | tail -5 || echo "none found"`
+
 <objective>
 Manage EF Core migrations and database operations with progressive step loading, MCP validation, and DbContext auto-detection.
 </objective>

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

@@ -0,0 +1,227 @@
+<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.
+</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/efcore/steps/db/step-deploy.md

@@ -189,18 +189,39 @@ Next: /efcore db-status, /efcore db-seed
 
 ## BOTH CONTEXTS:
 
-If "Both" selected for DbContext:
+**If `RUN_BOTH=true` (auto-detected for client projects with SmartStack NuGet):**
+
+Run the full deploy sequence (steps 2-6) TWICE, in order:
 
 ```bash
-# Deploy CoreDbContext first
+# 1. Deploy CoreDbContext first (system tables: Users, Roles, Tenants...)
+echo "=== Deploying CoreDbContext (core schema) ==="
 DBCONTEXT="CoreDbContext"
-# ... run deploy ...
+SCHEMA="core"
+# Run steps 2-6 with CoreDbContext...
 
-# Then ExtensionsDbContext
+dotnet ef database update \
+  --context "CoreDbContext" \
+  --project "$INFRA_PROJECT" \
+  --startup-project "$STARTUP_PROJECT" \
+  --verbose
+
+# 2. Then ExtensionsDbContext (client tables)
+echo ""
+echo "=== Deploying ExtensionsDbContext (extensions schema) ==="
 DBCONTEXT="ExtensionsDbContext"
-# ... run deploy ...
+SCHEMA="extensions"
+# Run steps 2-6 with ExtensionsDbContext...
+
+dotnet ef database update \
+  --context "ExtensionsDbContext" \
+  --project "$INFRA_PROJECT" \
+  --startup-project "$STARTUP_PROJECT" \
+  --verbose
 ```
 
+**Order matters:** Core MUST be deployed first (Extensions may have foreign keys to Core tables).
+
 ---
 
 ## COMPLETION:

package/templates/skills/efcore/steps/migration/step-03-validate.md

@@ -51,6 +51,25 @@ echo "  Tables:      $UP_TABLES"
 echo "  Columns:     $UP_COLUMNS"
 echo "  Indexes:     $UP_INDEXES"
 echo "  Foreign Keys:$UP_FOREIGN"
+
+# Detect destructive operations
+DROP_COL=$(grep -c "DropColumn" "$MIGRATION_FILE" || echo "0")
+RENAME_COL=$(grep -c "RenameColumn" "$MIGRATION_FILE" || echo "0")
+ALTER_COL=$(grep -c "AlterColumn" "$MIGRATION_FILE" || echo "0")
+DROP_TABLE=$(grep -c "DropTable" "$MIGRATION_FILE" || echo "0")
+DESTRUCTIVE=$((DROP_COL + RENAME_COL + ALTER_COL + DROP_TABLE))
+
+if [ "$DESTRUCTIVE" -gt 0 ]; then
+  echo ""
+  echo "WARNING: Destructive operations detected:"
+  [ "$DROP_COL" -gt 0 ] && echo "  DropColumn:   $DROP_COL"
+  [ "$RENAME_COL" -gt 0 ] && echo "  RenameColumn: $RENAME_COL"
+  [ "$ALTER_COL" -gt 0 ] && echo "  AlterColumn:  $ALTER_COL"
+  [ "$DROP_TABLE" -gt 0 ] && echo "  DropTable:    $DROP_TABLE"
+  echo ""
+  echo "For production deployments, consider zero-downtime migration patterns."
+  echo "See: references/zero-downtime-patterns.md"
+fi
 ```
 
 ### 3. Ask User to Validate