From e2aeeaefb89a7422eb33e09d363c00dffae88c0f Mon Sep 17 00:00:00 2001 From: lmiranda Date: Mon, 26 Jan 2026 15:09:56 -0500 Subject: [PATCH] docs: update documentation for contract-validator (Sprint 2) - CHANGELOG.md: Add Sprint 2 completion notes in [Unreleased] - README.md: Add contract-validator plugin section - docs/CANONICAL-PATHS.md: Add contract-validator paths - docs/COMMANDS-CHEATSHEET.md: Add contract-validator commands Preparing for v5.0.0 release. Co-Authored-By: Claude Opus 4.5 --- CHANGELOG.md | 26 ++++++++++++++++++++ README.md | 15 ++++++++++++ docs/CANONICAL-PATHS.md | 49 +++++++++++++++++++++++++------------ docs/COMMANDS-CHEATSHEET.md | 7 +++++- 4 files changed, 81 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d74c28d..0b3ebc5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added +#### Sprint 2: contract-validator Plugin ✅ Completed +- **contract-validator** v1.0.0 - Cross-plugin compatibility validation and CLAUDE.md agent verification + - **Parse Tools** (2 tools): `parse_plugin_interface`, `parse_claude_md_agents` + - Extracts commands, agents, tools from plugin README.md files + - Parses CLAUDE.md Four-Agent Model tables and Agents sections + - **Validation Tools** (3 tools): `validate_compatibility`, `validate_agent_refs`, `validate_data_flow` + - Pairwise plugin compatibility checks for command/tool conflicts + - Agent tool reference validation against available plugins + - Data flow validation for producer/consumer sequences + - **Report Tools** (2 tools): `generate_compatibility_report`, `list_issues` + - Full marketplace validation reports (markdown or JSON) + - Filtered issue listing by severity or type + - **Commands**: `/validate-contracts`, `/check-agent`, `/list-interfaces` + - **Agents**: `full-validation`, `agent-check` + - **Tests**: 34 tests passing + - parse_tools.py: 79% coverage + - validation_tools.py: 96% coverage + - report_tools.py: 89% coverage + +**Sprint Completed:** +- Milestone: Sprint 2 - contract-validator Plugin (closed 2026-01-26) +- Issues: #185-#193 (9/9 closed) +- Real issue discovered: `/initial-setup` command conflict between projman, data-platform, and pr-review + +--- + #### Sprint 1: viz-platform Plugin ✅ Completed - **viz-platform** v1.0.0 - Visualization tools with Dash Mantine Components validation and theming - **DMC Tools** (3 tools): `list_components`, `get_component_props`, `validate_component` diff --git a/README.md b/README.md index 75c4a6a..8fbd749 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,21 @@ Visualization toolkit with version-locked component validation and design token **Commands:** `/chart`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/initial-setup` +### Validation + +#### [contract-validator](./plugins/contract-validator/README.md) *NEW* +**Cross-Plugin Compatibility Validation** + +Validates plugin interfaces and CLAUDE.md agent definitions for compatibility issues. + +- 2 Parse tools for extracting interfaces from README.md and CLAUDE.md +- 3 Validation tools for compatibility checks and data flow verification +- 2 Report tools for comprehensive marketplace reports +- Detects command conflicts, tool overlaps, and missing references +- 34 tests with 88% average coverage + +**Commands:** `/validate-contracts`, `/check-agent`, `/list-interfaces` + ## MCP Servers MCP servers are **shared at repository root** with **symlinks** from plugins that use them. diff --git a/docs/CANONICAL-PATHS.md b/docs/CANONICAL-PATHS.md index ef19a09..ea36777 100644 --- a/docs/CANONICAL-PATHS.md +++ b/docs/CANONICAL-PATHS.md @@ -2,7 +2,7 @@ **This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.** -Last Updated: 2026-01-26 (v4.1.0) +Last Updated: 2026-01-26 (v5.0.0) --- @@ -49,19 +49,28 @@ leo-claude-mktplace/ │ │ │ └── dbt_tools.py │ │ ├── requirements.txt │ │ └── .venv/ -│ └── viz-platform/ # Visualization MCP (NEW v4.1.0) +│ ├── viz-platform/ # Visualization MCP (NEW v4.1.0) +│ │ ├── mcp_server/ +│ │ │ ├── server.py +│ │ │ ├── config.py +│ │ │ ├── component_registry.py +│ │ │ ├── dmc_tools.py +│ │ │ ├── chart_tools.py +│ │ │ ├── layout_tools.py +│ │ │ ├── theme_tools.py +│ │ │ ├── theme_store.py +│ │ │ └── page_tools.py +│ │ ├── registry/ # DMC component JSON registries +│ │ ├── tests/ # 94 tests +│ │ ├── requirements.txt +│ │ └── .venv/ +│ └── contract-validator/ # Validation MCP (NEW v5.0.0) │ ├── mcp_server/ │ │ ├── server.py -│ │ ├── config.py -│ │ ├── component_registry.py -│ │ ├── dmc_tools.py -│ │ ├── chart_tools.py -│ │ ├── layout_tools.py -│ │ ├── theme_tools.py -│ │ ├── theme_store.py -│ │ └── page_tools.py -│ ├── registry/ # DMC component JSON registries -│ ├── tests/ # 94 tests +│ │ ├── parse_tools.py +│ │ ├── validation_tools.py +│ │ └── report_tools.py +│ ├── tests/ # 34 tests │ ├── requirements.txt │ └── .venv/ ├── plugins/ # ALL plugins @@ -135,14 +144,22 @@ leo-claude-mktplace/ │ │ ├── agents/ │ │ ├── hooks/ │ │ └── claude-md-integration.md -│ └── viz-platform/ # NEW in v4.1.0 +│ ├── viz-platform/ # NEW in v4.1.0 +│ │ ├── .claude-plugin/ +│ │ ├── .mcp.json +│ │ ├── mcp-servers/ +│ │ │ └── viz-platform -> ../../../mcp-servers/viz-platform # SYMLINK +│ │ ├── commands/ +│ │ ├── agents/ +│ │ ├── hooks/ +│ │ └── claude-md-integration.md +│ └── contract-validator/ # NEW in v5.0.0 │ ├── .claude-plugin/ │ ├── .mcp.json │ ├── mcp-servers/ -│ │ └── viz-platform -> ../../../mcp-servers/viz-platform # SYMLINK +│ │ └── contract-validator -> ../../../mcp-servers/contract-validator # SYMLINK │ ├── commands/ │ ├── agents/ -│ ├── hooks/ │ └── claude-md-integration.md ├── scripts/ # Setup and maintenance scripts │ ├── setup.sh # Initial setup (create venvs, config templates) @@ -269,6 +286,7 @@ plugins/cmdb-assistant/mcp-servers/netbox -> ../../../mcp-servers/netbox plugins/pr-review/mcp-servers/gitea -> ../../../mcp-servers/gitea plugins/data-platform/mcp-servers/data-platform -> ../../../mcp-servers/data-platform plugins/viz-platform/mcp-servers/viz-platform -> ../../../mcp-servers/viz-platform +plugins/contract-validator/mcp-servers/contract-validator -> ../../../mcp-servers/contract-validator ``` --- @@ -277,6 +295,7 @@ plugins/viz-platform/mcp-servers/viz-platform -> ../../../mcp-servers/viz-platfo | Date | Change | By | |------|--------|-----| +| 2026-01-26 | v5.0.0: Added contract-validator plugin and MCP server | Claude Code | | 2026-01-26 | v4.1.0: Added viz-platform plugin and MCP server | Claude Code | | 2026-01-25 | v4.0.0: Added data-platform plugin and MCP server | Claude Code | | 2026-01-20 | v3.0.0: MCP servers moved to root with symlinks | Claude Code | diff --git a/docs/COMMANDS-CHEATSHEET.md b/docs/COMMANDS-CHEATSHEET.md index 04207fd..7e5f152 100644 --- a/docs/COMMANDS-CHEATSHEET.md +++ b/docs/COMMANDS-CHEATSHEET.md @@ -72,6 +72,9 @@ Quick reference for all commands in the Leo Claude Marketplace. | **viz-platform** | `/theme-css` | | X | Export theme as CSS custom properties | | **viz-platform** | `/component` | | X | Inspect DMC component props and validation | | **viz-platform** | *SessionStart hook* | X | | Checks DMC version (non-blocking warning) | +| **contract-validator** | `/validate-contracts` | | X | Full marketplace cross-plugin compatibility validation | +| **contract-validator** | `/check-agent` | | X | Validate single agent definition and tool references | +| **contract-validator** | `/list-interfaces` | | X | Show all plugin interfaces (commands, agents, tools) | --- @@ -87,6 +90,7 @@ Quick reference for all commands in the Leo Claude Marketplace. | **Infrastructure** | cmdb-assistant | NetBox CMDB management | | **Data Engineering** | data-platform | pandas, PostgreSQL, dbt operations | | **Visualization** | viz-platform | DMC validation, Plotly charts, theming | +| **Validation** | contract-validator | Cross-plugin compatibility validation | | **Maintenance** | project-hygiene | Automatic cleanup | --- @@ -245,9 +249,10 @@ Some plugins require MCP server connectivity: | cmdb-assistant | NetBox | Infrastructure CMDB | | data-platform | pandas, PostgreSQL, dbt | DataFrames, database queries, dbt builds | | viz-platform | viz-platform | DMC validation, charts, layouts, themes, pages | +| contract-validator | contract-validator | Plugin parsing, compatibility validation, reports | Ensure credentials are configured in `~/.config/claude/gitea.env`, `~/.config/claude/netbox.env`, or `~/.config/claude/postgres.env`. --- -*Last Updated: 2026-01-26* +*Last Updated: 2026-01-26 (v5.0.0)*