@atlashub/smartstack-cli 3.8.0 → 3.9.0

package/templates/skills/review-code/steps/step-01-smartstack.md

@@ -0,0 +1,96 @@
+# SmartStack Project Detection & MCP Validation
+
+**CRITICAL**: Before starting any code review, detect if this is a SmartStack project and run MCP validation.
+
+## Detection
+
+**Detect SmartStack project by checking for ANY of these:**
+- `.claude/mcp-status.json` exists
+- `SmartStack.Domain/` or `SmartStack.Application/` directories
+- `*.sln` file containing "SmartStack"
+- `package.json` with `@smartstack/` dependencies
+
+## MCP Validation
+
+**If SmartStack detected, run comprehensive code review via MCP:**
+
+**Primary tool - `review_code`** (unified review):
+```
+mcp__smartstack__review_code
+scope: "changed"   # or "all" or "staged"
+checks: ["all"]    # 9 categories covered
+severity: "all"    # blocking, critical, warning, info
+```
+
+**This single tool covers ALL categories:**
+- Security (OWASP, secrets, SQL injection, XSS)
+- Architecture (layer violations, DI bypass)
+- Hardcoded values (magic numbers, URLs, feature flags)
+- Tests (missing tests, test quality)
+- AI Hallucinations (non-existent imports, phantom methods)
+- Performance (N+1 queries, over-fetching)
+- Dead Code (unused imports, functions)
+- i18n (non-translated UI text)
+- Accessibility (missing alt, ARIA issues)
+
+**Optional: Additional convention checks:**
+```
+mcp__smartstack__validate_conventions
+checks: ["all"]
+```
+
+## MCP Check Categories
+
+**SmartStack code review categories via MCP `review_code`:**
+
+| Category | Check ID | What it detects |
+|----------|----------|-----------------|
+| **Security** | SEC-xxx | Hardcoded secrets, SQL injection, XSS, missing [Authorize] |
+| **Architecture** | ARCH-xxx | Layer violations (Domain->Infrastructure), DI bypass |
+| **Hardcoded** | HARD-xxx | Magic numbers, hardcoded URLs, feature flags |
+| **Tests** | TEST-xxx | Missing tests, useless assertions, no coverage |
+| **AI Hallucinations** | AI-xxx | Non-existent imports, phantom methods, placeholders |
+| **Performance** | PERF-xxx | N+1 queries, ToList before Where, over-fetching |
+| **Dead Code** | DEAD-xxx | Unused imports, functions, commented code, TODOs |
+| **i18n** | I18N-xxx | Hardcoded UI text, missing translations |
+| **Accessibility** | A11Y-xxx | Missing alt, no aria-label, focus issues |
+
+**Severity levels:**
+- `blocking` -> Must fix before merge (security, hallucinations)
+- `critical` -> Should fix ASAP (architecture, tests)
+- `warning` -> Recommended fix (performance, dead code)
+- `info` -> Nice to have (i18n, a11y)
+
+## Output Integration
+
+**Merge MCP `review_code` results into review output:**
+
+```markdown
+## Code Review Results (via MCP)
+
+### Summary
+| Metric | Value |
+|--------|-------|
+| Status | {PASSED/FAILED/WARNING} |
+| Score | {score}/100 |
+| Grade | {A/B/C/D/F} |
+
+### Blocking Issues ({count})
+| ID | Issue | File:Line | Fix |
+|----|-------|-----------|-----|
+| SEC-001 | {title} | `{file}:{line}` | {suggestion} |
+
+### Critical Issues ({count})
+| ID | Issue | File:Line | Fix |
+|----|-------|-----------|-----|
+| ARCH-001 | {title} | `{file}:{line}` | {suggestion} |
+
+### Warnings ({count})
+(List or summarize)
+```
+
+**Priority mapping from MCP:**
+- `blocking` -> `[BLOCKING]` - Must fix before merge
+- `critical` -> `[CRITICAL]` - Should fix ASAP
+- `warning` -> `[SUGGESTION]` - Recommended
+- `info` -> `[NIT]` - Nice to have

package/templates/skills/review-code/steps/step-02-detailed-review.md

