@hiai-gg/agent-plugins-doctor

v0.0.7

Published

a month ago

Diagnose and fix Agent Plugins

0High
0Medium
0Low

vlgalib

agent-plugins agent-skills validation diagnostics security compatibility mcp cli typescript bun

Agent Plugin Doctor

Build, validate, and use portable Agent Plugins. Doctor validates, diagnoses, and safely fixes Agent Plugins — the quality gate between building a plugin and shipping it.

Ecosystem

| Project | Purpose | | ----------------------------------------------------------- | --------------------------------------------------------------------- | | Agent Plugins | The portable Agent Plugins standard | | Builder | Create, migrate, and package portable Agent Plugins | | Doctor | Validate, diagnose, and safely fix Agent Plugins (this project) | | Collection | 13 curated product plugins built with Builder and validated by Doctor |

Doctor is standalone tooling — it is not one of the 13 product plugins in the collection. Builder creates plugins; Doctor validates, diagnoses, and safely fixes them; the collection ships curated plugins that pass Doctor's checks.

What Doctor Does

Validate — checks plugin.json, mcp.json, and SKILL.md files against the official Agent Plugins v1.0.0 specification
Diagnose — explains what is wrong and why, with stable diagnostic codes
Safely fix — applies 12 automatic fixes for common issues; preview every change with --dry-run first

Quick Start

# Check a plugin (current release 0.0.7)
npx @hiai-gg/[email protected] check ./my-plugin

# Preview safe fixes without touching your files
npx @hiai-gg/[email protected] fix ./my-plugin --dry-run

# Apply the safe fixes
npx @hiai-gg/[email protected] fix ./my-plugin --yes

# Generate a report
npx @hiai-gg/[email protected] report ./my-plugin --format markdown

Or install globally and run the agent-plugins-doctor binary:

npm install -g @hiai-gg/agent-plugins-doctor
# or: bun install -g @hiai-gg/agent-plugins-doctor
agent-plugins-doctor check ./my-plugin

The CLI is published to npm as a single self-contained package, @hiai-gg/agent-plugins-doctor (runs on Node ≥ 18 — no Bun required); inside this repository it resolves to the local workspace binary (see Development).

Exit codes:

0 — valid
1 — spec errors
2 — security-critical
3 — tool failure

Collection CI

Validate the collection in CI with a single command:

npx @hiai-gg/agent-plugins-doctor check plugins/<plugin-name>

The npm package is self-contained (no Bun required, Node ≥ 18).

What is Agent Plugin Doctor?

Agent Plugin Doctor is the canonical validation, diagnostics, and security-auditing tool for the Agent Plugins ecosystem. Its role: validate, diagnose, and safely fix Agent Plugins. It validates plugins against the official specification, checks compatibility with verified clients, and provides safe automatic fixes.

Features

Specification Validation — Validates plugin.json, mcp.json, and SKILL.md files against the official Agent Plugins v1.0.0 specification
Security Auditing — Detects embedded secrets, path traversal, and symlink escapes
Compatibility Checking — Checks compatibility with VS Code, Cursor, GitHub Copilot, ChatGPT & Codex, and Kiro
Safe Auto-Fixes — 12 automatic fixes for common issues like formatting, missing fields, and naming mismatches
Multiple Output Formats — Human-readable terminal output, JSON for CI, and Markdown for documentation
Self-Hosting — Doctor validates itself as an Agent Plugin (check . exits 0 with zero diagnostics)
Cross-Platform — CI runs the full suite on Linux, macOS, and Windows (Bun 1.3.14)
Comprehensive Test Suite — 673 tests across 83 files: unit, integration, E2E (spawns the real binary), fixture-based, and benchmark budgets

CLI Commands

check

Validate a plugin and report issues.

agent-plugins-doctor check [dir] [options]

Options:
  --json          Output as JSON
  --markdown      Output as Markdown
  --strict        Treat warnings as errors
  --rule <id>     Run only specific rules
  --exclude-rule  Exclude specific rules
  --verbose       Show detailed output
  --no-color      Disable colors

fix

Apply safe fixes to a plugin.

