@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/review-code/SKILL.md

@@ -1,95 +0,0 @@
----
-name: review-code
-description: Expert code review covering security (OWASP), architecture, clean code (SOLID), performance, and SmartStack conventions via MCP. Use for PR reviews, security audits, and code quality checks.
-model: sonnet
----
-
-## Files to review (auto-injected)
-- Preflight: !`if [ -f .git ] && grep -q '^gitdir: [A-Za-z]:' .git 2>/dev/null && grep -qi microsoft /proc/version 2>/dev/null; then p=$(sed 's/^gitdir: //' .git | tr -d '\r\n'); d=$(echo "${p:0:1}" | tr A-Z a-z); r="${p:2}"; r="${r//\\//}"; printf 'gitdir: %s\n' "$(realpath -m --relative-to="$(pwd)" "/mnt/$d$r")" > .git && echo "repaired"; else echo "ok"; fi`
-- Changed files: !`git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --staged 2>/dev/null || echo "no changes detected"`
-- Diff stats: !`git diff --stat HEAD~1 2>/dev/null || git diff --stat --staged 2>/dev/null || echo "no stats"`
-- SmartStack detected: !`test -f "*.sln" && grep -l "SmartStack" *.sln 2>/dev/null && echo "YES" || echo "NO"`
-
-<objective>
-Provide expert-level code review guidance that focuses on high-impact issues: security vulnerabilities, logic errors, maintainability problems, and architectural concerns. Skip nitpicks and style issues that should be automated.
-
-Based on research from Google, Microsoft, OWASP, and academic studies on code review effectiveness.
-
-**For SmartStack projects**: Automatically validates SmartStack-specific conventions via MCP.
-See [steps/step-01-smartstack.md](steps/step-01-smartstack.md) for full MCP integration workflow.
-</objective>
-
-<quick_start>
-
-**Priority order**: Security > Correctness > Maintainability > Performance
-
-**High-value feedback** (36-43% implementation rate):
-- Bug fixes and logic errors
-- Security vulnerabilities
-- Readability/maintainability issues
-- Missing error handling
-
-**Skip these** (automate instead):
-- Formatting/whitespace
-- Simple naming conventions
-- Linting violations
-
-**Essential checks:**
-1. **Security**: Input validation, auth checks, secrets exposure
-2. **Logic**: Edge cases, error handling, null checks
-3. **Architecture**: Single responsibility, proper abstractions
-4. **Tests**: Coverage for new functionality
-
-See [steps/step-02-detailed-review.md](steps/step-02-detailed-review.md) for full review categories, metrics, and anti-patterns.
-</quick_start>
-
-<feedback_guidelines>
-
-**Structure**: What + Why + How
-
-Good:
-- "This function is 80 lines with 5 responsibilities. Consider extracting the validation logic (lines 20-45) into `validateUserInput()` for testability."
-- "SQL query uses string concatenation (line 34). Use parameterized queries to prevent injection: `db.query('SELECT * FROM users WHERE id = ?', [userId])`"
-- "Missing null check on `user.profile` (line 52). This will throw if user hasn't completed onboarding. Add: `if (!user.profile) return defaultProfile;`"
-
-Bad:
-- "This could be cleaner" (vague)
-- "Rename this variable" (nitpick - use linter)
-- "I would do this differently" (subjective without reason)
-
-**Priority labels:**
-- **[BLOCKING]**: Must fix before merge (security, bugs)
-- **[SUGGESTION]**: Would improve code but not required
-- **[NIT]**: Minor preference (mark clearly or skip entirely)
-
-See [references/feedback-patterns.md](references/feedback-patterns.md) for communication strategies.
-</feedback_guidelines>
-
-<react_nextjs>
-**When reviewing a React or Next.js project**, launch an additional parallel code-reviewer agent.
-See [steps/step-03-react.md](steps/step-03-react.md) for detection and agent configuration.
-</react_nextjs>
-
-<success_criteria>
-A good code review:
-- Identifies security vulnerabilities (if any)
-- Catches logic errors and edge cases
-- Flags maintainability issues with specific fixes
-- Uses priority labels ([BLOCKING] vs [SUGGESTION])
-- Provides actionable feedback (What + Why + How)
-- Avoids nitpicks on style/formatting
-- Completes in reasonable time (<4 hours for small PRs)
-- **[React/Next.js]** Includes Vercel best practices review when applicable
-- **[SmartStack]** Runs MCP validation and integrates results into review output
-</success_criteria>
-
-<reference_guides>
-For detailed guidance and patterns:
-
-- **`references/security-checklist.md`** - OWASP Top 10, authentication patterns, input validation, rate limiting, security headers
-- **`references/owasp-api-top10.md`** - OWASP API Security Top 10: BOLA, mass assignment, SSRF, resource consumption, SmartStack-specific detection patterns
-- **`references/clean-code-principles.md`** - SOLID principles, naming conventions, function design, code smell detection
-- **`references/feedback-patterns.md`** - Valuable vs wasteful feedback patterns, communication strategies, priority labeling
-- **`references/code-quality-metrics.md`** - Complexity calculations, maintainability index, measurement techniques
-- **`references/smartstack-conventions.md`** - SmartStack-specific conventions, MCP integration, multi-tenant patterns
-</reference_guides>

