@atlashub/smartstack-cli 3.7.0 → 3.9.0

package/templates/skills/refactor/SKILL.md

@@ -23,198 +23,34 @@ This skill finds all relevant files, creates ONE instruction file, then launches
 <workflow>
 
 ## Phase 1: Discovery
+1. Parse the refactor request (method name, pattern, code smell)
+2. Find all affected files (Grep for code, Glob for file patterns)
+3. Analyze scope — if >15 files, confirm with user
 
-### 1. Parse the Refactor Request
-
-Understand what the pattern means:
-- Could be: method name, component name, pattern, code smell, etc.
-- Identify the search strategy (Grep for code patterns, Glob for file patterns)
-
-### 2. Find All Affected Files
-
-```
-Use Grep to search for the pattern in the codebase
-Use Glob if searching by file name patterns
-Exclude: node_modules, .git, dist, build, bin, obj
-```
-
-### 3. Analyze Scope
-
-- Count total files found
-- If more than 15 files, ask user to confirm or narrow scope
-- Show preview of files to refactor
+See [steps/step-01-discover.md](steps/step-01-discover.md) for search strategy and instruction file template.
 
 ## Phase 2: Create Instructions
-
-### 4. Create Task Folder
-
-```
-Generate unique ID: refactor-{timestamp}
-Create folder: .claude/tasks/refactor-{timestamp}/
-```
-
-### 5. Create ONE Instruction File
-
-Create `.claude/tasks/refactor-{id}/instructions.md`:
-
-```markdown
-# Refactor: {title}
-
-## Objective
-{What needs to be refactored - derived from user request}
-
-## Pattern to Find
-{Exact code pattern, method name, or structure to locate}
-
-## Transformation
-{How to transform the found pattern - be specific and adaptive}
-
-## Examples
-Before:
-{example of current code}
-
-After:
-{example of refactored code}
-
-## Constraints
-- Only modify code matching the pattern
-- Preserve all existing functionality
-- Follow codebase conventions
-- No comments unless necessary
-```
-
-**IMPORTANT**: Make instructions adaptive - they should work for ANY file in the list.
+4. Create task folder: `.claude/tasks/refactor-{timestamp}/`
+5. Create ONE `instructions.md` with: Objective, Pattern, Transformation, Examples, Constraints
 
 ## Phase 3: Group and Execute
-
-### 6. Group Files into Batches
-
-- Maximum 3 files per batch
-- Group by related functionality when possible
-
-### 7. Launch Snipper Agents in Parallel
-
-For EACH batch, use Task tool with `subagent_type='Snipper'`:
-
-```
-Using the instructions in .claude/tasks/refactor-{id}/instructions.md, refactor these files:
-- {file_1}
-- {file_2}
-- {file_3}
-```
-
-**CRITICAL**: Launch ALL batches in a SINGLE message with multiple Task calls.
-
-### 8. Wait for Completion
-
-- All Snipper agents run in parallel
-- Collect results from each
+6. Group files into batches (max 3 per batch)
+7. Launch ALL Snipper agents in parallel (single message, multiple Task calls)
+8. Wait for completion
 
 ## Phase 4: Verification
+9. Validate changes (lint/typecheck/build)
+10. Provide summary report
 
-### 9. Validate Changes
-
-```bash
-# For TypeScript/JavaScript
-pnpm lint || npm run lint
-pnpm tsc || npx tsc
-
-# For .NET
-dotnet build
-```
-
-Fix any errors immediately.
-
-### 10. Summary Report
-
-```
-Refactor Complete: {title}
-
-Files modified: {count}
-Batches executed: {count}
-Errors: {count}
-
-Modified files:
-- {file1}
-- {file2}
-...
-
-Next steps:
-- Review changes: git diff
-- Run tests: pnpm test
-- Commit: /gitflow:commit
-```
+See [steps/step-02-execute.md](steps/step-02-execute.md) for execution details and report format.
 
 </workflow>
 