@@ -0,0 +1,80 @@
+# Detailed Review Categories & Metrics
+
+## Review Categories
+
+### Security (Critical Priority)
+**Must check in every review:**
+- No hardcoded credentials (search: `password.*=.*['"]`, `api[_-]?key.*=`)
+- Input validation on all user data
+- Parameterized queries (no string concatenation for SQL)
+- Authorization checks on every endpoint
+- No `eval()`, `exec()`, dangerous functions
+
+See [references/security-checklist.md](../references/security-checklist.md) for OWASP Top 10 patterns.
+See [references/owasp-api-top10.md](../references/owasp-api-top10.md) for OWASP API Security Top 10.
+
+### Logic (Critical Priority)
+**Verify correctness:**
+- Business logic matches requirements
+- Edge cases handled (null, empty, boundary values)
+- Error handling present and appropriate
+- Race conditions in async code
+- Resource cleanup (connections, file handles)
+
+### Clean Code (High Priority)
+**Check for code smells:**
+- Large functions (>50 lines) - violate Single Responsibility
+- Deep nesting (>3 levels) - extract to functions
+- Long parameter lists (>3 params) - use objects
+- Duplicated code - extract to shared functions
+- Magic numbers/strings - use named constants
+
+See [references/clean-code-principles.md](../references/clean-code-principles.md) for SOLID principles.
+
+### Maintainability (Medium Priority)
+**Assess long-term health:**
+- Cognitive complexity <15 per function
+- Clear naming that reveals intent
+- Appropriate abstractions (not over-engineered)
+- Test coverage for critical paths
+
+## Code Quality Metrics
+
+### Cognitive Complexity
+- Target: <15 per function, <50 per module
+- Each nesting level adds complexity
+- Prefer early returns over deep nesting
+
+### Function Size
+- Target: <50 lines, ideally <20
+- Should fit on one screen
+- One function = one responsibility
+
+### Cyclomatic Complexity
+- Target: <10 per function
+- Count: 1 + (if + while + for + case + catch + && + ||)
+- High complexity = hard to test
+
+See [references/code-quality-metrics.md](../references/code-quality-metrics.md) for detailed calculations.
+
+## Anti-Patterns to Flag
+
+### Nitpicking
+**Problem**: Excessive minor comments bury critical issues
+**Impact**: Developers become defensive, stop reading feedback
+**Solution**: Automate style with linters; focus humans on logic/security
+
+### Vague Criticism
+**Problem**: "This is wrong" without explanation
+**Impact**: Developer doesn't know how to fix; creates friction
+**Solution**: Always include What + Why + How
+
+### Blocking on Preferences
+**Problem**: Blocking merge for subjective style preferences
+**Impact**: Delays delivery; damages team trust
+**Solution**: Reserve blocking for security/correctness only
+
+### Reviewing Unchanged Code
+**Problem**: Commenting on code outside the PR diff
+**Impact**: Scope creep; unfair to author
+**Solution**: Focus only on changed lines; file separate issues for existing problems

package/templates/skills/review-code/steps/step-03-react.md

@@ -0,0 +1,44 @@
+# React/Next.js Review
+
+## Codebase Detection
+
+**When reviewing a React or Next.js project**, launch an additional parallel agent for Vercel React best practices.
+
+**Detect React/Next.js codebase by checking:**
+- `package.json` contains `"next"` or `"react"` dependencies
+- Files with `.tsx`, `.jsx` extensions in changes
+- `next.config.js` or `next.config.ts` exists
+- `app/` or `pages/` directory structure (Next.js)
+
+## Parallel Agent
+
+**If React/Next.js detected, launch parallel agent:**
+
+```yaml
+agent:
+  type: code-reviewer
+  focus: "vercel-react-best-practices"
+  task: |
+    Review the recent code changes using Vercel React best practices.
+    Focus on:
+    - Eliminating waterfalls (async patterns, Promise.all)
+    - Bundle size optimization (dynamic imports, barrel files)
+    - Server-side performance (caching, serialization)
+    - Re-render optimization (memoization, state management)
+    - Rendering performance patterns
+
+    Use the /vercel-react-best-practices skill as reference.
+    Report findings with [BLOCKING], [SUGGESTION], or [NIT] labels.
+```
+
+**Execution:**
+1. Check for React/Next.js in `package.json`
+2. If detected, use Task tool to launch parallel agent:
+   ```
+   Task tool with subagent_type="code-reviewer":
+   "Review recent changes against Vercel React best practices from /vercel-react-best-practices skill.
+   Focus on: async patterns, bundle optimization, server performance, re-renders.
+   Check changed files for violations of rules like async-parallel, bundle-barrel-imports,
+   server-cache-react, rerender-memo. Report with priority labels."
+   ```
+3. Merge findings into main review output

package/templates/skills/ui-components/SKILL.md

@@ -128,3 +128,10 @@ import { EntityCard, ProviderCard, TemplateCard } from '@/components/ui/EntityCa
 - Always provide retry button for recoverable errors
 - Use Lucide `AlertCircle` icon (not inline SVG)
 - Keep error messages user-friendly (not technical stack traces)
