nemonix-cli 1.0.0

package/src/config/claude-code-config/skills/workflow-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)
+</priority_labels>
+
+See [references/feedback-patterns.md](references/feedback-patterns.md) for communication strategies.
+</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/src/config/claude-code-config/skills/workflow-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/src/config/claude-code-config/skills/workflow-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>

package/src/config/claude-code-config/skills/workflow-review-code/references/feedback-patterns.md

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