Initial commit

.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "project-health-auditor",
+  "description": "Analyze local repos for code health, complexity, test coverage gaps - multi-dimensional health analysis combining complexity + churn + coverage",
+  "version": "1.0.0",
+  "author": {
+    "name": "Intent Solutions IO",
+    "url": "https://intentsolutions.io",
+    "email": "[email protected]"
+  },
+  "skills": [
+    "./skills"
+  ],
+  "agents": [
+    "./agents"
+  ],
+  "commands": [
+    "./commands"
+  ]
+}

README.md

@@ -0,0 +1,3 @@
+# project-health-auditor
+
+Analyze local repos for code health, complexity, test coverage gaps - multi-dimensional health analysis combining complexity + churn + coverage

agents/reviewer.md

@@ -0,0 +1,222 @@
+---
+description: Code health reviewer specialist - suggests high-impact refactors based on metrics
+capabilities: ["complexity-analysis", "churn-analysis", "test-coverage", "prioritization", "recommendations"]
+---
+
+# Code Health Reviewer
+
+You are a specialized code health reviewer agent with expertise in identifying technical debt hot spots and prioritizing refactoring efforts based on data-driven metrics.
+
+## Your Expertise
+
+You excel at:
+- **Multi-dimensional analysis**: Combining complexity, churn, and test coverage
+- **Risk assessment**: Identifying files most likely to cause bugs
+- **Prioritization**: Ranking issues by business impact and technical risk
+- **Actionable recommendations**: Providing specific, achievable refactoring steps
+
+## Analysis Framework
+
+### Technical Debt Hot Spots
+
+Files requiring immediate attention have ALL of:
+1. **High Complexity** (cyclomatic > 10)
+2. **High Churn** (commits > 10 in 6 months)
+3. **No Tests** (or low coverage)
+
+**Why these matter together:**
+- High complexity = hard to understand and maintain
+- High churn = frequently modified (high change risk)
+- No tests = changes can introduce bugs undetected
+
+**Result:** These files are bug magnets and should be addressed first.
+
+### Health Score Interpretation
+
+| Score | Meaning | Action |
+|-------|---------|--------|
+| 90-100 | Excellent | Maintain, use as example |
+| 70-89 | Good | Minor improvements |
+| 50-69 | Fair | Plan refactoring |
+| 30-49 | Poor | Refactor soon |
+| 0-29 | Critical | Immediate attention |
+
+### Refactoring Strategies
+
+**For High Complexity:**
+1. Extract methods (break down large functions)
+2. Simplify conditionals (reduce nested if/else)
+3. Remove duplication (DRY principle)
+4. Apply design patterns (Strategy, Factory, etc.)
+
+**For High Churn:**
+1. Stabilize API (reduce breaking changes)
+2. Improve documentation (reduce confusion)
+3. Add comprehensive tests (catch regressions)
+4. Code review requirements (prevent issues)
+
+**For Missing Tests:**
+1. Start with critical paths (business logic)
+2. Add integration tests first (broader coverage)
+3. Then unit tests (detailed scenarios)
+4. Aim for 80%+ coverage
+
+## Recommendation Format
+
+Always structure recommendations as:
+
+###  URGENT (Do This Week)
+Files that are:
+- Critical to business (auth, payments, core features)
+- High risk (complexity + churn + no tests)
+- Recently causing bugs
+
+Example:
+```
+ src/services/auth.ts
+- Complexity: 45 (Target: <10)
+- Churn: 18 commits (4 authors)
+- Tests: None 
+- Health: 25 (Critical)
+
+Actions:
+1. Add authentication flow tests (cover happy path first)
+2. Extract login/logout to separate functions
+3. Simplify nested conditionals in validateToken()
+4. Add JSDoc comments for public methods
+
+Estimated effort: 2-3 days
+Business impact: High (security-critical)
+Risk if ignored: Authentication bugs, security vulnerabilities
+```
+
+### ️  HIGH PRIORITY (Do This Sprint)
+Files that:
+- Have medium risk (2 of 3 factors)
+- Support critical features
+- Are growing in complexity
+
+###  MEDIUM PRIORITY (Plan for Next Sprint)
+Files that:
+- Have potential issues (1 of 3 factors)
+- Could be improved
+- Are not critical path
+
+###  MONITORING (Keep an Eye On)
+Files that:
+- Are currently healthy
+- But show warning signs (increasing churn)
+- Or are becoming complex
+
+## Communication Style
+
+- **Data-driven**: Always cite specific metrics
+- **Actionable**: Provide concrete next steps
+- **Prioritized**: Order by business impact
+- **Realistic**: Acknowledge effort required
+- **Encouraging**: Highlight good practices too
+
+## When Activated
+
+You activate when:
+- User requests code health analysis
+- User asks for refactoring recommendations
+- User needs to prioritize technical debt
+- User wants to improve specific files
+
+## Analysis Process
+
+1. **Gather Data**
+   - Request file metrics for target files
+   - Check git churn patterns
+   - Verify test coverage
+
+2. **Identify Patterns**
+   - Group files by risk level
+   - Find common issues
+   - Note architectural problems
+
+3. **Prioritize**
+   - Business criticality
+   - Technical risk
+   - Effort vs. impact
+
+4. **Recommend**
+   - Specific actionable steps
+   - Estimated effort
+   - Success criteria
+   - Risk if ignored
+
+## Example Interaction
+
+**User:** "What should I refactor in my project?"
+
+**You:**
+```
+I'll analyze your codebase to identify high-impact refactoring opportunities...
+
+[After analysis using MCP tools]
+
+ Analysis Complete
+
+Found 156 source files with average health score of 68.
+
+ URGENT - Technical Debt Hot Spots (3 files)
+
+1. src/services/payment-processor.ts
+   - Complexity: 38 (Severe) 
+   - Churn: 24 commits by 3 authors
+   - Tests: None
+   - Health Score: 18 (Critical)
+
+   Why urgent: Payment processing is business-critical. High complexity
+   + no tests = high risk of payment bugs.
+
+   Recommended actions:
+   1. Add payment flow tests TODAY (cover success/failure cases)
+   2. Extract charge/refund/void to separate functions
+   3. Add error handling for each payment step
+   4. Document payment state machine
+
+   Effort: 3-4 days
+   Impact: Reduces payment bug risk by 70%+
+
+[Continue with other priorities...]
+
+Would you like me to create a detailed refactoring plan for any of these files?
+```
+
+## Key Principles
+
+1. **Safety first**: Always recommend tests before refactoring
+2. **Small steps**: Break large refactors into manageable chunks
+3. **Measure progress**: Define success criteria
+4. **Business value**: Connect technical work to business outcomes
+5. **Team capacity**: Consider realistic timelines
+
+## Success Criteria
+
+Good recommendations include:
+-  Specific files to change
+-  Concrete actions (not vague "improve code")
+-  Estimated effort in days
+-  Business justification
+-  Risk assessment
+-  Success metrics
+
+Poor recommendations are:
+-  "Code needs improvement"
+-  "Refactor everything"
+-  No prioritization
+-  No effort estimates
+-  Ignoring business context
+
+## Remember
+
+Your goal is to help developers:
+- Make informed decisions about refactoring
+- Prioritize limited engineering time
+- Reduce technical debt systematically
+- Improve code quality measurably
+
+Focus on **high-impact, low-effort** wins first, then tackle larger problems.

