From 5321b2929e8f912f9f59e1a41adcb438200924cb Mon Sep 17 00:00:00 2001 From: lmiranda Date: Sun, 25 Jan 2026 15:41:46 -0500 Subject: [PATCH 1/3] fix(data-platform): use separate hooks.json file (not inline) Previous fix was wrong. Hooks should be in separate hooks/hooks.json file (auto-discovered), NOT inline in plugin.json. Pattern matches working plugins: projman, pr-review, claude-config-maintainer Co-Authored-By: Claude Opus 4.5 --- plugins/data-platform/.claude-plugin/plugin.json | 8 -------- plugins/data-platform/hooks/hooks.json | 10 ++++++++++ 2 files changed, 10 insertions(+), 8 deletions(-) create mode 100644 plugins/data-platform/hooks/hooks.json diff --git a/plugins/data-platform/.claude-plugin/plugin.json b/plugins/data-platform/.claude-plugin/plugin.json index 00bae91..489fcee 100644 --- a/plugins/data-platform/.claude-plugin/plugin.json +++ b/plugins/data-platform/.claude-plugin/plugin.json @@ -18,14 +18,6 @@ "etl", "dataframe" ], - "hooks": { - "SessionStart": [ - { - "type": "command", - "command": "${CLAUDE_PLUGIN_ROOT}/hooks/startup-check.sh" - } - ] - }, "commands": ["./commands/"], "mcpServers": ["./.mcp.json"] } diff --git a/plugins/data-platform/hooks/hooks.json b/plugins/data-platform/hooks/hooks.json new file mode 100644 index 0000000..529b5ec --- /dev/null +++ b/plugins/data-platform/hooks/hooks.json @@ -0,0 +1,10 @@ +{ + "hooks": { + "SessionStart": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/startup-check.sh" + } + ] + } +} From 35d5f14003e5eb26325d0e24899656d4cbafce45 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Sun, 25 Jan 2026 15:42:13 -0500 Subject: [PATCH 2/3] docs: correct plugin.json hooks format rules Hooks should be in separate hooks/hooks.json file (auto-discovered), NOT inline in plugin.json. Previous documentation was wrong. Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index b4eb294..10785aa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -164,9 +164,11 @@ leo-claude-mktplace/ - **CLI tools forbidden** - Use MCP tools exclusively (never `tea`, `gh`, etc.) #### ⚠️ plugin.json Format Rules (CRITICAL) -- **Hooks MUST be inline** - NEVER use `"hooks": "path/to/file.json"` +- **Hooks in separate file** - Use `hooks/hooks.json` (auto-discovered), NOT inline in plugin.json +- **NEVER reference hooks** - Don't add `"hooks": "..."` field to plugin.json at all - **Agents auto-discover** - NEVER add `"agents": ["./agents/"]` - .md files found automatically - **Always validate** - Run `./scripts/validate-marketplace.sh` before committing +- **Working examples:** projman, pr-review, claude-config-maintainer all use `hooks/hooks.json` - See lesson: `lessons/patterns/plugin-manifest-validation---hooks-and-agents-format-requirements` ### Hooks (Valid Events Only) From 2b9cb5defde5a73a6245223e89c8599938018515 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Mon, 26 Jan 2026 15:55:17 -0500 Subject: [PATCH 3/3] docs: add contract-validator initial-setup and update version tags - Add /initial-setup command for contract-validator plugin - Add contract-validator section to README.md (NEW in v5.0.0) - Update data-platform version tag: *NEW* -> *NEW in v4.0.0* - Update viz-platform version tag: *NEW* -> *NEW in v4.0.0* - Add Contract Validator MCP Server section to README.md - Add contract-validator to test commands table and repo structure Co-Authored-By: Claude Opus 4.5 --- README.md | 38 ++++- plugins/contract-validator/README.md | 1 + .../commands/initial-setup.md | 152 ++++++++++++++++++ 3 files changed, 185 insertions(+), 6 deletions(-) create mode 100644 plugins/contract-validator/commands/initial-setup.md diff --git a/README.md b/README.md index 7c7fc29..77a260b 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,19 @@ Analyze, optimize, and create CLAUDE.md configuration files for Claude Code proj **Commands:** `/config-analyze`, `/config-optimize`, `/config-init` +#### [contract-validator](./plugins/contract-validator/README.md) *NEW in v5.0.0* +**Cross-Plugin Compatibility Validation** + +Validate plugin marketplaces for command conflicts, tool overlaps, and broken agent references. + +- Interface parsing from plugin README.md files +- Agent extraction from CLAUDE.md definitions +- Pairwise compatibility checks between all plugins +- Data flow validation for agent sequences +- Markdown or JSON reports with actionable suggestions + +**Commands:** `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/initial-setup` + ### Productivity #### [clarity-assist](./plugins/clarity-assist/README.md) *NEW in v3.0.0* @@ -98,7 +111,7 @@ Full CRUD operations for network infrastructure management directly from Claude ### Data Engineering -#### [data-platform](./plugins/data-platform/README.md) *NEW* +#### [data-platform](./plugins/data-platform/README.md) *NEW in v4.0.0* **pandas, PostgreSQL/PostGIS, and dbt Integration** Comprehensive data engineering toolkit with persistent DataFrame storage. @@ -113,7 +126,7 @@ Comprehensive data engineering toolkit with persistent DataFrame storage. ### Visualization -#### [viz-platform](./plugins/viz-platform/README.md) *NEW* +#### [viz-platform](./plugins/viz-platform/README.md) *NEW in v4.0.0* **Dash Mantine Components Validation and Theming** Visualization toolkit with version-locked component validation and design token theming. @@ -157,7 +170,7 @@ Comprehensive NetBox REST API integration for infrastructure management. | Virtualization | Clusters, VMs, Interfaces | | Extras | Tags, Custom Fields, Audit Log | -### Data Platform MCP Server (shared) *NEW* +### Data Platform MCP Server (shared) *NEW in v4.0.0* pandas, PostgreSQL/PostGIS, and dbt integration for data engineering. @@ -168,7 +181,7 @@ pandas, PostgreSQL/PostGIS, and dbt integration for data engineering. | PostGIS | `st_tables`, `st_geometry_type`, `st_srid`, `st_extent` | | dbt | `dbt_parse`, `dbt_run`, `dbt_test`, `dbt_build`, `dbt_compile`, `dbt_ls`, `dbt_docs_generate`, `dbt_lineage` | -### Viz Platform MCP Server (shared) *NEW* +### Viz Platform MCP Server (shared) *NEW in v4.0.0* Dash Mantine Components validation and visualization tools. @@ -180,6 +193,16 @@ Dash Mantine Components validation and visualization tools. | Theme | `theme_create`, `theme_extend`, `theme_validate`, `theme_export_css`, `theme_list`, `theme_activate` | | Page | `page_create`, `page_add_navbar`, `page_set_auth`, `page_list`, `page_get_app_config` | +### Contract Validator MCP Server (shared) *NEW in v5.0.0* + +Cross-plugin compatibility validation tools. + +| Category | Tools | +|----------|-------| +| Parse | `parse_plugin_interface`, `parse_claude_md_agents` | +| Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow` | +| Report | `generate_compatibility_report`, `list_issues` | + ## Installation ### Prerequisites @@ -278,6 +301,7 @@ After installing plugins, the `/plugin` command may show `(no content)` - this i | cmdb-assistant | `/cmdb-assistant:cmdb-search` | | data-platform | `/data-platform:ingest` | | viz-platform | `/viz-platform:chart` | +| contract-validator | `/contract-validator:validate-contracts` | ## Repository Structure @@ -289,14 +313,16 @@ leo-claude-mktplace/ │ ├── gitea/ # Gitea MCP (issues, PRs, wiki) │ ├── netbox/ # NetBox MCP (CMDB) │ ├── data-platform/ # Data engineering (pandas, PostgreSQL, dbt) -│ └── viz-platform/ # Visualization (DMC, Plotly, theming) +│ ├── viz-platform/ # Visualization (DMC, Plotly, theming) +│ └── contract-validator/ # Cross-plugin validation (v5.0.0) ├── plugins/ # All plugins │ ├── projman/ # Sprint management │ ├── git-flow/ # Git workflow automation │ ├── pr-review/ # PR review │ ├── clarity-assist/ # Prompt optimization │ ├── data-platform/ # Data engineering -│ ├── viz-platform/ # Visualization (NEW) +│ ├── viz-platform/ # Visualization +│ ├── contract-validator/ # Cross-plugin validation (NEW) │ ├── claude-config-maintainer/ # CLAUDE.md optimization │ ├── cmdb-assistant/ # NetBox CMDB integration │ ├── doc-guardian/ # Documentation drift detection diff --git a/plugins/contract-validator/README.md b/plugins/contract-validator/README.md index 6af6bef..a5abf18 100644 --- a/plugins/contract-validator/README.md +++ b/plugins/contract-validator/README.md @@ -40,6 +40,7 @@ pip install -r requirements.txt | 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 | diff --git a/plugins/contract-validator/commands/initial-setup.md b/plugins/contract-validator/commands/initial-setup.md new file mode 100644 index 0000000..d04c961 --- /dev/null +++ b/plugins/contract-validator/commands/initial-setup.md @@ -0,0 +1,152 @@ +--- +description: Interactive setup wizard for contract-validator plugin - verifies MCP server and shows capabilities +--- + +# Contract-Validator Setup Wizard + +This command sets up the contract-validator plugin for cross-plugin compatibility validation. + +## Important Context + +- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools +- **MCP tools won't work until after setup + session restart** +- **No external credentials required** - this plugin validates local files only + +--- + +## Phase 1: Environment Validation + +### Step 1.1: Check Python Version + +```bash +python3 --version +``` + +Requires Python 3.10+. If below, stop setup and inform user: +``` +Python 3.10 or higher is required. Please install it and run /initial-setup again. +``` + +--- + +## Phase 2: MCP Server Setup + +### Step 2.1: Locate Contract-Validator MCP Server + +```bash +# If running from installed marketplace +ls -la ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/contract-validator/ 2>/dev/null || echo "NOT_FOUND_INSTALLED" + +# If running from source +ls -la ~/claude-plugins-work/mcp-servers/contract-validator/ 2>/dev/null || echo "NOT_FOUND_SOURCE" +``` + +Determine which path exists and use that as the MCP server path. + +### Step 2.2: Check Virtual Environment + +```bash +ls -la /path/to/mcp-servers/contract-validator/.venv/bin/python 2>/dev/null && echo "VENV_EXISTS" || echo "VENV_MISSING" +``` + +### Step 2.3: Create Virtual Environment (if missing) + +```bash +cd /path/to/mcp-servers/contract-validator && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate +``` + +**If pip install fails:** +- Show the error to the user +- Suggest: "Check your internet connection and try again." + +--- + +## Phase 3: Validation + +### Step 3.1: Verify MCP Server + +```bash +cd /path/to/mcp-servers/contract-validator && .venv/bin/python -c "from mcp_server.server import ContractValidatorMCPServer; print('MCP Server OK')" +``` + +If this fails, check the error and report it to the user. + +### Step 3.2: Summary + +Display: + +``` +╔════════════════════════════════════════════════════════════════╗ +║ CONTRACT-VALIDATOR SETUP COMPLETE ║ +╠════════════════════════════════════════════════════════════════╣ +║ MCP Server: ✓ Ready ║ +║ Parse Tools: ✓ Available (2 tools) ║ +║ Validation Tools: ✓ Available (3 tools) ║ +║ Report Tools: ✓ Available (2 tools) ║ +╚════════════════════════════════════════════════════════════════╝ +``` + +### Step 3.3: Session Restart Notice + +--- + +**Session Restart Required** + +Restart your Claude Code session for MCP tools to become available. + +**After restart, you can:** +- Run `/validate-contracts` to check all plugins for compatibility issues +- Run `/check-agent` to validate a single agent definition +- Run `/list-interfaces` to see all plugin commands and tools + +--- + +## Available Tools + +| Category | Tools | Description | +|----------|-------|-------------| +| Parse | `parse_plugin_interface`, `parse_claude_md_agents` | Extract interfaces from README.md and agents from CLAUDE.md | +| Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow` | Check conflicts, tool references, and data flows | +| Report | `generate_compatibility_report`, `list_issues` | Generate reports and filter issues | + +--- + +## Available Commands + +| Command | Description | +|---------|-------------| +| `/validate-contracts` | Full marketplace compatibility validation | +| `/check-agent` | Validate single agent definition | +| `/list-interfaces` | Show all plugin interfaces | + +--- + +## Use Cases + +### 1. Pre-Release Validation +Run `/validate-contracts` before releasing a new marketplace version to catch: +- Command name conflicts between plugins +- Missing tool references in agents +- Broken data flows + +### 2. Agent Development +Run `/check-agent` when creating or modifying agents to verify: +- All referenced tools exist +- Data flows are valid +- No undeclared dependencies + +### 3. Plugin Audit +Run `/list-interfaces` to get a complete view of: +- All commands across plugins +- All tools available +- Potential overlap areas + +--- + +## No Configuration Required + +This plugin doesn't require any configuration files. It reads plugin manifests and README files directly from the filesystem. + +**Paths it scans:** +- Marketplace: `~/.claude/plugins/marketplaces/leo-claude-mktplace/plugins/` +- Source (if available): `~/claude-plugins-work/plugins/`