-<instructions_template>
-
-Create ONE file at `.claude/tasks/refactor-{id}/instructions.md`:
-
-```markdown
-# Refactor: {title}
-
-## Objective
-{What needs to be refactored - derived from user request}
-
-## Pattern to Find
-{Exact code pattern, method name, or structure to locate}
-
-## Transformation
-{How to transform the found pattern - be specific and adaptive}
-
-## Examples
-Before:
-```
-{example of current code}
-```
-
-After:
-```
-{example of refactored code}
-```
-
-## Constraints
-- Only modify code matching the pattern
-- Preserve all existing functionality
-- Follow codebase conventions
-- No comments unless necessary
-```
-
-</instructions_template>
-
-<snipper_prompt_template>
-
-For each batch, call Snipper with:
-
-```
-Using the instructions in .claude/tasks/refactor-{id}/instructions.md, refactor these files:
-- {file_path_1}
-- {file_path_2}
-- {file_path_3}
-
-Read the instructions file first, then apply the refactor to each file.
-```
-
-</snipper_prompt_template>
-
-<execution_rules>
-
-- **PARALLEL EXECUTION**: Launch all Snipper batches simultaneously
-- **SINGLE INSTRUCTION FILE**: One instructions.md for all batches
-- **MAX 3 FILES PER BATCH**: Keep Snipper agents focused
-- **VALIDATE AFTER**: Run lint/typecheck after all batches complete
-- **PRESERVE FUNCTIONALITY**: Never break existing behavior
-
-</execution_rules>
-
 <success_criteria>
-
 - All target files identified
 - ONE instruction file created in `.claude/tasks/refactor-{id}/instructions.md`
 - Snipper agents launched in parallel (max 3 files per agent)
 - All batches completed successfully
 - Lint/type checks pass
 - Summary provided to user
-
 </success_criteria>

package/templates/skills/refactor/steps/step-01-discover.md

@@ -0,0 +1,60 @@
+# Phase 1: Discovery & Instructions
+
+## 1. Parse the Refactor Request
+
+Understand what the pattern means:
+- Could be: method name, component name, pattern, code smell, etc.
+- Identify the search strategy (Grep for code patterns, Glob for file patterns)
+
+## 2. Find All Affected Files
+
+```
+Use Grep to search for the pattern in the codebase
+Use Glob if searching by file name patterns
+Exclude: node_modules, .git, dist, build, bin, obj
+```
+
+## 3. Analyze Scope
+
+- Count total files found
+- If more than 15 files, ask user to confirm or narrow scope
+- Show preview of files to refactor
+
+## 4. Create Task Folder
+
+```
+Generate unique ID: refactor-{timestamp}
+Create folder: .claude/tasks/refactor-{timestamp}/
+```
+
+## 5. Create ONE Instruction File
+
+Create `.claude/tasks/refactor-{id}/instructions.md`:
+
+```markdown
+# Refactor: {title}
+
+## Objective
+{What needs to be refactored - derived from user request}
+
+## Pattern to Find
+{Exact code pattern, method name, or structure to locate}
+
+## Transformation
+{How to transform the found pattern - be specific and adaptive}
+
+## Examples
+Before:
+{example of current code}
+
+After:
+{example of refactored code}
+
+## Constraints
+- Only modify code matching the pattern
+- Preserve all existing functionality
+- Follow codebase conventions
+- No comments unless necessary
+```
+
+**IMPORTANT**: Make instructions adaptive - they should work for ANY file in the list.

package/templates/skills/refactor/steps/step-02-execute.md

@@ -0,0 +1,67 @@
+# Phase 3-4: Execute & Verify
+
+## Group Files into Batches
+
+- Maximum 3 files per batch
+- Group by related functionality when possible
+
+## Launch Snipper Agents in Parallel
+
+For EACH batch, use Task tool with `subagent_type='Snipper'`:
+
+```
+Using the instructions in .claude/tasks/refactor-{id}/instructions.md, refactor these files:
+- {file_1}
+- {file_2}
+- {file_3}
+
+Read the instructions file first, then apply the refactor to each file.
+```
+
+**CRITICAL**: Launch ALL batches in a SINGLE message with multiple Task calls.
+
+## Wait for Completion
+
+- All Snipper agents run in parallel
+- Collect results from each
+
+## Validate Changes
+
+```bash
+# For TypeScript/JavaScript
+pnpm lint || npm run lint
+pnpm tsc || npx tsc
+
+# For .NET
+dotnet build
+```
+
+Fix any errors immediately.
+
+## Summary Report
+
+```
+Refactor Complete: {title}
+
+Files modified: {count}
+Batches executed: {count}
+Errors: {count}
+
+Modified files:
+- {file1}
+- {file2}
+...
+
+Next steps:
+- Review changes: git diff
+- Run tests: pnpm test
+- Commit: /gitflow:commit
+```
+
+## Execution Rules
+
+- **PARALLEL EXECUTION**: Launch all Snipper batches simultaneously
+- **SINGLE INSTRUCTION FILE**: One instructions.md for all batches
+- **MAX 3 FILES PER BATCH**: Keep Snipper agents focused
+- **VALIDATE AFTER**: Run lint/typecheck after all batches complete
+- **PRESERVE FUNCTIONALITY**: Never break existing behavior

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