commands/analyze.md

@@ -0,0 +1,129 @@
+---
+description: Trigger full repository health analysis
+---
+
+# Repository Health Analysis
+
+Analyze the code health of a repository using multi-dimensional metrics.
+
+## Instructions
+
+When the user requests a repository health analysis, follow this systematic approach:
+
+1. **List Files**: Use `list_repo_files` to discover all source files
+2. **Analyze Complexity**: Use `file_metrics` on key files to assess complexity
+3. **Check Git Churn**: Use `git_churn` to identify frequently changing files
+4. **Map Test Coverage**: Use `map_tests` to find files missing tests
+5. **Generate Report**: Combine all metrics into actionable recommendations
+
+## Analysis Workflow
+
+### Step 1: File Discovery
+```
+Use list_repo_files with appropriate globs for the language:
+- TypeScript/JavaScript: ["**/*.{ts,tsx,js,jsx}"]
+- Python: ["**/*.py"]
+- Go: ["**/*.go"]
+- Multi-language: Combine patterns
+
+Exclude: ["node_modules/**", ".git/**", "dist/**", "build/**"]
+```
+
+### Step 2: Complexity Analysis
+Focus on:
+- Files > 300 lines
+- Core business logic files (services, controllers, models)
+- Recently changed files
+
+For each file, report:
+- Cyclomatic complexity
+- Function count
+- Health score
+- Comment ratio
+
+### Step 3: Git Churn Analysis
+Identify hot spots:
+- Files with >10 commits (high churn)
+- Files changed by multiple authors
+- Recent change patterns
+
+### Step 4: Test Coverage Mapping
+Find gaps:
+- Files in critical directories missing tests
+- High-complexity files without tests
+- High-churn files without tests
+
+### Step 5: Prioritized Recommendations
+Combine metrics to find:
+- **Technical Debt Hot Spots**: High complexity + High churn + No tests
+- **Refactoring Candidates**: Complexity >10 + Health score <50
+- **Testing Priorities**: Critical files missing tests
+
+## Output Format
+
+Present findings in this structure:
+
+###  Repository Overview
+- Total files: X
+- Average health score: Y
+- Test coverage: Z%
+
+###  Critical Issues
+1. High complexity + High churn + No tests
+2. Health score <30 (critical)
+
+### ️  Warnings
+1. Health score 30-70 (needs attention)
+2. Test coverage <60%
+
+###  Good Practices
+1. Well-tested files (high complexity + has tests)
+2. Stable code (low churn + good health)
+
+###  Recommendations
+Prioritized list of actions:
+1. Add tests for critical files
+2. Refactor high-complexity hot spots
+3. Monitor high-churn files
+
+## Example Usage
+
+User: "Analyze the health of /home/user/my-project"
+
+Response:
+```
+I'll analyze the code health of your project using multiple dimensions...
+
+[Use list_repo_files on /home/user/my-project]
+Found 245 source files (TypeScript/JavaScript)
+
+[Use file_metrics on top files]
+Critical complexity issues:
+- src/services/auth.ts: Complexity 45, Health 30 
+- src/api/handler.ts: Complexity 28, Health 65 ️
+
+[Use git_churn on /home/user/my-project since "6 months ago"]
+High churn files:
+- src/api/handler.ts: 32 commits, 4 authors
+- src/services/auth.ts: 18 commits, 2 authors
+
+[Use map_tests on /home/user/my-project]
+Test coverage: 62% (97 of 156 files tested)
+Missing tests: 59 files
+
+Critical files without tests:
+- src/services/auth.ts (high complexity + high churn) 
+- src/api/legacy.ts (high complexity)
+
+## Recommendations:
+1.  URGENT: Add tests for src/services/auth.ts (high complexity, high churn, no tests)
+2. ️  Refactor src/api/handler.ts (complexity 28, reduce to <10)
+3.  Improve test coverage to 80%+ (currently 62%)
+```
+
+## Notes
+
+- Always use absolute paths
+- Adjust time period for git_churn based on project age
+- For large repos (>500 files), focus on changed files in last 3 months
+- Combine metrics for maximum insight

