refactor(projman): extract skills and consolidate commands
Major refactoring of projman plugin architecture: Skills Extraction (17 new files): - Extracted reusable knowledge from commands and agents into skills/ - branch-security, dependency-management, git-workflow, input-detection - issue-conventions, lessons-learned, mcp-tools-reference, planning-workflow - progress-tracking, repo-validation, review-checklist, runaway-detection - setup-workflows, sprint-approval, task-sizing, test-standards, wiki-conventions Command Consolidation (17 → 12 commands): - /setup: consolidates initial-setup, project-init, project-sync (--full/--quick/--sync) - /debug: consolidates debug-report, debug-review (report/review modes) - /test: consolidates test-check, test-gen (run/gen modes) - /sprint-status: absorbs sprint-diagram via --diagram flag Architecture Cleanup: - Remove plugin-level mcp-servers/ symlinks (6 plugins) - Remove plugin README.md files (12 files, ~2000 lines) - Update all documentation to reflect new command structure - Fix documentation drift in CONFIGURATION.md, COMMANDS-CHEATSHEET.md Commands are now thin dispatchers (~20-50 lines) that reference skills. Agents reference skills for domain knowledge instead of inline content. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,169 +0,0 @@
|
||||
# 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
|
||||
- **Dependency Visualization**: Generate Mermaid flowcharts showing plugin relationships
|
||||
- **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 |
|
||||
|---------|-------------|
|
||||
| `/initial-setup` | Interactive setup wizard |
|
||||
| `/validate-contracts` | Full marketplace compatibility validation |
|
||||
| `/check-agent` | Validate single agent definition |
|
||||
| `/list-interfaces` | Show all plugin interfaces |
|
||||
| `/dependency-graph` | Generate Mermaid flowchart of plugin dependencies |
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
```
|
||||
/dependency-graph
|
||||
|
||||
# Output: Mermaid flowchart showing:
|
||||
# - Plugins grouped by shared MCP servers
|
||||
# - Data flow from data-platform to viz-platform
|
||||
# - Required vs optional dependencies
|
||||
# - Command counts per plugin
|
||||
```
|
||||
|
||||
## 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
|
||||
@@ -1 +0,0 @@
|
||||
../../../mcp-servers/contract-validator
|
||||
Reference in New Issue
Block a user