From 97362576dca9de794fcfb14655bd815cc1f8a8ca Mon Sep 17 00:00:00 2001 From: lmiranda Date: Sat, 7 Feb 2026 16:34:36 -0500 Subject: [PATCH] docs(marketplace): README rewrite, scripts audit, stale reference cleanup (v9.1.1) - README.md fully rewritten: clean domain-grouped plugin tables, accurate structure tree matching CANONICAL-PATHS, all 10 scripts and 7 docs listed - CLAUDE.md structure tree updated to match (was showing only 12 plugins) - Deleted scripts/check-venv.sh (dead code for unimplemented SessionStart hooks) - Fixed stale .doc-guardian-queue references in doc-sync.md and sync-workflow.md - Removed check-venv.sh from CANONICAL-PATHS.md, added missing consumer scripts - Version bumped to 9.1.1 Co-Authored-By: Claude Opus 4.6 --- .claude-plugin/marketplace.json | 2 +- CHANGELOG.md | 12 + CLAUDE.md | 93 +-- README.md | 593 +++++-------------- docs/CANONICAL-PATHS.md | 8 +- plugins/doc-guardian/commands/doc-sync.md | 11 +- plugins/doc-guardian/skills/sync-workflow.md | 26 +- scripts/check-venv.sh | 37 -- 8 files changed, 239 insertions(+), 543 deletions(-) delete mode 100755 scripts/check-venv.sh diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1d575b2..e302985 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ }, "metadata": { "description": "Project management plugins with Gitea and NetBox integrations", - "version": "9.1.0" + "version": "9.1.1" }, "plugins": [ { diff --git a/CHANGELOG.md b/CHANGELOG.md index 2953c03..c44caca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +## [9.1.1] - 2026-02-07 + +### Changed + +- README.md fully rewritten — clean structure with plugins grouped by domain, accurate structure tree, all 10 scripts, all 7 docs +- CLAUDE.md structure tree updated to match README (was showing only 12 plugins, 3 scripts, 2 docs) +- doc-guardian `/doc sync` and `sync-workflow.md` updated to remove stale `.doc-guardian-queue` references (queue file deleted in v8.1.0) + +### Removed + +- `scripts/check-venv.sh` — dead code designed for SessionStart hooks that were never implemented; functionality covered by `setup-venvs.sh` + ## [9.1.0] - 2026-02-07 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index d7f4360..f54b407 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -154,7 +154,7 @@ When user says "fix the sprint plan command", edit the SOURCE code. ## Project Overview **Repository:** leo-claude-mktplace -**Version:** 9.1.0 +**Version:** 9.1.1 **Status:** Production Ready A plugin marketplace for Claude Code containing: @@ -231,55 +231,66 @@ These commands are being developed but don't apply to this project's workflow: ``` leo-claude-mktplace/ -├── .claude-plugin/ -│ └── marketplace.json # Marketplace manifest +├── .claude-plugin/ # Marketplace manifest +│ ├── marketplace.json +│ ├── marketplace-lean.json # Lean profile (6 core plugins) +│ └── marketplace-full.json # Full profile (all plugins) ├── .mcp.json # MCP server configuration (all servers) ├── mcp-servers/ # SHARED MCP servers -│ ├── gitea/ # Gitea MCP (issues, PRs, wiki) -│ ├── netbox/ # NetBox MCP (CMDB) +│ ├── gitea/ # Gitea (issues, PRs, wiki) +│ ├── netbox/ # NetBox (DCIM, IPAM) │ ├── data-platform/ # pandas, PostgreSQL, dbt -│ ├── viz-platform/ # DMC validation, charts, themes +│ ├── viz-platform/ # DMC, Plotly, theming │ └── contract-validator/ # Plugin compatibility validation -├── plugins/ -│ ├── projman/ # Sprint management +├── plugins/ # All plugins (20 total) +│ ├── projman/ # [core] Sprint management │ │ ├── .claude-plugin/plugin.json │ │ ├── commands/ # 19 commands │ │ ├── agents/ # 4 agents │ │ └── skills/ # 23 reusable skill files -│ ├── git-flow/ # Git workflow automation -│ │ ├── .claude-plugin/plugin.json -│ │ ├── commands/ # 5 commands -│ │ └── agents/ -│ ├── pr-review/ # Multi-agent PR review -│ │ ├── .claude-plugin/plugin.json -│ │ ├── commands/ # 8 commands -│ │ └── agents/ # 5 agents -│ ├── clarity-assist/ # Prompt optimization -│ │ ├── .claude-plugin/plugin.json -│ │ ├── commands/ # 2 commands -│ │ └── agents/ -│ ├── data-platform/ # Data engineering -│ │ ├── .claude-plugin/plugin.json -│ │ ├── commands/ # 7 commands -│ │ └── agents/ # 2 agents -│ ├── viz-platform/ # Visualization -│ │ ├── .claude-plugin/plugin.json -│ │ ├── commands/ # 7 commands -│ │ └── agents/ # 3 agents -│ ├── doc-guardian/ # Documentation drift detection -│ ├── code-sentinel/ # Security scanning & refactoring -│ ├── claude-config-maintainer/ -│ ├── cmdb-assistant/ -│ ├── contract-validator/ -│ └── project-hygiene/ -├── scripts/ -│ ├── setup.sh, post-update.sh +│ ├── git-flow/ # [core] Git workflow automation +│ ├── pr-review/ # [core] PR review +│ ├── clarity-assist/ # [core] Prompt optimization +│ ├── doc-guardian/ # [core] Documentation drift detection +│ ├── code-sentinel/ # [core] Security scanning +│ ├── claude-config-maintainer/ # [core] CLAUDE.md optimization +│ ├── contract-validator/ # [core] Cross-plugin validation +│ ├── project-hygiene/ # [core] Manual cleanup checks +│ ├── cmdb-assistant/ # [ops] NetBox CMDB integration +│ ├── data-platform/ # [data] Data engineering +│ ├── viz-platform/ # [data] Visualization +│ ├── data-seed/ # [data] Test data generation (scaffold) +│ ├── saas-api-platform/ # [saas] API scaffolding (scaffold) +│ ├── saas-db-migrate/ # [saas] DB migrations (scaffold) +│ ├── saas-react-platform/ # [saas] React toolkit (scaffold) +│ ├── saas-test-pilot/ # [saas] Test automation (scaffold) +│ ├── ops-release-manager/ # [ops] Release management (scaffold) +│ ├── ops-deploy-pipeline/ # [ops] Deployment pipeline (scaffold) +│ └── debug-mcp/ # [debug] MCP debugging (scaffold) +├── scripts/ # Setup and maintenance +│ ├── setup.sh # Initial setup (create venvs, config) +│ ├── post-update.sh # Post-update (clear cache, changelog) +│ ├── setup-venvs.sh # MCP server venv management (cache-based) │ ├── validate-marketplace.sh # Marketplace compliance validation -│ ├── verify-hooks.sh # Verify all hooks are command type -│ └── check-venv.sh # Check MCP server venvs exist -└── docs/ - ├── CANONICAL-PATHS.md # Single source of truth for paths - └── CONFIGURATION.md # Centralized configuration guide +│ ├── verify-hooks.sh # Hook inventory verification +│ ├── release.sh # Release automation with version bumping +│ ├── claude-launch.sh # Profile-based launcher +│ ├── install-plugin.sh # Install plugin to consumer project +│ ├── list-installed.sh # Show installed plugins in a project +│ └── uninstall-plugin.sh # Remove plugin from consumer project +├── docs/ # Documentation +│ ├── ARCHITECTURE.md # System architecture & plugin reference +│ ├── CANONICAL-PATHS.md # Authoritative path reference +│ ├── COMMANDS-CHEATSHEET.md # All commands quick reference +│ ├── CONFIGURATION.md # Centralized setup guide +│ ├── DEBUGGING-CHECKLIST.md # Systematic troubleshooting guide +│ ├── MIGRATION-v9.md # v8.x to v9.0.0 migration guide +│ └── UPDATING.md # Update guide +├── CLAUDE.md # Project instructions for Claude Code +├── README.md +├── CHANGELOG.md +├── LICENSE +└── .gitignore ``` ## Architecture diff --git a/README.md b/README.md index afd56b7..73ed04e 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,57 @@ -# Leo Claude Marketplace - v9.1.0 +# Leo Claude Marketplace — v9.1.1 -A collection of Claude Code plugins for project management, infrastructure automation, and development workflows. +A plugin marketplace for Claude Code providing sprint management, code review, security scanning, infrastructure automation, and development workflow tools. 20 plugins across 5 domains, backed by 5 shared MCP servers. + +## Plugins + +### Core (9 plugins — v9.0.1) + +| Plugin | Description | +|--------|-------------| +| `projman` | Sprint planning and project management with Gitea integration | +| `git-flow` | Git workflow automation with intelligent commit messages and branch management | +| `pr-review` | Multi-agent pull request review with confidence scoring | +| `code-sentinel` | Security scanning and code refactoring tools | +| `doc-guardian` | Documentation drift detection and synchronization | +| `clarity-assist` | Prompt optimization with ND-friendly accommodations | +| `contract-validator` | Cross-plugin compatibility validation and agent verification | +| `claude-config-maintainer` | CLAUDE.md and settings.local.json optimization | +| `project-hygiene` | Manual project file cleanup checks | + +### Data (3 plugins) + +| Plugin | Version | Description | +|--------|---------|-------------| +| `data-platform` | 9.0.1 | pandas, PostgreSQL/PostGIS, and dbt integration | +| `viz-platform` | 9.0.1 | Dash Mantine Components validation, Plotly charts, and theming | +| `data-seed` | 0.1.0 — scaffold | Test data generation and database seeding | + +### Ops (3 plugins) + +| Plugin | Version | Description | +|--------|---------|-------------| +| `cmdb-assistant` | 9.0.1 | NetBox CMDB integration with data quality validation | +| `ops-release-manager` | 0.1.0 — scaffold | Release management with SemVer and changelog automation | +| `ops-deploy-pipeline` | 0.1.0 — scaffold | Deployment pipeline for Docker Compose and systemd | + +### SaaS (4 plugins — v0.1.0 scaffolds) + +| Plugin | Description | +|--------|-------------| +| `saas-api-platform` | REST/GraphQL API scaffolding for FastAPI and Express | +| `saas-db-migrate` | Database migration management for Alembic, Prisma, raw SQL | +| `saas-react-platform` | React frontend toolkit for Next.js and Vite | +| `saas-test-pilot` | Test automation for pytest, Jest, Vitest, Playwright | + +### Debug (1 plugin — v0.1.0 scaffold) + +| Plugin | Description | +|--------|-------------| +| `debug-mcp` | MCP server debugging, inspection, and development toolkit | ## Quick Start -Use the launcher script to load only the plugins you need, reducing token overhead from ~22K to ~4-6K tokens: +### Launch with profiles ```bash ./scripts/claude-launch.sh [profile] [extra-args...] @@ -16,337 +63,98 @@ Use the launcher script to load only the plugins you need, reducing token overhe | `review` | pr-review, code-sentinel | Lightweight code review | | `data` | data-platform, viz-platform | Data engineering and visualization | | `infra` | cmdb-assistant | Infrastructure/CMDB management | -| `full` | All 20 plugins via marketplace.json | When you need everything | +| `full` | All 20 plugins | When you need everything | -**Examples:** ```bash ./scripts/claude-launch.sh # Default sprint profile ./scripts/claude-launch.sh data --model opus # Data profile with Opus ./scripts/claude-launch.sh full # Load all plugins ``` -The script enables `ENABLE_TOOL_SEARCH=true` for MCP lazy loading. - -## Plugins - -### Development & Project Management - -#### [projman](./plugins/projman) -**Sprint Planning and Project Management** - -AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sprint workflow into a distributable plugin. - -- Four-agent model: Planner, Orchestrator, Executor, Code Reviewer -- Plan-then-batch execution: skills loaded once per phase, API calls batched for ~80% token savings -- Intelligent label suggestions from 43-label taxonomy -- Lessons learned capture via Gitea Wiki -- Native issue dependencies with parallel execution -- Milestone management for sprint organization -- Branch-aware security (development/staging/production) -- Pre-sprint-close code quality review and test verification - -**Commands:** `/sprint plan`, `/sprint start`, `/sprint status`, `/sprint close`, `/sprint review`, `/sprint test`, `/labels sync`, `/projman setup`, `/projman debug`, `/projman suggest-version`, `/projman proposal-status`, `/rfc create`, `/rfc list`, `/rfc review`, `/rfc approve`, `/rfc reject`, `/project initiation`, `/project plan`, `/project status`, `/project close`, `/adr create`, `/adr list`, `/adr update`, `/adr supersede` - -#### [git-flow](./plugins/git-flow) -**Git Workflow Automation** - -Smart git operations with intelligent commit messages and branch management. - -- Auto-generated conventional commit messages -- Multiple workflow styles (simple, feature-branch, pr-required, trunk-based) -- Branch naming enforcement -- Merge and cleanup automation -- Protected branch awareness - -**Commands:** `/gitflow commit` (with `--push`, `--merge`, `--sync` flags), `/gitflow branch-start`, `/gitflow branch-cleanup`, `/gitflow status`, `/gitflow config` - -#### [pr-review](./plugins/pr-review) -**Multi-Agent PR Review** - -Comprehensive pull request review using specialized agents. - -- Multi-agent review: Security, Performance, Maintainability, Tests -- Confidence scoring (only reports HIGH/MEDIUM confidence findings) -- Actionable feedback with suggested fixes -- Gitea integration for automated review submission - -**Commands:** `/pr review`, `/pr summary`, `/pr findings`, `/pr diff`, `/pr setup`, `/pr init`, `/pr sync` - -#### [claude-config-maintainer](./plugins/claude-config-maintainer) -**CLAUDE.md and Settings Optimization** - -Analyze, optimize, and create CLAUDE.md configuration files. Audit and optimize settings.local.json permissions. - -**Commands:** `/claude-config analyze`, `/claude-config optimize`, `/claude-config init`, `/claude-config diff`, `/claude-config lint`, `/claude-config audit-settings`, `/claude-config optimize-settings`, `/claude-config permissions-map` - -#### [contract-validator](./plugins/contract-validator) -**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:** `/cv validate`, `/cv check-agent`, `/cv list-interfaces`, `/cv dependency-graph`, `/cv setup` - -### Productivity - -#### [clarity-assist](./plugins/clarity-assist) -**Prompt Optimization with ND Accommodations** - -Transform vague requests into clear specifications using structured methodology. - -- 4-D methodology: Deconstruct, Diagnose, Develop, Deliver -- ND-friendly question patterns (option-based, chunked) -- Conflict detection and escalation protocols - -**Commands:** `/clarity clarify`, `/clarity quick-clarify` - -#### [doc-guardian](./plugins/doc-guardian) -**Documentation Lifecycle Management** - -Automatic documentation drift detection and synchronization. - -**Commands:** `/doc audit`, `/doc sync`, `/doc changelog-gen`, `/doc coverage`, `/doc stale-docs` - -#### [project-hygiene](./plugins/project-hygiene) -**Manual Project Hygiene Checks** - -Project file organization and cleanup checks — temp files, misplaced files, empty dirs, debug artifacts. - -**Commands:** `/hygiene check` (with `--fix` flag for auto-fix) - -### Security - -#### [code-sentinel](./plugins/code-sentinel) -**Security Scanning & Refactoring** - -Security vulnerability detection and code refactoring tools. - -**Commands:** `/sentinel scan`, `/sentinel refactor`, `/sentinel refactor-dry` - -### Infrastructure - -#### [cmdb-assistant](./plugins/cmdb-assistant) -**NetBox CMDB Integration** - -Full CRUD operations for network infrastructure management directly from Claude Code. - -**Commands:** `/cmdb setup`, `/cmdb search`, `/cmdb device`, `/cmdb ip`, `/cmdb site`, `/cmdb audit`, `/cmdb register`, `/cmdb sync`, `/cmdb topology`, `/cmdb change-audit`, `/cmdb ip-conflicts` - -### Data Engineering - -#### [data-platform](./plugins/data-platform) -**pandas, PostgreSQL/PostGIS, and dbt Integration** - -Comprehensive data engineering toolkit with persistent DataFrame storage. - -- 14 pandas tools with Arrow IPC data_ref system -- 10 PostgreSQL/PostGIS tools with connection pooling -- 8 dbt tools with automatic pre-validation -- 100k row limit with chunking support -- Auto-detection of dbt projects - -**Commands:** `/data ingest`, `/data profile`, `/data schema`, `/data explain`, `/data lineage`, `/data lineage-viz`, `/data run`, `/data dbt-test`, `/data quality`, `/data review`, `/data gate`, `/data setup` - -### Visualization - -#### [viz-platform](./plugins/viz-platform) -**Dash Mantine Components Validation and Theming** - -Visualization toolkit with version-locked component validation and design token theming. - -- 3 DMC tools with static JSON registry (prevents prop hallucination) -- 2 Chart tools with Plotly and theme integration -- 5 Layout tools for dashboard composition -- 6 Theme tools with design token system -- 5 Page tools for multi-page app structure -- Dual theme storage: user-level and project-level - -**Commands:** `/viz chart`, `/viz chart-export`, `/viz dashboard`, `/viz theme`, `/viz theme-new`, `/viz theme-css`, `/viz component`, `/viz accessibility-check`, `/viz breakpoints`, `/viz design-review`, `/viz design-gate`, `/viz setup` - -#### [data-seed](./plugins/data-seed) -**Test Data Generation and Database Seeding** - -Relationship-aware test data generation with reusable seed profiles. - -- Schema inference from existing databases -- Faker-based data generation with locale support -- Foreign key relationship resolution -- Reusable seed profiles for consistent test environments - -**Commands:** `/seed setup`, `/seed generate`, `/seed profile`, `/seed validate`, `/seed apply` - -### SaaS Development - -#### [saas-api-platform](./plugins/saas-api-platform) -**REST and GraphQL API Scaffolding** - -API development toolkit for FastAPI and Express projects with OpenAPI integration. - -- Framework-aware scaffolding (FastAPI, Express) -- OpenAPI spec generation and validation -- Middleware catalog with authentication, CORS, rate limiting -- Route pattern enforcement and test generation - -**Commands:** `/api setup`, `/api scaffold`, `/api validate`, `/api docs`, `/api middleware`, `/api test-routes` - -#### [saas-db-migrate](./plugins/saas-db-migrate) -**Database Migration Management** - -Migration toolkit for Alembic, Prisma, and raw SQL with safety validation. - -- ORM/tool auto-detection -- Migration safety analysis (data loss, locks, rollback) -- Execution planning with rollback strategies -- Migration history tracking - -**Commands:** `/db-migrate setup`, `/db-migrate generate`, `/db-migrate validate`, `/db-migrate plan`, `/db-migrate history`, `/db-migrate rollback` - -#### [saas-react-platform](./plugins/saas-react-platform) -**React Frontend Development Toolkit** - -Component scaffolding, routing, and state management for Next.js and Vite projects. - -- Framework detection (Next.js App Router/Pages, Vite, CRA, Remix) -- TypeScript-first component generation with co-located tests -- State management pattern selection (Context, Zustand, Redux Toolkit) -- Anti-pattern detection and component tree analysis - -**Commands:** `/react setup`, `/react component`, `/react route`, `/react state`, `/react hook`, `/react lint` - -#### [saas-test-pilot](./plugins/saas-test-pilot) -**Test Automation Toolkit** - -Test generation and coverage analysis for pytest, Jest, Vitest, and Playwright. - -- Framework auto-detection and configuration -- Test case generation from code analysis -- Coverage gap detection with risk prioritization -- E2E test scenario generation from user stories - -**Commands:** `/test setup`, `/test generate`, `/test coverage`, `/test fixtures`, `/test e2e`, `/test run` - -### Operations - -#### [ops-release-manager](./plugins/ops-release-manager) -**Release Management Automation** - -Semantic versioning, changelog generation, and tag management. - -- Version location auto-detection across manifests -- Conventional commit-based bump suggestions -- Keep a Changelog format automation -- Release branch/tag creation and rollback - -**Commands:** `/release setup`, `/release prepare`, `/release validate`, `/release tag`, `/release rollback`, `/release status` - -#### [ops-deploy-pipeline](./plugins/ops-deploy-pipeline) -**Deployment Pipeline Management** - -CI/CD for Docker Compose and systemd-based services on self-hosted infrastructure. - -- Docker Compose configuration generation -- Caddy reverse proxy patterns -- Environment-specific config management -- Pre-deployment health checks and rollback planning - -**Commands:** `/deploy setup`, `/deploy generate`, `/deploy validate`, `/deploy env`, `/deploy check`, `/deploy rollback` - -### Debugging - -#### [debug-mcp](./plugins/debug-mcp) -**MCP Server Debugging Toolkit** - -Diagnostic tools for MCP server health, testing, and development. - -- MCP server health status dashboard -- Individual tool call testing -- Server log analysis with error pattern recognition -- MCP server scaffold generation - -**Commands:** `/debug-mcp status`, `/debug-mcp test`, `/debug-mcp logs`, `/debug-mcp inspect`, `/debug-mcp scaffold` - -## Domain Advisory Pattern - -The marketplace supports cross-plugin domain advisory integration: - -- **Domain Detection**: projman automatically detects when issues involve specialized domains (frontend/viz, data engineering) -- **Acceptance Criteria**: Domain-specific acceptance criteria are added to issues during planning -- **Execution Gates**: Domain validation gates (`/viz design-gate`, `/data gate`) run before issue completion -- **Extensible**: New domains can be added by creating advisory agents and gate commands - -**Current Domains:** -| Domain | Plugin | Gate Command | -|--------|--------|--------------| -| Visualization | viz-platform | `/viz design-gate` | -| Data | data-platform | `/data gate` | +### Common commands + +```bash +/sprint plan # Plan a sprint with architecture analysis +/sprint start # Begin sprint execution +/gitflow commit --push # Commit with auto-generated message and push +/pr review # Full multi-agent PR review +/sentinel scan # Security audit +/doc audit # Check for documentation drift +/cv status # Marketplace health check +``` + +## Repository Structure + +``` +leo-claude-mktplace/ +├── .claude-plugin/ # Marketplace manifest +│ ├── marketplace.json +│ ├── marketplace-lean.json # Lean profile (6 core plugins) +│ └── marketplace-full.json # Full profile (all plugins) +├── mcp-servers/ # Shared MCP servers +│ ├── gitea/ # Gitea (issues, PRs, wiki) +│ ├── netbox/ # NetBox (DCIM, IPAM) +│ ├── data-platform/ # pandas, PostgreSQL, dbt +│ ├── viz-platform/ # DMC, Plotly, theming +│ └── contract-validator/ # Plugin compatibility validation +├── plugins/ # All plugins (20 total) +│ ├── projman/ # [core] Sprint management +│ ├── git-flow/ # [core] Git workflow automation +│ ├── pr-review/ # [core] PR review +│ ├── clarity-assist/ # [core] Prompt optimization +│ ├── doc-guardian/ # [core] Documentation drift detection +│ ├── code-sentinel/ # [core] Security scanning +│ ├── claude-config-maintainer/ # [core] CLAUDE.md optimization +│ ├── contract-validator/ # [core] Cross-plugin validation +│ ├── project-hygiene/ # [core] Manual cleanup checks +│ ├── cmdb-assistant/ # [ops] NetBox CMDB integration +│ ├── data-platform/ # [data] Data engineering +│ ├── viz-platform/ # [data] Visualization +│ ├── data-seed/ # [data] Test data generation (scaffold) +│ ├── saas-api-platform/ # [saas] API scaffolding (scaffold) +│ ├── saas-db-migrate/ # [saas] DB migrations (scaffold) +│ ├── saas-react-platform/ # [saas] React toolkit (scaffold) +│ ├── saas-test-pilot/ # [saas] Test automation (scaffold) +│ ├── ops-release-manager/ # [ops] Release management (scaffold) +│ ├── ops-deploy-pipeline/ # [ops] Deployment pipeline (scaffold) +│ └── debug-mcp/ # [debug] MCP debugging (scaffold) +├── scripts/ # Setup and maintenance +│ ├── setup.sh # Initial setup (create venvs, config) +│ ├── post-update.sh # Post-update (clear cache, changelog) +│ ├── setup-venvs.sh # MCP server venv management (cache-based) +│ ├── validate-marketplace.sh # Marketplace compliance validation +│ ├── verify-hooks.sh # Hook inventory verification +│ ├── release.sh # Release automation with version bumping +│ ├── claude-launch.sh # Profile-based launcher +│ ├── install-plugin.sh # Install plugin to consumer project +│ ├── list-installed.sh # Show installed plugins in a project +│ └── uninstall-plugin.sh # Remove plugin from consumer project +├── docs/ # Documentation +│ ├── ARCHITECTURE.md # System architecture & plugin reference +│ ├── CANONICAL-PATHS.md # Authoritative path reference +│ ├── COMMANDS-CHEATSHEET.md # All commands quick reference +│ ├── CONFIGURATION.md # Centralized setup guide +│ ├── DEBUGGING-CHECKLIST.md # Systematic troubleshooting guide +│ ├── MIGRATION-v9.md # v8.x to v9.0.0 migration guide +│ └── UPDATING.md # Update guide +├── CLAUDE.md # Project instructions for Claude Code +├── README.md +├── CHANGELOG.md +├── LICENSE +└── .gitignore +``` ## MCP Servers -MCP servers are **shared at repository root** and configured in `.mcp.json`. +All MCP servers are shared at repository root and configured in `.mcp.json`. -### Gitea MCP Server (shared) - -Full Gitea API integration for project management. - -| Category | Tools | -|----------|-------| -| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment`, `aggregate_issues` | -| Labels | `get_labels`, `suggest_labels`, `create_label`, `create_label_smart` | -| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `update_wiki_page`, `create_lesson`, `search_lessons` | -| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone`, `delete_milestone` | -| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `remove_issue_dependency`, `get_execution_order` | -| **Pull Requests** | `list_pull_requests`, `get_pull_request`, `get_pr_diff`, `get_pr_comments`, `create_pr_review`, `add_pr_comment` | -| Validation | `validate_repo_org`, `get_branch_protection` | - -### NetBox MCP Server (shared) - -Comprehensive NetBox REST API integration for infrastructure management. - -| Module | Coverage | -|--------|----------| -| DCIM | Sites, Racks, Devices, Interfaces, Cables | -| IPAM | Prefixes, IPs, VLANs, VRFs | -| Circuits | Providers, Circuits, Terminations | -| Virtualization | Clusters, VMs, Interfaces | -| Extras | Tags, Custom Fields, Audit Log | - -### Data Platform MCP Server (shared) - -pandas, PostgreSQL/PostGIS, and dbt integration for data engineering. - -| Category | Tools | -|----------|-------| -| pandas | `read_csv`, `read_parquet`, `read_json`, `to_csv`, `to_parquet`, `describe`, `head`, `tail`, `filter`, `select`, `groupby`, `join`, `list_data`, `drop_data` | -| PostgreSQL | `pg_connect`, `pg_query`, `pg_execute`, `pg_tables`, `pg_columns`, `pg_schemas` | -| 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) - -Dash Mantine Components validation and visualization tools. - -| Category | Tools | -|----------|-------| -| DMC | `list_components`, `get_component_props`, `validate_component` | -| Chart | `chart_create`, `chart_configure_interaction` | -| Layout | `layout_create`, `layout_add_filter`, `layout_set_grid`, `layout_get`, `layout_add_section` | -| 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) - -Cross-plugin compatibility validation tools. - -| Category | Tools | -|----------|-------| -| Parse | `parse_plugin_interface`, `parse_claude_md_agents` | -| Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow`, `validate_workflow_integration` | -| Report | `generate_compatibility_report`, `list_issues` | +| Server | Used By | External System | +|--------|---------|-----------------| +| gitea | projman, pr-review | Gitea (issues, PRs, wiki, milestones) | +| netbox | cmdb-assistant | NetBox (DCIM, IPAM) | +| data-platform | data-platform | PostgreSQL, dbt | +| viz-platform | viz-platform | DMC component registry | +| contract-validator | contract-validator | Internal validation | ## Installation @@ -356,16 +164,14 @@ Cross-plugin compatibility validation tools. - Python 3.10+ - Access to target services (Gitea, NetBox as needed) -### Add Marketplace to Claude Code +### Add marketplace to Claude Code -**Option 1 - CLI command (recommended):** ```bash /plugin marketplace add https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git ``` -**Option 2 - Settings file (for team distribution):** +Or add to `.claude/settings.json`: -Add to `.claude/settings.json` in your target project: ```json { "extraKnownMarketplaces": { @@ -379,136 +185,55 @@ Add to `.claude/settings.json` in your target project: } ``` -### Run Interactive Setup +### Setup MCP servers -After installing plugins, run the setup wizard: +After installing, create Python venvs for MCP servers: + +```bash +cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh +``` + +Then restart Claude Code and run the interactive setup: ``` /projman setup ``` -The wizard handles everything: -- Sets up MCP server (Python venv + dependencies) -- Creates system config (`~/.config/claude/gitea.env`) -- Guides you through adding your API token -- Detects and validates your repository via API -- Creates project config (`.env`) +See [CONFIGURATION.md](./docs/CONFIGURATION.md) for manual setup and advanced options. -**For new projects** (when system is already configured): -``` -/pr init -``` +### Install to consumer projects -**After moving a repository:** -``` -/pr sync -``` - -See [docs/CONFIGURATION.md](./docs/CONFIGURATION.md) for manual setup and advanced options. - -## Verifying Plugin Installation - -After installing plugins, the `/plugin` command may show `(no content)` - this is normal Claude Code behavior and doesn't indicate an error. - -**To verify a plugin is installed correctly:** - -1. **Check installed plugins list:** - ``` - /plugin list - ``` - Look for `✔ plugin-name · Installed` - -2. **Test a plugin command directly:** - ``` - /git-flow:git-status - /projman:sprint-status - /clarity-assist:clarify - ``` - If the command executes and shows output, the plugin is working. - -3. **Check for loading errors:** - ``` - /plugin list - ``` - Look for any `Plugin Loading Errors` section - this indicates manifest issues. - -**Command format:** All plugin commands use the format `/plugin-name:command-name` - -| Plugin | Test Command | -|--------|--------------| -| git-flow | `/git-flow:gitflow-status` | -| projman | `/projman:sprint-status` | -| pr-review | `/pr-review:pr-summary` | -| clarity-assist | `/clarity-assist:clarity-clarify` | -| doc-guardian | `/doc-guardian:doc-audit` | -| code-sentinel | `/code-sentinel:sentinel-scan` | -| claude-config-maintainer | `/claude-config-maintainer:claude-config-analyze` | -| cmdb-assistant | `/cmdb-assistant:cmdb-search` | -| data-platform | `/data-platform:data-ingest` | -| viz-platform | `/viz-platform:viz-chart` | -| contract-validator | `/contract-validator:cv-validate` | - -## Repository Structure - -``` -leo-claude-mktplace/ -├── .claude-plugin/ # Marketplace manifest -│ └── marketplace.json -├── mcp-servers/ # SHARED MCP servers (v3.0.0+) -│ ├── gitea/ # Gitea MCP (issues, PRs, wiki) -│ ├── netbox/ # NetBox MCP (CMDB) -│ ├── data-platform/ # Data engineering (pandas, PostgreSQL, dbt) -│ ├── viz-platform/ # Visualization (DMC, Plotly, theming) -│ └── contract-validator/ # Cross-plugin validation (v5.0.0) -├── plugins/ # All plugins (20 total) -│ ├── projman/ # Sprint management -│ ├── git-flow/ # Git workflow automation -│ ├── pr-review/ # PR review -│ ├── clarity-assist/ # Prompt optimization -│ ├── doc-guardian/ # Documentation drift detection -│ ├── code-sentinel/ # Security scanning -│ ├── claude-config-maintainer/ # CLAUDE.md optimization -│ ├── contract-validator/ # Cross-plugin validation -│ ├── project-hygiene/ # Manual cleanup checks -│ ├── cmdb-assistant/ # NetBox CMDB integration -│ ├── data-platform/ # Data engineering -│ ├── viz-platform/ # Visualization -│ ├── data-seed/ # Test data generation (scaffold) -│ ├── saas-api-platform/ # API scaffolding (scaffold) -│ ├── saas-db-migrate/ # DB migrations (scaffold) -│ ├── saas-react-platform/ # React toolkit (scaffold) -│ ├── saas-test-pilot/ # Test automation (scaffold) -│ ├── ops-release-manager/ # Release management (scaffold) -│ ├── ops-deploy-pipeline/ # Deployment pipeline (scaffold) -│ └── debug-mcp/ # MCP debugging (scaffold) -├── docs/ # Documentation -│ ├── ARCHITECTURE.md # System architecture & plugin reference -│ ├── CANONICAL-PATHS.md # Path reference -│ ├── CONFIGURATION.md # Setup guide -│ └── MIGRATION-v9.md # v8→v9 migration guide -├── scripts/ # Setup scripts -└── CHANGELOG.md # Version history +```bash +./scripts/install-plugin.sh /path/to/project +./scripts/list-installed.sh /path/to/project +./scripts/uninstall-plugin.sh /path/to/project ``` ## Documentation | Document | Description | |----------|-------------| -| [CLAUDE.md](./CLAUDE.md) | Main project instructions | +| [CLAUDE.md](./CLAUDE.md) | Project instructions for Claude Code | | [ARCHITECTURE.md](./docs/ARCHITECTURE.md) | System architecture and plugin reference | -| [CONFIGURATION.md](./docs/CONFIGURATION.md) | Centralized setup guide | | [COMMANDS-CHEATSHEET.md](./docs/COMMANDS-CHEATSHEET.md) | All commands quick reference | -| [UPDATING.md](./docs/UPDATING.md) | Update guide for the marketplace | -| [CANONICAL-PATHS.md](./docs/CANONICAL-PATHS.md) | Authoritative path reference | +| [CONFIGURATION.md](./docs/CONFIGURATION.md) | Centralized setup guide | | [DEBUGGING-CHECKLIST.md](./docs/DEBUGGING-CHECKLIST.md) | Systematic troubleshooting guide | +| [UPDATING.md](./docs/UPDATING.md) | Update guide for the marketplace | | [MIGRATION-v9.md](./docs/MIGRATION-v9.md) | v8.x to v9.0.0 migration guide | +| [CANONICAL-PATHS.md](./docs/CANONICAL-PATHS.md) | Authoritative path reference | | [CHANGELOG.md](./CHANGELOG.md) | Version history | +## Validation + +```bash +./scripts/validate-marketplace.sh # Marketplace compliance (manifests, domains, paths) +./scripts/verify-hooks.sh # Hook inventory (4 PreToolUse + 1 UserPromptSubmit) +``` + ## License MIT License ## Support -- **Issues**: Contact repository maintainer -- **Repository**: `https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git` +- **Repository**: https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git diff --git a/docs/CANONICAL-PATHS.md b/docs/CANONICAL-PATHS.md index c952977..2ac5a56 100644 --- a/docs/CANONICAL-PATHS.md +++ b/docs/CANONICAL-PATHS.md @@ -195,12 +195,14 @@ leo-claude-mktplace/ ├── scripts/ # Setup and maintenance scripts │ ├── setup.sh # Initial setup (create venvs, config templates) │ ├── post-update.sh # Post-update (clear cache, show changelog) -│ ├── check-venv.sh # Check if venvs exist (read-only) +│ ├── setup-venvs.sh # Setup MCP server venvs (create only, never delete) │ ├── validate-marketplace.sh # Marketplace compliance validation │ ├── verify-hooks.sh # Verify all hooks use correct event types -│ ├── setup-venvs.sh # Setup MCP server venvs (create only, never delete) │ ├── release.sh # Release automation with version bumping -│ └── claude-launch.sh # Task-specific launcher with profile selection +│ ├── claude-launch.sh # Task-specific launcher with profile selection +│ ├── install-plugin.sh # Install plugin to consumer project +│ ├── list-installed.sh # Show installed plugins in a project +│ └── uninstall-plugin.sh # Remove plugin from consumer project ├── CLAUDE.md ├── README.md ├── LICENSE diff --git a/plugins/doc-guardian/commands/doc-sync.md b/plugins/doc-guardian/commands/doc-sync.md index 98fd713..344be2f 100644 --- a/plugins/doc-guardian/commands/doc-sync.md +++ b/plugins/doc-guardian/commands/doc-sync.md @@ -22,11 +22,11 @@ Apply all pending documentation updates detected by `/doc audit`. ## Process -1. **Review Pending Queue** - Execute `skills/sync-workflow.md` - read `.doc-guardian-queue` +1. **Detect Drift** + Run `/doc audit` first (or use its most recent results) to identify documentation that is out of sync with code. 2. **Batch Updates** - For each pending item: + For each drift item: - Show the specific change needed - Apply the update - Track in change list @@ -36,8 +36,5 @@ Apply all pending documentation updates detected by `/doc audit`. - Single commit: `docs: sync documentation with code changes` - Include summary in commit body -4. **Clear Queue** - After successful sync, clear the queue file - -5. **Output** +4. **Output** Use format from `skills/sync-workflow.md` diff --git a/plugins/doc-guardian/skills/sync-workflow.md b/plugins/doc-guardian/skills/sync-workflow.md index 7084dff..1848dd5 100644 --- a/plugins/doc-guardian/skills/sync-workflow.md +++ b/plugins/doc-guardian/skills/sync-workflow.md @@ -16,20 +16,11 @@ Defines how to synchronize documentation with code changes. --- -## Queue File +## Drift Detection -Location: `.doc-guardian-queue` in project root +Run `/doc audit` to detect documentation drift. The audit produces a list of files and changes that need synchronization. Use those results as input to the sync process below. -Format: -``` -# Doc Guardian Queue -# Generated: YYYY-MM-DD HH:MM:SS - -## Pending Updates -- README.md:45 | reference | calculate_total -> compute_total -- CLAUDE.md:23 | version | Python 3.9 -> 3.11 -- src/api/README.md:12 | path | old/path.py -> new/path.py -``` +> **Note:** The queue file (`.doc-guardian-queue`) was removed in v8.1.0 when the PostToolUse hook was deleted (Decision #29). Drift detection is now manual via `/doc audit`. --- @@ -55,9 +46,9 @@ Format: ## Sync Process -1. **Review Queue** - - Read `.doc-guardian-queue` - - List all pending items +1. **Review Drift Results** + - Use output from `/doc audit` + - List all items needing sync 2. **Batch Updates** - Apply each update @@ -68,11 +59,6 @@ Format: - Single commit: `docs: sync documentation with code changes` - Include summary in commit body -4. **Clear Queue** - ```bash - echo "# Doc Guardian Queue - cleared after sync on $(date +%Y-%m-%d)" > .doc-guardian-queue - ``` - --- ## Output Format diff --git a/scripts/check-venv.sh b/scripts/check-venv.sh deleted file mode 100755 index 81c4b16..0000000 --- a/scripts/check-venv.sh +++ /dev/null @@ -1,37 +0,0 @@ -#!/usr/bin/env bash -# -# check-venv.sh - Check if MCP server venvs exist in installed marketplace -# -# Usage: ./scripts/check-venv.sh -# -# Exit codes: -# 0 - All venvs exist (or not installed via marketplace) -# 1 - Venvs missing, needs setup -# -# This script is designed to be called from SessionStart hooks -# to enable self-healing MCP server setup. - -set -euo pipefail - -# Installed marketplace location -MKTPLACE="$HOME/.claude/plugins/marketplaces/leo-claude-mktplace" - -# If not installed via marketplace, exit silently -if [[ ! -d "$MKTPLACE" ]]; then - exit 0 -fi - -# Check if gitea venv exists -if [[ ! -f "$MKTPLACE/mcp-servers/gitea/.venv/bin/python" ]]; then - echo "SETUP_NEEDED" - exit 1 -fi - -# Check if netbox venv exists -if [[ ! -f "$MKTPLACE/mcp-servers/netbox/.venv/bin/python" ]]; then - echo "SETUP_NEEDED" - exit 1 -fi - -# All good -exit 0