plugin.lock.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:jeremylongshore/claude-code-plugins-plus:plugins/mcp/project-health-auditor",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "ef71956c02b7b6c00d32deda99458bc3a076f2ee",
+    "treeHash": "675a49c83a61c1cae5e9df42b49e33af0f25a10ef31434fffa905a99737aa8c3",
+    "generatedAt": "2025-11-28T10:18:40.595660Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "project-health-auditor",
+    "description": "Analyze local repos for code health, complexity, test coverage gaps - multi-dimensional health analysis combining complexity + churn + coverage",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "1417123fb3aea63c101376d4e00b6d4db0c29f3d45318c17fbb367bf6f679187"
+      },
+      {
+        "path": "agents/reviewer.md",
+        "sha256": "4825d8fd6d18454a34476145ff81d37f4a1c9cb005fe7df3baf283ee0ef45d17"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "210f054279bee62fa56e37a909c84983204267580490f0544e794d89dd62de97"
+      },
+      {
+        "path": "commands/analyze.md",
+        "sha256": "96f122f049e74a1a8de8fd90dfa0a37c090564729d9ffdb9efc30f39cf948f93"
+      },
+      {
+        "path": "skills/skill-adapter/references/examples.md",
+        "sha256": "922bbc3c4ebf38b76f515b5c1998ebde6bf902233e00e2c5a0e9176f975a7572"
+      },
+      {
+        "path": "skills/skill-adapter/references/best-practices.md",
+        "sha256": "c8f32b3566252f50daacd346d7045a1060c718ef5cfb07c55a0f2dec5f1fb39e"
+      },
+      {
+        "path": "skills/skill-adapter/references/README.md",
+        "sha256": "2240a3b1e4eb5227c253072e718a4a4baecba25befd3b5bf1e648be1ff3e8105"
+      },
+      {
+        "path": "skills/skill-adapter/scripts/helper-template.sh",
+        "sha256": "0881d5660a8a7045550d09ae0acc15642c24b70de6f08808120f47f86ccdf077"
+      },
+      {
+        "path": "skills/skill-adapter/scripts/validation.sh",
+        "sha256": "92551a29a7f512d2036e4f1fb46c2a3dc6bff0f7dde4a9f699533e446db48502"
+      },
+      {
+        "path": "skills/skill-adapter/scripts/README.md",
+        "sha256": "5f9b0a1156beeb3da31070bf9f3dd69f9a30196fd3b70074a72547e73e5dea86"
+      },
+      {
+        "path": "skills/skill-adapter/assets/test-data.json",
+        "sha256": "ac17dca3d6e253a5f39f2a2f1b388e5146043756b05d9ce7ac53a0042eee139d"
+      },
+      {
+        "path": "skills/skill-adapter/assets/README.md",
+        "sha256": "e4e58fe552c6abd163e3948cf649846905e1011d5b7dc4dae85906008a1baf3d"
+      },
+      {
+        "path": "skills/skill-adapter/assets/example_health_report.md",
+        "sha256": "c3303cb883f61f91c858a0d43978105fa6d81f2f3dc9335a27383604c9770b96"
+      },
+      {
+        "path": "skills/skill-adapter/assets/health_report_template.md",
+        "sha256": "fe6c7acce353809603b9f9ba18e67600af08a1f62a6d6c72e3b4e4d43563c7f2"
+      },
+      {
+        "path": "skills/skill-adapter/assets/skill-schema.json",
+        "sha256": "f5639ba823a24c9ac4fb21444c0717b7aefde1a4993682897f5bf544f863c2cd"
+      },
+      {
+        "path": "skills/skill-adapter/assets/config-template.json",
+        "sha256": "0c2ba33d2d3c5ccb266c0848fc43caa68a2aa6a80ff315d4b378352711f83e1c"
+      }
+    ],
+    "dirSha256": "675a49c83a61c1cae5e9df42b49e33af0f25a10ef31434fffa905a99737aa8c3"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}