agent-plugins-doctor fix [dir] [options]

Options:
  --dry-run       Show what would be fixed
  --yes           Apply fixes without confirmation
  --json          Output as JSON
  --no-color      Disable colors

report

Generate a detailed report.

agent-plugins-doctor report [dir] [options]

Options:
  --format <fmt>  human|json|markdown (default: human)
  --output <file> Write to file

compatibility

Check client compatibility.

agent-plugins-doctor compatibility [dir] [options]

Options:
  --client <id>   Check specific client (vscode|cursor|copilot|codex|kiro)
  --json          Output as JSON

SDK (Library API)

The CLI is published as @hiai-gg/agent-plugins-doctor, a single bundled package that includes everything — no separate library dependencies are needed to use it.

The six @agent-plugins-doctor/* packages (core, parser, rules, compatibility, report, cli) are not yet published to npm — SDK publication is deferred. Until they are published, import them from the monorepo. See docs/SDK.md for the complete API reference and PUBLISHING.md for the npm publish procedure.

Supported Specifications

Agent Plugins v1.0.0
Agent Skills (via agentskills.io)
MCP (Model Context Protocol)

Supported Clients

| Client | Skills | MCP stdio | MCP Streamable HTTP | MCP SSE | | --------------- | ------ | --------- | ------------------- | ------- | | VS Code | ✅ | ✅ | ✅ | ✅ | | Cursor | ✅ | ✅ | ✅ | ✅ | | GitHub Copilot | ✅ | ✅ | ✅ | ✅ | | ChatGPT & Codex | ✅ | ✅ | ✅ | ❌ | | Kiro | ✅ | ✅ | ✅ | ✅ |

Relationship with Builder and the Collection

Agent Plugin Doctor is the validation counterpart to Agent Plugin Builder. Builder creates plugins; Doctor validates, diagnoses, and safely fixes them. Builder will consume Doctor as a dependency to ensure generated plugins are valid. The collection ships 13 curated product plugins that pass Doctor's checks — Doctor itself is standalone tooling, not one of those plugins.

See docs/BUILDER_INTEGRATION.md for integration details.

Diagnostic Codes

Doctor uses 36 stable diagnostic codes:

DOC-1xxx — Manifest & spec conformance
DOC-2xxx — Skills
DOC-3xxx — MCP
DOC-4xxx — Security
DOC-5xxx — Structure & packaging
DOC-6xxx — Compatibility
DOC-7xxx — Format & quality

Of the 36 codes, 25 are reachable from the public CLI (7 of them emitted by the parser during load), 10 fire only through the SDK, and 1 (DOC-6002) is intentionally dormant under v1.0.0.

See docs/DIAGNOSTICS.md for the complete catalog, per-code reachability, and the autofix list.

Exit Codes

| Code | Meaning | | ---- | -------------------------------------------------------------- | | 0 | Valid (warnings/info allowed, unless --strict) | | 1 | Validation errors (malformed input, spec violations) | | 2 | Security-critical findings | | 3 | Tool failure (inaccessible plugin root, internal rule failure) |

Development

# From a clean clone, install dependencies and run every quality gate
bun install --frozen-lockfile && bun run check

# Individual public gates build first, so they also work from a clean checkout
bun run test

# Type check
bun run typecheck

# Lint
bun run lint

# Run all gates: build, typecheck, lint, tests, formatting, strict self-check
bun run check

CI (.github/workflows/ci.yml) runs the same frozen install and unified check on Linux, macOS, and Windows.

Documentation

docs/ARCHITECTURE.md — package architecture, design decisions (ADRs), data flow, and performance model
docs/SDK.md — complete API reference for all 6 packages
docs/DIAGNOSTICS.md — catalog of all diagnostic codes and their exit-code mapping
docs/COMPATIBILITY.md — verified-client compatibility matrix and evidence
docs/EXTENSIBILITY.md — how to add rules, spec versions, report formats, client profiles, and fixes
docs/RELEASING.md — release and git-tag procedure
PUBLISHING.md — npm publish procedure for the six packages

Contributing

See CONTRIBUTING.md for contribution guidelines.