@@ -15,111 +15,11 @@ Provide expert-level code review guidance that focuses on high-impact issues: se
 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>
 
-<smartstack_integration>
-## 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
-</detection>
-
-<mcp_validation>
-**If SmartStack detected, run comprehensive code review via MCP:**
-
-**Primary tool - `review_code`** (NEW - 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_validation>
-
-<mcp_checks>
-**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)
-</mcp_checks>
-
-<output_integration>
-**Merge MCP `review_code` results into review output:**
-
-The MCP tool returns a structured report. Display it as-is or integrate key findings:
-
-```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
-</output_integration>
-</smartstack_integration>
-
 <quick_start>
-<review_priority>
+
 **Priority order**: Security > Correctness > Maintainability > Performance
 
 **High-value feedback** (36-43% implementation rate):
@@ -132,180 +32,42 @@ The MCP tool returns a structured report. Display it as-is or integrate key find
 - Formatting/whitespace
 - Simple naming conventions
 - Linting violations
-</review_priority>
 
-<essential_checks>
+**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
-</essential_checks>
-</quick_start>
-
-<review_categories>
-<category name="security" priority="critical">
-**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 (web application vulnerabilities).
-See [references/owasp-api-top10.md](references/owasp-api-top10.md) for OWASP API Security Top 10 (API-specific threats: BOLA, mass assignment, SSRF, resource consumption).
-</category>
 
-<category name="logic" priority="critical">
-**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)
-</category>
-
-<category name="clean_code" priority="high">
-**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 and code smells.
-</category>
-
-<category name="maintainability" priority="medium">
-**Assess long-term health:**
-- Cognitive complexity <15 per function
-- Clear naming that reveals intent
-- Appropriate abstractions (not over-engineered)
-- Test coverage for critical paths
-</category>
-</review_categories>
+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>
-<valuable_feedback>
-**Structure**: What + Why + How
-
-✓ "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])`"
+**Structure**: What + Why + How
 
-✓ "Missing null check on `user.profile` (line 52). This will throw if user hasn't completed onboarding. Add: `if (!user.profile) return defaultProfile;`"
-</valuable_feedback>
+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;`"
 
-<wasteful_feedback>
-✗ "This could be cleaner" (vague)
-✗ "Rename this variable" (nitpick - use linter)
-✗ "Add a comment here" (if code is clear, no comment needed)
-✗ "I would do this differently" (subjective without reason)
-</wasteful_feedback>
+Bad:
+- "This could be cleaner" (vague)
+- "Rename this variable" (nitpick - use linter)
+- "I would do this differently" (subjective without reason)
 
-<priority_labels>
-Use clear labels to distinguish severity:
+**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.
-</priority_labels>
 </feedback_guidelines>
 
-<code_quality_metrics>
-<metric name="cognitive_complexity">
-- Target: <15 per function, <50 per module
-- Each nesting level adds complexity
-- Prefer early returns over deep nesting
-</metric>
-
-<metric name="function_size">
-- Target: <50 lines, ideally <20
-- Should fit on one screen
-- One function = one responsibility
-</metric>
-
-<metric name="cyclomatic_complexity">
-- Target: <10 per function
-- Count: 1 + (if + while + for + case + catch + && + ||)
-- High complexity = hard to test
-</metric>
-
-See [references/code-quality-metrics.md](references/code-quality-metrics.md) for detailed calculations.
-</code_quality_metrics>
-
-<anti_patterns>
-<pattern name="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
-</pattern>
-
-<pattern name="vague_criticism">
-**Problem**: "This is wrong" without explanation
-**Impact**: Developer doesn't know how to fix; creates friction
-**Solution**: Always include What + Why + How
-</pattern>
-
-<pattern name="blocking_on_preferences">
-**Problem**: Blocking merge for subjective style preferences
-**Impact**: Delays delivery; damages team trust
-**Solution**: Reserve blocking for security/correctness only
-</pattern>
-
-<pattern name="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
-</pattern>
-</anti_patterns>
-
-<react_nextjs_review>
-## React/Next.js Codebase Detection
-
-**When reviewing a React or Next.js project**, launch an additional parallel agent for Vercel React best practices.
-
-<detection>
-**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)
-</detection>
-
-<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
-</parallel_agent>
-</react_nextjs_review>
+<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: