From ec965dc8ee02efb0891b6d63db57177591a7979c Mon Sep 17 00:00:00 2001 From: lmiranda Date: Mon, 26 Jan 2026 14:58:34 -0500 Subject: [PATCH] docs(contract-validator): create documentation (#191) Add comprehensive plugin documentation: - README.md: Plugin overview, problem statement, tool docs, example workflows, issue types, best practices - claude-md-integration.md: CLAUDE.md snippets, interface documentation standards, CI/CD integration guide Co-Authored-By: Claude Opus 4.5 --- plugins/contract-validator/README.md | 156 ++++++++++++++++++ .../claude-md-integration.md | 152 +++++++++++++++++ 2 files changed, 308 insertions(+) create mode 100644 plugins/contract-validator/README.md create mode 100644 plugins/contract-validator/claude-md-integration.md diff --git a/plugins/contract-validator/README.md b/plugins/contract-validator/README.md new file mode 100644 index 0000000..6af6bef --- /dev/null +++ b/plugins/contract-validator/README.md @@ -0,0 +1,156 @@ +# 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: + +```bash +# 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 | +|---------|-------------| +| `/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: + +```json +{ + "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 diff --git a/plugins/contract-validator/claude-md-integration.md b/plugins/contract-validator/claude-md-integration.md new file mode 100644 index 0000000..e2b396a --- /dev/null +++ b/plugins/contract-validator/claude-md-integration.md @@ -0,0 +1,152 @@ +# contract-validator Plugin - CLAUDE.md Integration + +Add this section to your marketplace or project's CLAUDE.md to enable contract validation features. + +## Suggested CLAUDE.md Section + +```markdown +## Contract Validation + +This marketplace uses the contract-validator plugin for cross-plugin compatibility checks. + +### Available Commands + +| Command | Purpose | +|---------|---------| +| `/validate-contracts` | Full marketplace compatibility validation | +| `/check-agent` | Validate single agent definition | +| `/list-interfaces` | Show all plugin interfaces | + +### Validation Workflow + +Run before merging plugin changes: + +1. `/validate-contracts` - Check for conflicts +2. Review errors (must fix) and warnings (should review) +3. Fix issues before merging + +### Interface Documentation Standards + +For plugins to be validated correctly, document interfaces in README.md: + +**Commands Section:** +```markdown +## Commands + +| Command | Description | +|---------|-------------| +| `/my-command` | What it does | +``` + +**Tools Section:** +```markdown +## Tools Summary + +### Category (N tools) +`tool_a`, `tool_b`, `tool_c` +``` + +**Agents Section:** +```markdown +## Agents + +| Agent | Description | +|-------|-------------| +| `my-agent` | What it does | +``` +``` + +## Declaring Agent Tool References + +For agent validation to work, document tool usage in CLAUDE.md: + +### Option 1: Four-Agent Model Table + +```markdown +### Four-Agent Model + +| Agent | Personality | Responsibilities | +|-------|-------------|------------------| +| **Planner** | Methodical | Planning via `create_issue`, `search_lessons` | +``` + +### Option 2: Agent Sections + +```markdown +### Planner Agent + +Uses these tools: +- `create_issue` - Create planning issues +- `search_lessons` - Find relevant lessons +``` + +## Best Practices for Plugin Authors + +### Unique Command Names + +Avoid generic names that may conflict: + +```markdown +# BAD - Will conflict with other plugins +| `/setup` | Setup wizard | + +# GOOD - Plugin-specific prefix +| `/data-setup` | Data platform setup wizard | +``` + +### Document All Tools + +Ensure every MCP tool is listed in README.md: + +```markdown +## Tools Summary + +### pandas (14 tools) +`read_csv`, `read_parquet`, `read_json`, `to_csv`, `to_parquet`, +`describe`, `head`, `tail`, `filter`, `select`, `groupby`, `join`, +`list_data`, `drop_data` +``` + +### Specify Dependencies + +If agents depend on tools from other plugins, document it: + +```markdown +## Dependencies + +This agent uses tools from: +- `projman` - Issue management (`create_issue`, `update_issue`) +- `data-platform` - Data loading (`read_csv`, `describe`) +``` + +## Typical Workflows + +### Pre-Merge Validation + +``` +# Before merging new plugin +/validate-contracts + +# Check specific agent after changes +/check-agent Orchestrator +``` + +### Plugin Development + +``` +# See what interfaces exist +/list-interfaces + +# After adding new command, verify no conflicts +/validate-contracts +``` + +### CI/CD Integration + +Add to your pipeline: + +```yaml +- name: Validate Plugin Contracts + run: | + claude --skill contract-validator:validate-contracts --args "${{ github.workspace }}" +```