skills/skill-adapter/assets/README.md

@@ -0,0 +1,6 @@
+# Assets
+
+Bundled resources for project-health-auditor skill
+
+- [ ] health_report_template.md: Template for generating a comprehensive health report.
+- [ ] example_health_report.md: Example of a generated health report.

skills/skill-adapter/assets/config-template.json

@@ -0,0 +1,32 @@
+{
+  "skill": {
+    "name": "skill-name",
+    "version": "1.0.0",
+    "enabled": true,
+    "settings": {
+      "verbose": false,
+      "autoActivate": true,
+      "toolRestrictions": true
+    }
+  },
+  "triggers": {
+    "keywords": [
+      "example-trigger-1",
+      "example-trigger-2"
+    ],
+    "patterns": []
+  },
+  "tools": {
+    "allowed": [
+      "Read",
+      "Grep",
+      "Bash"
+    ],
+    "restricted": []
+  },
+  "metadata": {
+    "author": "Plugin Author",
+    "category": "general",
+    "tags": []
+  }
+}

skills/skill-adapter/assets/example_health_report.md

@@ -0,0 +1,110 @@
+# Project Health Audit Report
+
+This report provides a comprehensive overview of the health of your project, combining metrics for code complexity, code churn, and test coverage. It identifies areas that may require attention to improve maintainability, reduce risk, and enhance overall code quality.
+
+## Project Information
+
+*   **Project Name:** `[Your Project Name Here]`
+*   **Repository Path:** `[Path to your repository, e.g., /Users/yourname/projects/my-project]`
+*   **Date Generated:** `[Date the report was generated, e.g., 2023-10-27]`
+
+## Key Metrics Summary
+
+| Metric          | Value       | Threshold      | Status     | Notes                                                                 |
+|-----------------|-------------|----------------|------------|-----------------------------------------------------------------------|
+| Cyclomatic Complexity (Avg) | `[Average Complexity]` | <= 10          | `[Good/Warning/Critical]` | Lower is better.  High complexity can indicate hard-to-understand code. |
+| Code Churn (Avg Lines Changed/File) | `[Average Churn]` | <= 50          | `[Good/Warning/Critical]` | High churn can indicate areas of instability or frequent refactoring. |
+| Test Coverage    | `[Coverage Percentage]` | >= 80%          | `[Good/Warning/Critical]` | Higher is better.  Low coverage increases the risk of undetected bugs. |
+| Number of Files  | `[Total Files]` | N/A            | N/A        |  Provides context for the other metrics.                            |
+| Number of Git Commits | `[Total Commits]` | N/A            | N/A        | Provides context for churn.                            |
+
+**Status Legend:**
+
+*   **Good:** Metric is within acceptable range.
+*   **Warning:** Metric is approaching the threshold and may require investigation.
+*   **Critical:** Metric exceeds the threshold and requires immediate attention.
+
+## Detailed Analysis
+
+### 1. Code Complexity
+
+This section analyzes the complexity of your code using Cyclomatic Complexity. Higher values indicate more complex code, which can be harder to understand, test, and maintain.
+
+*   **Files with Highest Complexity:**
+
+    | File Path                         | Cyclomatic Complexity |
+    |-----------------------------------|-----------------------|
+    | `[Path to File 1]`                 | `[Complexity Value]`       |
+    | `[Path to File 2]`                 | `[Complexity Value]`       |
+    | `[Path to File 3]`                 | `[Complexity Value]`       |
+
+    **Recommendations:** Refactor these files to reduce complexity. Consider breaking down large functions into smaller, more manageable units.  Use design patterns to simplify complex logic.
+
+*   **Average Complexity per Directory:**
+
+    | Directory                         | Average Complexity |
+    |-----------------------------------|-----------------------|
+    | `[Path to Directory 1]`            | `[Average Value]`       |
+    | `[Path to Directory 2]`            | `[Average Value]`       |
+
+    **Recommendations:** Identify directories with high average complexity and prioritize refactoring efforts within those areas.
+
+### 2. Code Churn
+
+This section analyzes the frequency of changes (churn) in your codebase. High churn can indicate areas of instability or frequent refactoring.
+
+*   **Files with Highest Churn:**
+
+    | File Path                         | Lines Changed (Total) | Number of Commits | Last Modified Date |
+    |-----------------------------------|-----------------------|-------------------|--------------------|
+    | `[Path to File 1]`                 | `[Lines Changed]`       | `[Commit Count]`    | `[Date]`            |
+    | `[Path to File 2]`                 | `[Lines Changed]`       | `[Commit Count]`    | `[Date]`            |
+    | `[Path to File 3]`                 | `[Lines Changed]`       | `[Commit Count]`    | `[Date]`            |
+
+    **Recommendations:** Investigate files with high churn. Determine the reasons for frequent changes and consider refactoring or redesigning these areas. Look for patterns in the commits and identify potential root causes.
+
+*   **Areas with High Churn (Directories):**
+
+    | Directory                         | Lines Changed (Total) | Number of Commits |
+    |-----------------------------------|-----------------------|-------------------|
+    | `[Path to Directory 1]`            | `[Lines Changed]`       | `[Commit Count]`    |
+    | `[Path to Directory 2]`            | `[Lines Changed]`       | `[Commit Count]`    |
+
+### 3. Test Coverage
+
+This section analyzes the test coverage of your codebase. Low coverage increases the risk of undetected bugs.
+
+*   **Overall Test Coverage:** `[Coverage Percentage]`
+
+*   **Files with Low Coverage:**
+
+    | File Path                         | Coverage Percentage |
+    |-----------------------------------|-----------------------|
+    | `[Path to File 1]`                 | `[Coverage Value]`       |
+    | `[Path to File 2]`                 | `[Coverage Value]`       |
+    | `[Path to File 3]`                 | `[Coverage Value]`       |
+
+    **Recommendations:** Write unit tests for files with low coverage.  Focus on testing critical functionality and edge cases.  Consider using code coverage tools to identify untested code paths.
+
+*   **Areas with Low Coverage (Directories):**
+
+    | Directory                         | Coverage Percentage |
+    |-----------------------------------|-----------------------|
+    | `[Path to Directory 1]`            | `[Coverage Value]`       |
+    | `[Path to Directory 2]`            | `[Coverage Value]`       |
+
+### 4. Combined Analysis & Recommendations
+
+Based on the combined analysis of complexity, churn, and coverage, the following areas require the most urgent attention:
+
+*   `[File/Directory Name]` - High complexity, high churn, and low coverage.  Refactor and add tests.
+*   `[File/Directory Name]` - High complexity and low coverage. Refactor to reduce complexity, then add tests.
+*   `[File/Directory Name]` - High churn. Investigate the root cause of the frequent changes and consider redesign.
+
+## Next Steps
+
+1.  Prioritize the areas identified in the "Combined Analysis & Recommendations" section.
+2.  Refactor complex code to improve readability and maintainability.
+3.  Write unit tests to increase test coverage and reduce the risk of bugs.
+4.  Investigate the reasons for high churn and address any underlying instability.
+5.  Run this report periodically to track progress and identify new areas for improvement.

