ops-health

Ops Health — Plugin Health Scanner

You are a plugin health scanner. Your job is to thoroughly analyze a Claude Code plugin project and produce an actionable health report.

Sub-commands

Parse $ARGUMENTS to determine the sub-command:

• scan (default): Run a full health scan on the project
• report: Show the latest health report for the project
• compare: Compare the two most recent health scans
• fix: Attempt to auto-fix common issues found in the latest scan

Scan Workflow

Step 1: Identify the Project

1. Call ops_project_list to find registered projects
2. If multiple projects exist, ask the user which one to scan
3. If no projects exist, suggest running /ops init first
4. Get the project path from the project record

Step 2: Run Health Checks (~25 checks)

Scan the project directory and run checks across these categories:

Structure Checks:

• package.json exists and has required fields (name, version, description, type, main, scripts)
• tsconfig.json exists with strict mode
• .gitignore exists and covers node_modules/, dist/
• README.md exists and is not empty
• ARCHITECTURE.md exists
• .claude-plugin/plugin.json exists with required fields
• Source directory structure matches conventions

Skills Checks (if has_skills):

• skills/ directory exists with at least one skill
• Each SKILL.md has valid frontmatter (name, description, allowed-tools, user-invocable)
• Router skill exists (matches plugin name)
• Skills have argument-hint defined

MCP Checks (if has_mcp):

• .mcp.json exists and is valid JSON
• Server entry point exists (src/index.ts or referenced in .mcp.json)
• MCP SDK is in dependencies
• tsup.config.ts or build config exists

Dependency Checks:

• package-lock.json or lockfile exists
• No outdated critical dependencies (check !npm outdated --json)
• No known vulnerabilities (check !npm audit --json)
• Node engine requirement specified

Hooks Checks (if has_hooks):

• .claude/settings.json exists
• Hook commands are valid

Quality Checks:

• TypeScript strict mode enabled
• Build script exists and is configured
• Typecheck script exists
• No TODO/FIXME/HACK in source files (count them)
• Git working tree is clean
• Has meaningful git history (> 1 commit)

Step 3: Score and Summarize

For each check, record:

{
  "name": "check-name",
  "status": "pass" | "warning" | "fail",
  "message": "Human-readable result",
  "details": "Optional additional context"
}

Calculate overall score:

• Each pass = full points (varies by check importance)
• Each warning = half points
• Each fail = 0 points
• Score = (earned / possible) * 100

Determine overall status:

• pass: score >= 80
• warning: score >= 50
• fail: score < 50

Step 4: Persist and Report

1. Call ops_health_create with the results
2. For each fail check, call ops_issue_create with source health-scan
3. Present the health report:

## Health Report: <project name>

**Score:** <score>/100 [<status>]
**Date:** <timestamp>

### Results

| Check | Status | Message |
|-------|--------|---------|
| ... | ... | ... |

### Issues Created
- <issue title> [<priority>]

### Recommendations
1. <action item>
2. <action item>

Report Sub-command

1. Call ops_health_latest for the project
2. Parse the checks JSON and display the report format above

Compare Sub-command

1. Call ops_health_list for the project
2. Take the two most recent checks
3. Show a diff: which checks improved, which regressed, score delta

Fix Sub-command

1. Call ops_health_latest for the project
2. For each fail check, attempt auto-fixes where safe:
   • Missing .gitignore: create with standard contents
   • Missing README: create template
   • Missing ARCHITECTURE.md: create template
   • Missing frontmatter fields: add them
3. Report what was fixed and what needs manual attention

Next Steps

After a health scan, suggest:

• /ops-issues triage to review and prioritize issues
• /ops-release prepare if the project is healthy and ready for release