@atlashub/smartstack-cli 1.13.2 → 1.14.0

package/templates/skills/ralph-loop/steps/step-05-report.md

@@ -0,0 +1,181 @@
+---
+name: step-05-report
+description: Generate final feature report
+next_step: null
+---
+
+# Step 5: Generate Report
+
+## YOUR TASK:
+
+Generate a comprehensive feature report documenting what was accomplished.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Gather Statistics
+
+**Collect data from prd.json and progress.txt:**
+
+```javascript
+const prd = readJSON('.ralph/prd.json');
+const stats = {
+  feature: prd.feature,
+  started: prd.created,
+  completed: new Date().toISOString(),
+  iterations: prd.current_iteration,
+  maxIterations: prd.max_iterations,
+  tasksCompleted: prd.tasks.filter(t => t.passes).length,
+  tasksTotal: prd.tasks.length,
+  status: allComplete ? "COMPLETE" : "PARTIAL"
+};
+```
+
+### 2. Collect File Changes
+
+**Get files from git log:**
+
+```bash
+git log --name-status --pretty=format:"%H" HEAD~{iterations}..HEAD
+```
+
+**Categorize:**
+- Files created (A)
+- Files modified (M)
+- Files deleted (D)
+
+### 3. Collect MCP Usage
+
+**From verbose logs (if available):**
+
+```javascript
+const mcpStats = {
+  validate_conventions: X,
+  check_migrations: Y,
+  scaffold_extension: Z,
+  context7_queries: W
+};
+```
+
+### 4. Generate Report File
+
+**Write to `.ralph/reports/{feature-slug}.md`:**
+
+```markdown
+# Feature Report: {feature}
+
+## Summary
+- **Started**: {started}
+- **Completed**: {completed}
+- **Duration**: {iterations} iterations
+- **Status**: {status}
+
+## Task Progress
+
+| # | Task | Status |
+|---|------|--------|
+| 1 | {task_1_description} | ✅ |
+| 2 | {task_2_description} | ✅ |
+| 3 | {task_3_description} | ❌ (if incomplete) |
+
+## MCP Usage Statistics
+
+| Tool | Calls | Success | Failures |
+|------|-------|---------|----------|
+| validate_conventions | X | X | 0 |
+| check_migrations | Y | Y | 0 |
+| scaffold_extension | Z | Z | 0 |
+| context7 query-docs | W | W | 0 |
+
+## Files Created
+
+```
+{list of created files}
+```
+
+## Files Modified
+
+```
+{list of modified files}
+```
+
+## Git Commits
+
+```
+{commit_hash_1} feat(ralph): {message_1}
+{commit_hash_2} feat(ralph): {message_2}
+```
+
+## Validations Performed
+
+- [x] SmartStack conventions validated
+- [x] EF Core migrations checked (if applicable)
+- [x] No conflicts detected
+- [x] Build passes
+- [x] Tests pass (if applicable)
+
+## Key Learnings
+
+{Extracted from progress.txt - key insights from each iteration}
+
+## Notes
+
+{Any additional observations about the implementation}
+```
+
+### 5. Display Final Summary
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║                    RALPH LOOP COMPLETE                            ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Feature: {feature}                                               ║
+║  Status:  {status}                                                ║
+║  Iterations: {iterations}                                         ║
+║  Tasks: {tasksCompleted} / {tasksTotal}                          ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Files Created:  {created_count}                                  ║
+║  Files Modified: {modified_count}                                 ║
+║  Commits:        {commit_count}                                   ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Report saved to:                                                 ║
+║  .ralph/reports/{feature-slug}.md                                 ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+### 6. Output Completion (if applicable)
+
+**If all tasks complete and not already output:**
+
+```
+<promise>{completion_promise}</promise>
+```
+
+---
+
+## CLEANUP OPTIONS:
+
+**Suggest to user:**
+
+```
+Next steps:
+1. Review report: .ralph/reports/{feature-slug}.md
+2. Run full test suite: dotnet test
+3. Create PR: /gitflow:7-pull-request
+4. Clean up Ralph files: rm -rf .ralph/
+```
+
+---
+
+## SUCCESS CRITERIA:
+
+- Report generated in `.ralph/reports/`
+- All statistics accurate
+- File lists complete
+- Learnings documented
+- Final summary displayed
+
+## COMPLETION:
+
+Ralph loop complete. No more steps.

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

@@ -0,0 +1,219 @@
+---
+name: review-code
+description: This skill should be used when the user asks to "review code", "review this PR", "code review", "audit this code", or mentions reviewing pull requests, security checks, or code quality. Covers security (OWASP), clean code (SOLID), code smells, complexity metrics, and high-value feedback patterns. Focuses on impactful issues, not nitpicks.
+---
+
+<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.
+</objective>
+
+<quick_start>
+<review_priority>
+**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
+</review_priority>
+
+<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.
+</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>
+
+<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])`"
+
+✓ "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>
+
+<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>
+
+<priority_labels>
+Use clear labels to distinguish severity:
+- **[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>
+
+<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
+</success_criteria>
+
+<reference_guides>
+For detailed guidance and patterns:
+
+- **`references/security-checklist.md`** - OWASP Top 10, authentication patterns, input validation, common vulnerabilities
+- **`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
+</reference_guides>

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

@@ -0,0 +1,140 @@
+<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
+</parameters>
+
+<naming>
+Function naming patterns:
+
+- Verbs for functions: `getUserById()`, `calculateTotal()`
+- Reveals intent without reading body
+- No abbreviations: `getTransaction()` not `getTx()`
+</naming>
+</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 |
+</medium_smells>
+</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

@@ -0,0 +1,174 @@
+<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>