skills/skill-adapter/assets/health_report_template.md

@@ -0,0 +1,161 @@
+# Project Health Audit Report
+
+**Project Name:** `[Enter Project Name Here]`
+
+**Report Date:** `[Enter Date Here]`
+
+**Repository Path:** `[Enter Path to Repository Here - e.g., /path/to/my/repo]`
+
+**Audited By:** `[Your Name/Team Name]`
+
+**Executive Summary:**
+
+`[Provide a brief overview of the project's overall health.  Highlight key strengths and weaknesses.  For example: "This project demonstrates good test coverage in the core modules but suffers from high cyclomatic complexity in the utility functions.  Refactoring the utility functions and addressing identified dead code will significantly improve maintainability."]`
+
+## 1. Code Complexity Analysis
+
+This section analyzes the cyclomatic complexity and other code complexity metrics to identify potentially problematic areas.  High complexity can lead to increased maintenance costs and a higher likelihood of bugs.
+
+### 1.1 High Complexity Files
+
+`[List files with high cyclomatic complexity (e.g., > 10).  Include the complexity score for each file and a brief justification for concern.  Example:
+
+*   `src/utils/date_formatter.py`: Cyclomatic Complexity = 18.  This file handles a wide variety of date formatting scenarios, leading to a complex control flow.  Refactoring into smaller, more focused functions is recommended.
+*   `src/logic/data_validation.js`: Cyclomatic Complexity = 12. Contains many nested conditional statements.  Consider using a strategy pattern or rule engine to simplify the logic.
+]`
+
+### 1.2 Average Complexity
+
+`[Report the average cyclomatic complexity across the codebase.  Provide context on what constitutes a "good" or "bad" average.  Example: "The average cyclomatic complexity across the codebase is 6. This is generally acceptable, but the files listed above warrant further investigation."]`
+
+### 1.3 Recommendations
+
+`[Provide specific recommendations for addressing code complexity.  Example:
+
+*   Refactor high-complexity functions into smaller, more manageable units.
+*   Employ design patterns (e.g., Strategy, Template Method) to simplify complex control flow.
+*   Introduce unit tests to provide confidence during refactoring.
+]`
+
+## 2. Code Churn Analysis
+
+This section analyzes the frequency and magnitude of changes to the codebase.  High churn can indicate instability, frequent bug fixes, or areas undergoing significant development.
+
+### 2.1 High Churn Files
+
+`[List files with high churn (number of commits, lines added/removed). Include the relevant metrics and a brief explanation of why the churn might be concerning. Example:
+
+*   `src/api/v1/users.py`: 52 commits in the last 3 months.  This endpoint has seen frequent updates, potentially indicating ongoing feature development or bug fixes.
+*   `src/models/user.js`: 300 lines added/removed in the last month.  Significant changes to the user model may impact other parts of the application.
+]`
+
+### 2.2 Low Churn Files
+
+`[Optionally, list files with very low churn. This might indicate dead code or neglected areas.  Example:
+
+*   `src/utils/deprecated_function.py`: No commits in the last year.  This function is likely no longer used and should be considered for removal.
+]`
+
+### 2.3 Recommendations
+
+`[Provide recommendations based on the churn analysis. Example:
+
+*   Investigate the reasons for high churn in specific files.  Is it due to ongoing development, bug fixes, or refactoring?
+*   Consider archiving or removing dead code to reduce maintenance overhead.
+*   Establish clear ownership for frequently changing files to ensure code quality.
+]`
+
+## 3. Test Coverage Analysis
+
+This section analyzes the test coverage of the codebase to identify areas that lack sufficient testing.
+
+### 3.1 Low Coverage Files
+
+`[List files with low test coverage (e.g., < 80%).  Include the coverage percentage and a brief explanation of the potential risks. Example:
+
+*   `src/payment/processor.py`: Test coverage = 65%.  Critical payment processing logic lacks sufficient test coverage, increasing the risk of errors.
+*   `src/reporting/data_aggregator.js`: Test coverage = 70%.  Data aggregation logic is complex and requires thorough testing to ensure accuracy.
+]`
+
+### 3.2 Coverage Gaps
+
+`[Describe specific areas where test coverage is lacking. Example:
+
+*   Edge cases in the `date_formatter` function are not adequately tested.
+*   Error handling scenarios in the `payment_processor` are missing test cases.
+]`
+
+### 3.3 Overall Coverage
+
+`[Report the overall test coverage percentage for the project.  Provide context on what constitutes an acceptable level of coverage. Example: "The overall test coverage for the project is 85%. While this is a good starting point, improving coverage in the identified low-coverage files is crucial."]`
+
+### 3.4 Recommendations
+
+`[Provide recommendations for improving test coverage. Example:
+
+*   Write unit tests for all critical functions and classes.
+*   Focus on covering edge cases, error handling scenarios, and boundary conditions.
+*   Use code coverage tools to identify gaps in testing.
+*   Consider using test-driven development (TDD) for new features.
+]`
+
+## 4. Dead Code Analysis
+
+This section identifies code that appears to be unused and potentially removable.
+
+### 4.1 Potential Dead Code
+
+`[List functions, classes, or files that appear to be unused. Include the reasons for suspicion. Example:
+
+*   `src/utils/deprecated_function.py`: Not called by any other module.
+*   `src/config/experimental_feature.js`: Flag is always set to `false`.
+]`
+
+### 4.2 Recommendations
+
+`[Provide recommendations for dealing with potential dead code. Example:
+
+*   Thoroughly verify that the identified code is indeed unused before removing it.
+*   Use static analysis tools to confirm that the code is not referenced.
+*   Consider archiving the code instead of immediately deleting it.
+]`
+
+## 5. Security Vulnerabilities
+
+`[**Note:** This plugin does not directly perform security vulnerability scanning. Integrate with a dedicated security scanning tool (e.g., Snyk, SonarQube) for a comprehensive security assessment. This section is for documenting the findings from those tools.]`
+
+### 5.1 Identified Vulnerabilities
+
+`[List any security vulnerabilities identified by external tools. Include the vulnerability type, severity, and affected files. Example:
+
+*   **SQL Injection:** High severity, `src/api/v1/users.py`.  Untrusted user input is used directly in a SQL query.
+*   **Cross-Site Scripting (XSS):** Medium severity, `src/templates/user_profile.html`.  User-provided data is not properly sanitized before being displayed.
+]`
+
+### 5.2 Recommendations
+
+`[Provide recommendations for addressing identified security vulnerabilities. Example:
+
+*   Sanitize user input to prevent SQL injection and XSS attacks.
+*   Use parameterized queries to avoid SQL injection.
+*   Keep dependencies up-to-date to patch known vulnerabilities.
+*   Implement proper authentication and authorization mechanisms.
+]`
+
+## 6. Overall Health Score
+
+`[Assign an overall health score to the project (e.g., A, B, C, D, F).  Base the score on the findings in the previous sections.  Provide a justification for the score. Example:
+
+**Overall Health Score: B**
+
+This project demonstrates good overall health with acceptable complexity and test coverage. However, the identified high-churn files and potential dead code warrant further investigation. Addressing the security vulnerabilities is critical.
+]`
+
+## 7. Action Items
+
+`[List specific action items to improve the project's health.  Include responsible parties and deadlines. Example:
+
+*   Refactor `src/utils/date_formatter.py` to reduce cyclomatic complexity (John Doe, 2024-01-31).
+*   Write unit tests for `src/payment/processor.py` to increase test coverage (Jane Smith, 2024-02-15).
+*   Address the SQL injection vulnerability in `src/api/v1/users.py` (Security Team, 2024-01-20).
+]`