package/templates/skills/review-code/references/clean-code-principles.md

@@ -1,292 +0,0 @@
-<overview>
-Clean code principles based on Robert Martin's Clean Code and industry research. SOLID principles, naming conventions, and code smell detection.
-</overview>
-
-<solid_principles>
-| Principle | Rule | Violation Sign |
-|-----------|------|----------------|
-| **S**ingle Responsibility | One reason to change | Class/function does multiple things |
-| **O**pen/Closed | Open for extension, closed for modification | Adding features requires changing existing code |
-| **L**iskov Substitution | Subtypes must be substitutable | Subclass breaks when used as parent |
-| **I**nterface Segregation | No forced dependencies | Implementing unused interface methods |
-| **D**ependency Inversion | Depend on abstractions | Direct instantiation of dependencies |
-</solid_principles>
-
-<function_guidelines>
-<size_and_scope>
-Function size targets:
-
-- Maximum 50 lines (ideally <20)
-- Do ONE thing well
-- Single level of abstraction
-- Fit on one screen without scrolling
-</size_and_scope>
-
-<parameters>
-Parameter limits:
-
-- Maximum 3 parameters
-- Avoid flag arguments (split into separate methods)
-- Use objects for related parameters
-
-**Parameter Object Pattern (for 4+ parameters):**
-
-```csharp
-// ❌ BAD - Too many parameters (S107)
-public void CreateUser(
-    string name,
-    string email,
-    string phone,
-    string address,
-    bool isActive,
-    Guid tenantId)
-{
-    // ...
-}
-
-// ✅ GOOD - Use parameter object
-public record CreateUserRequest(
-    string Name,
-    string Email,
-    string Phone,
-    string Address,
-    bool IsActive,
-    Guid TenantId);
-
-public void CreateUser(CreateUserRequest request)
-{
-    // Access via request.Name, request.Email, etc.
-}
-```
-
-**Benefits:**
-- Easier to extend (add new parameters without changing signature)
-- Self-documenting (grouped related data)
-- Enables validation logic on the object itself
-- Reduces method signature complexity
-</parameters>
-
-<naming>
-Function naming patterns:
-
-- Verbs for functions: `getUserById()`, `calculateTotal()`
-- Reveals intent without reading body
-- No abbreviations: `getTransaction()` not `getTx()`
-</naming>
-
-<string_comparison>
-**C# String Comparison Best Practices:**
-
-ALWAYS use `StringComparison` overloads to avoid culture-specific issues (CA1873).
-
-```csharp
-// ❌ BAD - Culture-dependent, performance issue
-if (str1.ToLower() == str2.ToLower()) { ... }
-if (str1.ToUpper() == str2.ToUpper()) { ... }
-
-// ✅ GOOD - Explicit comparison
-if (string.Equals(str1, str2, StringComparison.OrdinalIgnoreCase)) { ... }
-if (str1.Equals(str2, StringComparison.OrdinalIgnoreCase)) { ... }
-
-// ❌ BAD - Culture-dependent Contains
-if (str.ToLower().Contains("keyword")) { ... }
-
-// ✅ GOOD - Explicit comparison (C# 5.0+)
-if (str.Contains("keyword", StringComparison.OrdinalIgnoreCase)) { ... }
-
-// ❌ BAD - Culture-dependent StartsWith/EndsWith
-if (str.ToLower().StartsWith("prefix")) { ... }
-
-// ✅ GOOD - Explicit comparison
-if (str.StartsWith("prefix", StringComparison.OrdinalIgnoreCase)) { ... }
-```
-
-**StringComparison options:**
-- `Ordinal` - Binary comparison (fastest, case-sensitive)
-- `OrdinalIgnoreCase` - Binary comparison (case-insensitive)
-- `CurrentCulture` - Culture-aware (rarely needed)
-- `InvariantCulture` - Culture-invariant (for data storage)
-
-**Rule of thumb:**
-- Use `Ordinal` for identifiers, file paths, keys
-- Use `OrdinalIgnoreCase` for user input comparison
-- Avoid `ToLower()`/`ToUpper()` for comparison
-</string_comparison>
-</function_guidelines>
-
-<naming_conventions>
-General naming rules:
-
-✓ Descriptive, unambiguous names
-✓ Pronounceable and searchable
-✓ Class names: nouns (User, PaymentProcessor)
-✓ Method names: verbs (validate, calculate, fetch)
-✗ Single letter variables (except loop counters)
-✗ Hungarian notation (strName, intCount)
-✗ Abbreviations (usr, txn, cfg)
-</naming_conventions>
-
-<code_smells>
-<critical_smells>
-Flag these in review:
-
-| Smell | Detection | Fix |
-|-------|-----------|-----|
-| **Duplicated Code** | Same logic in 2+ places | Extract to shared function |
-| **Large Class/Method** | >50 lines, multiple responsibilities | Split by responsibility |
-| **Long Parameter List** | >3 parameters | Use parameter object |
-| **Feature Envy** | Method uses another class's data more | Move method to that class |
-| **God Object** | One class controls everything | Split into focused classes |
-</critical_smells>
-
-<medium_smells>
-Suggest these fixes:
-
-| Smell | Detection | Fix |
-|-------|-----------|-----|
-| **Deep Nesting** | >3 levels of indentation | Guard clauses, early returns |
-| **Magic Numbers** | Unexplained literals | Named constants |
-| **Dead Code** | Commented-out or unreachable code | Delete it |
-| **Shotgun Surgery** | Small change touches many files | Consolidate related code |
-| **Nested Ternary** | `? ( ? : ) :` patterns | Extract to function/if-else |
-| **TODO/FIXME** | Untracked technical debt | Create ticket or fix immediately |
-</medium_smells>
-
-<nested_ternary_detection>
-**Nested Ternary Operators (S3358):**
-
-Nested ternaries are hard to read and maintain.
-
-```typescript
-// ❌ BAD - Nested ternary
-const status = isActive
-  ? (isPremium ? 'premium-active' : 'standard-active')
-  : 'inactive';
-
-const color = type === 'error'
-  ? 'red'
-  : type === 'warning' ? 'yellow' : 'blue';
-
-// ✅ GOOD - Early returns in function
-function getStatus(isActive: boolean, isPremium: boolean): string {
-  if (!isActive) return 'inactive';
-  if (isPremium) return 'premium-active';
-  return 'standard-active';
-}
-
-// ✅ GOOD - If-else chain
-let color: string;
-if (type === 'error') {
-  color = 'red';
-} else if (type === 'warning') {
-  color = 'yellow';
-} else {
-  color = 'blue';
-}
-
-// ✅ GOOD - Map/lookup for simple cases
-const colorMap: Record<string, string> = {
-  error: 'red',
-  warning: 'yellow',
-  info: 'blue'
-};
-const color = colorMap[type] ?? 'blue';
-```
-
-**Detection pattern:** Look for `? ... ? ... : ... :` in code.
-</nested_ternary_detection>
-
-<todo_fixme_tracking>
-**TODO/FIXME Comments (S1135):**
-
-Untracked TODOs become technical debt. Either fix immediately or create a tracked ticket.
-
-```typescript
-// ❌ BAD - Untracked TODO
-// TODO: handle edge case
-
-// ❌ BAD - Vague FIXME
-// FIXME: this is broken
-
-// ✅ ACCEPTABLE - Linked to ticket
-// TODO(#1234): Implement retry logic for transient failures
-
-// ✅ ACCEPTABLE - With deadline
-// FIXME(2026-02-15): Remove legacy API call after migration
-
-// ✅ BEST - No comment, just fix it
-// (Actually implement the fix instead of leaving a comment)
-```
-
-**Code review action:**
-1. Search for `TODO`, `FIXME`, `HACK`, `XXX`, `REFACTOR` comments
-2. For each:
-   - Is it linked to a ticket? If not, create one or fix now
-   - Is it still relevant? If not, delete
-   - Does it have context? If not, add details
-3. Report untracked TODOs as `[SUGGESTION]` in review
-</todo_fixme_tracking>
-</code_smells>
-
-<complexity_reduction>
-<example_before>
-Complex nested conditions:
-
-```javascript
-function process(user) {
-  if (user) {
-    if (user.isActive) {
-      if (user.hasPermission) {
-        // actual logic here
-      }
-    }
-  }
-}
-```
-</example_before>
-
-<example_after>
-Simplified with guard clauses:
-
-```javascript
-function process(user) {
-  if (!user) return;
-  if (!user.isActive) return;
-  if (!user.hasPermission) return;
-
-  // actual logic here
-}
-```
-</example_after>
-</complexity_reduction>
-
-<comments_best_practices>
-<good_comments>
-Valuable comments explain:
-
-- Explain WHY (intent), not WHAT (code does that)
-- Warn of consequences
-- TODO with ticket number
-</good_comments>
-
-<bad_comments>
-Avoid these comment types:
-
-- Redundant (restates the code)
-- Commented-out code (delete it)
-- Closing brace comments (`} // end if`)
-- Journal comments (use git history)
-</bad_comments>
-</comments_best_practices>
-
-<boy_scout_rule>
-> Leave code cleaner than you found it.
-
-**Important**: In PRs, only clean code already being changed. Don't expand scope.
-</boy_scout_rule>
-
-<sources>
-- Clean Code by Robert C. Martin
-- [Google Engineering Practices](https://google.github.io/eng-practices/)
-- [Microsoft Code Review Guide](https://microsoft.github.io/code-with-engineering-playbook/)
-</sources>

package/templates/skills/review-code/references/code-quality-metrics.md

@@ -1,174 +0,0 @@
-<overview>
-Quantitative code quality metrics for informed review decisions. Includes cognitive complexity, cyclomatic complexity, maintainability index, and technical debt indicators.
-</overview>
-
-<cognitive_complexity>
-<definition>
-**What it measures**: Mental effort required to understand code
-</definition>
-
-<targets>
-Target complexity levels:
-
-- Per function: <15 (ideal <10)
-- Per module: <50
-- Per file: <100
-</targets>
-
-<complexity_factors>
-Factors that increase complexity:
-
-- Each nesting level (+1 per level)
-- Logical operators (&&, ||)
-- Recursion
-- Breaks in linear flow (break, continue, goto)
-</complexity_factors>
-
-<reduction_example>
-Reducing cognitive complexity:
-
-```javascript
-// HIGH COMPLEXITY (nested conditionals)
-function process(data) {
-  if (data) {
-    if (data.valid) {
-      if (data.items.length > 0) {
-        for (const item of data.items) {
-          if (item.active) {
-            // process
-          }
-        }
-      }
-    }
-  }
-}
-
-// LOW COMPLEXITY (guard clauses + extraction)
-function process(data) {
-  if (!data?.valid) return;
-  if (!data.items?.length) return;
-
-  processActiveItems(data.items);
-}
-
-function processActiveItems(items) {
-  const active = items.filter(item => item.active);
-  active.forEach(processItem);
-}
-```
-</reduction_example>
-</cognitive_complexity>
-
-<cyclomatic_complexity>
-<definition>
-**What it measures**: Number of independent paths through code
-</definition>
-
-<formula>
-**Formula**: 1 + (if + while + for + case + catch + && + ||)
-</formula>
-
-<targets>
-| Score | Risk | Action |
-|-------|------|--------|
-| 1-4 | Low | Good |
-| 5-7 | Moderate | Consider simplifying |
-| 8-10 | High | Refactor recommended |
-| >10 | Very High | Must refactor |
-</targets>
-</cyclomatic_complexity>
-
-<function_size_metrics>
-| Metric | Target | Warning | Critical |
-|--------|--------|---------|----------|
-| Lines | <20 | >30 | >50 |
-| Parameters | ≤3 | 4 | >5 |
-| Nesting depth | ≤2 | 3 | >3 |
-| Return statements | 1-2 | 3-4 | >4 |
-</function_size_metrics>
-
-<maintainability_index>
-<formula>
-Microsoft's formula:
-
-```
-MI = MAX(0, (171 - 5.2*ln(HalsteadVolume) - 0.23*CC - 16.2*ln(LOC)) * 100/171)
-```
-</formula>
-
-<interpretation>
-| Score | Maintainability |
-|-------|-----------------|
-| 80-100 | High - easy to maintain |
-| 60-79 | Moderate - some concerns |
-| 40-59 | Low - refactoring recommended |
-| <40 | Very Low - significant refactoring needed |
-</interpretation>
-</maintainability_index>
-
-<technical_debt_indicators>
-| Indicator | Healthy | Warning |
-|-----------|---------|---------|
-| Code duplication | <5% | >10% |
-| Test coverage | >80% | <60% |
-| Cyclomatic complexity avg | <5 | >8 |
-| TODO/FIXME count | Stable | Growing |
-| Dependency age | <6 months | >12 months |
-</technical_debt_indicators>
-
-<code_churn>
-<definition>
-**What it measures**: Frequency of code changes
-</definition>
-
-<warning_signs>
-Signs of problematic churn:
-
-- Same file changed in >50% of recent commits
-- High churn + low test coverage = risk
-- Late-project churn indicates instability
-</warning_signs>
-</code_churn>
-
-<review_thresholds>
-<must_comment>
-Always comment on:
-
-- Function complexity >15
-- Nesting >3 levels
-- Function >50 lines
-- >3 parameters without object
-</must_comment>
-
-<consider_commenting>
-Consider commenting on:
-
-- Duplicated blocks >10 lines
-- Method doing multiple things
-- Unclear naming
-</consider_commenting>
-
-<dont_comment>
-Skip commenting on:
-
-- Slightly suboptimal but working code
-- Style preferences
-- Minor naming improvements
-</dont_comment>
-</review_thresholds>
-
-<measurement_tools>
-| Language | Tool |
-|----------|------|
-| JavaScript/TypeScript | ESLint (complexity rules), SonarQube |
-| Python | Radon, Pylint |
-| Java | SonarQube, PMD |
-| Go | gocyclo, golangci-lint |
-| General | SonarQube, CodeClimate |
-</measurement_tools>
-
-<sources>
-- [SonarQube Cognitive Complexity](https://www.sonarsource.com/docs/CognitiveComplexity.pdf)
-- [Microsoft Maintainability Index](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-maintainability-index-range-and-meaning)
-- [Cyclomatic Complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity)
-</sources>

package/templates/skills/review-code/references/feedback-patterns.md

@@ -1,149 +0,0 @@
-<overview>
-Code review feedback patterns based on research from Google, Microsoft, and academic studies on effective code review communication.
-</overview>
-
-<what_why_how_pattern>
-Every valuable comment includes three components:
-
-1. **What**: The specific issue
-2. **Why**: Why it matters
-3. **How**: Concrete fix or direction
-
-<good_example>
-```
-[BLOCKING] SQL injection vulnerability at line 34.
-The query uses string concatenation with user input, allowing attackers to modify the query.
-Fix: Use parameterized query: db.query('SELECT * FROM users WHERE id = ?', [userId])
-```
-</good_example>
-
-<bad_example>
-```
-This query looks unsafe.
-```
-</bad_example>
-</what_why_how_pattern>
-
-<priority_labels>
-Use consistent labels so authors know severity:
-
-| Label | Meaning | Merge? |
-|-------|---------|--------|
-| `[BLOCKING]` | Must fix - security, bugs, missing requirements | No |
-| `[CRITICAL]` | Strongly recommended - architecture, major issues | Discuss |
-| `[SUGGESTION]` | Would improve code - not required | Yes |
-| `[NIT]` | Minor preference - skip if busy | Yes |
-| `[QUESTION]` | Need clarification - not blocking | Yes |
-</priority_labels>
-
-<feedback_value>
-<high_value>
-High-value feedback (36-43% implementation rate):
-
-- Security vulnerabilities with exploit scenario
-- Logic errors with failing test case
-- Missing error handling with consequences
-- Performance issues with measurements
-</high_value>
-
-<wasteful>
-Wasteful feedback (damages team dynamics):
-
-- Style preferences covered by linters
-- Renaming suggestions without clear benefit
-- "I would do it differently" without why
-- Comments on code outside the diff
-</wasteful>
-</feedback_value>
-
-<communication_patterns>
-<collaborative_framing>
-Use collaborative, question-based framing:
-
-```
-✓ "Have you considered using a Map here for O(1) lookup?"
-✓ "This could throw if user is null - should we add a check?"
-✓ "I'm not sure I understand this logic - could you explain?"
-
-✗ "You need to fix this."
-✗ "This is wrong."
-✗ "Obviously this should be..."
-```
-</collaborative_framing>
-
-<avoid_belittling>
-Remove belittling words: "just", "simply", "obviously", "easy", "only"
-
-```
-✗ "Just add a null check"
-✗ "This is obviously wrong"
-✓ "Add a null check for user.profile"
-```
-</avoid_belittling>
-</communication_patterns>
-
-<merge_decisions>
-<block_merge>
-Block merge for:
-
-- Security vulnerabilities (any severity)
-- Logic bugs that affect functionality
-- Missing required tests
-- Breaking API changes without migration
-</block_merge>
-
-<approve_with_comments>
-Approve with comments for:
-
-- Suggestions for future improvement
-- Minor refactoring opportunities
-- Documentation improvements
-- Style preferences (should be in linter)
-</approve_with_comments>
-
-<approve_clean>
-Approve cleanly when:
-
-- Code meets requirements
-- Tests pass
-- No security issues
-- Follows project conventions
-</approve_clean>
-</merge_decisions>
-
-<avoiding_nitpick_culture>
-**Research finding**: Nitpicking damages team relationships more than it improves code quality. Developers become defensive and less receptive to legitimate feedback.
-
-<solution>
-1. Automate style enforcement (linters, formatters)
-2. Block CI on lint failures, not PR comments
-3. Reserve human review for logic and design
-4. Mark true nitpicks with `[NIT]` prefix
-5. Limit to 3-5 critical items per review
-</solution>
-</avoiding_nitpick_culture>
-
-<review_efficiency>
-<google_data>
-Google's review data shows:
-
-- 90% of reviews: <10 files changed
-- Average turnaround: 4 hours
-- 75% need only one reviewer
-</google_data>
-
-<best_practices>
-Efficiency best practices:
-
-- Small PRs get better feedback
-- Review within 4 hours if possible
-- Focus on changed code only
-- One pass, thorough, then done
-</best_practices>
-</review_efficiency>
-
-<sources>
-- [Google Code Review Guide](https://google.github.io/eng-practices/review/)
-- [Microsoft Reviewer Guidance](https://microsoft.github.io/code-with-engineering-playbook/code-reviews/)
-- [Conventional Comments](https://conventionalcomments.org/)
-</sources>