From 8f450c0e7b24c3735a1224184e468bc6fbe25643 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Mon, 26 Jan 2026 14:55:58 -0500 Subject: [PATCH] feat(contract-validator): create commands (#189) Add 3 user-facing commands: - /validate-contracts: Full marketplace compatibility validation - /check-agent: Validate single agent definition - /list-interfaces: Show plugin interfaces summary Each command documents usage, workflow, parameters, and available MCP tools for implementation. Co-Authored-By: Claude Opus 4.5 --- .../commands/check-agent.md | 51 ++++++++++++++++ .../commands/list-interfaces.md | 58 +++++++++++++++++++ .../commands/validate-contracts.md | 50 ++++++++++++++++ 3 files changed, 159 insertions(+) create mode 100644 plugins/contract-validator/commands/check-agent.md create mode 100644 plugins/contract-validator/commands/list-interfaces.md create mode 100644 plugins/contract-validator/commands/validate-contracts.md diff --git a/plugins/contract-validator/commands/check-agent.md b/plugins/contract-validator/commands/check-agent.md new file mode 100644 index 0000000..c6061be --- /dev/null +++ b/plugins/contract-validator/commands/check-agent.md @@ -0,0 +1,51 @@ +# /check-agent - Validate Agent Definition + +Validate a single agent's tool references and data flow. + +## Usage + +``` +/check-agent [claude_md_path] +``` + +## Parameters + +- `agent_name` (required): Name of the agent to validate (e.g., "Planner", "Orchestrator") +- `claude_md_path` (optional): Path to CLAUDE.md file. Defaults to `./CLAUDE.md` + +## Workflow + +1. **Parse agent definition**: + - Locate agent in CLAUDE.md (Four-Agent Model table or Agents section) + - Extract responsibilities, tool references, workflow steps + +2. **Validate tool references**: + - Check each referenced tool exists in available plugins + - Report missing or misspelled tool names + - Suggest corrections for common mistakes + +3. **Validate data flow**: + - Analyze sequence of tools in agent workflow + - Verify data producers precede data consumers + - Check for orphaned data references + +4. **Report findings**: + - List all tool references found + - List any missing tools + - Data flow validation results + - Suggestions for improvement + +## Examples + +``` +/check-agent Planner +/check-agent Orchestrator ./CLAUDE.md +/check-agent data-analysis ~/project/CLAUDE.md +``` + +## Available Tools + +Use these MCP tools: +- `validate_agent_refs` - Check agent tool references exist +- `validate_data_flow` - Verify data flow through agent sequence +- `parse_claude_md_agents` - Parse all agents from CLAUDE.md diff --git a/plugins/contract-validator/commands/list-interfaces.md b/plugins/contract-validator/commands/list-interfaces.md new file mode 100644 index 0000000..b9a9667 --- /dev/null +++ b/plugins/contract-validator/commands/list-interfaces.md @@ -0,0 +1,58 @@ +# /list-interfaces - Show Plugin Interfaces + +Display what each plugin in the marketplace produces and accepts. + +## Usage + +``` +/list-interfaces [marketplace_path] +``` + +## Parameters + +- `marketplace_path` (optional): Path to marketplace root. Defaults to current project root. + +## Workflow + +1. **Discover plugins**: + - Scan plugins directory for all plugins with `.claude-plugin/` marker + - Read each plugin's README.md + +2. **Parse interfaces**: + - Extract commands (slash commands offered by plugin) + - Extract agents (autonomous agents defined) + - Extract tools (MCP tools provided) + - Identify tool categories and features + +3. **Display summary**: + - Table of plugins with command/agent/tool counts + - Detailed breakdown per plugin + - Tool categories and their contents + +## Output Format + +``` +| Plugin | Commands | Agents | Tools | +|-------------|----------|--------|-------| +| projman | 12 | 4 | 26 | +| data-platform| 7 | 2 | 32 | +| ... | ... | ... | ... | + +## projman +- Commands: /sprint-plan, /sprint-start, ... +- Agents: Planner, Orchestrator, Executor, Code Reviewer +- Tools: list_issues, create_issue, ... +``` + +## Examples + +``` +/list-interfaces +/list-interfaces ~/claude-plugins-work +``` + +## Available Tools + +Use these MCP tools: +- `parse_plugin_interface` - Parse individual plugin README +- `generate_compatibility_report` - Get full interface data (JSON format) diff --git a/plugins/contract-validator/commands/validate-contracts.md b/plugins/contract-validator/commands/validate-contracts.md new file mode 100644 index 0000000..a4f57b5 --- /dev/null +++ b/plugins/contract-validator/commands/validate-contracts.md @@ -0,0 +1,50 @@ +# /validate-contracts - Full Contract Validation + +Run comprehensive cross-plugin compatibility validation for the entire marketplace. + +## Usage + +``` +/validate-contracts [marketplace_path] +``` + +## Parameters + +- `marketplace_path` (optional): Path to marketplace root. Defaults to current project root. + +## Workflow + +1. **Discover plugins**: + - Scan plugins directory for all plugins with `.claude-plugin/` marker + - Parse each plugin's README.md to extract interface + +2. **Run compatibility checks**: + - Perform pairwise compatibility validation between all plugins + - Check for command name conflicts + - Check for tool name overlaps + - Identify interface mismatches + +3. **Validate CLAUDE.md agents**: + - Parse agent definitions from CLAUDE.md + - Validate all tool references exist + - Check data flow through agent sequences + +4. **Generate report**: + - Summary statistics (plugins, commands, tools, issues) + - Detailed findings by severity (error, warning, info) + - Actionable suggestions for each issue + +## Examples + +``` +/validate-contracts +/validate-contracts ~/claude-plugins-work +``` + +## Available Tools + +Use these MCP tools: +- `generate_compatibility_report` - Generate full marketplace report +- `list_issues` - Filter issues by severity or type +- `parse_plugin_interface` - Parse individual plugin interface +- `validate_compatibility` - Check two plugins for conflicts