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 <noreply@anthropic.com>
This commit is contained in:
156
plugins/contract-validator/README.md
Normal file
156
plugins/contract-validator/README.md
Normal file
@@ -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
|
||||||
152
plugins/contract-validator/claude-md-integration.md
Normal file
152
plugins/contract-validator/claude-md-integration.md
Normal file
@@ -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 }}"
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user