+
+<success_criteria>
+- Component created following SmartStack UI patterns (CSS variables, Lucide icons, i18n)
+- Correct file placement in src/pages/ or src/components/
+- Loading, error, and empty states handled
+- Responsive layout with SmartStack grid system
+</success_criteria>

package/templates/skills/utils/SKILL.md

@@ -36,3 +36,9 @@ Route to subcommand file:
 | `test-web-config` | `subcommands/test-web-config.md` |
 
 </entry_point>
+
+<success_criteria>
+- Subcommand routed and executed successfully
+- Test results displayed with pass/fail status
+- Configuration saved when using test-web-config
+</success_criteria>

package/templates/skills/validate/SKILL.md

@@ -173,3 +173,9 @@ WARNINGS ({count})
 4. **Structured Output:** Typed responses for automation
 
 </why_mcp>
+
+<success_criteria>
+- MCP validate_conventions called with correct checks
+- Validation report displayed with pass/fail per check
+- All errors and warnings listed with file references and suggestions
+</success_criteria>

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

@@ -81,3 +81,11 @@ A validation report showing pass/fail for each check:
 
 Result: ALL CHECKS PASSED
 ```
+
+<success_criteria>
+- Solution compiles without errors
+- All unit tests pass
+- All integration tests pass
+- API smoke tests return expected HTTP status codes (200, 201, 204)
+- Validation report displayed with per-check results
+</success_criteria>

package/templates/skills/workflow/SKILL.md

@@ -12,11 +12,11 @@ description: |
 
 # Skill Workflow SmartStack
 
-> **Architecture:** Trigger → Steps → Actions (Email/Wait/Condition/Webhook)
+> **Architecture:** Trigger -> Steps -> Actions (Email/Wait/Condition/Webhook)
 
 **Reference:** [_shared.md](../_shared.md) for common services
 
-## WHEN THIS SKILL ACTIVATES
+## When This Skill Activates
 
 | Trigger | Example |
 |---------|---------|
@@ -25,17 +25,17 @@ description: |
 | Chaining | "After 24h without response, send a reminder" |
 | Keywords | "workflow", "trigger", "automation", "email template" |
 
-## FLOW
+## Flow
 
 ```
-EVENT → WorkflowTrigger("user.registered")
-    ↓
+EVENT -> WorkflowTrigger("user.registered")
+    |
 IWorkflowService.TriggerAsync(code, variables)
-    ↓
-Workflow Steps: SendEmail → Wait → Condition → Webhook
+    |
+Workflow Steps: SendEmail -> Wait -> Condition -> Webhook
 ```
 
-## AVAILABLE TRIGGERS
+## Available Triggers
 
 ### User Events
 | Trigger | Variables |
@@ -62,138 +62,53 @@ new { Id = Guid.Parse("..."), Code = "entity.event", Name = "Entity Event",
 await _workflowService.TriggerAsync("entity.event", new Dictionary<string, object>{...}, language: "en");
 ```
 
-## STEP TYPES
+## Implementation
 
-### 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);
-```
+See [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
 
-## 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)
-```
-
-## 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
-```
-
-## RELATION WITH DOMAIN EVENTS
+## 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 a complementary pattern for **in-process** side effects (audit logging, cache invalidation, read-model updates).
-
-**Recommended pattern:** Domain Event handler bridges to Workflow triggers:
-```csharp
-// OrderCreatedEventHandler calls TriggerAsync for cross-process actions
-public async Task Handle(OrderCreatedEvent notification, CancellationToken ct)
-{
-    await _workflowService.TriggerAsync("order.created",
-        new Dictionary<string, object>{ ["orderId"] = notification.OrderId }, ct: ct);
-}
-```
+**Domain Events** (MediatR `INotificationHandler<T>`) are complementary for **in-process** side effects (audit logging, cache invalidation, read-model updates).
 
-**When to use which:**
 | 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 |
+| Notify multiple services of same change | Domain Event -> Workflow Trigger |
 
-See `review-code/references/smartstack-conventions.md` (Domain Events section) for the full implementation pattern.
+See `review-code/references/smartstack-conventions.md` (Domain Events section) for full pattern.
 
-## ABSOLUTE RULES
+## 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) |
+| Unique kebab-case codes | Infinite loops (A->B->A) |
 | Log executions | Forget email templates |
 
-## KEY FILES
+## Key Files
 
 | File | Role |
 |------|------|
@@ -203,3 +118,10 @@ See `review-code/references/smartstack-conventions.md` (Domain Events section) f
 | `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-01-implementation.md

@@ -0,0 +1,84 @@
+# 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)
+```