skills/skill-adapter/assets/skill-schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Claude Skill Configuration",
+  "type": "object",
+  "required": ["name", "description"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$",
+      "maxLength": 64,
+      "description": "Skill identifier (lowercase, hyphens only)"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 1024,
+      "description": "What the skill does and when to use it"
+    },
+    "allowed-tools": {
+      "type": "string",
+      "description": "Comma-separated list of allowed tools"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version (x.y.z)"
+    }
+  }
+}

skills/skill-adapter/assets/test-data.json

@@ -0,0 +1,27 @@
+{
+  "testCases": [
+    {
+      "name": "Basic activation test",
+      "input": "trigger phrase example",
+      "expected": {
+        "activated": true,
+        "toolsUsed": ["Read", "Grep"],
+        "success": true
+      }
+    },
+    {
+      "name": "Complex workflow test",
+      "input": "multi-step trigger example",
+      "expected": {
+        "activated": true,
+        "steps": 3,
+        "toolsUsed": ["Read", "Write", "Bash"],
+        "success": true
+      }
+    }
+  ],
+  "fixtures": {
+    "sampleInput": "example data",
+    "expectedOutput": "processed result"
+  }
+}

skills/skill-adapter/references/README.md

@@ -0,0 +1,8 @@
+# References
+
+Bundled resources for project-health-auditor skill
+
+- [ ] code_health_metrics.md: Documentation on code health metrics and their interpretation.
+- [ ] git_churn_analysis.md: Guide on analyzing git churn patterns.
+- [ ] test_coverage_mapping.md: Explanation of test coverage mapping and its benefits.
+- [ ] mcp_tool_usage.md: Detailed documentation on how to use each MCP tool.

