leo-claude-mktplace/plugins/contract-validator/README.md

contract-validator Plugin

Cross-plugin compatibility validation and CLAUDE.md agent verification for Claude Code plugin marketplaces.

Problem Statement

As plugin marketplaces grow, several compatibility issues emerge:

• Command conflicts: Multiple plugins defining the same slash command (e.g., /initial-setup)
• Tool name overlaps: Different plugins using identical tool names with incompatible interfaces
• Undocumented dependencies: Agents referencing tools that don't exist
• Broken data flows: Agent sequences that expect outputs not produced by prior steps

Contract-validator solves these by parsing plugin interfaces and validating compatibility before runtime.

Features

• Interface Parsing: Extract commands, agents, and tools from plugin README.md files
• Agent Extraction: Parse CLAUDE.md Four-Agent Model tables and Agents sections
• Compatibility Checks: Pairwise validation between all plugins in a marketplace
• Data Flow Validation: Verify agent tool sequences have valid data producers/consumers
• Comprehensive Reports: Markdown or JSON reports with actionable suggestions

Installation

This plugin is part of the leo-claude-mktplace. Install via:

# From marketplace
claude plugins install leo-claude-mktplace/contract-validator

# Setup MCP server venv
cd ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/contract-validator
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Commands

Command	Description
/initial-setup	Interactive setup wizard
/validate-contracts	Full marketplace compatibility validation
/check-agent	Validate single agent definition
/list-interfaces	Show all plugin interfaces

Agents

Agent	Description
full-validation	Complete cross-plugin compatibility validation
agent-check	Single agent definition verification

Tools Summary

Parse Tools (2)

• parse_plugin_interface - Extract interface from plugin README.md
• parse_claude_md_agents - Extract agents from CLAUDE.md

Validation Tools (3)

• validate_compatibility - Check two plugins for conflicts
• validate_agent_refs - Verify agent tool references exist
• validate_data_flow - Check data flow through agent sequences

Report Tools (2)

• generate_compatibility_report - Full marketplace validation report
• list_issues - Filter issues by severity or type

Example Workflow

/validate-contracts ~/claude-plugins-work

# Output:
# Contract Validation Report
#
# | Metric     | Count |
# |------------|-------|
# | Plugins    | 12    |
# | Commands   | 39    |
# | Tools      | 32    |
# | **Issues** | **7** |
# | - Errors   | 3     |
# | - Warnings | 0     |
# | - Info     | 4     |
#
# ## Issues Found
# [ERROR] Command conflict: projman and data-platform both define /initial-setup
# [ERROR] Command conflict: projman and pr-review both define /initial-setup
# ...

/check-agent Planner ./CLAUDE.md

# Output:
# Agent: Planner
# Status: VALID
#
# Tool References Found (3):
# - create_issue ✓
# - search_lessons ✓
# - get_execution_order ✓
#
# Data Flow: No issues detected

Issue Types

Type	Severity	Description
interface_mismatch	ERROR	Command name conflict between plugins
missing_tool	ERROR	Agent references non-existent tool
interface_mismatch	WARNING	Tool name overlap (different plugins)
optional_dependency	WARNING	Agent uses tool from non-required plugin
undeclared_output	INFO	Agent has no documented tool references

Parsed Interface Structure

When parsing a plugin README.md, the following structure is extracted:

{
  "plugin_name": "data-platform",
  "description": "Data engineering tools...",
  "commands": [
    {"name": "/ingest", "description": "Load data..."}
  ],
  "agents": [
    {"name": "data-analysis", "description": "..."}
  ],
  "tools": [
    {"name": "read_csv", "category": "pandas"}
  ],
  "tool_categories": {
    "pandas": ["read_csv", "to_csv", ...],
    "PostgreSQL": ["pg_query", ...]
  },
  "features": ["pandas Operations", "PostgreSQL/PostGIS", ...]
}

Best Practices

For Plugin Authors

1. Use unique command names: Prefix with plugin name if generic (e.g., /data-setup vs /initial-setup)
2. Document all tools: Include tool names in README.md with backticks
3. Specify tool categories: Use ### Category (N tools) headers
4. Declare agent tools: List tools used by agents in their definitions

For Marketplace Maintainers

1. Run validation before merging: Use /validate-contracts in CI/CD
2. Review warnings: Tool overlaps may indicate design issues
3. Track issues over time: Use JSON format for programmatic tracking