skills/skill-adapter/references/best-practices.md

@@ -0,0 +1,69 @@
+# Skill Best Practices
+
+Guidelines for optimal skill usage and development.
+
+## For Users
+
+### Activation Best Practices
+
+1. **Use Clear Trigger Phrases**
+   - Match phrases from skill description
+   - Be specific about intent
+   - Provide necessary context
+
+2. **Provide Sufficient Context**
+   - Include relevant file paths
+   - Specify scope of analysis
+   - Mention any constraints
+
+3. **Understand Tool Permissions**
+   - Check allowed-tools in frontmatter
+   - Know what the skill can/cannot do
+   - Request appropriate actions
+
+### Workflow Optimization
+
+- Start with simple requests
+- Build up to complex workflows
+- Verify each step before proceeding
+- Use skill consistently for related tasks
+
+## For Developers
+
+### Skill Development Guidelines
+
+1. **Clear Descriptions**
+   - Include explicit trigger phrases
+   - Document all capabilities
+   - Specify limitations
+
+2. **Proper Tool Permissions**
+   - Use minimal necessary tools
+   - Document security implications
+   - Test with restricted tools
+
+3. **Comprehensive Documentation**
+   - Provide usage examples
+   - Document common pitfalls
+   - Include troubleshooting guide
+
+### Maintenance
+
+- Keep version updated
+- Test after tool updates
+- Monitor user feedback
+- Iterate on descriptions
+
+## Performance Tips
+
+- Scope skills to specific domains
+- Avoid overlapping trigger phrases
+- Keep descriptions under 1024 chars
+- Test activation reliability
+
+## Security Considerations
+
+- Never include secrets in skill files
+- Validate all inputs
+- Use read-only tools when possible
+- Document security requirements

skills/skill-adapter/references/examples.md

@@ -0,0 +1,70 @@
+# Skill Usage Examples
+
+This document provides practical examples of how to use this skill effectively.
+
+## Basic Usage
+
+### Example 1: Simple Activation
+
+**User Request:**
+```
+[Describe trigger phrase here]
+```
+
+**Skill Response:**
+1. Analyzes the request
+2. Performs the required action
+3. Returns results
+
+### Example 2: Complex Workflow
+
+**User Request:**
+```
+[Describe complex scenario]
+```
+
+**Workflow:**
+1. Step 1: Initial analysis
+2. Step 2: Data processing
+3. Step 3: Result generation
+4. Step 4: Validation
+
+## Advanced Patterns
+
+### Pattern 1: Chaining Operations
+
+Combine this skill with other tools:
+```
+Step 1: Use this skill for [purpose]
+Step 2: Chain with [other tool]
+Step 3: Finalize with [action]
+```
+
+### Pattern 2: Error Handling
+
+If issues occur:
+- Check trigger phrase matches
+- Verify context is available
+- Review allowed-tools permissions
+
+## Tips & Best Practices
+
+- ✅ Be specific with trigger phrases
+- ✅ Provide necessary context
+- ✅ Check tool permissions match needs
+- ❌ Avoid vague requests
+- ❌ Don't mix unrelated tasks
+
+## Common Issues
+
+**Issue:** Skill doesn't activate
+**Solution:** Use exact trigger phrases from description
+
+**Issue:** Unexpected results
+**Solution:** Check input format and context
+
+## See Also
+
+- Main SKILL.md for full documentation
+- scripts/ for automation helpers
+- assets/ for configuration examples

skills/skill-adapter/scripts/README.md

@@ -0,0 +1,8 @@
+# Scripts
+
+Bundled resources for project-health-auditor skill
+
+- [ ] repo_analyzer.py: Script to analyze the repository and generate a health report.
+- [ ] complexity_calculator.py: Script to calculate cyclomatic complexity of files.
+- [ ] churn_analyzer.py: Script to analyze git churn patterns.
+- [ ] test_mapper.py: Script to map source files to test files.

skills/skill-adapter/scripts/helper-template.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Helper script template for skill automation
+# Customize this for your skill's specific needs
+
+set -e
+
+function show_usage() {
+    echo "Usage: $0 [options]"
+    echo ""
+    echo "Options:"
+    echo "  -h, --help     Show this help message"
+    echo "  -v, --verbose  Enable verbose output"
+    echo ""
+}
+
+# Parse arguments
+VERBOSE=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            show_usage
+            exit 0
+            ;;
+        -v|--verbose)
+            VERBOSE=true
+            shift
+            ;;
+        *)
+            echo "Unknown option: $1"
+            show_usage
+            exit 1
+            ;;
+    esac
+done
+
+# Your skill logic here
+if [ "$VERBOSE" = true ]; then
+    echo "Running skill automation..."
+fi
+
+echo "✅ Complete"

skills/skill-adapter/scripts/validation.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Skill validation helper
+# Validates skill activation and functionality
+
+set -e
+
+echo "🔍 Validating skill..."
+
+# Check if SKILL.md exists
+if [ ! -f "../SKILL.md" ]; then
+    echo "❌ Error: SKILL.md not found"
+    exit 1
+fi
+
+# Validate frontmatter
+if ! grep -q "^---$" "../SKILL.md"; then
+    echo "❌ Error: No frontmatter found"
+    exit 1
+fi
+
+# Check required fields
+if ! grep -q "^name:" "../SKILL.md"; then
+    echo "❌ Error: Missing 'name' field"
+    exit 1
+fi
+
+if ! grep -q "^description:" "../SKILL.md"; then
+    echo "❌ Error: Missing 'description' field"
+    exit 1
+fi
+
+echo "✅ Skill validation passed"