Merge pull request 'development' (#289) from development into main

Reviewed-on: #289

.claude-plugin/marketplace.json

@@ -6,12 +6,12 @@
   },
   "metadata": {
     "description": "Project management plugins with Gitea and NetBox integrations",
-    "version": "5.7.1"
+    "version": "5.3.0"
   },
   "plugins": [
     {
       "name": "projman",
-      "version": "3.4.0",
+      "version": "3.3.0",
       "description": "Sprint planning and project management with Gitea integration",
       "source": "./plugins/projman",
       "author": {
@@ -20,7 +20,7 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/projman/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "hooks": ["./hooks/hooks.json"],
+      "mcpServers": ["./.mcp.json"],
       "category": "development",
       "tags": ["sprint", "agile", "gitea", "project-management"],
       "license": "MIT"
@@ -43,7 +43,7 @@
     },
     {
       "name": "code-sentinel",
-      "version": "1.0.1",
+      "version": "1.0.0",
       "description": "Security scanning and code refactoring tools",
       "source": "./plugins/code-sentinel",
       "author": {
@@ -84,7 +84,7 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/cmdb-assistant/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "hooks": ["./hooks/hooks.json"],
+      "mcpServers": ["./.mcp.json"],
       "category": "infrastructure",
       "tags": ["cmdb", "netbox", "dcim", "ipam", "data-quality", "validation"],
       "license": "MIT"
@@ -100,7 +100,6 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/claude-config-maintainer/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "hooks": ["./hooks/hooks.json"],
       "category": "development",
       "tags": ["claude-md", "configuration", "optimization"],
       "license": "MIT"
@@ -116,7 +115,6 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/clarity-assist/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "hooks": ["./hooks/hooks.json"],
       "category": "productivity",
       "tags": ["prompts", "requirements", "clarification", "nd-friendly"],
       "license": "MIT"
@@ -132,7 +130,6 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/git-flow/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "hooks": ["./hooks/hooks.json"],
       "category": "development",
       "tags": ["git", "workflow", "commits", "branching"],
       "license": "MIT"
@@ -148,14 +145,14 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/pr-review/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "hooks": ["./hooks/hooks.json"],
+      "mcpServers": ["./.mcp.json"],
       "category": "development",
       "tags": ["code-review", "pull-requests", "security", "quality"],
       "license": "MIT"
     },
     {
       "name": "data-platform",
-      "version": "1.3.0",
+      "version": "1.2.0",
       "description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
       "source": "./plugins/data-platform",
       "author": {
@@ -164,7 +161,7 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/data-platform/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "hooks": ["./hooks/hooks.json"],
+      "mcpServers": ["./.mcp.json"],
       "category": "data",
       "tags": ["pandas", "postgresql", "postgis", "dbt", "data-engineering", "etl"],
       "license": "MIT"
@@ -180,7 +177,7 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/viz-platform/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "hooks": ["./hooks/hooks.json"],
+      "mcpServers": ["./.mcp.json"],
       "category": "visualization",
       "tags": ["dash", "plotly", "mantine", "charts", "dashboards", "theming", "dmc"],
       "license": "MIT"
@@ -196,7 +193,7 @@
       },
       "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/contract-validator/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "hooks": ["./hooks/hooks.json"],
+      "mcpServers": ["./.mcp.json"],
       "category": "development",
       "tags": ["validation", "contracts", "compatibility", "agents", "interfaces", "cross-plugin"],
       "license": "MIT"

.mcp.json

@@ -1,24 +0,0 @@
-{
-  "mcpServers": {
-    "gitea": {
-      "command": "./mcp-servers/gitea/run.sh",
-      "args": []
-    },
-    "netbox": {
-      "command": "./mcp-servers/netbox/run.sh",
-      "args": []
-    },
-    "viz-platform": {
-      "command": "./mcp-servers/viz-platform/run.sh",
-      "args": []
-    },
-    "data-platform": {
-      "command": "./mcp-servers/data-platform/run.sh",
-      "args": []
-    },
-    "contract-validator": {
-      "command": "./mcp-servers/contract-validator/run.sh",
-      "args": []
-    }
-  }
-}

CHANGELOG.md

@@ -4,138 +4,6 @@ All notable changes to the Leo Claude Marketplace will be documented in this fil
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
-## [5.7.1] - 2026-02-02
-
-### Added
-- **contract-validator**: New `validate_workflow_integration` MCP tool — validates domain plugins expose required advisory interfaces (gate command, review command, advisory agent)
-- **contract-validator**: New `MISSING_INTEGRATION` issue type for workflow integration validation
-
-### Fixed
-- `scripts/setup.sh` banner version updated from v5.1.0 to v5.7.1
-
-### Reverted
-- **marketplace.json**: Removed `integrates_with` field — Claude Code schema does not support custom plugin fields (causes marketplace load failure)
-
----
-
-## [5.7.0] - 2026-02-02
-
-### Added
-- **data-platform**: New `data-advisor` agent for data integrity, schema, and dbt compliance validation
-- **data-platform**: New `data-integrity-audit.md` skill defining audit rules, severity levels, and scanning strategies
-- **data-platform**: New `/data-gate` command for binary pass/fail data integrity gates (projman integration)
-- **data-platform**: New `/data-review` command for comprehensive data integrity audits
-
-### Changed
-- Domain Advisory Pattern now fully operational for both Viz and Data domains
-- projman orchestrator `Domain/Data` gates now resolve to live `/data-gate` command (previously fell through to "gate unavailable" warning)
-
----
-
-## [5.6.0] - 2026-02-01
-
-### Added
-- **Domain Advisory Pattern**: Cross-plugin integration enabling projman to consult domain-specific plugins during sprint lifecycle
-- **projman**: New `domain-consultation.md` skill for domain detection and gate protocols
-- **viz-platform**: New `design-reviewer` agent for design system compliance auditing
-- **viz-platform**: New `design-system-audit.md` skill defining audit rules and severity levels
-- **viz-platform**: New `/design-review` command for detailed design system audits
-- **viz-platform**: New `/design-gate` command for binary pass/fail validation gates
-- **Labels**: New `Domain/Viz` and `Domain/Data` labels for domain routing
-
-### Changed
-- **projman planner**: Now loads domain-consultation skill and performs domain detection during planning
-- **projman orchestrator**: Now runs domain gates before marking Domain/* labeled issues as complete
-
----
-
-## [5.5.0] - 2026-02-01
-
-### Added
-
-#### RFC System for Feature Tracking
-Wiki-based Request for Comments (RFC) system for capturing, reviewing, and tracking feature ideas through their lifecycle.
-
-**New Commands (projman):**
-- `/rfc-create` - Create new RFC from conversation or clarified specification
-- `/rfc-list` - List all RFCs grouped by status (Draft, Review, Approved, Implementing, Implemented, Rejected, Stale)
-- `/rfc-review` - Submit Draft RFC for maintainer review
-- `/rfc-approve` - Approve RFC, making it available for sprint planning
-- `/rfc-reject` - Reject RFC with documented reason
-
-**RFC Lifecycle:**
-- Draft → Review → Approved → Implementing → Implemented
-- Terminal states: Rejected, Superseded
-- Stale: Drafts with no activity >90 days
-
-**Sprint Integration:**
-- `/sprint-plan` now detects approved RFCs and offers selection
-- `/sprint-close` updates RFC status to Implemented on completion
-- RFC-Index wiki page auto-maintained with status sections
-
-**Clarity-Assist Integration:**
-- Vagueness hook now detects feature request patterns
-- Suggests `/rfc-create` for feature ideas
-- `/clarify` offers RFC creation after delivering clarified spec
-
-**New MCP Tool:**
-- `allocate_rfc_number` - Allocates next sequential RFC number
-
-**New Skills:**
-- `skills/rfc-workflow.md` - RFC lifecycle and state transitions
-- `skills/rfc-templates.md` - RFC page template specifications
-
-### Changed
-
-#### Sprint 8: Hook Efficiency Quick Wins
-Performance optimizations for plugin hooks to reduce overhead on every command.
-
-**Changes:**
-- **viz-platform:** Remove SessionStart hook that only echoed "loaded" (zero value)
-- **git-flow:** Add early exit to `branch-check.sh` for non-git commands (skip JSON parsing)
-- **git-flow:** Add early exit to `commit-msg-check.sh` for non-git commands (skip Python spawn)
-- **project-hygiene:** Add 60-second cooldown to `cleanup.sh` (reduce find operations)
-
-**Impact:** Hooks now exit immediately for 90%+ of Bash commands that don't need processing.
-
-**Issues:** #321, #322, #323, #324
-**PR:** #334
-
----
-
-## [5.4.1] - 2026-01-30
-
-### Removed
-
-#### Multi-Model Agent Support (REVERTED)
-
-**Reason:** Claude Code does not support `defaultModel` in plugin.json or `model` in agent frontmatter. The schema validation rejects these as "Unrecognized key".
-
-**Removed:**
-- `defaultModel` field from all plugin.json files (6 plugins)
-- `model` field references from agent frontmatter
-- `docs/MODEL-RECOMMENDATIONS.md` - Deleted entirely
-- Model configuration sections from `docs/CONFIGURATION.md` and `CLAUDE.md`
-
-**Lesson:** Do not implement features without verifying they are supported by Claude Code's plugin schema.
-
----
-
-## [5.4.0] - 2026-01-28 [REVERTED]
-
-### Added (NOW REMOVED - See 5.4.1)
-
-#### Sprint 7: Multi-Model Agent Support
-~~Configurable model selection for agents with inheritance chain.~~
-
-**This feature was reverted in 5.4.1 - Claude Code does not support these fields.**
-
-Original sprint work:
-- Issues: #302, #303, #304, #305, #306
-- PRs: #307, #308
-
----
-
 ## [5.3.0] - 2026-01-28
 
 ### Added

CLAUDE.md

@@ -1,5 +1,6 @@
 # CLAUDE.md
 
+This file provides guidance to Claude Code when working with code in this repository.
 ## ⛔ MANDATORY BEHAVIOR RULES - READ FIRST
 
 **These rules are NON-NEGOTIABLE. Violating them wastes the user's time and money.**
@@ -8,145 +9,48 @@
 - Search ALL locations, not just where you think it is
 - Check cache directories: `~/.claude/plugins/cache/`
 - Check installed: `~/.claude/plugins/marketplaces/`
-- Check source directories
+- Check source: `~/claude-plugins-work/`
 - **NEVER say "no" or "that's not the issue" without exhaustive verification**
 
 ### 2. WHEN USER SAYS SOMETHING IS WRONG - BELIEVE THEM
 - The user knows their system better than you
 - Investigate thoroughly before disagreeing
+- If user suspects cache, CHECK THE CACHE
+- If user suspects a file, READ THE FILE
 - **Your confidence is often wrong. User's instincts are often right.**
 
 ### 3. NEVER SAY "DONE" WITHOUT VERIFICATION
 - Run the actual command/script to verify
 - Show the output to the user
+- Check ALL affected locations
 - **"Done" means VERIFIED WORKING, not "I made changes"**
 
 ### 4. SHOW EXACTLY WHAT USER ASKS FOR
 - If user asks for messages, show the MESSAGES
 - If user asks for code, show the CODE
-- **Do not interpret or summarize unless asked**
+- If user asks for output, show the OUTPUT
+- **Don't interpret or summarize unless asked**
+
+### 5. AFTER PLUGIN UPDATES - VERIFY AND RESTART
+
+**⚠️ DO NOT clear cache mid-session** - this breaks MCP tools that are already loaded.
+
+1. Run `./scripts/verify-hooks.sh` to check hook types
+2. If changes affect MCP servers or hooks, inform the user:
+   > "Plugin changes require a session restart to take effect. Please restart Claude Code."
+3. Cache clearing is ONLY safe **before** starting a new session (not during)
+
+See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing.
 
 **FAILURE TO FOLLOW THESE RULES = WASTED USER TIME = UNACCEPTABLE**
 
 ---
 
 
-
-This file provides guidance to Claude Code when working with code in this repository.
-
-## ⛔ RULES - READ FIRST
-
-### Behavioral Rules
-
-| Rule | Summary |
-|------|---------|
-| **Check everything** | Search cache (`~/.claude/plugins/cache/`), installed (`~/.claude/plugins/marketplaces/`), and source (`~/claude-plugins-work/`) |
-| **Believe the user** | User knows their system. Investigate before disagreeing. |
-| **Verify before "done"** | Run commands, show output, check all locations. "Done" = verified working. |
-| **Show what's asked** | Don't interpret or summarize unless asked. |
-
-### After Plugin Updates
-
-Run `./scripts/verify-hooks.sh`. If changes affect MCP servers or hooks, inform user to restart session.
-**DO NOT clear cache mid-session** - breaks loaded MCP tools.
-
-### NEVER USE CLI TOOLS FOR EXTERNAL SERVICES
-- **FORBIDDEN:** `gh`, `tea`, `curl` to APIs, any CLI that talks to Gitea/GitHub/external services
-- **REQUIRED:** Use MCP tools exclusively (`mcp__plugin_projman_gitea__*`, `mcp__plugin_pr-review_gitea__*`)
-- **NO EXCEPTIONS.** Don't try CLI first. Don't fall back to CLI. MCP ONLY.
-
-### NEVER PUSH DIRECTLY TO PROTECTED BRANCHES
-- **FORBIDDEN:** `git push origin development`, `git push origin main`, `git push origin master`
-- **REQUIRED:** Create feature branch → push feature branch → create PR via MCP
-- If you accidentally commit to a protected branch locally: `git checkout -b fix/branch-name` then reset the protected branch
-
-### Repository Rules
-
-| Rule | Details |
-|------|---------|
-| **File creation** | Only in allowed paths. Use `.scratch/` for temp work. Verify against `docs/CANONICAL-PATHS.md` |
-| **plugin.json location** | Must be in `.claude-plugin/` directory |
-| **Hooks** | Use `hooks/hooks.json` (auto-discovered). Never inline in plugin.json |
-| **MCP servers** | Defined in root `.mcp.json`. Use MCP tools, never CLI (`tea`, `gh`) |
-| **Allowed root files** | `CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example` |
-
-**Valid hook events:** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
-
-### ⛔ MANDATORY: Before Any Code Change
-
-**Claude MUST show this checklist BEFORE editing any file:**
-
-#### 1. Impact Search Results
-Run and show output of:
-```bash
-grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
-```
-
-#### 2. Files That Will Be Affected
-Numbered list of every file to be modified, with the specific change for each.
-
-#### 3. Files Searched But Not Changed (and why)
-Proof that related files were checked and determined unchanged.
-
-#### 4. Documentation That References This
-List of docs that mention this feature/script/function.
-
-**User verifies this list before Claude proceeds. If Claude skips this, STOP IMMEDIATELY.**
-
-#### After Changes
-Run the same grep and show results proving no references remain unaddressed.
-
----
-
-## ⚠️ Development Context: We Build AND Use These Plugins
-
-**This is a self-referential project.** We are:
-1. **BUILDING** a plugin marketplace (source code in `plugins/`)
-2. **USING** the installed marketplace to build it (dogfooding)
-
-### Plugins ACTIVELY USED in This Project
-
-These plugins are installed and should be used during development:
-
-| Plugin | Used For |
-|--------|----------|
-| **projman** | Sprint planning, issue management, lessons learned |
-| **git-flow** | Commits, branch management |
-| **pr-review** | Pull request reviews |
-| **doc-guardian** | Documentation drift detection |
-| **code-sentinel** | Security scanning, refactoring |
-| **clarity-assist** | Prompt clarification |
-| **claude-config-maintainer** | CLAUDE.md optimization |
-| **contract-validator** | Cross-plugin compatibility |
-
-### Plugins NOT Used Here (Development Only)
-
-These plugins exist in source but are **NOT relevant** to this project's workflow:
-
-| Plugin | Why Not Used |
-|--------|--------------|
-| **data-platform** | For data engineering projects (pandas, PostgreSQL, dbt) |
-| **viz-platform** | For dashboard projects (Dash, Plotly) |
-| **cmdb-assistant** | For infrastructure projects (NetBox) |
-
-**Do NOT suggest** `/ingest`, `/profile`, `/chart`, `/cmdb-*` commands - they don't apply here.
-
-### Key Distinction
-
-| Context | Path | What To Do |
-|---------|------|------------|
-| **Editing plugin source** | `~/claude-plugins-work/plugins/` | Modify code, add features |
-| **Using installed plugins** | `~/.claude/plugins/marketplaces/` | Run commands like `/sprint-plan` |
-
-When user says "run /sprint-plan", use the INSTALLED plugin.
-When user says "fix the sprint-plan command", edit the SOURCE code.
-
----
-
 ## Project Overview
 
 **Repository:** leo-claude-mktplace
-**Version:** 5.4.0
+**Version:** 5.3.0
 **Status:** Production Ready
 
 A plugin marketplace for Claude Code containing:
@@ -154,16 +58,16 @@ A plugin marketplace for Claude Code containing:
 | Plugin | Description | Version |
 |--------|-------------|---------|
 | `projman` | Sprint planning and project management with Gitea integration | 3.3.0 |
-| `git-flow` | Git workflow automation with smart commits and branch management | 1.0.0 |
+| `git-flow` | Git workflow automation with smart commits and branch management | 1.2.0 |
 | `pr-review` | Multi-agent PR review with confidence scoring | 1.1.0 |
-| `clarity-assist` | Prompt optimization with ND-friendly accommodations | 1.0.0 |
+| `clarity-assist` | Prompt optimization with ND-friendly accommodations | 1.2.0 |
-| `doc-guardian` | Automatic documentation drift detection and synchronization | 1.0.0 |
+| `doc-guardian` | Automatic documentation drift detection and synchronization | 1.1.0 |
-| `code-sentinel` | Security scanning and code refactoring tools | 1.0.1 |
+| `code-sentinel` | Security scanning and code refactoring tools | 1.0.0 |
-| `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 1.0.0 |
+| `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 1.1.0 |
 | `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 1.2.0 |
-| `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 1.1.0 |
+| `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 1.2.0 |
 | `viz-platform` | DMC validation, Plotly charts, and theming for dashboards | 1.1.0 |
-| `contract-validator` | Cross-plugin compatibility validation and agent verification | 1.1.0 |
+| `contract-validator` | Cross-plugin compatibility validation and agent verification | 1.2.0 |
 | `project-hygiene` | Post-task cleanup automation via hooks | 0.1.0 |
 
 ## Quick Start
@@ -173,33 +77,26 @@ A plugin marketplace for Claude Code containing:
 ./scripts/validate-marketplace.sh
 
 # After updates
-./scripts/post-update.sh   # Rebuild venvs
+./scripts/post-update.sh   # Rebuild venvs, verify symlinks
 ```
 
-### Plugin Commands - USE THESE in This Project
+### Plugin Commands by Category
 
 | Category | Commands |
 |----------|----------|
-| **Setup** | `/setup` (modes: `--full`, `--quick`, `--sync`) |
+| **Setup** | `/initial-setup`, `/project-init`, `/project-sync` |
-| **Sprint** | `/sprint-plan`, `/sprint-start`, `/sprint-status` (with `--diagram`), `/sprint-close` |
+| **Sprint** | `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/sprint-diagram` |
-| **Quality** | `/review`, `/test` (modes: `run`, `gen`) |
+| **Quality** | `/review`, `/test-check`, `/test-gen` |
 | **Versioning** | `/suggest-version` |
 | **PR Review** | `/pr-review`, `/pr-summary`, `/pr-findings`, `/pr-diff` |
 | **Docs** | `/doc-audit`, `/doc-sync`, `/changelog-gen`, `/doc-coverage`, `/stale-docs` |
 | **Security** | `/security-scan`, `/refactor`, `/refactor-dry` |
 | **Config** | `/config-analyze`, `/config-optimize`, `/config-diff`, `/config-lint` |
+| **Data** | `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/lineage-viz`, `/run`, `/dbt-test`, `/data-quality` |
+| **Visualization** | `/component`, `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/accessibility-check`, `/breakpoints` |
 | **Validation** | `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/dependency-graph` |
-| **Debug** | `/debug` (modes: `report`, `review`) |
+| **CMDB** | `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`, `/cmdb-audit`, `/cmdb-register`, `/cmdb-sync`, `/cmdb-topology`, `/change-audit`, `/ip-conflicts` |
-
+| **Debug** | `/debug-report`, `/debug-review` |
-### Plugin Commands - NOT RELEVANT to This Project
-
-These commands are being developed but don't apply to this project's workflow:
-
-| Category | Commands | For Projects Using |
-|----------|----------|-------------------|
-| **Data** | `/ingest`, `/profile`, `/schema`, `/lineage`, `/dbt-test` | pandas, PostgreSQL, dbt |
-| **Visualization** | `/component`, `/chart`, `/dashboard`, `/theme` | Dash, Plotly dashboards |
-| **CMDB** | `/cmdb-search`, `/cmdb-device`, `/cmdb-sync` | NetBox infrastructure |
 
 ## Repository Structure
 
@@ -207,40 +104,46 @@ These commands are being developed but don't apply to this project's workflow:
 leo-claude-mktplace/
 ├── .claude-plugin/
 │   └── marketplace.json          # Marketplace manifest
-├── .mcp.json                     # MCP server configuration (all servers)
+├── mcp-servers/                  # SHARED MCP servers (v3.0.0+)
-├── mcp-servers/                  # SHARED MCP servers
 │   ├── gitea/                    # Gitea MCP (issues, PRs, wiki)
 │   ├── netbox/                   # NetBox MCP (CMDB)
 │   ├── data-platform/            # pandas, PostgreSQL, dbt
-│   ├── viz-platform/             # DMC validation, charts, themes
+│   └── viz-platform/             # DMC validation, charts, themes
-│   └── contract-validator/       # Plugin compatibility validation
 ├── plugins/
 │   ├── projman/                  # Sprint management
 │   │   ├── .claude-plugin/plugin.json
-│   │   ├── commands/             # 12 commands
+│   │   ├── .mcp.json
-│   │   ├── hooks/                # SessionStart: mismatch detection
+│   │   ├── mcp-servers/gitea -> ../../../mcp-servers/gitea  # SYMLINK
+│   │   ├── commands/             # 14 commands (incl. setup, debug, suggest-version)
+│   │   ├── hooks/                # SessionStart: mismatch detection + sprint suggestions
 │   │   ├── agents/               # 4 agents
-│   │   └── skills/               # 17 reusable skill files
+│   │   └── skills/label-taxonomy/
 │   ├── git-flow/                 # Git workflow automation
 │   │   ├── .claude-plugin/plugin.json
 │   │   ├── commands/             # 8 commands
 │   │   └── agents/
 │   ├── pr-review/                # Multi-agent PR review
 │   │   ├── .claude-plugin/plugin.json
-│   │   ├── commands/             # 6 commands
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/gitea -> ../../../mcp-servers/gitea  # SYMLINK
+│   │   ├── commands/             # 6 commands (incl. setup)
 │   │   ├── hooks/                # SessionStart mismatch detection
 │   │   └── agents/               # 5 agents
 │   ├── clarity-assist/           # Prompt optimization
 │   │   ├── .claude-plugin/plugin.json
 │   │   ├── commands/             # 2 commands
 │   │   └── agents/
-│   ├── data-platform/            # Data engineering
+│   ├── data-platform/            # Data engineering (NEW v4.0.0)
 │   │   ├── .claude-plugin/plugin.json
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/          # pandas, postgresql, dbt MCPs
 │   │   ├── commands/             # 7 commands
 │   │   ├── hooks/                # SessionStart PostgreSQL check
 │   │   └── agents/               # 2 agents
-│   ├── viz-platform/             # Visualization
+│   ├── viz-platform/             # Visualization (NEW v4.0.0)
 │   │   ├── .claude-plugin/plugin.json
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/          # viz-platform MCP
 │   │   ├── commands/             # 7 commands
 │   │   ├── hooks/                # SessionStart DMC check
 │   │   └── agents/               # 3 agents
@@ -248,7 +151,6 @@ leo-claude-mktplace/
 │   ├── code-sentinel/            # Security scanning & refactoring
 │   ├── claude-config-maintainer/
 │   ├── cmdb-assistant/
-│   ├── contract-validator/
 │   └── project-hygiene/
 ├── scripts/
 │   ├── setup.sh, post-update.sh
@@ -260,6 +162,40 @@ leo-claude-mktplace/
     └── CONFIGURATION.md          # Centralized configuration guide
 ```
 
+## CRITICAL: Rules You MUST Follow
+
+### File Operations
+- **NEVER** create files in repository root unless listed in "Allowed Root Files"
+- **NEVER** modify `.gitignore` without explicit permission
+- **ALWAYS** use `.scratch/` for temporary/exploratory work
+- **ALWAYS** verify paths against `docs/CANONICAL-PATHS.md` before creating files
+
+### Plugin Development
+- **plugin.json MUST be in `.claude-plugin/` directory** (not plugin root)
+- **Every plugin MUST be listed in marketplace.json**
+- **MCP servers are SHARED at root** with symlinks from plugins
+- **MCP server venv path**: `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{name}/.venv/bin/python`
+- **CLI tools forbidden** - Use MCP tools exclusively (never `tea`, `gh`, etc.)
+
+#### ⚠️ plugin.json Format Rules (CRITICAL)
+- **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)
+`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
+
+**INVALID:** `task-completed`, `file-changed`, `git-commit-msg-needed`
+
+### Allowed Root Files
+`CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example`
+
+### Allowed Root Directories
+`.claude/`, `.claude-plugin/`, `.claude-plugins/`, `.scratch/`, `docs/`, `hooks/`, `mcp-servers/`, `plugins/`, `scripts/`
+
 ## Architecture
 
 ### Four-Agent Model (projman)
@@ -279,7 +215,7 @@ leo-claude-mktplace/
 | Labels | `get_labels`, `suggest_labels`, `create_label`, `create_label_smart` |
 | Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone`, `delete_milestone` |
 | Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `remove_issue_dependency`, `get_execution_order` |
-| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `update_wiki_page`, `create_lesson`, `search_lessons`, `allocate_rfc_number` |
+| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `update_wiki_page`, `create_lesson`, `search_lessons` |
 | **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` |
 
@@ -300,20 +236,6 @@ leo-claude-mktplace/
 | `staging` | Staging | Read-only code, can create issues |
 | `main`, `master` | Production | Read-only, emergency only |
 
-### RFC System
-
-Wiki-based Request for Comments system for tracking feature ideas from proposal through implementation.
-
-**RFC Wiki Naming:**
-- RFC pages: `RFC-NNNN: Short Title` (4-digit zero-padded)
-- Index page: `RFC-Index` (auto-maintained)
-
-**Lifecycle:** Draft → Review → Approved → Implementing → Implemented
-
-**Integration with Sprint Planning:**
-- `/sprint-plan` detects approved RFCs and offers selection
-- `/sprint-close` updates RFC status on completion
-
 ## Label Taxonomy
 
 43 labels total: 27 organization + 16 repository
@@ -338,15 +260,16 @@ Stored in Gitea Wiki under `lessons-learned/sprints/`.
 
 1. Create `plugins/{name}/.claude-plugin/plugin.json`
 2. Add entry to `.claude-plugin/marketplace.json` with category, tags, license
-3. Create `claude-md-integration.md`
+3. Create `README.md` and `claude-md-integration.md`
-4. If using new MCP server, add to root `mcp-servers/` and update `.mcp.json`
+4. If using MCP server, create symlink: `ln -s ../../../mcp-servers/{server} plugins/{name}/mcp-servers/{server}`
 5. Run `./scripts/validate-marketplace.sh`
 6. Update `CHANGELOG.md`
 
 ### Adding a Command to projman
 
 1. Create `plugins/projman/commands/{name}.md`
-2. Update marketplace description if significant
+2. Update `plugins/projman/README.md`
+3. Update marketplace description if significant
 
 ### Validation
 
@@ -373,6 +296,7 @@ Stored in Gitea Wiki under `lessons-learned/sprints/`.
 | `docs/DEBUGGING-CHECKLIST.md` | Systematic troubleshooting guide |
 | `docs/UPDATING.md` | Update guide for the marketplace |
 | `plugins/projman/CONFIGURATION.md` | Projman quick reference (links to central) |
+| `plugins/projman/README.md` | Projman full documentation |
 
 ## Installation Paths
 
@@ -394,12 +318,12 @@ See `docs/DEBUGGING-CHECKLIST.md` for systematic troubleshooting.
 | Symptom | Likely Cause | Fix |
 |---------|--------------|-----|
 | "X MCP servers failed" | Missing venv in installed path | `cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh` |
-| MCP tools not available | Venv missing or .mcp.json misconfigured | Run `/debug report` to diagnose |
+| MCP tools not available | Symlink broken or venv missing | Run `/debug-report` to diagnose |
 | Changes not taking effect | Editing source, not installed | Reinstall plugin or edit installed path |
 
 **Debug Commands:**
-- `/debug report` - Run full diagnostics, create issue if needed
+- `/debug-report` - Run full diagnostics, create issue if needed
-- `/debug review` - Investigate and propose fixes
+- `/debug-review` - Investigate and propose fixes
 
 ## Versioning Workflow
 
@@ -453,4 +377,4 @@ The script will:
 
 ---
 
-**Last Updated:** 2026-01-30
+**Last Updated:** 2026-01-28

README.md

@@ -1,4 +1,4 @@
-# Leo Claude Marketplace - v5.7.1
+# Leo Claude Marketplace - v5.3.0
 
 A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
 
@@ -6,7 +6,7 @@ A collection of Claude Code plugins for project management, infrastructure autom
 
 ### Development & Project Management
 
-#### [projman](./plugins/projman)
+#### [projman](./plugins/projman/README.md)
 **Sprint Planning and Project Management**
 
 AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sprint workflow into a distributable plugin.
@@ -19,9 +19,9 @@ AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sp
 - Branch-aware security (development/staging/production)
 - Pre-sprint-close code quality review and test verification
 
-**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/setup`, `/review`, `/test`, `/debug`, `/suggest-version`, `/proposal-status`, `/clear-cache`, `/rfc-create`, `/rfc-list`, `/rfc-review`, `/rfc-approve`, `/rfc-reject`
+**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/sprint-diagram`, `/labels-sync`, `/initial-setup`, `/project-init`, `/project-sync`, `/review`, `/test-check`, `/test-gen`, `/debug-report`, `/debug-review`, `/suggest-version`, `/proposal-status`
 
-#### [git-flow](./plugins/git-flow) *NEW in v3.0.0*
+#### [git-flow](./plugins/git-flow/README.md) *NEW in v3.0.0*
 **Git Workflow Automation**
 
 Smart git operations with intelligent commit messages and branch management.
@@ -34,7 +34,7 @@ Smart git operations with intelligent commit messages and branch management.
 
 **Commands:** `/commit`, `/commit-push`, `/commit-merge`, `/commit-sync`, `/branch-start`, `/branch-cleanup`, `/git-status`, `/git-config`
 
-#### [pr-review](./plugins/pr-review) *NEW in v3.0.0*
+#### [pr-review](./plugins/pr-review/README.md) *NEW in v3.0.0*
 **Multi-Agent PR Review**
 
 Comprehensive pull request review using specialized agents.
@@ -46,14 +46,14 @@ Comprehensive pull request review using specialized agents.
 
 **Commands:** `/pr-review`, `/pr-summary`, `/pr-findings`, `/pr-diff`, `/initial-setup`, `/project-init`, `/project-sync`
 
-#### [claude-config-maintainer](./plugins/claude-config-maintainer)
+#### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md)
 **CLAUDE.md Optimization and Maintenance**
 
 Analyze, optimize, and create CLAUDE.md configuration files for Claude Code projects.
 
 **Commands:** `/config-analyze`, `/config-optimize`, `/config-init`, `/config-diff`, `/config-lint`
 
-#### [contract-validator](./plugins/contract-validator) *NEW in v5.0.0*
+#### [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.
@@ -68,7 +68,7 @@ Validate plugin marketplaces for command conflicts, tool overlaps, and broken ag
 
 ### Productivity
 
-#### [clarity-assist](./plugins/clarity-assist) *NEW in v3.0.0*
+#### [clarity-assist](./plugins/clarity-assist/README.md) *NEW in v3.0.0*
 **Prompt Optimization with ND Accommodations**
 
 Transform vague requests into clear specifications using structured methodology.
@@ -79,21 +79,21 @@ Transform vague requests into clear specifications using structured methodology.
 
 **Commands:** `/clarify`, `/quick-clarify`
 
-#### [doc-guardian](./plugins/doc-guardian)
+#### [doc-guardian](./plugins/doc-guardian/README.md)
 **Documentation Lifecycle Management**
 
 Automatic documentation drift detection and synchronization.
 
 **Commands:** `/doc-audit`, `/doc-sync`, `/changelog-gen`, `/doc-coverage`, `/stale-docs`
 
-#### [project-hygiene](./plugins/project-hygiene)
+#### [project-hygiene](./plugins/project-hygiene/README.md)
 **Post-Task Cleanup Automation**
 
 Hook-based cleanup that runs after Claude completes work.
 
 ### Security
 
-#### [code-sentinel](./plugins/code-sentinel)
+#### [code-sentinel](./plugins/code-sentinel/README.md)
 **Security Scanning & Refactoring**
 
 Security vulnerability detection and code refactoring tools.
@@ -102,7 +102,7 @@ Security vulnerability detection and code refactoring tools.
 
 ### Infrastructure
 
-#### [cmdb-assistant](./plugins/cmdb-assistant)
+#### [cmdb-assistant](./plugins/cmdb-assistant/README.md)
 **NetBox CMDB Integration**
 
 Full CRUD operations for network infrastructure management directly from Claude Code.
@@ -111,7 +111,7 @@ Full CRUD operations for network infrastructure management directly from Claude
 
 ### Data Engineering
 
-#### [data-platform](./plugins/data-platform) *NEW in v4.0.0*
+#### [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.
@@ -126,7 +126,7 @@ Comprehensive data engineering toolkit with persistent DataFrame storage.
 
 ### Visualization
 
-#### [viz-platform](./plugins/viz-platform) *NEW in v4.0.0*
+#### [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.
@@ -138,26 +138,11 @@ Visualization toolkit with version-locked component validation and design token
 - 5 Page tools for multi-page app structure
 - Dual theme storage: user-level and project-level
 
-**Commands:** `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/accessibility-check`, `/breakpoints`, `/design-review`, `/design-gate`, `/initial-setup`
+**Commands:** `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/accessibility-check`, `/breakpoints`, `/initial-setup`
-
-## 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 (`/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 | `/design-gate` |
-| Data | data-platform | `/data-gate` |
 
 ## MCP Servers
 
-MCP servers are **shared at repository root** and configured in `.mcp.json`.
+MCP servers are **shared at repository root** with **symlinks** from plugins that use them.
 
 ### Gitea MCP Server (shared)
 
@@ -215,7 +200,7 @@ 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` |
+| Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow` |
 | Report | `generate_compatibility_report`, `list_issues` |
 
 ## Installation

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-30 (v5.4.1)
+Last Updated: 2026-01-27 (v5.1.0)
 
 ---
 
@@ -76,6 +76,9 @@ leo-claude-mktplace/
 ├── plugins/                    # ALL plugins
 │   ├── projman/                # Sprint management
 │   │   ├── .claude-plugin/
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/
+│   │   │   └── gitea -> ../../../mcp-servers/gitea  # SYMLINK
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── skills/
@@ -96,6 +99,9 @@ leo-claude-mktplace/
 │   │   └── claude-md-integration.md
 │   ├── cmdb-assistant/         # NetBox CMDB integration
 │   │   ├── .claude-plugin/
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/
+│   │   │   └── netbox -> ../../../mcp-servers/netbox  # SYMLINK
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   └── claude-md-integration.md
@@ -108,48 +114,61 @@ leo-claude-mktplace/
 │   │   ├── .claude-plugin/
 │   │   ├── hooks/
 │   │   └── claude-md-integration.md
-│   ├── clarity-assist/
+│   ├── clarity-assist/         # NEW in v3.0.0
 │   │   ├── .claude-plugin/
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── skills/
 │   │   └── claude-md-integration.md
-│   ├── git-flow/
+│   ├── git-flow/               # NEW in v3.0.0
 │   │   ├── .claude-plugin/
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── skills/
 │   │   └── claude-md-integration.md
-│   ├── pr-review/
+│   ├── pr-review/              # NEW in v3.0.0
 │   │   ├── .claude-plugin/
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/
+│   │   │   └── gitea -> ../../../mcp-servers/gitea  # SYMLINK
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── skills/
 │   │   └── claude-md-integration.md
-│   ├── data-platform/
+│   ├── data-platform/          # NEW in v4.0.0
 │   │   ├── .claude-plugin/
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/
+│   │   │   └── data-platform -> ../../../mcp-servers/data-platform  # SYMLINK
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── hooks/
 │   │   └── claude-md-integration.md
-│   ├── contract-validator/
+│   ├── contract-validator/     # NEW in v5.0.0
 │   │   ├── .claude-plugin/
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/
+│   │   │   └── contract-validator -> ../../../mcp-servers/contract-validator  # SYMLINK
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   └── claude-md-integration.md
-│   └── viz-platform/
+│   └── 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
 ├── scripts/                    # Setup and maintenance scripts
 │   ├── setup.sh                # Initial setup (create venvs, config templates)
-│   ├── post-update.sh          # Post-update (clear cache, show changelog)
+│   ├── post-update.sh          # Post-update (rebuild venvs, verify symlinks)
-│   ├── check-venv.sh           # Check if venvs exist (read-only)
+│   ├── check-venv.sh           # Check if venvs exist (for hooks)
 │   ├── 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)
+│   ├── setup-venvs.sh          # Setup/repair MCP server venvs
+│   ├── venv-repair.sh          # Repair broken venv symlinks
 │   └── release.sh              # Release automation with version bumping
 ├── CLAUDE.md
 ├── README.md
@@ -170,21 +189,29 @@ leo-claude-mktplace/
 | Plugin manifest | `plugins/{plugin-name}/.claude-plugin/plugin.json` | `plugins/projman/.claude-plugin/plugin.json` |
 | Plugin commands | `plugins/{plugin-name}/commands/` | `plugins/projman/commands/` |
 | Plugin agents | `plugins/{plugin-name}/agents/` | `plugins/projman/agents/` |
-| Plugin skills | `plugins/{plugin-name}/skills/` | `plugins/projman/skills/` |
+| Plugin .mcp.json | `plugins/{plugin-name}/.mcp.json` | `plugins/projman/.mcp.json` |
 | Plugin integration snippet | `plugins/{plugin-name}/claude-md-integration.md` | `plugins/projman/claude-md-integration.md` |
 
-### MCP Server Paths
+### MCP Server Paths (v3.0.0 Architecture)
 
-MCP servers are **shared at repository root** and configured in `.mcp.json`.
+MCP servers are **shared at repository root** with **symlinks** from plugins.
 
 | Context | Pattern | Example |
 |---------|---------|---------|
-| MCP configuration | `.mcp.json` | `.mcp.json` (at repo root) |
 | Shared MCP server | `mcp-servers/{server}/` | `mcp-servers/gitea/` |
 | MCP server code | `mcp-servers/{server}/mcp_server/` | `mcp-servers/gitea/mcp_server/` |
 | MCP venv | `mcp-servers/{server}/.venv/` | `mcp-servers/gitea/.venv/` |
+| Plugin symlink | `plugins/{plugin}/mcp-servers/{server}` | `plugins/projman/mcp-servers/gitea` |
 
-**Note:** Plugins do NOT have their own `mcp-servers/` directories. All MCP servers are shared at root and configured via `.mcp.json`.
+### Symlink Pattern
+
+Plugins that use MCP servers create symlinks:
+```bash
+# From plugin directory
+ln -s ../../../mcp-servers/gitea plugins/projman/mcp-servers/gitea
+```
+
+The symlink target is relative: `../../../mcp-servers/{server}`
 
 ### Documentation Paths
 
@@ -213,12 +240,15 @@ MCP servers are **shared at repository root** and configured in `.mcp.json`.
 2. Verify each path against patterns in this file
 3. Show verification to user before proceeding
 
-### Relative Path Calculation
+### Relative Path Calculation (v3.0.0)
 
-From `.mcp.json` (at root) to `mcp-servers/gitea/`:
+From `plugins/projman/.mcp.json` to shared `mcp-servers/gitea/`:
 ```
-.mcp.json (at repository root)
+plugins/projman/.mcp.json
-  → Uses absolute installed path: ~/.claude/plugins/marketplaces/.../mcp-servers/gitea/run.sh
+  → Uses ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/
+  → Symlink at plugins/projman/mcp-servers/gitea points to ../../../mcp-servers/gitea
+
+Result in .mcp.json: ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/.venv/bin/python
 ```
 
 From `.claude-plugin/marketplace.json` to `plugins/projman/`:
@@ -237,34 +267,30 @@ Result: ./plugins/projman
 | Wrong | Why | Correct |
 |-------|-----|---------|
 | `projman/` at root | Plugins go in `plugins/` | `plugins/projman/` |
-| `mcp-servers/` inside plugins | MCP servers are shared at root | Use root `mcp-servers/` |
+| Direct path in .mcp.json to root mcp-servers | Use symlink | Symlink at `plugins/{plugin}/mcp-servers/` |
-| Plugin-level `.mcp.json` | MCP config is at root | Use root `.mcp.json` |
+| Creating new mcp-servers inside plugins | Use shared + symlink | Symlink to `mcp-servers/` |
-| Hardcoding absolute paths in source | Breaks portability | Use relative paths or `${CLAUDE_PLUGIN_ROOT}` |
+| Hardcoding absolute paths | Breaks portability | Use `${CLAUDE_PLUGIN_ROOT}` |
 
 ---
 
-## Architecture Note
+## Architecture Note (v3.0.0)
 
-MCP servers are **shared at repository root** and configured in a single `.mcp.json` file.
+MCP servers are now **shared at repository root** with **symlinks** from plugins:
 
 **Benefits:**
 - Single source of truth for each MCP server
 - Updates apply to all plugins automatically
-- No duplication - clean plugin structure
+- Reduced duplication
-- Simple configuration in one place
+- Symlinks work with Claude Code caching
 
-**Configuration:**
+**Symlink Pattern:**
-All MCP servers are defined in `.mcp.json` at repository root:
+```
-```json
+plugins/projman/mcp-servers/gitea -> ../../../mcp-servers/gitea
-{
+plugins/cmdb-assistant/mcp-servers/netbox -> ../../../mcp-servers/netbox
-  "mcpServers": {
+plugins/pr-review/mcp-servers/gitea -> ../../../mcp-servers/gitea
-    "gitea": { "command": ".../mcp-servers/gitea/run.sh" },
+plugins/data-platform/mcp-servers/data-platform -> ../../../mcp-servers/data-platform
-    "netbox": { "command": ".../mcp-servers/netbox/run.sh" },
+plugins/viz-platform/mcp-servers/viz-platform -> ../../../mcp-servers/viz-platform
-    "data-platform": { "command": ".../mcp-servers/data-platform/run.sh" },
+plugins/contract-validator/mcp-servers/contract-validator -> ../../../mcp-servers/contract-validator
-    "viz-platform": { "command": ".../mcp-servers/viz-platform/run.sh" },
-    "contract-validator": { "command": ".../mcp-servers/contract-validator/run.sh" }
-  }
-}
 ```
 
 ---
@@ -273,7 +299,6 @@ All MCP servers are defined in `.mcp.json` at repository root:
 
 | Date | Change | By |
 |------|--------|-----|
-| 2026-01-30 | v5.5.0: Removed plugin-level mcp-servers symlinks - all MCP config now in root .mcp.json | Claude Code |
 | 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 |

docs/COMMANDS-CHEATSHEET.md

@@ -10,22 +10,21 @@ Quick reference for all commands in the Leo Claude Marketplace.
 |--------|---------|:----:|:------:|-------------|
 | **projman** | `/sprint-plan` | | X | Start sprint planning with AI-guided architecture analysis and issue creation |
 | **projman** | `/sprint-start` | | X | Begin sprint execution with dependency analysis and parallel task coordination |
-| **projman** | `/sprint-status` | | X | Check current sprint progress (add `--diagram` for Mermaid visualization) |
+| **projman** | `/sprint-status` | | X | Check current sprint progress and identify blockers |
 | **projman** | `/review` | | X | Pre-sprint-close code quality review (debug artifacts, security, error handling) |
-| **projman** | `/test` | | X | Run tests (`/test run`) or generate tests (`/test gen <target>`) |
+| **projman** | `/test-check` | | X | Run tests and verify coverage before sprint close |
 | **projman** | `/sprint-close` | | X | Complete sprint and capture lessons learned to Gitea Wiki |
 | **projman** | `/labels-sync` | | X | Synchronize label taxonomy from Gitea |
-| **projman** | `/setup` | | X | Auto-detect mode or use `--full`, `--quick`, `--sync` |
+| **projman** | `/initial-setup` | | X | Full setup wizard: MCP server + system config + project config |
-| **projman** | *SessionStart hook* | X | | Detects git remote vs .env mismatch, warns to run `/setup --sync` |
+| **projman** | `/project-init` | | X | Quick project setup (assumes system config exists) |
-| **projman** | `/debug` | | X | Diagnostics (`/debug report`) or investigate (`/debug review`) |
+| **projman** | `/project-sync` | | X | Sync config with git remote after repo move/rename |
+| **projman** | *SessionStart hook* | X | | Detects git remote vs .env mismatch, warns to run /project-sync |
+| **projman** | `/test-gen` | | X | Generate comprehensive tests for specified code |
+| **projman** | `/debug-report` | | X | Run diagnostics and create structured issue in marketplace |
+| **projman** | `/debug-review` | | X | Investigate diagnostic issues and propose fixes with approval gates |
 | **projman** | `/suggest-version` | | X | Analyze CHANGELOG and recommend semantic version bump |
 | **projman** | `/proposal-status` | | X | View proposal and implementation hierarchy with status |
-| **projman** | `/clear-cache` | | X | Clear plugin cache to force fresh configuration reload |
+| **projman** | `/sprint-diagram` | | X | Generate Mermaid diagram of sprint issues with dependencies |
-| **projman** | `/rfc-create` | | X | Create new RFC from conversation or clarified spec |
-| **projman** | `/rfc-list` | | X | List all RFCs grouped by status |
-| **projman** | `/rfc-review` | | X | Submit Draft RFC for review |
-| **projman** | `/rfc-approve` | | X | Approve RFC in Review status for sprint planning |
-| **projman** | `/rfc-reject` | | X | Reject RFC with documented reason |
 | **git-flow** | `/commit` | | X | Create commit with auto-generated conventional message |
 | **git-flow** | `/commit-push` | | X | Commit and push to remote in one operation |
 | **git-flow** | `/commit-merge` | | X | Commit current changes, then merge into target branch |
@@ -92,11 +91,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **viz-platform** | `/chart-export` | | X | Export charts to PNG, SVG, PDF via kaleido |
 | **viz-platform** | `/accessibility-check` | | X | Color blind validation (WCAG contrast ratios) |
 | **viz-platform** | `/breakpoints` | | X | Configure responsive layout breakpoints |
-| **viz-platform** | `/design-review` | | X | Detailed design system audits |
-| **viz-platform** | `/design-gate` | | X | Binary pass/fail design system validation gates |
 | **viz-platform** | *SessionStart hook* | X | | Checks DMC version (non-blocking warning) |
-| **data-platform** | `/data-review` | | X | Comprehensive data integrity audits |
-| **data-platform** | `/data-gate` | | X | Binary pass/fail data integrity gates |
 | **contract-validator** | `/validate-contracts` | | X | Full marketplace compatibility validation |
 | **contract-validator** | `/check-agent` | | X | Validate single agent definition |
 | **contract-validator** | `/list-interfaces` | | X | Show all plugin interfaces |
@@ -109,7 +104,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
 
 | Category | Plugins | Primary Use |
 |----------|---------|-------------|
-| **Setup** | projman, pr-review, cmdb-assistant, data-platform | `/setup`, `/initial-setup` |
+| **Setup** | projman, pr-review, cmdb-assistant, data-platform | `/initial-setup`, `/project-init` |
 | **Task Planning** | projman, clarity-assist | Sprint management, requirement clarification |
 | **Code Quality** | code-sentinel, pr-review | Security scanning, PR reviews |
 | **Documentation** | doc-guardian, claude-config-maintainer | Doc sync, CLAUDE.md maintenance |
@@ -138,22 +133,6 @@ Quick reference for all commands in the Leo Claude Marketplace.
 
 ## Dev Workflow Examples
 
-### Example 0: RFC-Driven Feature Development
-
-Full workflow from idea to implementation using RFCs:
-
-```
-1. /clarify                  # Clarify the feature idea
-2. /rfc-create               # Create RFC from clarified spec
-   ... refine RFC content ...
-3. /rfc-review 0001          # Submit RFC for review
-   ... review discussion ...
-4. /rfc-approve 0001         # Approve RFC for implementation
-5. /sprint-plan              # Select approved RFC for sprint
-   ... implement feature ...
-6. /sprint-close             # Complete sprint, RFC marked Implemented
-```
-
 ### Example 1: Starting a New Feature Sprint
 
 A typical workflow for planning and executing a feature sprint:
@@ -166,9 +145,9 @@ A typical workflow for planning and executing a feature sprint:
 5. /branch-start feat/...    # Create feature branch
    ... implement features ...
 6. /commit                   # Commit with conventional message
-7. /sprint-status --diagram  # Check progress with visualization
+7. /sprint-status            # Check progress mid-sprint
 8. /review                   # Pre-close quality review
-9. /test run                 # Verify test coverage
+9. /test-check               # Verify test coverage
 10. /sprint-close            # Capture lessons learned
 ```
 
@@ -215,7 +194,7 @@ Safe refactoring with preview:
 1. /refactor-dry             # Preview opportunities
 2. /security-scan            # Baseline security check
 3. /refactor                 # Apply improvements
-4. /test run                 # Verify nothing broke
+4. /test-check               # Verify nothing broke
 5. /commit                   # Commit with descriptive message
 ```
 
@@ -248,7 +227,7 @@ Working with data pipelines:
 Setting up the marketplace for the first time:
 
 ```
-1. /setup --full             # Full setup: MCP + system config + project
+1. /initial-setup            # Full setup: MCP + system config + project
    # → Follow prompts for Gitea URL, org
    # → Add token manually when prompted
    # → Confirm repository name
@@ -262,7 +241,7 @@ Setting up the marketplace for the first time:
 Adding a new project when system config exists:
 
 ```
-1. /setup --quick            # Quick project setup (auto-detected)
+1. /project-init             # Quick project setup
    # → Confirms detected repo name
    # → Creates .env
 2. /labels-sync              # Sync Gitea labels
@@ -298,4 +277,4 @@ Ensure credentials are configured in `~/.config/claude/gitea.env`, `~/.config/cl
 
 ---
 
-*Last Updated: 2026-02-02*
+*Last Updated: 2026-01-28*

docs/CONFIGURATION.md

@@ -9,10 +9,10 @@ Centralized configuration documentation for all plugins and MCP servers in the L
 **After installing the marketplace and plugins via Claude Code:**
 
 ```
-/setup
+/initial-setup
 ```
 
-The interactive wizard auto-detects what's needed and handles everything except manually adding your API tokens.
+The interactive wizard handles everything except manually adding your API tokens.
 
 ---
 
@@ -25,8 +25,7 @@ The interactive wizard auto-detects what's needed and handles everything except
 └─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
-                              /setup --full
+                            /initial-setup
-                          (or /setup auto-detects)
                                     │
      ┌──────────────────────────────┼──────────────────────────────┐
      ▼                              ▼                              ▼
@@ -79,8 +78,8 @@ The interactive wizard auto-detects what's needed and handles everything except
                                     │
                     ┌───────────────┴───────────────┐
                     ▼                               ▼
-             /setup --quick                     /setup
+             /project-init                   /initial-setup
-             (explicit mode)               (auto-detects mode)
+             (direct path)                   (smart detection)
                     │                               │
                     │                    ┌──────────┴──────────┐
                     │                    ▼                     ▼
@@ -109,7 +108,7 @@ The interactive wizard auto-detects what's needed and handles everything except
 
 ## What Runs Automatically vs User Interaction
 
-### `/setup --full` - Full Setup
+### `/initial-setup` - Full Setup
 
 | Phase | Type | What Happens |
 |-------|------|--------------|
@@ -121,7 +120,7 @@ The interactive wizard auto-detects what's needed and handles everything except
 | **6. Project Config** | Automated | Creates `.env` file, checks `.gitignore` |
 | **7. Validation** | Automated | Tests API connectivity, shows summary |
 
-### `/setup --quick` - Quick Project Setup
+### `/project-init` - Quick Project Setup
 
 | Phase | Type | What Happens |
 |-------|------|--------------|
@@ -132,25 +131,23 @@ The interactive wizard auto-detects what's needed and handles everything except
 
 ---
 
-## One Command, Three Modes
+## Three Commands for Different Scenarios
 
-| Mode | When to Use | What It Does |
+| Command | When to Use | What It Does |
-|------|-------------|--------------|
+|---------|-------------|--------------|
-| `/setup` | Any time | Auto-detects: runs full, quick, or sync as needed |
+| `/initial-setup` | First time on a machine | Full setup: MCP server + system config + project config |
-| `/setup --full` | First time on a machine | Full setup: MCP server + system config + project config |
+| `/project-init` | Starting a new project | Quick setup: project config only (assumes system is ready) |
-| `/setup --quick` | Starting a new project | Quick setup: project config only (assumes system is ready) |
+| `/project-sync` | After repo move/rename | Updates .env to match current git remote |
-| `/setup --sync` | After repo move/rename | Updates .env to match current git remote |
-
-**Auto-detection logic:**
-1. No system config → **full** mode
-2. System config exists, no project config → **quick** mode
-3. Both exist, git remote differs → **sync** mode
-4. Both exist, match → already configured, offer to reconfigure
 
 **Typical workflow:**
-1. Install plugin → run `/setup` (auto-runs full mode)
+1. Install plugin → run `/initial-setup` (once per machine)
-2. Start new project → run `/setup` (auto-runs quick mode)
+2. Start new project → run `/project-init` (once per project)
-3. Repository moved? → run `/setup` (auto-runs sync mode)
+3. Repository moved? → run `/project-sync` (updates config)
+
+**Smart features:**
+- `/initial-setup` detects existing system config and offers quick project setup
+- All commands validate org/repo via Gitea API before saving (auto-fills if verified)
+- SessionStart hook automatically detects git remote vs .env mismatches
 
 ---
 
@@ -182,7 +179,7 @@ This marketplace uses a **hybrid configuration** approach:
 
 **Benefits:**
 - Single token per service (update once, use everywhere)
-- Easy multi-project setup (just run `/setup` in each project)
+- Easy multi-project setup (just run `/project-init` in each project)
 - Security (tokens never committed to git, never typed into AI chat)
 - Project isolation (each project can override defaults)
 
@@ -190,7 +187,7 @@ This marketplace uses a **hybrid configuration** approach:
 
 ## Prerequisites
 
-Before running `/setup`:
+Before running `/initial-setup`:
 
 1. **Python 3.10+** installed
    ```bash
@@ -213,10 +210,10 @@ Before running `/setup`:
 Run the setup wizard in Claude Code:
 
 ```
-/setup
+/initial-setup
 ```
 
-The wizard will guide you through each step interactively and auto-detect the appropriate mode.
+The wizard will guide you through each step interactively.
 
 **Note:** After first-time setup, you'll need to restart your Claude Code session for MCP tools to become available.
 
@@ -385,10 +382,10 @@ PR_REVIEW_AUTO_SUBMIT=false
 
 ## Plugin Configuration Summary
 
-| Plugin | System Config | Project Config | Setup Command |
+| Plugin | System Config | Project Config | Setup Commands |
-|--------|---------------|----------------|---------------|
+|--------|---------------|----------------|----------------|
-| **projman** | gitea.env | .env (GITEA_REPO=owner/repo) | `/setup` |
+| **projman** | gitea.env | .env (GITEA_REPO=owner/repo) | `/initial-setup`, `/project-init`, `/project-sync` |
-| **pr-review** | gitea.env | .env (GITEA_REPO=owner/repo) | `/initial-setup` |
+| **pr-review** | gitea.env | .env (GITEA_REPO=owner/repo) | `/initial-setup`, `/project-init`, `/project-sync` |
 | **git-flow** | git-flow.env (optional) | .env (optional) | None needed |
 | **clarity-assist** | None | None | None needed |
 | **cmdb-assistant** | netbox.env | None | `/initial-setup` |
@@ -398,7 +395,6 @@ PR_REVIEW_AUTO_SUBMIT=false
 | **code-sentinel** | None | None | None needed |
 | **project-hygiene** | None | None | None needed |
 | **claude-config-maintainer** | None | None | None needed |
-| **contract-validator** | None | None | `/initial-setup` |
 
 ---
 
@@ -406,12 +402,21 @@ PR_REVIEW_AUTO_SUBMIT=false
 
 Once system-level config is set up, adding new projects is simple:
 
+**Option 1: Use `/project-init` (faster)**
 ```
 cd ~/projects/new-project
-/setup
+/project-init
 ```
 
-The command auto-detects that system config exists and runs quick project setup.
+**Option 2: Use `/initial-setup` (auto-detects)**
+```
+cd ~/projects/new-project
+/initial-setup
+# → Detects system config exists
+# → Offers "Quick project setup" option
+```
+
+Both approaches work. Use `/project-init` when you know the system is already configured.
 
 ---
 
@@ -419,12 +424,12 @@ The command auto-detects that system config exists and runs quick project setup.
 
 ### API Validation
 
-When running `/setup`, the command:
+When running `/initial-setup`, `/project-init`, or `/project-sync`, the commands:
 
-1. **Detects** organization and repository from git remote URL
+1. **Detect** organization and repository from git remote URL
-2. **Validates** via Gitea API: `GET /api/v1/repos/{org}/{repo}`
+2. **Validate** via Gitea API: `GET /api/v1/repos/{org}/{repo}`
-3. **Auto-fills** if repository exists and is accessible (no confirmation needed)
+3. **Auto-fill** if repository exists and is accessible (no confirmation needed)
-4. **Asks for confirmation** only if validation fails (404 or permission error)
+4. **Ask for confirmation** only if validation fails (404 or permission error)
 
 This catches typos and permission issues before saving configuration.
 
@@ -434,7 +439,7 @@ When you start a Claude Code session, a hook automatically:
 
 1. Reads `GITEA_REPO` (in `owner/repo` format) from `.env`
 2. Compares with current `git remote get-url origin`
-3. **Warns** if mismatch detected: "Repository location mismatch. Run `/setup --sync` to update."
+3. **Warns** if mismatch detected: "Repository location mismatch. Run `/project-sync` to update."
 
 This helps when you:
 - Move a repository to a different organization
@@ -496,8 +501,9 @@ If you get 401, regenerate your token in Gitea.
 # Check venv exists
 ls /path/to/mcp-servers/gitea/.venv
 
-# If missing, create venv (do NOT delete existing venvs)
+# Reinstall if missing
 cd /path/to/mcp-servers/gitea
+rm -rf .venv
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
@@ -529,7 +535,7 @@ cat .env
 
 3. **Never type tokens into AI chat**
    - Always edit config files directly in your editor
-   - The `/setup` wizard respects this
+   - The `/initial-setup` wizard respects this
 
 4. **Rotate tokens periodically**
    - Every 6-12 months

docs/DEBUGGING-CHECKLIST.md

@@ -73,19 +73,25 @@ cd $RUNTIME && ./scripts/setup.sh
 
 ---
 
-## Step 4: Verify MCP Configuration
+## Step 4: Verify Symlink Resolution
 
-Check `.mcp.json` at marketplace root is correctly configured:
+Plugins use symlinks to shared MCP servers. Verify they resolve correctly:
 
 ```bash
 RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
 
-# Check .mcp.json exists and has valid content
+# Check symlinks exist and resolve
-cat $RUNTIME/.mcp.json | jq '.mcpServers | keys'
+readlink -f $RUNTIME/plugins/projman/mcp-servers/gitea
+readlink -f $RUNTIME/plugins/pr-review/mcp-servers/gitea
+readlink -f $RUNTIME/plugins/cmdb-assistant/mcp-servers/netbox
 
-# Should list: gitea, netbox, data-platform, viz-platform, contract-validator
+# Should resolve to:
+# $RUNTIME/mcp-servers/gitea
+# $RUNTIME/mcp-servers/netbox
 ```
 
+**If broken:** Symlinks are relative. If directory structure differs, they'll break.
+
 ---
 
 ## Step 5: Test MCP Server Startup
@@ -159,8 +165,10 @@ echo -e "\n=== Virtual Environments ==="
 [ -f "$RUNTIME/mcp-servers/gitea/.venv/bin/python" ] && echo "Gitea venv: OK" || echo "Gitea venv: MISSING"
 [ -f "$RUNTIME/mcp-servers/netbox/.venv/bin/python" ] && echo "NetBox venv: OK" || echo "NetBox venv: MISSING"
 
-echo -e "\n=== MCP Configuration ==="
+echo -e "\n=== Symlinks ==="
-[ -f "$RUNTIME/.mcp.json" ] && echo ".mcp.json: OK" || echo ".mcp.json: MISSING"
+[ -L "$RUNTIME/plugins/projman/mcp-servers/gitea" ] && echo "projman->gitea: OK" || echo "projman->gitea: MISSING"
+[ -L "$RUNTIME/plugins/pr-review/mcp-servers/gitea" ] && echo "pr-review->gitea: OK" || echo "pr-review->gitea: MISSING"
+[ -L "$RUNTIME/plugins/cmdb-assistant/mcp-servers/netbox" ] && echo "cmdb-assistant->netbox: OK" || echo "cmdb-assistant->netbox: MISSING"
 
 echo -e "\n=== Config Files ==="
 [ -f ~/.config/claude/gitea.env ] && echo "gitea.env: OK" || echo "gitea.env: MISSING"
@@ -174,7 +182,7 @@ echo -e "\n=== Config Files ==="
 | Issue | Symptom | Fix |
 |-------|---------|-----|
 | Missing venvs | "X MCP servers failed" | `cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh` |
-| Missing .mcp.json | MCP tools not available | Check `.mcp.json` exists at marketplace root |
+| Broken symlinks | MCP tools not available | Reinstall marketplace or manually recreate symlinks |
 | Wrong path edits | Changes don't take effect | Edit installed path or reinstall after source changes |
 | Missing credentials | MCP connection errors | Create `~/.config/claude/gitea.env` with API credentials |
 | Invalid hook events | Hooks don't fire | Use only valid event names (see Step 7) |
@@ -279,8 +287,8 @@ Error: Could not find a suitable TLS CA certificate bundle, invalid path:
 
 Use these commands for automated checking:
 
-- `/debug report` - Run full diagnostics, create issue if problems found
+- `/debug-report` - Run full diagnostics, create issue if problems found
-- `/debug review` - Investigate existing diagnostic issues and propose fixes
+- `/debug-review` - Investigate existing diagnostic issues and propose fixes
 
 ---
 

docs/UPDATING.md

@@ -132,8 +132,10 @@ When updating, review if changes affect the setup workflow:
 ### Dependencies fail to install
 
 ```bash
-# Install missing dependencies (do NOT delete .venv)
+# Rebuild virtual environment
 cd mcp-servers/gitea
+rm -rf .venv
+python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
 deactivate
@@ -162,7 +164,7 @@ If that doesn't work:
    ls ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/gitea/.venv
    ls ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/netbox/.venv
    ```
-3. If missing, run setup.sh as shown above.
+3. If missing, the symlinks won't resolve. Run setup.sh as shown above.
 4. Restart Claude Code session
 5. Check logs for specific errors
 

mcp-servers/contract-validator/mcp_server/server.py

@@ -131,24 +131,6 @@ class ContractValidatorMCPServer:
                         "required": ["agent_name", "claude_md_path"]
                     }
                 ),
-                Tool(
-                    name="validate_workflow_integration",
-                    description="Validate that a domain plugin exposes the required advisory interfaces (gate command, review command, advisory agent) expected by projman's domain-consultation skill",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "plugin_path": {
-                                "type": "string",
-                                "description": "Path to the domain plugin directory"
-                            },
-                            "domain_label": {
-                                "type": "string",
-                                "description": "The Domain/* label it claims to handle, e.g. Domain/Viz"
-                            }
-                        },
-                        "required": ["plugin_path", "domain_label"]
-                    }
-                ),
                 # Report tools (to be implemented in #188)
                 Tool(
                     name="generate_compatibility_report",
@@ -216,8 +198,6 @@ class ContractValidatorMCPServer:
                     result = await self._validate_agent_refs(**arguments)
                 elif name == "validate_data_flow":
                     result = await self._validate_data_flow(**arguments)
-                elif name == "validate_workflow_integration":
-                    result = await self._validate_workflow_integration(**arguments)
                 elif name == "generate_compatibility_report":
                     result = await self._generate_compatibility_report(**arguments)
                 elif name == "list_issues":
@@ -261,10 +241,6 @@ class ContractValidatorMCPServer:
         """Validate agent data flow"""
         return await self.validation_tools.validate_data_flow(agent_name, claude_md_path)
 
-    async def _validate_workflow_integration(self, plugin_path: str, domain_label: str) -> dict:
-        """Validate domain plugin exposes required advisory interfaces"""
-        return await self.validation_tools.validate_workflow_integration(plugin_path, domain_label)
-
     # Report tool implementations (Issue #188)
 
     async def _generate_compatibility_report(self, marketplace_path: str, format: str = "markdown") -> dict:

mcp-servers/contract-validator/mcp_server/validation_tools.py

@@ -26,7 +26,6 @@ class IssueType(str, Enum):
     OPTIONAL_DEPENDENCY = "optional_dependency"
     UNDECLARED_OUTPUT = "undeclared_output"
     INVALID_SEQUENCE = "invalid_sequence"
-    MISSING_INTEGRATION = "missing_integration"
 
 
 class ValidationIssue(BaseModel):
@@ -66,17 +65,6 @@ class DataFlowResult(BaseModel):
     issues: list[ValidationIssue] = []
 
 
-class WorkflowIntegrationResult(BaseModel):
-    """Result of workflow integration validation for domain plugins"""
-    plugin_name: str
-    domain_label: str
-    valid: bool
-    gate_command_found: bool
-    review_command_found: bool
-    advisory_agent_found: bool
-    issues: list[ValidationIssue] = []
-
-
 class ValidationTools:
     """Tools for validating plugin compatibility and agent references"""
 
@@ -348,107 +336,3 @@ class ValidationTools:
         )
 
         return result.model_dump()
-
-    async def validate_workflow_integration(self, plugin_path: str, domain_label: str) -> dict:
-        """
-        Validate that a domain plugin exposes required advisory interfaces.
-
-        Checks for:
-        - Gate command (e.g., /design-gate, /data-gate) - REQUIRED
-        - Review command (e.g., /design-review, /data-review) - recommended
-        - Advisory agent referencing the domain label - recommended
-
-        Args:
-            plugin_path: Path to the domain plugin directory
-            domain_label: The Domain/* label it claims to handle (e.g., Domain/Viz)
-
-        Returns:
-            Validation result with found interfaces and issues
-        """
-        plugin_path_obj = Path(plugin_path)
-        issues = []
-
-        # Extract plugin name from path
-        plugin_name = plugin_path_obj.name
-        if not plugin_path_obj.exists():
-            return {
-                "error": f"Plugin directory not found: {plugin_path}",
-                "plugin_path": plugin_path,
-                "domain_label": domain_label
-            }
-
-        # Extract domain short name from label (e.g., "Domain/Viz" -> "viz", "Domain/Data" -> "data")
-        domain_short = domain_label.split("/")[-1].lower() if "/" in domain_label else domain_label.lower()
-
-        # Check for gate command
-        commands_dir = plugin_path_obj / "commands"
-        gate_command_found = False
-        gate_patterns = ["pass", "fail", "PASS", "FAIL", "Binary pass/fail", "gate"]
-
-        if commands_dir.exists():
-            for cmd_file in commands_dir.glob("*.md"):
-                if "gate" in cmd_file.name.lower():
-                    # Verify it's actually a gate command by checking content
-                    content = cmd_file.read_text()
-                    if any(pattern in content for pattern in gate_patterns):
-                        gate_command_found = True
-                        break
-
-        if not gate_command_found:
-            issues.append(ValidationIssue(
-                severity=IssueSeverity.ERROR,
-                issue_type=IssueType.MISSING_INTEGRATION,
-                message=f"Plugin '{plugin_name}' lacks a gate command for domain '{domain_label}'",
-                location=str(commands_dir),
-                suggestion=f"Create commands/{domain_short}-gate.md with binary PASS/FAIL output"
-            ))
-
-        # Check for review command
-        review_command_found = False
-        if commands_dir.exists():
-            for cmd_file in commands_dir.glob("*.md"):
-                if "review" in cmd_file.name.lower() and "gate" not in cmd_file.name.lower():
-                    review_command_found = True
-                    break
-
-        if not review_command_found:
-            issues.append(ValidationIssue(
-                severity=IssueSeverity.WARNING,
-                issue_type=IssueType.MISSING_INTEGRATION,
-                message=f"Plugin '{plugin_name}' lacks a review command for domain '{domain_label}'",
-                location=str(commands_dir),
-                suggestion=f"Create commands/{domain_short}-review.md for detailed audits"
-            ))
-
-        # Check for advisory agent
-        agents_dir = plugin_path_obj / "agents"
-        advisory_agent_found = False
-
-        if agents_dir.exists():
-            for agent_file in agents_dir.glob("*.md"):
-                content = agent_file.read_text()
-                # Check if agent references the domain label or gate command
-                if domain_label in content or f"{domain_short}-gate" in content.lower() or "advisor" in agent_file.name.lower() or "reviewer" in agent_file.name.lower():
-                    advisory_agent_found = True
-                    break
-
-        if not advisory_agent_found:
-            issues.append(ValidationIssue(
-                severity=IssueSeverity.WARNING,
-                issue_type=IssueType.MISSING_INTEGRATION,
-                message=f"Plugin '{plugin_name}' lacks an advisory agent for domain '{domain_label}'",
-                location=str(agents_dir) if agents_dir.exists() else str(plugin_path_obj),
-                suggestion=f"Create agents/{domain_short}-advisor.md referencing '{domain_label}'"
-            ))
-
-        result = WorkflowIntegrationResult(
-            plugin_name=plugin_name,
-            domain_label=domain_label,
-            valid=gate_command_found,  # Only gate is required for validity
-            gate_command_found=gate_command_found,
-            review_command_found=review_command_found,
-            advisory_agent_found=advisory_agent_found,
-            issues=issues
-        )
-
-        return result.model_dump()

mcp-servers/contract-validator/tests/test_validation_tools.py

@@ -254,153 +254,3 @@ async def test_validate_data_flow_missing_producer(validation_tools, tmp_path):
     # Should have warning about missing producer
     warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
     assert len(warning_issues) > 0
-
-
-# --- Workflow Integration Tests ---
-
-@pytest.fixture
-def domain_plugin_complete(tmp_path):
-    """Create a complete domain plugin with gate, review, and advisory agent"""
-    plugin_dir = tmp_path / "viz-platform"
-    plugin_dir.mkdir()
-    (plugin_dir / ".claude-plugin").mkdir()
-    (plugin_dir / "commands").mkdir()
-    (plugin_dir / "agents").mkdir()
-
-    # Gate command with PASS/FAIL pattern
-    gate_cmd = plugin_dir / "commands" / "design-gate.md"
-    gate_cmd.write_text("""# /design-gate
-
-Binary pass/fail validation gate for design system compliance.
-
-## Output
-
-- **PASS**: All design system checks passed
-- **FAIL**: Design system violations detected
-""")
-
-    # Review command
-    review_cmd = plugin_dir / "commands" / "design-review.md"
-    review_cmd.write_text("""# /design-review
-
-Comprehensive design system audit.
-""")
-
-    # Advisory agent
-    agent = plugin_dir / "agents" / "design-reviewer.md"
-    agent.write_text("""# design-reviewer
-
-Design system compliance auditor.
-
-Handles issues with `Domain/Viz` label.
-""")
-
-    return str(plugin_dir)
-
-
-@pytest.fixture
-def domain_plugin_missing_gate(tmp_path):
-    """Create domain plugin with review and agent but no gate command"""
-    plugin_dir = tmp_path / "data-platform"
-    plugin_dir.mkdir()
-    (plugin_dir / ".claude-plugin").mkdir()
-    (plugin_dir / "commands").mkdir()
-    (plugin_dir / "agents").mkdir()
-
-    # Review command (but no gate)
-    review_cmd = plugin_dir / "commands" / "data-review.md"
-    review_cmd.write_text("""# /data-review
-
-Data integrity audit.
-""")
-
-    # Advisory agent
-    agent = plugin_dir / "agents" / "data-advisor.md"
-    agent.write_text("""# data-advisor
-
-Data integrity advisor for Domain/Data issues.
-""")
-
-    return str(plugin_dir)
-
-
-@pytest.fixture
-def domain_plugin_minimal(tmp_path):
-    """Create minimal plugin with no commands or agents"""
-    plugin_dir = tmp_path / "minimal-plugin"
-    plugin_dir.mkdir()
-    (plugin_dir / ".claude-plugin").mkdir()
-
-    readme = plugin_dir / "README.md"
-    readme.write_text("# Minimal Plugin\n\nNo commands or agents.")
-
-    return str(plugin_dir)
-
-
-@pytest.mark.asyncio
-async def test_validate_workflow_integration_complete(validation_tools, domain_plugin_complete):
-    """Test complete domain plugin returns valid with all interfaces found"""
-    result = await validation_tools.validate_workflow_integration(
-        domain_plugin_complete,
-        "Domain/Viz"
-    )
-
-    assert "error" not in result
-    assert result["valid"] is True
-    assert result["gate_command_found"] is True
-    assert result["review_command_found"] is True
-    assert result["advisory_agent_found"] is True
-    assert len(result["issues"]) == 0
-
-
-@pytest.mark.asyncio
-async def test_validate_workflow_integration_missing_gate(validation_tools, domain_plugin_missing_gate):
-    """Test plugin missing gate command returns invalid with ERROR"""
-    result = await validation_tools.validate_workflow_integration(
-        domain_plugin_missing_gate,
-        "Domain/Data"
-    )
-
-    assert "error" not in result
-    assert result["valid"] is False
-    assert result["gate_command_found"] is False
-    assert result["review_command_found"] is True
-    assert result["advisory_agent_found"] is True
-
-    # Should have one ERROR for missing gate
-    error_issues = [i for i in result["issues"] if i["severity"].value == "error"]
-    assert len(error_issues) == 1
-    assert "gate" in error_issues[0]["message"].lower()
-
-
-@pytest.mark.asyncio
-async def test_validate_workflow_integration_minimal(validation_tools, domain_plugin_minimal):
-    """Test minimal plugin returns invalid with multiple issues"""
-    result = await validation_tools.validate_workflow_integration(
-        domain_plugin_minimal,
-        "Domain/Test"
-    )
-
-    assert "error" not in result
-    assert result["valid"] is False
-    assert result["gate_command_found"] is False
-    assert result["review_command_found"] is False
-    assert result["advisory_agent_found"] is False
-
-    # Should have one ERROR (gate) and two WARNINGs (review, agent)
-    error_issues = [i for i in result["issues"] if i["severity"].value == "error"]
-    warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
-    assert len(error_issues) == 1
-    assert len(warning_issues) == 2
-
-
-@pytest.mark.asyncio
-async def test_validate_workflow_integration_nonexistent_plugin(validation_tools, tmp_path):
-    """Test error when plugin directory doesn't exist"""
-    result = await validation_tools.validate_workflow_integration(
-        str(tmp_path / "nonexistent"),
-        "Domain/Test"
-    )
-
-    assert "error" in result
-    assert "not found" in result["error"].lower()

mcp-servers/gitea/mcp_server/server.py

@@ -144,7 +144,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "issue_number": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Issue number"
                             },
                             "repo": {
@@ -189,7 +189,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "issue_number": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Issue number"
                             },
                             "title": {
@@ -211,7 +211,7 @@ class GiteaMCPServer:
                                 "description": "New labels"
                             },
                             "milestone": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Milestone ID to assign"
                             },
                             "repo": {
@@ -229,7 +229,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "issue_number": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Issue number"
                             },
                             "comment": {
@@ -424,7 +424,7 @@ class GiteaMCPServer:
                                 "description": "Tags to filter by (optional)"
                             },
                             "limit": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "default": 20,
                                 "description": "Maximum results"
                             },
@@ -435,19 +435,6 @@ class GiteaMCPServer:
                         }
                     }
                 ),
-                Tool(
-                    name="allocate_rfc_number",
-                    description="Allocate the next available RFC number by scanning existing RFC wiki pages",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        }
-                    }
-                ),
                 # Milestone Tools
                 Tool(
                     name="list_milestones",
@@ -475,7 +462,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "milestone_id": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Milestone ID"
                             },
                             "repo": {
@@ -519,7 +506,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "milestone_id": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Milestone ID"
                             },
                             "title": {
@@ -554,7 +541,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "milestone_id": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Milestone ID"
                             },
                             "repo": {
@@ -573,7 +560,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "issue_number": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Issue number"
                             },
                             "repo": {
@@ -591,11 +578,11 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "issue_number": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Issue that will depend on another"
                             },
                             "depends_on": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Issue that blocks issue_number"
                             },
                             "repo": {
@@ -613,11 +600,11 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "issue_number": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Issue that depends on another"
                             },
                             "depends_on": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Issue being depended on"
                             },
                             "repo": {
@@ -795,7 +782,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "pr_number": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Pull request number"
                             },
                             "repo": {
@@ -813,7 +800,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "pr_number": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Pull request number"
                             },
                             "repo": {
@@ -831,7 +818,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "pr_number": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Pull request number"
                             },
                             "repo": {
@@ -849,7 +836,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "pr_number": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Pull request number"
                             },
                             "body": {
@@ -868,7 +855,7 @@ class GiteaMCPServer:
                                     "type": "object",
                                     "properties": {
                                         "path": {"type": "string"},
-                                        "position": {"type": ["integer", "string"]},
+                                        "position": {"type": "integer"},
                                         "body": {"type": "string"}
                                     }
                                 },
@@ -889,7 +876,7 @@ class GiteaMCPServer:
                         "type": "object",
                         "properties": {
                             "pr_number": {
-                                "type": ["integer", "string"],
+                                "type": "integer",
                                 "description": "Pull request number"
                             },
                             "body": {
@@ -993,10 +980,6 @@ class GiteaMCPServer:
                         limit=arguments.get('limit', 20),
                         repo=arguments.get('repo')
                     )
-                elif name == "allocate_rfc_number":
-                    result = await self.wiki_tools.allocate_rfc_number(
-                        repo=arguments.get('repo')
-                    )
                 # Milestone tools
                 elif name == "list_milestones":
                     result = await self.milestone_tools.list_milestones(**arguments)

mcp-servers/gitea/mcp_server/tools/wiki.py

@@ -4,11 +4,9 @@ Wiki management tools for MCP server.
 Provides async wrappers for wiki operations to support lessons learned:
 - Page CRUD operations
 - Lessons learned creation and search
-- RFC number allocation
 """
 import asyncio
 import logging
-import re
 from typing import List, Dict, Optional
 
 logging.basicConfig(level=logging.INFO)
@@ -149,39 +147,3 @@ class WikiTools:
             lambda: self.gitea.search_lessons(query, tags, repo)
         )
         return results[:limit]
-
-    async def allocate_rfc_number(self, repo: Optional[str] = None) -> Dict:
-        """
-        Allocate the next available RFC number.
-
-        Scans existing wiki pages for RFC-NNNN pattern and returns
-        the next sequential number.
-
-        Args:
-            repo: Repository in owner/repo format
-
-        Returns:
-            Dict with 'next_number' (int) and 'formatted' (str like 'RFC-0001')
-        """
-        pages = await self.list_wiki_pages(repo)
-
-        # Extract RFC numbers from page titles
-        rfc_numbers = []
-        rfc_pattern = re.compile(r'^RFC-(\d{4})')
-
-        for page in pages:
-            title = page.get('title', '')
-            match = rfc_pattern.match(title)
-            if match:
-                rfc_numbers.append(int(match.group(1)))
-
-        # Calculate next number
-        if rfc_numbers:
-            next_num = max(rfc_numbers) + 1
-        else:
-            next_num = 1
-
-        return {
-            'next_number': next_num,
-            'formatted': f'RFC-{next_num:04d}'
-        }

mcp-servers/viz-platform/README.md

@@ -112,4 +112,4 @@ pytest tests/ -v
 
 ## Usage
 
-This MCP server is used by the `viz-platform` plugin. See the plugin's commands in `plugins/viz-platform/commands/` for usage.
+This MCP server is used by the `viz-platform` plugin. See [plugins/viz-platform/README.md](../../plugins/viz-platform/README.md) for usage instructions.

plugins/clarity-assist/README.md

@@ -0,0 +1,103 @@
+# clarity-assist
+
+Prompt optimization and requirement clarification plugin with neurodivergent-friendly accommodations.
+
+## Overview
+
+clarity-assist helps transform vague, incomplete, or ambiguous requests into clear, actionable specifications. It uses a structured 4-D methodology (Deconstruct, Diagnose, Develop, Deliver) and ND-friendly communication patterns.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/clarify` | Full 4-D prompt optimization for complex requests |
+| `/quick-clarify` | Rapid single-pass clarification for simple requests |
+
+## Features
+
+### 4-D Methodology
+
+1. **Deconstruct** - Break down the request into components
+2. **Diagnose** - Analyze gaps and potential issues
+3. **Develop** - Gather clarifications through structured questions
+4. **Deliver** - Produce refined specification
+
+### ND-Friendly Design
+
+- **Option-based questioning** - Always provide 2-4 concrete choices
+- **Chunked questions** - Ask 1-2 questions at a time
+- **Context for questions** - Explain why you're asking
+- **Conflict detection** - Check previous answers before new questions
+- **Progress acknowledgment** - Summarize frequently
+
+### Escalation Protocol
+
+When requests are complex or users seem overwhelmed:
+- Acknowledge complexity
+- Offer to focus on one aspect at a time
+- Build incrementally
+
+## Installation
+
+Add to your project's `.claude/settings.json`:
+
+```json
+{
+  "plugins": ["clarity-assist"]
+}
+```
+
+## Usage
+
+### Full Clarification
+
+```
+/clarify
+
+[Your vague or complex request here]
+```
+
+### Quick Clarification
+
+```
+/quick-clarify
+
+[Your mostly-clear request here]
+```
+
+## Configuration
+
+No configuration required. The plugin uses sensible defaults.
+
+## Output Format
+
+After clarification, you receive a structured specification:
+
+```markdown
+## Clarified Request
+
+### Summary
+[Description of what will be built]
+
+### Scope
+**In Scope:** [items]
+**Out of Scope:** [items]
+
+### Requirements
+[Prioritized table]
+
+### Assumptions
+[List of assumptions]
+```
+
+## Documentation
+
+- [Neurodivergent Support Guide](docs/ND-SUPPORT.md) - How clarity-assist supports ND users with executive function challenges and cognitive differences
+
+## Integration
+
+For CLAUDE.md integration instructions, see `claude-md-integration.md`.
+
+## License
+
+MIT

plugins/clarity-assist/commands/clarify.md

@@ -2,12 +2,16 @@
 
 ## Visual Output
 
+When executing this command, display the plugin header:
+
 ```
-+----------------------------------------------------------------------+
+┌──────────────────────────────────────────────────────────────────┐
-|  CLARITY-ASSIST - Prompt Optimization                                |
+│  💬 CLARITY-ASSIST · Prompt Optimization                         │
-+----------------------------------------------------------------------+
+└──────────────────────────────────────────────────────────────────┘
 ```
 
+Then proceed with the workflow.
+
 ## Purpose
 
 Transform vague, incomplete, or ambiguous requests into clear, actionable specifications using the 4-D methodology with neurodivergent-friendly accommodations.
@@ -19,46 +23,127 @@ Transform vague, incomplete, or ambiguous requests into clear, actionable specif
 - Tasks requiring significant context gathering
 - When user seems uncertain about what they want
 
-## Skills to Load
+## 4-D Methodology
 
-Load these skills before proceeding:
+### Phase 1: Deconstruct
 
-- `skills/4d-methodology.md` - Core 4-phase process
+Break down the user's request into components:
-- `skills/nd-accommodations.md` - ND-friendly question patterns
-- `skills/clarification-techniques.md` - Anti-patterns and templates
-- `skills/escalation-patterns.md` - When to adjust approach
 
-## Workflow
+1. **Extract explicit requirements** - What was directly stated
+2. **Identify implicit assumptions** - What seems assumed but not stated
+3. **Note ambiguities** - Points that could go multiple ways
+4. **List dependencies** - External factors that might affect implementation
 
-1. **Deconstruct** - Break down request into components
+### Phase 2: Diagnose
-2. **Diagnose** - Identify gaps and conflicts
+
-3. **Develop** - Gather clarifications via structured questions
+Analyze gaps and potential issues:
-4. **Deliver** - Present refined specification
+
-5. **Offer RFC Creation** - For feature work, offer to save as RFC
+1. **Missing information** - What do we need to know?
+2. **Conflicting requirements** - Do any stated goals contradict?
+3. **Scope boundaries** - What's in/out of scope?
+4. **Technical constraints** - Platform, language, architecture limits
+
+### Phase 3: Develop
+
+Gather clarifications through structured questioning:
+
+**ND-Friendly Question Rules:**
+- Present 2-4 concrete options (never open-ended alone)
+- Include "Other" for custom responses
+- Ask 1-2 questions at a time maximum
+- Provide brief context for why you're asking
+- Check for conflicts with previous answers
+
+**Example Format:**
+```
+To help me understand the scope better:
+
+**How should errors be handled?**
+1. Silent logging (user sees nothing)
+2. Toast notifications (brief, dismissible)
+3. Modal dialogs (requires user action)
+4. Other
+
+[Context: This affects both UX and how much error-handling code we need]
+```
+
+### Phase 4: Deliver
+
+Produce the refined specification:
+
+```markdown
+## Clarified Request
+
+### Summary
+[1-2 sentence description of what will be built]
+
+### Scope
+**In Scope:**
+- [Item 1]
+- [Item 2]
+
+**Out of Scope:**
+- [Item 1]
+
+### Requirements
+
+| # | Requirement | Priority | Notes |
+|---|-------------|----------|-------|
+| 1 | ... | Must | ... |
+| 2 | ... | Should | ... |
+
+### Assumptions
+- [Assumption made based on conversation]
+
+### Open Questions
+- [Any remaining ambiguities, if any]
+```
+
+## Conflict Detection
+
+Before each question, review previous answers for conflicts:
+
+```
+[Internal check]
+Previous: User said "keep it simple"
+Current question about: Adding configuration options
+Potential conflict: More options = more complexity
+→ Acknowledge: "Earlier you mentioned keeping it simple. With that in mind..."
+```
+
+## Escalation Protocol
+
+If the request is particularly messy or the user seems overwhelmed:
+
+1. Acknowledge the complexity
+2. Offer to start with just ONE aspect
+3. Build incrementally
+
+```
+"This touches a lot of areas. Rather than tackle everything at once,
+let's start with [most critical piece]. Once that's clear, we can
+add the other parts. Sound good?"
+```
+
+## Example Interaction
+
+**User:** Make the app faster
+
+**Clarify Response:**
+
+```
+Let me help clarify what kind of performance improvements you're looking for.
+
+**What type of slowness are you experiencing?**
+1. Initial page load takes too long
+2. Interactions feel sluggish (clicking, typing)
+3. API calls are slow
+4. All of the above
+5. Other
+
+[I'm asking because each has very different solutions]
+```
 
 ## Output Format
 
-Use the Deliver phase template from `skills/4d-methodology.md` to present the clarified specification for user confirmation.
+After gathering all necessary information, use the Deliver phase format to present the clarified specification for user confirmation.
-
-## RFC Creation Offer (Step 5)
-
-After presenting the clarified specification, if the request appears to be a feature or enhancement:
-
-```
----
-
-Would you like to save this as an RFC for formal tracking?
-
-An RFC (Request for Comments) provides:
-- Structured documentation of the proposal
-- Review workflow before implementation
-- Integration with sprint planning
-
-[1] Yes, create RFC from this specification
-[2] No, proceed with implementation directly
-```
-
-If user selects [1]:
-- Pass clarified specification to `/rfc-create`
-- The Summary, Motivation, and Design sections will be populated from the clarified spec
-- User can then refine the RFC and submit for review

plugins/clarity-assist/commands/quick-clarify.md

@@ -2,12 +2,16 @@
 
 ## Visual Output
 
+When executing this command, display the plugin header:
+
 ```
-+----------------------------------------------------------------------+
+┌──────────────────────────────────────────────────────────────────┐
-|  CLARITY-ASSIST - Quick Clarify                                      |
+│  💬 CLARITY-ASSIST · Quick Clarify                               │
-+----------------------------------------------------------------------+
+└──────────────────────────────────────────────────────────────────┘
 ```
 
+Then proceed with the workflow.
+
 ## Purpose
 
 Single-pass clarification for requests that are mostly clear but need minor disambiguation.
@@ -19,27 +23,74 @@ Single-pass clarification for requests that are mostly clear but need minor disa
 - Follow-up to an already-clarified request
 - Simple feature additions or bug fixes
 
-## Skills to Load
+## Process
 
-- `skills/nd-accommodations.md` - ND-friendly question patterns
+### Step 1: Echo Understanding
-- `skills/clarification-techniques.md` - Echo and micro-summary techniques
-- `skills/escalation-patterns.md` - When to escalate to full /clarify
 
-## Workflow
+Restate what you understood in a single sentence:
 
-1. **Echo Understanding** - Restate in a single sentence
+```
-2. **Quick Disambiguation** - Ask ONE multiple-choice question if needed
+"I understand you want [X] that does [Y]."
-3. **Proceed or Confirm** - Start work or offer micro-summary
+```
+
+### Step 2: Quick Disambiguation
+
+If needed, ask ONE multiple-choice question:
+
+```
+**Just to confirm:** Should this [A] or [B]?
+1. [Option A with brief description]
+2. [Option B with brief description]
+3. Both
+4. Neither / Other approach
+```
+
+### Step 3: Proceed or Confirm
+
+If confident (>90%), proceed with a brief confirmation:
+
+```
+"Got it. I'll implement [X with chosen option]. Starting now."
+```
+
+If less confident, offer a micro-summary:
+
+```
+"Quick summary before I start:
+- [Key point 1]
+- [Key point 2]
+- [Assumption made]
+
+Proceed? (Or clarify anything)"
+```
+
+## Example Interaction
+
+**User:** Add a delete button to the user list
+
+**Quick-Clarify Response:**
+
+```
+I'll add a delete button to each row in the user list.
+
+**Should deletion require confirmation?**
+1. Yes - show confirmation dialog (Recommended)
+2. No - delete immediately
+3. Soft delete - mark as deleted but keep data
+
+[Asking because accidental deletions can be problematic]
+```
+
+## Escalation to Full /clarify
+
+If quick-clarify reveals complexity:
+
+```
+"This is more involved than it first appeared - there are
+several decisions to make. Want me to switch to a more
+thorough clarification process? (Just say 'yes' or 'clarify')"
+```
 
 ## Output Format
 
-No formal specification document needed. Proceed after brief confirmation, documenting assumptions inline with the work.
+For quick-clarify, no formal specification document is needed. Just proceed with the task after brief confirmation, documenting assumptions inline with the work.
-
-## Escalation
-
-If complexity emerges, offer to switch to full `/clarify`:
-
-```
-"This is more involved than it first appeared. Want me to switch
-to a more thorough clarification process?"
-```

plugins/clarity-assist/hooks/hooks.json

@@ -2,13 +2,8 @@
   "hooks": {
     "UserPromptSubmit": [
       {
-        "matcher": "",
+        "type": "command",
-        "hooks": [
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/vagueness-check.sh"
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/vagueness-check.sh"
-          }
-        ]
       }
     ]
   }

plugins/clarity-assist/hooks/vagueness-check.sh

@@ -197,38 +197,6 @@ if (( $(echo "$SCORE > 1.0" | bc -l) )); then
     SCORE="1.0"
 fi
 
-# ============================================================================
-# Feature Request Detection (for RFC suggestion)
-# ============================================================================
-
-FEATURE_REQUEST=false
-
-# Feature request phrases
-FEATURE_PHRASES=(
-    "we should"
-    "it would be nice"
-    "feature request"
-    "idea:"
-    "suggestion:"
-    "what if we"
-    "wouldn't it be great"
-    "i think we need"
-    "we need to add"
-    "we could add"
-    "how about adding"
-    "can we add"
-    "new feature"
-    "enhancement"
-    "proposal"
-)
-
-for phrase in "${FEATURE_PHRASES[@]}"; do
-    if [[ "$PROMPT_LOWER" == *"$phrase"* ]]; then
-        FEATURE_REQUEST=true
-        break
-    fi
-done
-
 # ============================================================================
 # Output suggestion if score exceeds threshold
 # ============================================================================
@@ -240,16 +208,8 @@ if (( $(echo "$SCORE >= $THRESHOLD" | bc -l) )); then
 
     # Gentle, non-blocking suggestion
     echo "$PREFIX Your prompt could benefit from more clarity."
-    echo "$PREFIX Consider running /clarify to refine your request."
+    echo "$PREFIX Consider running /clarity-assist to refine your request."
     echo "$PREFIX (Vagueness score: ${SCORE_PCT}% - this is a suggestion, not a block)"
-
-    # Additional RFC suggestion if feature request detected
-    if [[ "$FEATURE_REQUEST" == true ]]; then
-        echo "$PREFIX This looks like a feature idea. Consider /rfc-create to track it formally."
-    fi
-elif [[ "$FEATURE_REQUEST" == true ]]; then
-    # Feature request detected but not vague - still suggest RFC
-    echo "$PREFIX This looks like a feature idea. Consider /rfc-create to track it formally."
 fi
 
 # Always exit 0 - this hook is non-blocking

plugins/clarity-assist/skills/4d-methodology.md

@@ -1,76 +0,0 @@
-# 4-D Methodology for Prompt Clarification
-
-The 4-D methodology transforms vague requests into actionable specifications.
-
-## Phase 1: Deconstruct
-
-Break down the user's request into components:
-
-1. **Extract explicit requirements** - What was directly stated
-2. **Identify implicit assumptions** - What seems assumed but not stated
-3. **Note ambiguities** - Points that could go multiple ways
-4. **List dependencies** - External factors that might affect implementation
-
-## Phase 2: Diagnose
-
-Analyze gaps and potential issues:
-
-1. **Missing information** - What do we need to know?
-2. **Conflicting requirements** - Do any stated goals contradict?
-3. **Scope boundaries** - What is in/out of scope?
-4. **Technical constraints** - Platform, language, architecture limits
-
-## Phase 3: Develop
-
-Gather clarifications through structured questioning:
-
-- Present 2-4 concrete options (never open-ended alone)
-- Include "Other" for custom responses
-- Ask 1-2 questions at a time maximum
-- Provide brief context for why you are asking
-- Check for conflicts with previous answers
-
-**Example Format:**
-```
-To help me understand the scope better:
-
-**How should errors be handled?**
-1. Silent logging (user sees nothing)
-2. Toast notifications (brief, dismissible)
-3. Modal dialogs (requires user action)
-4. Other
-
-[Context: This affects both UX and how much error-handling code we need]
-```
-
-## Phase 4: Deliver
-
-Produce the refined specification:
-
-```markdown
-## Clarified Request
-
-### Summary
-[1-2 sentence description of what will be built]
-
-### Scope
-**In Scope:**
-- [Item 1]
-- [Item 2]
-
-**Out of Scope:**
-- [Item 1]
-
-### Requirements
-
-| # | Requirement | Priority | Notes |
-|---|-------------|----------|-------|
-| 1 | ... | Must | ... |
-| 2 | ... | Should | ... |
-
-### Assumptions
-- [Assumption made based on conversation]
-
-### Open Questions
-- [Any remaining ambiguities, if any]
-```

plugins/clarity-assist/skills/clarification-techniques.md

@@ -1,86 +0,0 @@
-# Clarification Techniques
-
-Structured approaches for disambiguating user requests.
-
-## Anti-Patterns to Detect
-
-### Vague Requests
-**Triggers:** "improve", "fix", "update", "change", "better", "faster", "cleaner"
-
-**Response:** Ask for specific metrics or outcomes
-
-### Scope Creep Signals
-**Triggers:** "while you're at it", "also", "might as well", "and another thing"
-
-**Response:** Acknowledge, then isolate: "I'll note that for after the main task"
-
-### Assumption Gaps
-**Triggers:** References to "the" thing (which thing?), "it" (what?), "there" (where?)
-
-**Response:** Echo back specific understanding
-
-### Conflicting Requirements
-**Triggers:** "Simple but comprehensive", "Fast but thorough", "Minimal but complete"
-
-**Response:** Prioritize: "Which matters more: simplicity or completeness?"
-
-## Question Templates
-
-### For Unclear Purpose
-```
-**What problem does this solve?**
-1. [Specific problem A]
-2. [Specific problem B]
-3. Combination
-4. Different problem: ____
-```
-
-### For Missing Scope
-```
-**What should this include?**
-- [ ] Feature A
-- [ ] Feature B
-- [ ] Feature C
-- [ ] Other: ____
-```
-
-### For Ambiguous Behavior
-```
-**When [trigger event], what should happen?**
-1. [Behavior option A]
-2. [Behavior option B]
-3. Nothing (ignore)
-4. Depends on: ____
-```
-
-### For Technical Decisions
-```
-**Implementation approach:**
-1. [Approach A] - pros: X, cons: Y
-2. [Approach B] - pros: X, cons: Y
-3. Let me decide based on codebase
-4. Need more info about: ____
-```
-
-## Echo Understanding Technique
-
-Before diving into questions, restate understanding:
-
-```
-"I understand you want [X] that does [Y]."
-```
-
-This validates comprehension and gives user a chance to correct early.
-
-## Micro-Summary Technique
-
-For quick confirmations before proceeding:
-
-```
-"Quick summary before I start:
-- [Key point 1]
-- [Key point 2]
-- [Assumption made]
-
-Proceed? (Or clarify anything)"
-```

plugins/clarity-assist/skills/escalation-patterns.md

@@ -1,57 +0,0 @@
-# Escalation Patterns
-
-Guidelines for when to escalate between clarification modes.
-
-## Quick-Clarify to Full Clarify
-
-Escalate when quick-clarify reveals unexpected complexity:
-
-```
-"This is more involved than it first appeared - there are
-several decisions to make. Want me to switch to a more
-thorough clarification process? (Just say 'yes' or 'clarify')"
-```
-
-### Triggers for Escalation
-
-- Multiple ambiguities discovered during quick pass
-- User's answer reveals hidden dependencies
-- Scope expands beyond original understanding
-- Technical constraints emerge that need discussion
-- Conflicting requirements surface
-
-## Full Clarify to Incremental
-
-When user is overwhelmed by full 4-D process:
-
-```
-"This touches a lot of areas. Rather than tackle everything at once,
-let's start with [most critical piece]. Once that's clear, we can
-add the other parts. Sound good?"
-```
-
-### Signs of Overwhelm
-
-- Long pauses or hesitation
-- "I don't know" responses
-- Requesting breaks
-- Contradicting earlier answers
-- Expressing frustration
-
-## Choosing Initial Mode
-
-### Use /quick-clarify When
-
-- Request is fairly clear, just one or two ambiguities
-- User is in a hurry
-- Follow-up to an already-clarified request
-- Simple feature additions or bug fixes
-- Confidence is high (>90%)
-
-### Use /clarify When
-
-- Complex multi-step requests
-- Requirements with multiple possible interpretations
-- Tasks requiring significant context gathering
-- User seems uncertain about what they want
-- First time working on this feature/area

plugins/clarity-assist/skills/nd-accommodations.md

@@ -1,74 +0,0 @@
-# Neurodivergent-Friendly Accommodations
-
-Guidelines for making clarification interactions accessible and comfortable for neurodivergent users.
-
-## Core Principles
-
-### Reduce Cognitive Load
-- Maximum 4 options per question
-- Always include "Other" escape hatch
-- Provide examples, not just descriptions
-- Use numbered lists for easy reference
-
-### Support Working Memory
-- Summarize frequently
-- Reference earlier decisions explicitly
-- Do not assume user remembers context from many turns ago
-- Echo back understanding before proceeding
-
-### Allow Processing Time
-- Do not rapid-fire questions
-- Validate answers before moving on
-- Offer to revisit or change earlier answers
-- One question block at a time
-
-### Manage Overwhelm
-- Offer to break into smaller sessions
-- Prioritize must-haves vs nice-to-haves
-- Provide "good enough for now" options
-- Acknowledge complexity openly
-
-## Question Formatting Rules
-
-**Always do:**
-```
-**How should errors be handled?**
-1. Silent logging (user sees nothing)
-2. Toast notifications (brief, dismissible)
-3. Modal dialogs (requires user action)
-4. Other
-
-[Context: This affects both UX and error-handling complexity]
-```
-
-**Never do:**
-```
-How do you want to handle errors? There are many approaches...
-```
-
-## Conflict Acknowledgment
-
-Before asking about something that might conflict with a previous answer:
-
-```
-[Internal check]
-Previous: User said "keep it simple"
-Current question about: Adding configuration options
-Potential conflict: More options = more complexity
-```
-
-Then acknowledge: "Earlier you mentioned keeping it simple. With that in mind..."
-
-## Escalation for Overwhelm
-
-If the request is particularly complex or user seems overwhelmed:
-
-1. Acknowledge the complexity openly
-2. Offer to start with just ONE aspect
-3. Build incrementally
-
-```
-"This touches a lot of areas. Rather than tackle everything at once,
-let's start with [most critical piece]. Once that's clear, we can
-add the other parts. Sound good?"
-```

plugins/claude-config-maintainer/README.md

@@ -0,0 +1,126 @@
+# Claude Config Maintainer
+
+A Claude Code plugin for creating and maintaining optimized CLAUDE.md configuration files.
+
+## Overview
+
+CLAUDE.md files provide instructions to Claude Code when working with a project. This plugin helps you:
+
+- **Analyze** existing CLAUDE.md files for improvement opportunities
+- **Optimize** structure, clarity, and conciseness
+- **Initialize** new CLAUDE.md files with project-specific content
+
+## Installation
+
+This plugin is part of the Leo Claude Marketplace. Install the marketplace and the plugin will be available.
+
+## Commands
+
+### `/config-analyze`
+Analyze your CLAUDE.md and get a detailed report with scores and recommendations.
+
+```
+/config-analyze
+```
+
+### `/config-optimize`
+Automatically optimize your CLAUDE.md based on best practices.
+
+```
+/config-optimize
+```
+
+### `/config-init`
+Create a new CLAUDE.md tailored to your project.
+
+```
+/config-init
+```
+
+### `/config-diff`
+Show differences between current CLAUDE.md and previous versions.
+
+```
+/config-diff                    # Compare working copy vs last commit
+/config-diff --commit=abc1234   # Compare against specific commit
+/config-diff --from=v1.0 --to=v2.0  # Compare two commits
+/config-diff --section="Critical Rules"  # Focus on specific section
+```
+
+### `/config-lint`
+Lint CLAUDE.md for common anti-patterns and best practices.
+
+```
+/config-lint                    # Run all lint checks
+/config-lint --fix              # Auto-fix fixable issues
+/config-lint --rules=security   # Check only security rules
+/config-lint --severity=error   # Show only errors
+```
+
+**Lint Rule Categories:**
+- **Security (SEC)** - Hardcoded secrets, paths, credentials
+- **Structure (STR)** - Header hierarchy, required sections
+- **Content (CNT)** - Contradictions, duplicates, vague rules
+- **Format (FMT)** - Consistency, code blocks, whitespace
+- **Best Practice (BPR)** - Missing Quick Start, Critical Rules sections
+
+## Best Practices
+
+A good CLAUDE.md should be:
+
+- **Clear** - Easy to understand at a glance
+- **Concise** - No unnecessary content
+- **Complete** - All essential information included
+- **Current** - Up to date with the project
+
+### Recommended Structure
+
+```markdown
+# CLAUDE.md
+
+## Project Overview
+What does this project do?
+
+## Quick Start
+Essential build/test/run commands.
+
+## Critical Rules
+What must Claude NEVER do?
+
+## Architecture (optional)
+Key technical decisions.
+
+## Common Operations (optional)
+Frequent tasks and workflows.
+```
+
+### Length Guidelines
+
+| Project Size | Recommended Lines |
+|-------------|------------------|
+| Small | 50-100 |
+| Medium | 100-200 |
+| Large | 200-400 |
+
+## Scoring System
+
+The analyzer scores CLAUDE.md files on:
+
+- **Structure** (25 pts) - Organization and navigation
+- **Clarity** (25 pts) - Clear, unambiguous instructions
+- **Completeness** (25 pts) - Essential sections present
+- **Conciseness** (25 pts) - Efficient information density
+
+Target score: **70+** for effective Claude Code usage.
+
+## Tips
+
+1. Run `/config-analyze` periodically to maintain quality
+2. Update CLAUDE.md when adding major features
+3. Keep critical rules prominent and clear
+4. Include examples where they add clarity
+5. Remove generic advice that applies to all projects
+
+## Contributing
+
+This plugin is part of the personal-projects/leo-claude-mktplace repository.

plugins/claude-config-maintainer/agents/maintainer.md

@@ -277,39 +277,6 @@ Every CLAUDE.md should have:
 1. **Project Overview** - What is this?
 2. **Quick Start** - How do I build/test/run?
 3. **Important Rules** - What must I NOT do?
-4. **Pre-Change Protocol** - Mandatory dependency check before code changes
-
-### Pre-Change Protocol Section (MANDATORY)
-
-**This section is REQUIRED in every CLAUDE.md.** It ensures Claude performs comprehensive dependency analysis before making any code changes.
-
-```markdown
-## ⛔ MANDATORY: Before Any Code Change
-
-**Claude MUST show this checklist BEFORE editing any file:**
-
-### 1. Impact Search Results
-Run and show output of:
-```bash
-grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
-```
-
-### 2. Files That Will Be Affected
-Numbered list of every file to be modified, with the specific change for each.
-
-### 3. Files Searched But Not Changed (and why)
-Proof that related files were checked and determined unchanged.
-
-### 4. Documentation That References This
-List of docs that mention this feature/script/function.
-
-**User verifies this list before Claude proceeds. If Claude skips this, stop immediately.**
-
-### After Changes
-Run the same grep and show results proving no references remain unaddressed.
-```
-
-**When analyzing a CLAUDE.md, flag as HIGH priority issue if this section is missing.**
 
 ### Optional Sections (as needed)
 

plugins/claude-config-maintainer/commands/analyze.md

@@ -4,18 +4,29 @@ description: Analyze CLAUDE.md for optimization opportunities and plugin integra
 
 # Analyze CLAUDE.md
 
-Analyze your CLAUDE.md and provide a scored report with recommendations.
+This command analyzes your project's CLAUDE.md file and provides a detailed report on optimization opportunities and plugin integration status.
-
-## Skills to Load
-
-- skills/visual-header.md
-- skills/analysis-workflow.md
-- skills/optimization-patterns.md
-- skills/pre-change-protocol.md
 
 ## Visual Output
 
-Display: `CONFIG-MAINTAINER - CLAUDE.md Analysis`
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ⚙️ CONFIG-MAINTAINER · CLAUDE.md Analysis                       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the analysis.
+
+## What This Command Does
+
+1. **Read CLAUDE.md** - Locates and reads the project's CLAUDE.md file
+2. **Analyze Structure** - Evaluates organization, headers, and flow
+3. **Check Content** - Reviews clarity, completeness, and conciseness
+4. **Identify Issues** - Finds redundancy, verbosity, and missing sections
+5. **Detect Active Plugins** - Identifies marketplace plugins enabled in the project
+6. **Check Plugin Integration** - Verifies CLAUDE.md references active plugins
+7. **Generate Report** - Provides scored assessment with recommendations
 
 ## Usage
 
@@ -23,27 +34,165 @@ Display: `CONFIG-MAINTAINER - CLAUDE.md Analysis`
 /config-analyze
 ```
 
-## Workflow
+Or invoke the maintainer agent directly:
 
-1. Locate and parse CLAUDE.md
+```
-2. Evaluate structure, clarity, completeness, conciseness
+Analyze the CLAUDE.md file in this project
-3. Find redundancy, verbosity, missing sections
+```
-4. Detect active marketplace plugins
-5. Verify plugin integration in CLAUDE.md
-6. Generate scored report with recommendations
 
-## Scoring (100 points)
+## Analysis Criteria
 
-| Category | Points |
+### Structure (25 points)
-|----------|--------|
+- Logical section ordering
-| Structure | 25 |
+- Clear header hierarchy
-| Clarity | 25 |
+- Easy navigation
-| Completeness | 25 |
+- Appropriate grouping
-| Conciseness | 25 |
+
+### Clarity (25 points)
+- Clear instructions
+- Good examples
+- Unambiguous language
+- Appropriate detail level
+
+### Completeness (25 points)
+- Project overview present
+- Quick start commands documented
+- Critical rules highlighted
+- Key workflows covered
+
+### Conciseness (25 points)
+- No unnecessary repetition
+- Efficient information density
+- Appropriate length for project size
+- No generic filler content
+
+## Plugin Integration Analysis
+
+After the content analysis, the command detects and analyzes marketplace plugin integration:
+
+### Detection Method
+
+1. **Read `.claude/settings.local.json`** - Check for enabled MCP servers
+2. **Map MCP servers to plugins** - Use marketplace registry to identify active plugins:
+   - `gitea` → projman
+   - `netbox` → cmdb-assistant
+3. **Check for hooks** - Identify hook-based plugins (project-hygiene)
+4. **Scan CLAUDE.md** - Look for plugin integration content
+
+### Plugin Coverage Scoring
+
+For each detected plugin, verify CLAUDE.md contains:
+- Plugin section header or mention
+- Available commands documentation
+- MCP tools reference (if applicable)
+- Usage guidelines
+
+Coverage is reported as percentage: `(plugins referenced / plugins detected) * 100`
+
+## Expected Output
+
+```
+CLAUDE.md Analysis Report
+=========================
+
+File: /path/to/project/CLAUDE.md
+Lines: 245
+Last Modified: 2025-01-18
+
+Overall Score: 72/100
+
+Category Scores:
+- Structure:    20/25 (Good)
+- Clarity:      18/25 (Good)
+- Completeness: 22/25 (Excellent)
+- Conciseness:  12/25 (Needs Work)
+
+Strengths:
++ Clear project overview with good context
++ Critical rules prominently displayed
++ Comprehensive coverage of workflows
+
+Issues Found:
+
+1. [HIGH] Verbose explanations (lines 45-78)
+   Section "Running Tests" has 34 lines that could be 8 lines.
+   Impact: Harder to scan, important info buried
+
+2. [MEDIUM] Duplicate content (lines 102-115, 189-200)
+   Same git workflow documented twice.
+   Impact: Maintenance burden, inconsistency risk
+
+3. [MEDIUM] Missing Quick Start section
+   No clear "how to get started" instructions.
+   Impact: Slower onboarding for Claude
+
+4. [LOW] Inconsistent header formatting
+   Mix of "## Title" and "## Title:" styles.
+   Impact: Minor readability issue
+
+Recommendations:
+1. Add Quick Start section at top (priority: high)
+2. Condense Testing section to essentials (priority: high)
+3. Remove duplicate git workflow (priority: medium)
+4. Standardize header formatting (priority: low)
+
+Estimated improvement: 15-20 points after changes
+
+---
+
+Plugin Integration Analysis
+===========================
+
+Detected Active Plugins:
+  ✓ projman (via gitea MCP server)
+  ✓ cmdb-assistant (via netbox MCP server)
+  ✓ project-hygiene (via PostToolUse hook)
+
+Plugin Coverage: 33% (1/3 plugins referenced)
+
+  ✓ projman - Referenced in CLAUDE.md
+  ✗ cmdb-assistant - NOT referenced
+  ✗ project-hygiene - NOT referenced
+
+Missing Integration Content:
+
+1. cmdb-assistant
+   Add infrastructure management commands and NetBox MCP tools reference.
+
+2. project-hygiene
+   Add cleanup hook documentation and configuration options.
+
+---
+
+Would you like me to:
+[1] Implement all content recommendations
+[2] Add missing plugin integrations to CLAUDE.md
+[3] Do both (recommended)
+[4] Show preview of changes first
+```
+
+## When to Use
+
+Run `/config-analyze` when:
+- Setting up a new project with existing CLAUDE.md
+- CLAUDE.md feels too long or hard to use
+- Claude seems to miss instructions
+- Before major project changes
+- Periodic maintenance (quarterly)
+- After installing new marketplace plugins
+- When Claude doesn't seem to use available plugin tools
 
 ## Follow-Up Actions
 
-1. Implement content recommendations
+After analysis, you can:
-2. Add missing plugin integrations
+- Run `/config-optimize` to automatically improve the file
-3. Do both (recommended)
+- Manually address specific issues
-4. Show preview first
+- Request detailed recommendations for any section
+- Compare with best practice templates
+
+## Tips
+
+- Run analysis after significant project changes
+- Address HIGH priority issues first
+- Keep scores above 70/100 for best results
+- Re-analyze after making changes to verify improvement

plugins/claude-config-maintainer/commands/config-diff.md

@@ -4,45 +4,248 @@ description: Show diff between current CLAUDE.md and last commit
 
 # Compare CLAUDE.md Changes
 
-Show differences between CLAUDE.md versions to track configuration drift.
+This command shows differences between your current CLAUDE.md file and previous versions, helping track configuration drift and review changes before committing.
-
-## Skills to Load
-
-- skills/visual-header.md
-- skills/diff-analysis.md
 
 ## Visual Output
 
-Display: `CONFIG-MAINTAINER - CLAUDE.md Diff`
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ⚙️ CONFIG-MAINTAINER · CLAUDE.md Diff                           │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the diff.
+
+## What This Command Does
+
+1. **Detect CLAUDE.md Location** - Finds the project's CLAUDE.md file
+2. **Compare Versions** - Shows diff against last commit or specified revision
+3. **Highlight Sections** - Groups changes by affected sections
+4. **Summarize Impact** - Explains what the changes mean for Claude's behavior
 
 ## Usage
 
 ```
-/config-diff                           # Working vs last commit
+/config-diff
-/config-diff --commit=abc1234          # Working vs specific commit
-/config-diff --from=v1.0 --to=v2.0     # Compare two commits
-/config-diff --section="Critical Rules"  # Specific section only
 ```
 
-## Workflow
+Compare against a specific commit:
 
-1. Find project's CLAUDE.md file
+```
-2. Show diff against target revision
+/config-diff --commit=abc1234
-3. Group changes by affected sections
+/config-diff --commit=HEAD~3
-4. Explain behavioral implications
+```
+
+Compare two specific commits:
+
+```
+/config-diff --from=abc1234 --to=def5678
+```
+
+Show only specific sections:
+
+```
+/config-diff --section="Critical Rules"
+/config-diff --section="Quick Start"
+```
+
+## Comparison Modes
+
+### Default: Working vs Last Commit
+Shows uncommitted changes to CLAUDE.md:
+```
+/config-diff
+```
+
+### Working vs Specific Commit
+Shows changes since a specific point:
+```
+/config-diff --commit=v1.0.0
+```
+
+### Commit to Commit
+Shows changes between two historical versions:
+```
+/config-diff --from=v1.0.0 --to=v2.0.0
+```
+
+### Branch Comparison
+Shows CLAUDE.md differences between branches:
+```
+/config-diff --branch=main
+/config-diff --from=feature-branch --to=main
+```
+
+## Expected Output
+
+```
+CLAUDE.md Diff Report
+=====================
+
+File: /path/to/project/CLAUDE.md
+Comparing: Working copy vs HEAD (last commit)
+Commit: abc1234 "Update build commands" (2 days ago)
+
+Summary:
+- Lines added: 12
+- Lines removed: 5
+- Net change: +7 lines
+- Sections affected: 3
+
+Section Changes:
+----------------
+
+## Quick Start [MODIFIED]
+  - Added new environment variable requirement
+  - Updated test command with coverage flag
+
+## Critical Rules [ADDED CONTENT]
+  + New rule: "Never modify database migrations directly"
+
+## Architecture [UNCHANGED]
+
+## Common Operations [MODIFIED]
+  - Removed deprecated deployment command
+  - Added new Docker workflow
+
+Detailed Diff:
+--------------
+
+--- CLAUDE.md (HEAD)
++++ CLAUDE.md (working)
+
+@@ -15,7 +15,10 @@
+ ## Quick Start
+
+ ```bash
++export DATABASE_URL=postgres://...  # Required
+ pip install -r requirements.txt
+-pytest
++pytest --cov=src                    # Run with coverage
+ uvicorn main:app --reload
+ ```
+
+@@ -45,6 +48,7 @@
+ ## Critical Rules
+
+ - Never modify `.env` files directly
++- Never modify database migrations directly
+ - Always run tests before committing
+
+Behavioral Impact:
+------------------
+
+These changes will affect Claude's behavior:
+
+1. [NEW REQUIREMENT] Claude will now export DATABASE_URL before running
+2. [MODIFIED] Test command now includes coverage reporting
+3. [NEW RULE] Claude will avoid direct migration modifications
+
+Review: Do these changes reflect your intended configuration?
+```
+
+## Section-Focused View
+
+When using `--section`, output focuses on specific areas:
+
+```
+/config-diff --section="Critical Rules"
+
+CLAUDE.md Section Diff: Critical Rules
+======================================
+
+--- HEAD
++++ Working
+
+ ## Critical Rules
+
+ - Never modify `.env` files directly
++- Never modify database migrations directly
++- Always use type hints in Python code
+ - Always run tests before committing
+-- Keep functions under 50 lines
+
+Changes:
+  + 2 rules added
+  - 1 rule removed
+
+Impact: Claude will follow 2 new constraints and no longer enforce
+the 50-line function limit.
+```
 
 ## Options
 
 | Option | Description |
 |--------|-------------|
-| `--commit=REF` | Compare against specific commit |
+| `--commit=REF` | Compare working copy against specific commit/tag |
-| `--from=REF` | Starting point |
+| `--from=REF` | Starting point for comparison |
-| `--to=REF` | Ending point (default: HEAD) |
+| `--to=REF` | Ending point for comparison (default: HEAD) |
-| `--section=NAME` | Show only specific section |
+| `--branch=NAME` | Compare against branch tip |
-| `--stat` | Statistics only |
+| `--section=NAME` | Show only changes to specific section |
+| `--stat` | Show only statistics, no detailed diff |
+| `--no-color` | Disable colored output |
+| `--context=N` | Lines of context around changes (default: 3) |
+
+## Understanding the Output
+
+### Change Indicators
+
+| Symbol | Meaning |
+|--------|---------|
+| `+` | Line added |
+| `-` | Line removed |
+| `@@` | Location marker showing line numbers |
+| `[MODIFIED]` | Section has changes |
+| `[ADDED]` | New section created |
+| `[REMOVED]` | Section deleted |
+| `[UNCHANGED]` | No changes to section |
+
+### Impact Categories
+
+- **NEW REQUIREMENT** - Claude will now need to do something new
+- **REMOVED REQUIREMENT** - Claude no longer needs to do something
+- **MODIFIED** - Existing behavior changed
+- **NEW RULE** - New constraint added
+- **RELAXED RULE** - Constraint removed or softened
 
 ## When to Use
 
+Run `/config-diff` when:
 - Before committing CLAUDE.md changes
-- Reviewing changes after pull
+- Reviewing what changed after pulling updates
-- Debugging unexpected behavior
+- Debugging unexpected Claude behavior
+- Auditing configuration changes over time
+- Comparing configurations across branches
+
+## Integration with Other Commands
+
+| Workflow | Commands |
+|----------|----------|
+| Review before commit | `/config-diff` then `git commit` |
+| After optimization | `/config-optimize` then `/config-diff` |
+| Audit history | `/config-diff --from=v1.0.0 --to=HEAD` |
+| Branch comparison | `/config-diff --branch=main` |
+
+## Tips
+
+1. **Review before committing** - Always check what changed
+2. **Track behavioral changes** - Focus on rules and requirements sections
+3. **Use section filtering** - Large files benefit from focused diffs
+4. **Compare across releases** - Use tags to track major changes
+5. **Check after merges** - Ensure CLAUDE.md didn't get conflict artifacts
+
+## Troubleshooting
+
+### "No changes detected"
+- CLAUDE.md matches the comparison target
+- Check if you're comparing the right commits
+
+### "File not found in commit"
+- CLAUDE.md didn't exist at that commit
+- Use `git log -- CLAUDE.md` to find when it was created
+
+### "Not a git repository"
+- This command requires git history
+- Initialize git or use file backup comparison instead

plugins/claude-config-maintainer/commands/config-lint.md

@@ -4,45 +4,343 @@ description: Lint CLAUDE.md for common anti-patterns and best practices
 
 # Lint CLAUDE.md
 
-Check CLAUDE.md against best practices and detect common anti-patterns.
+This command checks your CLAUDE.md file against best practices and detects common anti-patterns that can cause issues with Claude Code.
-
-## Skills to Load
-
-- skills/visual-header.md
-- skills/lint-rules.md
 
 ## Visual Output
 
-Display: `CONFIG-MAINTAINER - CLAUDE.md Lint`
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ⚙️ CONFIG-MAINTAINER · CLAUDE.md Lint                           │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the linting.
+
+## What This Command Does
+
+1. **Parse Structure** - Validates markdown structure and hierarchy
+2. **Check Security** - Detects hardcoded paths, secrets, and sensitive data
+3. **Validate Content** - Identifies anti-patterns and problematic instructions
+4. **Verify Format** - Ensures consistent formatting and style
+5. **Generate Report** - Provides actionable findings with fix suggestions
 
 ## Usage
 
 ```
-/config-lint                         # Full lint
+/config-lint
-/config-lint --fix                   # Auto-fix issues
-/config-lint --rules=security        # Check specific category
 ```
 
-## Workflow
+Lint with auto-fix:
 
-1. Parse markdown structure and hierarchy
+```
-2. Check for hardcoded paths, secrets, sensitive data
+/config-lint --fix
-3. Identify content anti-patterns
+```
-4. Verify consistent formatting
+
-5. Generate report with fix suggestions
+Check specific rules only:
+
+```
+/config-lint --rules=security,structure
+```
+
+## Linting Rules
+
+### Security Rules (SEC)
+
+| Rule | Description | Severity |
+|------|-------------|----------|
+| SEC001 | Hardcoded absolute paths | Warning |
+| SEC002 | Potential secrets/API keys | Error |
+| SEC003 | Hardcoded IP addresses | Warning |
+| SEC004 | Exposed credentials patterns | Error |
+| SEC005 | Hardcoded URLs with tokens | Error |
+| SEC006 | Environment variable values (not names) | Warning |
+
+### Structure Rules (STR)
+
+| Rule | Description | Severity |
+|------|-------------|----------|
+| STR001 | Missing required sections | Error |
+| STR002 | Invalid header hierarchy (h3 before h2) | Warning |
+| STR003 | Orphaned content (text before first header) | Info |
+| STR004 | Excessive nesting depth (>4 levels) | Warning |
+| STR005 | Empty sections | Warning |
+| STR006 | Missing section content | Warning |
+
+### Content Rules (CNT)
+
+| Rule | Description | Severity |
+|------|-------------|----------|
+| CNT001 | Contradictory instructions | Error |
+| CNT002 | Vague or ambiguous rules | Warning |
+| CNT003 | Overly long sections (>100 lines) | Info |
+| CNT004 | Duplicate content | Warning |
+| CNT005 | TODO/FIXME in production config | Warning |
+| CNT006 | Outdated version references | Info |
+| CNT007 | Broken internal links | Warning |
+
+### Format Rules (FMT)
+
+| Rule | Description | Severity |
+|------|-------------|----------|
+| FMT001 | Inconsistent header styles | Info |
+| FMT002 | Inconsistent list markers | Info |
+| FMT003 | Missing code block language | Info |
+| FMT004 | Trailing whitespace | Info |
+| FMT005 | Missing blank lines around headers | Info |
+| FMT006 | Inconsistent indentation | Info |
+
+### Best Practice Rules (BPR)
+
+| Rule | Description | Severity |
+|------|-------------|----------|
+| BPR001 | No Quick Start section | Warning |
+| BPR002 | No Critical Rules section | Warning |
+| BPR003 | Instructions without examples | Info |
+| BPR004 | Commands without explanation | Info |
+| BPR005 | Rules without rationale | Info |
+| BPR006 | Missing plugin integration docs | Info |
+
+## Expected Output
+
+```
+CLAUDE.md Lint Report
+=====================
+
+File: /path/to/project/CLAUDE.md
+Rules checked: 25
+Time: 0.3s
+
+Summary:
+  Errors:   2
+  Warnings: 5
+  Info:     3
+
+Findings:
+---------
+
+[ERROR] SEC002: Potential secret detected (line 45)
+  │ api_key = "sk-1234567890abcdef"
+  │          ^^^^^^^^^^^^^^^^^^^^^^
+  └─ Hardcoded API key found. Use environment variable reference instead.
+
+  Suggested fix:
+  - api_key = "sk-1234567890abcdef"
+  + api_key = $OPENAI_API_KEY  # Set in environment
+
+[ERROR] CNT001: Contradictory instructions (lines 23, 67)
+  │ Line 23: "Always run tests before committing"
+  │ Line 67: "Skip tests for documentation-only changes"
+  │
+  └─ These rules conflict. Clarify the exception explicitly.
+
+  Suggested fix:
+  + "Always run tests before committing, except for documentation-only
+  +  changes (files in docs/ directory)"
+
+[WARNING] SEC001: Hardcoded absolute path (line 12)
+  │ Database location: /home/user/data/myapp.db
+  │                    ^^^^^^^^^^^^^^^^^^^^^^^^
+  └─ Absolute paths break portability. Use relative or variable.
+
+  Suggested fix:
+  - Database location: /home/user/data/myapp.db
+  + Database location: ./data/myapp.db  # Or $DATA_DIR/myapp.db
+
+[WARNING] STR002: Invalid header hierarchy (line 34)
+  │ ### Subsection
+  │ (no preceding ## header)
+  │
+  └─ H3 header without parent H2. Add H2 or promote to H2.
+
+[WARNING] CNT004: Duplicate content (lines 45-52, 89-96)
+  │ Same git workflow documented twice
+  │
+  └─ Remove duplicate or consolidate into single section.
+
+[WARNING] STR005: Empty section (line 78)
+  │ ## Troubleshooting
+  │ (no content)
+  │
+  └─ Add content or remove empty section.
+
+[WARNING] BPR002: No Critical Rules section
+  │ Missing "Critical Rules" or "Important Rules" section
+  │
+  └─ Add a section highlighting must-follow rules for Claude.
+
+[INFO] FMT003: Missing code block language (line 56)
+  │ ```
+  │ npm install
+  │ ```
+  │
+  └─ Specify language for syntax highlighting: ```bash
+
+[INFO] CNT003: Overly long section (lines 100-215)
+  │ "Architecture" section is 115 lines
+  │
+  └─ Consider breaking into subsections or condensing.
+
+[INFO] FMT001: Inconsistent header styles
+  │ Line 10: "## Quick Start"
+  │ Line 25: "## Architecture:"
+  │           (colon suffix inconsistent)
+  │
+  └─ Standardize header format throughout document.
+
+---
+
+Auto-fixable: 4 issues (run with --fix)
+Manual review required: 6 issues
+
+Run `/config-lint --fix` to apply automatic fixes.
+```
 
 ## Options
 
 | Option | Description |
 |--------|-------------|
-| `--fix` | Auto-fix issues |
+| `--fix` | Automatically fix auto-fixable issues |
-| `--rules=LIST` | Check specific categories |
+| `--rules=LIST` | Check only specified rule categories |
-| `--ignore=LIST` | Skip specified rules |
+| `--ignore=LIST` | Skip specified rules (e.g., `--ignore=FMT001,FMT002`) |
-| `--severity=LEVEL` | Filter by severity |
+| `--severity=LEVEL` | Show only issues at or above level (error/warning/info) |
+| `--format=FORMAT` | Output format: `text` (default), `json`, `sarif` |
+| `--config=FILE` | Use custom lint configuration |
 | `--strict` | Treat warnings as errors |
 
+## Rule Categories
+
+Use `--rules` to focus on specific areas:
+
+```
+/config-lint --rules=security        # Only security checks
+/config-lint --rules=structure       # Only structure checks
+/config-lint --rules=security,content  # Multiple categories
+```
+
+Available categories:
+- `security` - SEC rules
+- `structure` - STR rules
+- `content` - CNT rules
+- `format` - FMT rules
+- `bestpractice` - BPR rules
+
+## Custom Configuration
+
+Create `.claude-lint.json` in project root:
+
+```json
+{
+  "rules": {
+    "SEC001": "warning",
+    "FMT001": "off",
+    "CNT003": {
+      "severity": "warning",
+      "maxLines": 150
+    }
+  },
+  "ignore": [
+    "FMT*"
+  ],
+  "requiredSections": [
+    "Quick Start",
+    "Critical Rules",
+    "Project Overview"
+  ]
+}
+```
+
+## Anti-Pattern Examples
+
+### Hardcoded Secrets (SEC002)
+```markdown
+# BAD
+API_KEY=sk-1234567890abcdef
+
+# GOOD
+API_KEY=$OPENAI_API_KEY  # Set via environment
+```
+
+### Hardcoded Paths (SEC001)
+```markdown
+# BAD
+Config file: /home/john/projects/myapp/config.yml
+
+# GOOD
+Config file: ./config.yml
+Config file: $PROJECT_ROOT/config.yml
+```
+
+### Contradictory Rules (CNT001)
+```markdown
+# BAD
+- Always use TypeScript
+- JavaScript files are acceptable for scripts
+
+# GOOD
+- Always use TypeScript for source code
+- JavaScript (.js) is acceptable only for config files and scripts
+```
+
+### Vague Instructions (CNT002)
+```markdown
+# BAD
+- Be careful with the database
+
+# GOOD
+- Never run DELETE without WHERE clause
+- Always backup before migrations
+```
+
+### Invalid Hierarchy (STR002)
+```markdown
+# BAD
+# Main Title
+### Skipped Level
+
+# GOOD
+# Main Title
+## Section
+### Subsection
+```
+
 ## When to Use
 
+Run `/config-lint` when:
 - Before committing CLAUDE.md changes
-- During code review
+- During code review for CLAUDE.md modifications
-- Periodically as maintenance
+- Setting up CI/CD checks for configuration files
+- After major edits to catch introduced issues
+- Periodically as maintenance check
+
+## Integration with CI/CD
+
+Add to your CI pipeline:
+
+```yaml
+# GitHub Actions example
+- name: Lint CLAUDE.md
+  run: claude /config-lint --strict --format=sarif > lint-results.sarif
+
+- name: Upload SARIF
+  uses: github/codeql-action/upload-sarif@v2
+  with:
+    sarif_file: lint-results.sarif
+```
+
+## Tips
+
+1. **Start with errors** - Fix errors before warnings
+2. **Use --fix carefully** - Review auto-fixes before committing
+3. **Configure per-project** - Different projects have different needs
+4. **Integrate in CI** - Catch issues before they reach main
+5. **Review periodically** - Run lint check monthly as maintenance
+
+## Related Commands
+
+| Command | Relationship |
+|---------|--------------|
+| `/config-analyze` | Deeper content analysis (complements lint) |
+| `/config-optimize` | Applies fixes and improvements |
+| `/config-diff` | Shows what changed (run lint before commit) |

plugins/claude-config-maintainer/commands/init.md

@@ -4,46 +4,220 @@ description: Initialize a new CLAUDE.md file for a project
 
 # Initialize CLAUDE.md
 
-Create a new CLAUDE.md file tailored to your project.
+This command creates a new CLAUDE.md file tailored to your project, gathering context and generating appropriate content.
-
-## Skills to Load
-
-- skills/visual-header.md
-- skills/claude-md-structure.md
-- skills/pre-change-protocol.md
 
 ## Visual Output
 
-Display: `CONFIG-MAINTAINER - CLAUDE.md Initialization`
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ⚙️ CONFIG-MAINTAINER · CLAUDE.md Initialization                 │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the initialization.
+
+## What This Command Does
+
+1. **Gather Context** - Analyzes project structure and asks clarifying questions
+2. **Detect Stack** - Identifies technologies, frameworks, and tools
+3. **Generate Content** - Creates tailored CLAUDE.md sections
+4. **Review & Refine** - Allows customization before saving
+5. **Save File** - Creates the CLAUDE.md in project root
 
 ## Usage
 
 ```
-/config-init                    # Interactive
+/config-init
-/config-init --minimal          # Minimal version
-/config-init --comprehensive    # Detailed version
 ```
 
-## Workflow
+Or with options:
 
-1. Analyze project structure, ask clarifying questions
+```
-2. Detect technologies, frameworks, tools
+/config-init --template=api        # Use API project template
-3. Generate tailored CLAUDE.md sections
+/config-init --minimal             # Create minimal version
-4. Allow review and customization
+/config-init --comprehensive       # Create detailed version
-5. Save file in project root
+```
+
+## Initialization Workflow
+
+```
+CLAUDE.md Initialization
+========================
+
+Step 1: Project Analysis
+------------------------
+Scanning project structure...
+
+Detected:
+- Language: Python 3.11
+- Framework: FastAPI
+- Package Manager: pip (requirements.txt found)
+- Testing: pytest
+- Docker: Yes (Dockerfile found)
+- Git: Yes (.git directory)
+
+Step 2: Clarifying Questions
+----------------------------
+
+1. Project Description:
+   What does this project do? (1-2 sentences)
+   > [User provides description]
+
+2. Build/Run Commands:
+   Detected commands - are these correct?
+   - Install: pip install -r requirements.txt
+   - Test: pytest
+   - Run: uvicorn main:app --reload
+   [Y/n/edit]
+
+3. Critical Rules:
+   Any rules Claude MUST follow?
+   Examples: "Never modify migrations", "Always use type hints"
+   > [User provides rules]
+
+4. Sensitive Areas:
+   Any files/directories Claude should be careful with?
+   > [User provides or skips]
+
+Step 3: Generate CLAUDE.md
+--------------------------
+
+Generating content based on:
+- Project type: FastAPI web API
+- Detected technologies
+- Your provided context
+
+Preview:
+
+---
+# CLAUDE.md
+
+## Project Overview
+[Generated description]
+
+## Quick Start
+
+```bash
+pip install -r requirements.txt  # Install dependencies
+pytest                           # Run tests
+uvicorn main:app --reload        # Start dev server
+```
+
+## Architecture
+[Generated based on structure]
+
+## Critical Rules
+[Your provided rules]
+
+## File Structure
+[Generated from analysis]
+---
+
+Save this CLAUDE.md? [Y/n/edit]
+
+Step 4: Complete
+----------------
+
+CLAUDE.md created successfully!
+
+Location: /path/to/project/CLAUDE.md
+Lines: 87
+Score: 85/100 (following best practices)
+
+Recommendations:
+- Run /config-analyze periodically to maintain quality
+- Update when adding major features
+- Add troubleshooting section as issues are discovered
+```
 
 ## Templates
 
-| Template | Sections |
+### Minimal Template
-|----------|----------|
+For small projects or when starting fresh:
-| Minimal | Overview, Quick Start, Critical Rules, Pre-Change Protocol |
+- Project Overview (required)
-| Standard | + Architecture, Common Operations, File Structure |
+- Quick Start (required)
-| Comprehensive | + Troubleshooting, Integration Points, Workflow |
+- Critical Rules (required)
 
-**Note:** Pre-Change Protocol is MANDATORY in all templates.
+### Standard Template (default)
+For typical projects:
+- Project Overview
+- Quick Start
+- Architecture
+- Critical Rules
+- Common Operations
+- File Structure
+
+### Comprehensive Template
+For large or complex projects:
+- All standard sections plus:
+- Detailed Architecture
+- Troubleshooting
+- Integration Points
+- Development Workflow
+- Deployment Notes
+
+## Auto-Detection
+
+The command automatically detects:
+
+| What | How |
+|------|-----|
+| Language | File extensions, config files |
+| Framework | package.json, requirements.txt, etc. |
+| Build system | Makefile, package.json scripts, etc. |
+| Testing | pytest.ini, jest.config, etc. |
+| Docker | Dockerfile, docker-compose.yml |
+| Database | Connection strings, ORM configs |
+
+## Customization
+
+After generation, you can:
+- Edit any section before saving
+- Add additional sections
+- Remove unnecessary sections
+- Adjust detail level
+- Add project-specific content
 
 ## When to Use
 
+Run `/config-init` when:
 - Starting a new project
 - Project lacks CLAUDE.md
-- Taking over unfamiliar project
+- Existing CLAUDE.md is outdated/poor quality
+- Taking over an unfamiliar project
+
+## Tips
+
+1. **Provide accurate description** - This shapes the whole file
+2. **Include critical rules** - What must Claude never do?
+3. **Review generated content** - Auto-detection isn't perfect
+4. **Start minimal, grow as needed** - Add sections when required
+5. **Keep it current** - Update when project changes significantly
+
+## Examples
+
+### For a CLI Tool
+```
+/config-init
+
+> Description: CLI tool for managing cloud infrastructure
+> Critical rules: Never delete resources without confirmation, always show dry-run first
+```
+
+### For a Web App
+```
+/config-init
+
+> Description: E-commerce platform with React frontend and Node.js backend
+> Critical rules: Never expose API keys, always validate user input, follow the existing component patterns
+```
+
+### For a Library
+```
+/config-init --template=minimal
+
+> Description: Python library for parsing log files
+> Critical rules: Maintain backward compatibility, all public functions need docstrings
+```

plugins/claude-config-maintainer/commands/optimize.md

@@ -4,47 +4,187 @@ description: Optimize CLAUDE.md structure and content
 
 # Optimize CLAUDE.md
 
-Automatically optimize CLAUDE.md based on best practices.
+This command automatically optimizes your project's CLAUDE.md file based on best practices and identified issues.
-
-## Skills to Load
-
-- skills/visual-header.md
-- skills/optimization-patterns.md
-- skills/pre-change-protocol.md
-- skills/claude-md-structure.md
 
 ## Visual Output
 
-Display: `CONFIG-MAINTAINER - CLAUDE.md Optimization`
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ⚙️ CONFIG-MAINTAINER · CLAUDE.md Optimization                   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the optimization.
+
+## What This Command Does
+
+1. **Analyze Current File** - Identifies all optimization opportunities
+2. **Plan Changes** - Determines what to restructure, condense, or add
+3. **Show Preview** - Displays before/after comparison
+4. **Apply Changes** - Updates the file with your approval
+5. **Verify Results** - Confirms improvements achieved
 
 ## Usage
 
 ```
-/config-optimize                # Full optimization
+/config-optimize
-/config-optimize --condense     # Reduce verbosity
-/config-optimize --dry-run      # Preview only
 ```
 
-## Workflow
+Or specify specific optimizations:
 
-1. Identify optimization opportunities
+```
-2. Plan restructure, condense, or add actions
+/config-optimize --condense        # Focus on reducing verbosity
-3. Show before/after preview
+/config-optimize --restructure     # Focus on reorganization
-4. Apply changes with approval
+/config-optimize --add-missing     # Focus on adding missing sections
-5. Verify improvements
+```
+
+## Optimization Actions
+
+### Restructure
+- Reorder sections by importance
+- Group related content together
+- Improve header hierarchy
+- Add navigation aids
+
+### Condense
+- Remove redundant explanations
+- Convert verbose text to bullet points
+- Eliminate duplicate content
+- Shorten overly detailed sections
+
+### Enhance
+- Add missing essential sections
+- Improve unclear instructions
+- Add helpful examples
+- Highlight critical rules
+
+### Format
+- Standardize header styles
+- Fix code block formatting
+- Align list formatting
+- Improve table layouts
+
+## Expected Output
+
+```
+CLAUDE.md Optimization
+======================
+
+Current Analysis:
+- Score: 72/100
+- Lines: 245
+- Issues: 4
+
+Planned Optimizations:
+
+1. ADD: Quick Start section (new, ~15 lines)
+   + Build command
+   + Test command
+   + Run command
+
+2. CONDENSE: Testing section (34 → 8 lines)
+   Before: Verbose explanation with redundant setup info
+   After: Concise command reference with comments
+
+3. REMOVE: Duplicate git workflow (lines 189-200)
+   Keeping: Original at lines 102-115
+
+4. FORMAT: Standardize headers
+   Changing 12 headers from "## Title:" to "## Title"
+
+Preview Changes? [Y/n] y
+
+--- CLAUDE.md (before)
++++ CLAUDE.md (after)
+
+@@ -1,5 +1,20 @@
+ # CLAUDE.md
+
++## Quick Start
++
++```bash
++# Install dependencies
++pip install -r requirements.txt
++
++# Run tests
++pytest
++
++# Start development server
++python manage.py runserver
++```
++
+ ## Project Overview
+ ...
+
+[Full diff shown]
+
+Apply these changes? [Y/n] y
+
+Optimization Complete!
+- Previous score: 72/100
+- New score: 89/100
+- Lines reduced: 245 → 198 (-19%)
+- Issues resolved: 4/4
+
+Backup saved to: .claude/backups/CLAUDE.md.2025-01-18
+```
+
+## Safety Features
+
+### Backup Creation
+- Automatic backup before changes
+- Stored in `.claude/backups/`
+- Easy restoration if needed
+
+### Preview Mode
+- All changes shown before applying
+- Diff format for easy review
+- Option to approve/reject
+
+### Selective Application
+- Can apply individual changes
+- Skip specific optimizations
+- Iterative refinement
 
 ## Options
 
 | Option | Description |
 |--------|-------------|
-| `--dry-run` | Preview without applying |
+| `--dry-run` | Show changes without applying |
-| `--no-backup` | Skip backup |
+| `--no-backup` | Skip backup creation |
 | `--aggressive` | Maximum condensation |
-| `--section=NAME` | Optimize specific section |
+| `--preserve-comments` | Keep all existing comments |
+| `--section=NAME` | Optimize specific section only |
 
-**Priority:** Add Pre-Change Protocol if missing.
+## When to Use
 
-## Safety
+Run `/config-optimize` when:
+- Analysis shows score below 70
+- File has grown too long
+- Structure needs reorganization
+- Missing critical sections
+- After major refactoring
 
-- Auto backup to `.claude/backups/`
+## Best Practices
-- Preview before applying
+
+1. **Run analysis first** - Understand current state
+2. **Review preview carefully** - Ensure nothing important lost
+3. **Test after changes** - Verify Claude follows instructions
+4. **Keep backups** - Restore if issues arise
+5. **Iterate** - Multiple small optimizations beat one large one
+
+## Rollback
+
+If optimization causes issues:
+
+```bash
+# Restore from backup
+cp .claude/backups/CLAUDE.md.TIMESTAMP ./CLAUDE.md
+```
+
+Or ask:
+```
+Restore CLAUDE.md from the most recent backup
+```

plugins/claude-config-maintainer/hooks/hooks.json

@@ -2,13 +2,8 @@
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "",
+        "type": "command",
-        "hooks": [
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/enforce-rules.sh"
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/enforce-rules.sh"
-          }
-        ]
       }
     ]
   }

plugins/claude-config-maintainer/skills/analysis-workflow.md

@@ -1,112 +0,0 @@
-# CLAUDE.md Analysis Workflow
-
-This skill defines the workflow for analyzing CLAUDE.md files.
-
-## Analysis Steps
-
-1. **Locate File** - Find CLAUDE.md in project root
-2. **Parse Structure** - Extract headers and sections
-3. **Evaluate Content** - Score against criteria
-4. **Detect Plugins** - Identify active marketplace plugins
-5. **Check Integration** - Verify plugin references
-6. **Generate Report** - Provide scored assessment
-
-## Content Analysis
-
-### What to Check
-
-| Area | Check For |
-|------|-----------|
-| Structure | Header hierarchy, section ordering, grouping |
-| Clarity | Clear instructions, examples, unambiguous language |
-| Completeness | Required sections present, workflows documented |
-| Conciseness | No redundancy, efficient density, appropriate length |
-
-### Required Sections Check
-
-1. Project Overview - present?
-2. Quick Start - present with commands?
-3. Critical Rules - present?
-4. **Pre-Change Protocol** - present? (HIGH PRIORITY if missing)
-
-## Plugin Integration Analysis
-
-### Detection Method
-
-1. Read `.claude/settings.local.json` for enabled MCP servers
-2. Map MCP servers to plugins:
-   - `gitea` -> projman
-   - `netbox` -> cmdb-assistant
-3. Check for hook-based plugins (project-hygiene)
-4. Scan CLAUDE.md for plugin references
-
-### Coverage Scoring
-
-For each detected plugin, verify CLAUDE.md contains:
-- Plugin section header or mention
-- Available commands documentation
-- MCP tools reference (if applicable)
-- Usage guidelines
-
-Coverage = (plugins referenced / plugins detected) * 100%
-
-## Report Format
-
-```
-CLAUDE.md Analysis Report
-=========================
-
-File: /path/to/project/CLAUDE.md
-Lines: N
-Last Modified: YYYY-MM-DD
-
-Overall Score: NN/100
-
-Category Scores:
-- Structure:    NN/25 (Rating)
-- Clarity:      NN/25 (Rating)
-- Completeness: NN/25 (Rating)
-- Conciseness:  NN/25 (Rating)
-
-Strengths:
-+ [Positive finding]
-
-Issues Found:
-
-N. [SEVERITY] Issue description (location)
-   Context explaining the problem.
-   Impact: What happens if not fixed.
-
-Recommendations:
-N. Action to take (priority: high/medium/low)
-
----
-
-Plugin Integration Analysis
-===========================
-
-Detected Active Plugins:
-  [check] plugin-name (via detection method)
-
-Plugin Coverage: NN% (N/N plugins referenced)
-
-Missing Integration Content:
-N. plugin-name
-   What to add.
-```
-
-## Issue Severity
-
-| Level | When to Use |
-|-------|-------------|
-| HIGH | Missing mandatory sections, security issues |
-| MEDIUM | Missing recommended content, duplicate content |
-| LOW | Formatting issues, minor improvements |
-
-## Follow-Up Actions
-
-After analysis, offer:
-1. Implement all content recommendations
-2. Add missing plugin integrations
-3. Do both (recommended)
-4. Show preview of changes first

plugins/claude-config-maintainer/skills/claude-md-structure.md

@@ -1,113 +0,0 @@
-# CLAUDE.md Structure Reference
-
-This skill defines the standard structure, required sections, and templates for CLAUDE.md files.
-
-## Required Sections
-
-Every CLAUDE.md MUST have these sections:
-
-| Section | Purpose | Priority |
-|---------|---------|----------|
-| Project Overview | What the project does | Required |
-| Quick Start | Build/test/run commands | Required |
-| Critical Rules | Must-follow constraints | Required |
-| Pre-Change Protocol | Dependency check before edits | **MANDATORY** |
-
-## Recommended Sections
-
-| Section | When to Include |
-|---------|-----------------|
-| Architecture | Complex projects with multiple components |
-| Common Operations | Projects with repetitive tasks |
-| File Structure | Large codebases |
-| Troubleshooting | Projects with known gotchas |
-| Integration Points | Projects with external dependencies |
-
-## Header Hierarchy
-
-```
-# CLAUDE.md (H1 - only one)
-## Section (H2 - main sections)
-### Subsection (H3 - within sections)
-#### Detail (H4 - rarely needed)
-```
-
-**Rules:**
-- Never skip levels (no H3 before H2)
-- Maximum depth: 4 levels
-- No orphaned content before first header
-
-## Templates
-
-### Minimal Template
-For small projects:
-```markdown
-# CLAUDE.md
-
-## Project Overview
-[Description]
-
-## Quick Start
-[Commands]
-
-## Critical Rules
-[Constraints]
-
-## Pre-Change Protocol
-[Mandatory section - see pre-change-protocol.md]
-```
-
-### Standard Template (Default)
-```markdown
-# CLAUDE.md
-
-## Project Overview
-## Quick Start
-## Architecture
-## Critical Rules
-## Pre-Change Protocol
-## Common Operations
-## File Structure
-```
-
-### Comprehensive Template
-For large projects - adds:
-- Detailed Architecture
-- Troubleshooting
-- Integration Points
-- Development Workflow
-- Deployment Notes
-
-## Auto-Detection Signals
-
-| Technology | Detection Method |
-|------------|------------------|
-| Language | File extensions, config files |
-| Framework | package.json, requirements.txt, Cargo.toml |
-| Build system | Makefile, scripts in package.json |
-| Testing | pytest.ini, jest.config.js, go.mod |
-| Docker | Dockerfile, docker-compose.yml |
-| Database | ORM configs, connection strings |
-
-## Section Content Guidelines
-
-### Project Overview
-- 1-3 sentences describing purpose
-- Target audience if relevant
-- Key technologies used
-
-### Quick Start
-- Install command
-- Test command
-- Run command
-- Each with brief inline comment
-
-### Critical Rules
-- Numbered or bulleted list
-- Specific, actionable constraints
-- Include rationale for non-obvious rules
-
-### Architecture
-- High-level component diagram (ASCII or description)
-- Data flow explanation
-- Key file/directory purposes

plugins/claude-config-maintainer/skills/diff-analysis.md

@@ -1,97 +0,0 @@
-# CLAUDE.md Diff Analysis
-
-This skill defines how to analyze and present CLAUDE.md differences.
-
-## Comparison Modes
-
-| Mode | Command | Description |
-|------|---------|-------------|
-| Working vs HEAD | `/config-diff` | Uncommitted changes |
-| Working vs Commit | `--commit=REF` | Changes since specific point |
-| Commit to Commit | `--from=X --to=Y` | Historical comparison |
-| Branch Comparison | `--branch=NAME` | Cross-branch differences |
-
-## Change Indicators
-
-| Symbol | Meaning |
-|--------|---------|
-| `+` | Line added |
-| `-` | Line removed |
-| `@@` | Location marker (line numbers) |
-| `[MODIFIED]` | Section has changes |
-| `[ADDED]` | New section created |
-| `[REMOVED]` | Section deleted |
-| `[UNCHANGED]` | No changes to section |
-
-## Impact Categories
-
-| Category | Meaning |
-|----------|---------|
-| NEW REQUIREMENT | Claude will need to do something new |
-| REMOVED REQUIREMENT | Claude no longer needs to do something |
-| MODIFIED | Existing behavior changed |
-| NEW RULE | New constraint added |
-| RELAXED RULE | Constraint removed or softened |
-
-## Report Format
-
-```
-CLAUDE.md Diff Report
-=====================
-
-File: /path/to/project/CLAUDE.md
-Comparing: [mode description]
-Commit: [ref] "[message]" (time ago)
-
-Summary:
-- Lines added: N
-- Lines removed: N
-- Net change: +/-N lines
-- Sections affected: N
-
-Section Changes:
-----------------
-
-## Section Name [STATUS]
-  +/- Change description
-
-Detailed Diff:
---------------
-
---- CLAUDE.md (before)
-+++ CLAUDE.md (after)
-
-@@ -N,M +N,M @@
- context
--removed
-+added
- context
-
-Behavioral Impact:
-------------------
-
-These changes will affect Claude's behavior:
-
-N. [CATEGORY] Description of impact
-```
-
-## Section-Focused View
-
-When using `--section=NAME`:
-- Filter diff to only that section
-- Show section-specific statistics
-- Highlight behavioral impact for that area
-
-## Troubleshooting
-
-### No changes detected
-- File matches comparison target
-- Verify comparing correct commits
-
-### File not found in commit
-- CLAUDE.md didn't exist at that point
-- Use `git log -- CLAUDE.md` to find creation
-
-### Not a git repository
-- Command requires git history
-- Initialize git or use file backup comparison

plugins/claude-config-maintainer/skills/lint-rules.md

@@ -1,136 +0,0 @@
-# CLAUDE.md Lint Rules
-
-This skill defines all linting rules for validating CLAUDE.md files.
-
-## Rule Categories
-
-### Security Rules (SEC)
-
-| Rule | Description | Severity | Auto-fix |
-|------|-------------|----------|----------|
-| SEC001 | Hardcoded absolute paths | Warning | Yes |
-| SEC002 | Potential secrets/API keys | Error | No |
-| SEC003 | Hardcoded IP addresses | Warning | No |
-| SEC004 | Exposed credentials patterns | Error | No |
-| SEC005 | Hardcoded URLs with tokens | Error | No |
-| SEC006 | Environment variable values (not names) | Warning | No |
-
-### Structure Rules (STR)
-
-| Rule | Description | Severity | Auto-fix |
-|------|-------------|----------|----------|
-| STR001 | Missing required sections | Error | Yes |
-| STR002 | Invalid header hierarchy (h3 before h2) | Warning | Yes |
-| STR003 | Orphaned content before first header | Info | No |
-| STR004 | Excessive nesting depth (>4 levels) | Warning | No |
-| STR005 | Empty sections | Warning | Yes |
-| STR006 | Missing section content | Warning | No |
-
-### Content Rules (CNT)
-
-| Rule | Description | Severity | Auto-fix |
-|------|-------------|----------|----------|
-| CNT001 | Contradictory instructions | Error | No |
-| CNT002 | Vague or ambiguous rules | Warning | No |
-| CNT003 | Overly long sections (>100 lines) | Info | No |
-| CNT004 | Duplicate content | Warning | No |
-| CNT005 | TODO/FIXME in production config | Warning | No |
-| CNT006 | Outdated version references | Info | No |
-| CNT007 | Broken internal links | Warning | No |
-
-### Format Rules (FMT)
-
-| Rule | Description | Severity | Auto-fix |
-|------|-------------|----------|----------|
-| FMT001 | Inconsistent header styles | Info | Yes |
-| FMT002 | Inconsistent list markers | Info | Yes |
-| FMT003 | Missing code block language | Info | Yes |
-| FMT004 | Trailing whitespace | Info | Yes |
-| FMT005 | Missing blank lines around headers | Info | Yes |
-| FMT006 | Inconsistent indentation | Info | Yes |
-
-### Best Practice Rules (BPR)
-
-| Rule | Description | Severity | Auto-fix |
-|------|-------------|----------|----------|
-| BPR001 | No Quick Start section | Warning | No |
-| BPR002 | No Critical Rules section | Warning | No |
-| BPR003 | Instructions without examples | Info | No |
-| BPR004 | Commands without explanation | Info | No |
-| BPR005 | Rules without rationale | Info | No |
-| BPR006 | Missing plugin integration docs | Info | No |
-
-## Anti-Pattern Examples
-
-### SEC002: Hardcoded Secrets
-```markdown
-# BAD
-API_KEY=sk-1234567890abcdef
-
-# GOOD
-API_KEY=$OPENAI_API_KEY  # Set via environment
-```
-
-### SEC001: Hardcoded Paths
-```markdown
-# BAD
-Config file: /home/john/projects/myapp/config.yml
-
-# GOOD
-Config file: ./config.yml
-Config file: $PROJECT_ROOT/config.yml
-```
-
-### CNT001: Contradictory Rules
-```markdown
-# BAD
-- Always use TypeScript
-- JavaScript files are acceptable for scripts
-
-# GOOD
-- Always use TypeScript for source code
-- JavaScript (.js) is acceptable only for config files and scripts
-```
-
-### CNT002: Vague Instructions
-```markdown
-# BAD
-- Be careful with the database
-
-# GOOD
-- Never run DELETE without WHERE clause
-- Always backup before migrations
-```
-
-### STR002: Invalid Hierarchy
-```markdown
-# BAD
-# Main Title
-### Skipped Level
-
-# GOOD
-# Main Title
-## Section
-### Subsection
-```
-
-## Output Format
-
-```
-[SEVERITY] RULE_ID: Description (line N)
-  | Context line showing issue
-  |          ^^^^^^ indicator
-  +-- Explanation of problem
-
-  Suggested fix:
-  - old line
-  + new line
-```
-
-## Severity Levels
-
-| Level | Meaning | Action |
-|-------|---------|--------|
-| Error | Must fix | Blocks commit |
-| Warning | Should fix | Review recommended |
-| Info | Consider fixing | Optional improvement |

plugins/claude-config-maintainer/skills/optimization-patterns.md

@@ -1,136 +0,0 @@
-# CLAUDE.md Optimization Patterns
-
-This skill defines patterns for optimizing CLAUDE.md files.
-
-## Optimization Categories
-
-### Restructure
-- Reorder sections by importance (Quick Start near top)
-- Group related content together
-- Improve header hierarchy
-- Add navigation aids (TOC for long files)
-
-### Condense
-- Remove redundant explanations
-- Convert verbose text to bullet points
-- Eliminate duplicate content
-- Shorten overly detailed sections
-
-### Enhance
-- Add missing essential sections
-- **Add Pre-Change Protocol if missing (HIGH PRIORITY)**
-- Improve unclear instructions
-- Add helpful examples
-- Highlight critical rules
-
-### Format
-- Standardize header styles (no trailing colons)
-- Fix code block formatting (add language tags)
-- Align list formatting (consistent markers)
-- Improve table layouts
-
-## Scoring Criteria
-
-### Structure (25 points)
-- Logical section ordering
-- Clear header hierarchy
-- Easy navigation
-- Appropriate grouping
-
-### Clarity (25 points)
-- Clear instructions
-- Good examples
-- Unambiguous language
-- Appropriate detail level
-
-### Completeness (25 points)
-- Project overview present
-- Quick start commands documented
-- Critical rules highlighted
-- Key workflows covered
-- Pre-Change Protocol present (MANDATORY)
-
-### Conciseness (25 points)
-- No unnecessary repetition
-- Efficient information density
-- Appropriate length for project size
-- No generic filler content
-
-## Score Interpretation
-
-| Score | Rating | Action |
-|-------|--------|--------|
-| 90-100 | Excellent | Maintenance only |
-| 70-89 | Good | Minor improvements |
-| 50-69 | Needs Work | Optimization recommended |
-| Below 50 | Poor | Major restructuring needed |
-
-## Common Optimizations
-
-### Verbose to Concise
-```markdown
-# Before (34 lines)
-## Running Tests
-To run the tests, you first need to make sure you have all the
-dependencies installed. The dependencies are listed in requirements.txt.
-Once you have installed the dependencies, you can run the tests using
-pytest. Pytest will automatically discover all test files...
-
-# After (8 lines)
-## Running Tests
-```bash
-pip install -r requirements.txt  # Install dependencies
-pytest                           # Run all tests
-pytest -v                        # Verbose output
-pytest tests/unit/               # Run specific directory
-```
-```
-
-### Duplicate Removal
-- Keep first occurrence
-- Add cross-reference if needed: "See [Section Name] above"
-
-### Header Standardization
-```markdown
-# Before
-## Quick Start:
-## Architecture
-## Testing:
-
-# After
-## Quick Start
-## Architecture
-## Testing
-```
-
-### Code Block Enhancement
-```markdown
-# Before
-```
-npm install
-npm test
-```
-
-# After
-```bash
-npm install  # Install dependencies
-npm test     # Run test suite
-```
-```
-
-## Safety Features
-
-### Backup Creation
-- Always backup before changes
-- Store in `.claude/backups/CLAUDE.md.TIMESTAMP`
-- Easy restoration if needed
-
-### Preview Mode
-- Show all changes before applying
-- Use diff format for easy review
-- Allow approve/reject per change
-
-### Selective Application
-- Can apply individual changes
-- Skip specific optimizations
-- Iterative refinement supported

plugins/claude-config-maintainer/skills/pre-change-protocol.md

@@ -1,83 +0,0 @@
-# Pre-Change Protocol
-
-This skill defines the mandatory Pre-Change Protocol section that MUST be included in every CLAUDE.md file.
-
-## Why This Is Mandatory
-
-The Pre-Change Protocol prevents the #1 cause of bugs from AI-assisted coding: **incomplete changes where Claude modifies some files but misses others that reference the same code**.
-
-Without this protocol:
-- Claude may rename a function but miss callers
-- Claude may modify a config but miss documentation
-- Claude may update a schema but miss dependent code
-
-## Detection
-
-Search CLAUDE.md for these indicators:
-- Header containing "Pre-Change" or "Before Any Code Change"
-- References to `grep -rn` or impact search
-- Checklist with "Files That Will Be Affected"
-- User verification checkpoint
-
-## Required Section Content
-
-```markdown
-## MANDATORY: Before Any Code Change
-
-**Claude MUST show this checklist BEFORE editing any file:**
-
-### 1. Impact Search Results
-Run and show output of:
-```bash
-grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
-```
-
-### 2. Files That Will Be Affected
-Numbered list of every file to be modified, with the specific change for each.
-
-### 3. Files Searched But Not Changed (and why)
-Proof that related files were checked and determined unchanged.
-
-### 4. Documentation That References This
-List of docs that mention this feature/script/function.
-
-**User verifies this list before Claude proceeds. If Claude skips this, stop immediately.**
-
-### After Changes
-Run the same grep and show results proving no references remain unaddressed.
-```
-
-## Placement
-
-Insert Pre-Change Protocol section:
-- **After:** Critical Rules section
-- **Before:** Common Operations section
-
-## If Missing During Analysis
-
-Flag as **HIGH PRIORITY** issue:
-
-```
-1. [HIGH] Missing Pre-Change Protocol section
-   CLAUDE.md lacks mandatory dependency-check protocol.
-   Impact: Claude may miss file references when making changes,
-   leading to broken dependencies and incomplete updates.
-
-   Recommendation: Add Pre-Change Protocol section immediately.
-   This is the #1 cause of cascading bugs from incomplete changes.
-```
-
-## If Missing During Optimization
-
-**Automatically add the section** at the correct position. This is the highest priority enhancement.
-
-## Variations
-
-The exact wording can vary, but these elements are required:
-
-1. **Search requirement** - Must run grep/search before changes
-2. **Affected files list** - Must enumerate all files to modify
-3. **Non-affected files proof** - Must show what was checked but unchanged
-4. **Documentation check** - Must list referencing docs
-5. **User checkpoint** - Must pause for user verification
-6. **Post-change verification** - Must verify after changes

plugins/claude-config-maintainer/skills/visual-header.md

@@ -1,52 +0,0 @@
-# Visual Header Display
-
-This skill defines the standard visual header for claude-config-maintainer commands.
-
-## Header Format
-
-```
-+-----------------------------------------------------------------+
-|  CONFIG-MAINTAINER - [Command Name]                              |
-+-----------------------------------------------------------------+
-```
-
-## Command-Specific Headers
-
-### /config-analyze
-```
-+-----------------------------------------------------------------+
-|  CONFIG-MAINTAINER - CLAUDE.md Analysis                          |
-+-----------------------------------------------------------------+
-```
-
-### /config-optimize
-```
-+-----------------------------------------------------------------+
-|  CONFIG-MAINTAINER - CLAUDE.md Optimization                      |
-+-----------------------------------------------------------------+
-```
-
-### /config-lint
-```
-+-----------------------------------------------------------------+
-|  CONFIG-MAINTAINER - CLAUDE.md Lint                              |
-+-----------------------------------------------------------------+
-```
-
-### /config-diff
-```
-+-----------------------------------------------------------------+
-|  CONFIG-MAINTAINER - CLAUDE.md Diff                              |
-+-----------------------------------------------------------------+
-```
-
-### /config-init
-```
-+-----------------------------------------------------------------+
-|  CONFIG-MAINTAINER - CLAUDE.md Initialization                    |
-+-----------------------------------------------------------------+
-```
-
-## Usage
-
-Display the header at the start of command execution, before any analysis or output.

plugins/cmdb-assistant/.claude-plugin/plugin.json

@@ -19,5 +19,6 @@
     "data-quality",
     "validation"
   ],
-  "commands": ["./commands/"]
+  "commands": ["./commands/"],
+  "mcpServers": ["./.mcp.json"]
 }

plugins/cmdb-assistant/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "netbox": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/netbox/run.sh",
+      "args": []
+    }
+  }
+}

plugins/cmdb-assistant/README.md

@@ -0,0 +1,217 @@
+# CMDB Assistant
+
+A Claude Code plugin for NetBox CMDB integration - query, create, update, and manage your network infrastructure directly from Claude Code.
+
+## What's New in v1.2.0
+
+- **`/cmdb-topology`**: Generate Mermaid diagrams showing infrastructure topology (rack view, network view, site overview)
+- **`/change-audit`**: Query and analyze NetBox audit log for change tracking and compliance
+- **`/ip-conflicts`**: Detect IP address conflicts and overlapping prefixes
+
+## What's New in v1.1.0
+
+- **Data Quality Validation**: Hooks for SessionStart and PreToolUse that check data quality and warn about missing fields
+- **Best Practices Skill**: Reference documentation for NetBox patterns (naming conventions, dependency order, role management)
+- **`/cmdb-audit`**: Analyze data quality across VMs, devices, naming conventions, and roles
+- **`/cmdb-register`**: Register the current machine into NetBox with all running applications (Docker containers, systemd services)
+- **`/cmdb-sync`**: Synchronize existing machine state with NetBox (detect drift, update with confirmation)
+
+## Features
+
+- **Full CRUD Operations**: Create, read, update, and delete across all NetBox modules
+- **Smart Search**: Find devices, IPs, sites, and more with natural language queries
+- **IP Management**: Allocate IPs, manage prefixes, track VLANs
+- **Infrastructure Documentation**: Document servers, network devices, and connections
+- **Audit Trail**: Review changes and maintain infrastructure history
+- **Data Quality Validation**: Proactive checks for missing site, tenant, platform assignments
+- **Machine Registration**: Auto-discover and register servers with running applications
+- **Drift Detection**: Sync machine state and detect changes over time
+
+## Installation
+
+### Prerequisites
+
+1. A running NetBox instance (v4.x recommended)
+2. NetBox API token with appropriate permissions
+3. The NetBox MCP server configured (see below)
+
+### Configure NetBox Credentials
+
+Create the configuration file:
+
+```bash
+mkdir -p ~/.config/claude
+cat > ~/.config/claude/netbox.env << 'EOF'
+NETBOX_API_URL=https://your-netbox-instance/api
+NETBOX_API_TOKEN=your-api-token-here
+NETBOX_VERIFY_SSL=true
+NETBOX_TIMEOUT=30
+EOF
+```
+
+### Install the Plugin
+
+Add to your Claude Code plugins or marketplace configuration.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/initial-setup` | Interactive setup wizard for NetBox MCP server |
+| `/cmdb-search <query>` | Search for devices, IPs, sites, or any CMDB object |
+| `/cmdb-device <action>` | Manage network devices (list, create, update, delete) |
+| `/cmdb-ip <action>` | Manage IP addresses and prefixes |
+| `/cmdb-site <action>` | Manage sites and locations |
+| `/cmdb-audit [scope]` | Data quality analysis (all, vms, devices, naming, roles) |
+| `/cmdb-register` | Register current machine into NetBox with running apps |
+| `/cmdb-sync` | Sync machine state with NetBox (detect drift, update) |
+| `/cmdb-topology <view>` | Generate Mermaid diagrams (rack, network, site, full) |
+| `/change-audit [filters]` | Query NetBox audit log for change tracking |
+| `/ip-conflicts [scope]` | Detect IP conflicts and overlapping prefixes |
+
+## Agent
+
+The **cmdb-assistant** agent provides conversational infrastructure management:
+
+```
+@cmdb-assistant Show me all devices at the headquarters site
+@cmdb-assistant Allocate the next available IP from 10.0.1.0/24 for the new web server
+@cmdb-assistant What changes were made to the network today?
+```
+
+## Usage Examples
+
+### Search for Infrastructure
+
+```
+/cmdb-search router
+/cmdb-search 10.0.1.0/24
+/cmdb-search datacenter
+```
+
+### Device Management
+
+```
+/cmdb-device list
+/cmdb-device show core-router-01
+/cmdb-device create web-server-03
+/cmdb-device at headquarters
+```
+
+### IP Address Management
+
+```
+/cmdb-ip prefixes
+/cmdb-ip available in 10.0.1.0/24
+/cmdb-ip allocate from 10.0.1.0/24
+```
+
+### Site Management
+
+```
+/cmdb-site list
+/cmdb-site show headquarters
+/cmdb-site racks at datacenter-east
+```
+
+## NetBox Coverage
+
+This plugin provides access to the full NetBox API:
+
+- **DCIM**: Sites, Locations, Racks, Devices, Interfaces, Cables, Power
+- **IPAM**: IP Addresses, Prefixes, VLANs, VRFs, ASNs, Services
+- **Circuits**: Providers, Circuits, Terminations
+- **Virtualization**: Clusters, Virtual Machines, VM Interfaces
+- **Tenancy**: Tenants, Contacts
+- **VPN**: Tunnels, L2VPNs, IKE/IPSec Policies
+- **Wireless**: WLANs, Wireless Links
+- **Extras**: Tags, Custom Fields, Journal Entries, Audit Log
+
+## Hooks
+
+| Event | Purpose |
+|-------|---------|
+| `SessionStart` | Test NetBox connectivity, report data quality issues |
+| `PreToolUse` | Validate VM/device parameters before create/update |
+
+Hooks are **non-blocking** - they emit warnings but never prevent operations.
+
+## Architecture
+
+```
+cmdb-assistant/
+├── .claude-plugin/
+│   └── plugin.json          # Plugin manifest
+├── .mcp.json                 # MCP server configuration
+├── commands/
+│   ├── initial-setup.md     # Setup wizard
+│   ├── cmdb-search.md       # Search command
+│   ├── cmdb-device.md       # Device management
+│   ├── cmdb-ip.md           # IP management
+│   ├── cmdb-site.md         # Site management
+│   ├── cmdb-audit.md        # Data quality audit
+│   ├── cmdb-register.md     # Machine registration
+│   ├── cmdb-sync.md         # Machine sync
+│   ├── cmdb-topology.md     # Topology visualization (NEW)
+│   ├── change-audit.md      # Change audit log (NEW)
+│   └── ip-conflicts.md      # IP conflict detection (NEW)
+├── hooks/
+│   ├── hooks.json           # Hook configuration
+│   ├── startup-check.sh     # SessionStart validation
+│   └── validate-input.sh    # PreToolUse validation
+├── skills/
+│   └── netbox-patterns/
+│       └── SKILL.md         # NetBox best practices reference
+├── agents/
+│   └── cmdb-assistant.md    # Main assistant agent
+└── README.md
+```
+
+The plugin uses the shared NetBox MCP server at `mcp-servers/netbox/`.
+
+## Configuration
+
+### Required Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `NETBOX_API_URL` | Full URL to NetBox API (e.g., `https://netbox.example.com/api`) |
+| `NETBOX_API_TOKEN` | API authentication token |
+
+### Optional Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NETBOX_VERIFY_SSL` | `true` | Verify SSL certificates |
+| `NETBOX_TIMEOUT` | `30` | Request timeout in seconds |
+
+## Getting a NetBox API Token
+
+1. Log into your NetBox instance
+2. Navigate to your profile (top-right menu)
+3. Go to "API Tokens"
+4. Click "Add a token"
+5. Set appropriate permissions (read-only or read-write)
+6. Copy the generated token
+
+## Troubleshooting
+
+### Connection Issues
+
+- Verify `NETBOX_API_URL` is correct and accessible
+- Check firewall rules allow access to NetBox
+- For self-signed certificates, set `NETBOX_VERIFY_SSL=false`
+
+### Authentication Errors
+
+- Ensure API token is valid and not expired
+- Check token has required permissions for the operation
+
+### Timeout Errors
+
+- Increase `NETBOX_TIMEOUT` for slow connections
+- Check network latency to NetBox instance
+
+## License
+
+MIT License - Part of the Leo Claude Marketplace.

plugins/cmdb-assistant/agents/cmdb-assistant.md

@@ -1,20 +1,21 @@
 # CMDB Assistant Agent
 
-You are an infrastructure management assistant specialized in NetBox CMDB operations.
+You are an infrastructure management assistant specialized in NetBox CMDB operations. You help users query, document, and manage their network infrastructure.
 
-## Skills to Load
+## Visual Output Requirements
 
-- `skills/visual-header.md`
+**MANDATORY: Display header at start of every response.**
-- `skills/netbox-patterns/SKILL.md`
-- `skills/mcp-tools-reference.md`
 
-## Visual Output
+```
-
+┌──────────────────────────────────────────────────────────────────┐
-Execute `skills/visual-header.md` with context "Infrastructure Management".
+│  🖥️ CMDB-ASSISTANT · Infrastructure Management                   │
+└──────────────────────────────────────────────────────────────────┘
+```
 
 ## Capabilities
 
-Full access to NetBox via MCP tools covering:
+You have full access to NetBox via MCP tools covering:
+
 - **DCIM**: Sites, locations, racks, devices, interfaces, cables, power
 - **IPAM**: IP addresses, prefixes, VLANs, VRFs, ASNs, services
 - **Circuits**: Providers, circuits, terminations
@@ -28,66 +29,183 @@ Full access to NetBox via MCP tools covering:
 
 ### Query Operations
 - Start with list operations to find objects
-- Use filters to narrow results
+- Use filters to narrow results (name, status, site_id, etc.)
-- Follow up with get operations for details
+- Follow up with get operations for detailed information
+- Present results in clear, organized format
 
 ### Create Operations
-- Confirm required fields before creating
+- Always confirm required fields with user before creating
-- Look up related object IDs first
+- Look up related object IDs (device_type, role, site) first
-- Suggest follow-up actions after success
+- Provide the created object details after success
+- Suggest follow-up actions (add interfaces, assign IPs, etc.)
 
 ### Update Operations
 - Show current values before updating
 - Confirm changes with user
+- Report what was changed after success
 
 ### Delete Operations
-- ALWAYS ask for explicit confirmation
+- ALWAYS ask for explicit confirmation before deleting
-- Warn about dependent objects
+- Show what will be deleted
+- Warn about dependent objects that may be affected
+
+## Common Workflows
+
+### Document a New Server
+1. Create device with `dcim_create_device`
+2. Add interfaces with `dcim_create_interface`
+3. Assign IPs with `ipam_create_ip_address`
+4. Add journal entry with `extras_create_journal_entry`
+
+### Allocate IP Space
+1. Find available prefixes with `ipam_list_available_prefixes`
+2. Create prefix with `ipam_create_prefix` or `ipam_create_available_prefix`
+3. Allocate IPs with `ipam_create_available_ip`
+
+### Audit Infrastructure
+1. List recent changes with `extras_list_object_changes`
+2. Review devices by site with `dcim_list_devices`
+3. Check IP utilization with prefix operations
+
+### Cable Management
+1. List interfaces with `dcim_list_interfaces`
+2. Create cable with `dcim_create_cable`
+3. Verify connectivity
+
+## Response Format
+
+When presenting data:
+- Use tables for lists
+- Highlight key fields (name, status, IPs)
+- Include IDs for reference in follow-up operations
+- Suggest next steps when appropriate
+
+## Error Handling
+
+- If an operation fails, explain why clearly
+- Suggest corrective actions
+- For permission errors, note what access is needed
+- For validation errors, explain required fields/formats
 
 ## Data Quality Validation
 
-Reference `skills/netbox-patterns/SKILL.md` for best practices:
+**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference.
 
-### Before VM Operations
+Before ANY create or update operation, validate against NetBox best practices:
-1. Cluster/Site assignment required
-2. Recommend tenant if not provided
-3. Check naming convention
 
-### Before Device Operations
+### VM Operations
-1. Site is REQUIRED
-2. Recommend platform
-3. Check naming convention
-4. Offer to set primary IP after creation
 
-### Before Creating Roles
+**Required checks before `virt_create_vm` or `virt_update_vm`:**
-1. List existing roles first
-2. Recommend consolidation if >10 specific roles
 
-## Dependency Order
+1. **Cluster/Site Assignment** - VMs must have either cluster or site
+2. **Tenant Assignment** - Recommend if not provided
+3. **Platform Assignment** - Recommend for OS tracking
+4. **Naming Convention** - Check against `{env}-{app}-{number}` pattern
+5. **Role Assignment** - Recommend appropriate role
+
+**If user provides no site/tenant, ASK:**
+
+> "This VM has no site or tenant assigned. NetBox best practices recommend:
+> - **Site**: For location-based queries and power budgeting
+> - **Tenant**: For resource isolation and ownership tracking
+>
+> Would you like me to:
+> 1. Assign to an existing site/tenant (list available)
+> 2. Create new site/tenant first
+> 3. Proceed without (not recommended for production use)"
+
+### Device Operations
+
+**Required checks before `dcim_create_device` or `dcim_update_device`:**
+
+1. **Site is REQUIRED** - Fail without it
+2. **Platform Assignment** - Recommend for OS tracking
+3. **Naming Convention** - Check against `{role}-{location}-{number}` pattern
+4. **Role Assignment** - Ensure appropriate role selected
+5. **After Creation** - Offer to set primary IP
+
+### Cluster Operations
+
+**Required checks before `virt_create_cluster`:**
+
+1. **Site Scope** - Recommend assigning to site
+2. **Cluster Type** - Ensure appropriate type selected
+3. **Device Association** - Recommend linking to host device
+
+### Role Management
+
+**Before creating a new device role:**
+
+1. List existing roles with `dcim_list_device_roles`
+2. Check if a more general role already exists
+3. Recommend role consolidation if >10 specific roles exist
+
+**Example guidance:**
+
+> "You're creating role 'nginx-web-server'. An existing 'web-server' role exists.
+> Consider using 'web-server' and tracking nginx via the platform field instead.
+> This reduces role fragmentation and improves maintainability."
+
+## Dependency Order Enforcement
+
+When creating multiple objects, follow this order:
 
-Follow order from `skills/netbox-patterns/SKILL.md`:
 ```
-1. Regions -> Sites -> Locations -> Racks
+1. Regions → Sites → Locations → Racks
-2. Tenant Groups -> Tenants
+2. Tenant Groups → Tenants
-3. Manufacturers -> Device Types
+3. Manufacturers → Device Types
 4. Device Roles, Platforms
 5. Devices (with site, role, type)
 6. Clusters (with type, optional site)
 7. VMs (with cluster)
-8. Interfaces -> IP Addresses -> Primary IP
+8. Interfaces → IP Addresses → Primary IP assignment
 ```
 
+**CRITICAL Rules:**
+- NEVER create a VM before its cluster exists
+- NEVER create a device before its site exists
+- NEVER create an interface before its device exists
+- NEVER create an IP before its interface exists (if assigning)
+
+## Naming Convention Enforcement
+
+When user provides a name, check against patterns:
+
+| Object Type | Pattern | Example |
+|-------------|---------|---------|
+| Device | `{role}-{site}-{number}` | `web-dc1-01` |
+| VM | `{env}-{app}-{number}` or `{prefix}_{service}` | `prod-api-01` |
+| Cluster | `{site}-{type}` | `dc1-vmware`, `home-docker` |
+| Prefix | Include purpose in description | "Production /24 for web tier" |
+
+**If name doesn't match patterns, warn:**
+
+> "The name 'HotServ' doesn't follow naming conventions.
+> Suggested: `prod-hotserv-01` or `hotserv-cloud-01`.
+> Consistent naming improves searchability and automation compatibility.
+> Proceed with original name? [Y/n]"
+
 ## Duplicate Prevention
 
-Before creating, check for existing:
+Before creating objects, always check for existing duplicates:
+
 ```
+# Before creating device
 dcim_list_devices name=<proposed-name>
+
+# Before creating VM
 virt_list_vms name=<proposed-name>
+
+# Before creating prefix
 ipam_list_prefixes prefix=<proposed-prefix>
 ```
 
+If duplicate found, inform user and suggest update instead of create.
+
 ## Available Commands
 
+Users can invoke these commands for structured workflows:
+
 | Command | Purpose |
 |---------|---------|
 | `/cmdb-search <query>` | Search across all CMDB objects |
@@ -97,6 +215,3 @@ ipam_list_prefixes prefix=<proposed-prefix>
 | `/cmdb-audit [scope]` | Data quality analysis |
 | `/cmdb-register` | Register current machine |
 | `/cmdb-sync` | Sync machine state with NetBox |
-| `/cmdb-topology <view>` | Generate infrastructure diagrams |
-| `/change-audit [filters]` | Audit NetBox changes |
-| `/ip-conflicts [scope]` | Detect IP conflicts |

plugins/cmdb-assistant/commands/change-audit.md

@@ -4,14 +4,20 @@ description: Audit NetBox changes with filtering by date, user, or object type
 
 # CMDB Change Audit
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Change Audit                                │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the audit.
+
 Query and analyze the NetBox audit log for change tracking and compliance.
 
-## Skills to Load
-
-- `skills/visual-header.md`
-- `skills/change-audit.md`
-- `skills/mcp-tools-reference.md`
-
 ## Usage
 
 ```
@@ -27,30 +33,142 @@ Query and analyze the NetBox audit log for change tracking and compliance.
 
 ## Instructions
 
-Execute `skills/visual-header.md` with context "Change Audit".
+You are a change auditor that queries NetBox's object change log and generates audit reports.
 
-Execute `skills/change-audit.md` which covers:
+### MCP Tools
-1. Parse user request for filters
-2. Query object changes via MCP
-3. Enrich data with detailed records
-4. Analyze patterns
-5. Generate report
 
-## Security Audit Mode
+Use these tools to query the audit log:
+
+- `extras_list_object_changes` - List changes with filters:
+  - `user_id` - Filter by user ID
+  - `changed_object_type` - Filter by object type (e.g., "dcim.device", "ipam.ipaddress")
+  - `action` - Filter by action: "create", "update", "delete"
+
+- `extras_get_object_change` - Get detailed change record by ID
+
+### Common Object Types
+
+| Category | Object Types |
+|----------|--------------|
+| DCIM | `dcim.device`, `dcim.interface`, `dcim.site`, `dcim.rack`, `dcim.cable` |
+| IPAM | `ipam.ipaddress`, `ipam.prefix`, `ipam.vlan`, `ipam.vrf` |
+| Virtualization | `virtualization.virtualmachine`, `virtualization.cluster` |
+| Tenancy | `tenancy.tenant`, `tenancy.contact` |
+
+### Workflow
+
+1. **Parse user request** to determine filters
+2. **Query object changes** using `extras_list_object_changes`
+3. **Enrich data** by fetching detailed records if needed
+4. **Analyze patterns** in the changes
+5. **Generate report** in structured format
+
+### Report Format
+
+```markdown
+## NetBox Change Audit Report
+
+**Generated:** [timestamp]
+**Period:** [date range or "All time"]
+**Filters:** [applied filters]
+
+### Summary
+
+| Metric | Count |
+|--------|-------|
+| Total Changes | X |
+| Creates | Y |
+| Updates | Z |
+| Deletes | W |
+| Unique Users | N |
+| Object Types | M |
+
+### Changes by Action
+
+#### Created Objects (Y)
+
+| Time | User | Object Type | Object | Details |
+|------|------|-------------|--------|---------|
+| 2024-01-15 14:30 | admin | dcim.device | server-01 | Created device |
+| ... | ... | ... | ... | ... |
+
+#### Updated Objects (Z)
+
+| Time | User | Object Type | Object | Changed Fields |
+|------|------|-------------|--------|----------------|
+| 2024-01-15 15:00 | john | ipam.ipaddress | 10.0.1.50/24 | status, description |
+| ... | ... | ... | ... | ... |
+
+#### Deleted Objects (W)
+
+| Time | User | Object Type | Object | Details |
+|------|------|-------------|--------|---------|
+| 2024-01-14 09:00 | admin | dcim.interface | eth2 | Removed from server-01 |
+| ... | ... | ... | ... | ... |
+
+### Changes by User
+
+| User | Creates | Updates | Deletes | Total |
+|------|---------|---------|---------|-------|
+| admin | 5 | 10 | 2 | 17 |
+| john | 3 | 8 | 0 | 11 |
+
+### Changes by Object Type
+
+| Object Type | Creates | Updates | Deletes | Total |
+|-------------|---------|---------|---------|-------|
+| dcim.device | 2 | 5 | 0 | 7 |
+| ipam.ipaddress | 4 | 3 | 1 | 8 |
+
+### Timeline
+
+```
+2024-01-15: ████████ 8 changes
+2024-01-14: ████ 4 changes
+2024-01-13: ██ 2 changes
+```
+
+### Notable Patterns
+
+- **Bulk operations:** [Identify if many changes happened in short time]
+- **Unusual activity:** [Flag unexpected deletions or after-hours changes]
+- **Missing audit trail:** [Note if expected changes are not logged]
+
+### Recommendations
+
+1. [Any security or process recommendations based on findings]
+```
+
+### Time Period Handling
+
+When user specifies "last N days":
+- The NetBox API may not have direct date filtering in `extras_list_object_changes`
+- Fetch recent changes and filter client-side by the `time` field
+- Note any limitations in the report
+
+### Enriching Change Details
+
+For detailed audit, use `extras_get_object_change` with the change ID to see:
+- `prechange_data` - Object state before change
+- `postchange_data` - Object state after change
+- `request_id` - Links related changes in same request
+
+### Security Audit Mode
 
 If user asks for "security audit" or "compliance report":
-- Focus on deletions and permission-sensitive changes
+1. Focus on deletions and permission-sensitive changes
-- Highlight changes to critical objects (firewalls, VRFs, prefixes)
+2. Highlight changes to critical objects (firewalls, VRFs, prefixes)
-- Flag changes outside business hours
+3. Flag changes outside business hours
-- Identify users with high change counts
+4. Identify users with high change counts
 
 ## Examples
 
-- `/change-audit` - Recent changes (last 24 hours)
+- `/change-audit` - Show recent changes (last 24 hours)
-- `/change-audit last 7 days` - Past week
+- `/change-audit last 7 days` - Changes in past week
-- `/change-audit by admin` - All changes by admin
+- `/change-audit by admin` - All changes by admin user
 - `/change-audit type dcim.device` - Device changes only
 - `/change-audit action delete` - All deletions
+- `/change-audit object server-01` - Changes to server-01
 
 ## User Request
 

plugins/cmdb-assistant/commands/cmdb-audit.md

@@ -4,15 +4,20 @@ description: Audit NetBox data quality and identify consistency issues
 
 # CMDB Data Quality Audit
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Data Quality Audit                          │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the audit.
+
 Analyze NetBox data for quality issues and best practice violations.
 
-## Skills to Load
-
-- `skills/visual-header.md`
-- `skills/audit-workflow.md`
-- `skills/netbox-patterns/SKILL.md`
-- `skills/mcp-tools-reference.md`
-
 ## Usage
 
 ```
@@ -28,30 +33,174 @@ Analyze NetBox data for quality issues and best practice violations.
 
 ## Instructions
 
-Execute `skills/visual-header.md` with context "Data Quality Audit".
+You are a data quality auditor for NetBox. Your job is to identify consistency issues and best practice violations.
 
-Execute `skills/audit-workflow.md` which covers:
+**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference.
-1. Data collection via MCP
-2. Quality checks by severity (CRITICAL, HIGH, MEDIUM, LOW)
-3. Naming convention analysis
-4. Role fragmentation analysis
-5. Report generation with recommendations
 
-## Scope-Specific Focus
+### Phase 1: Data Collection
 
-| Scope | Focus |
+Run these MCP tool calls to gather data for analysis:
-|-------|-------|
-| `all` | Full audit across all categories |
-| `vms` | Virtual Machine checks only |
-| `devices` | Device checks only |
-| `naming` | Naming convention analysis |
-| `roles` | Role fragmentation analysis |
 
-## Examples
+```
+1. virt_list_vms (no filters - get all)
+2. dcim_list_devices (no filters - get all)
+3. virt_list_clusters (no filters)
+4. dcim_list_sites
+5. tenancy_list_tenants
+6. dcim_list_device_roles
+7. dcim_list_platforms
+```
 
-- `/cmdb-audit` - Full audit
+Store the results for analysis.
-- `/cmdb-audit vms` - VM-specific checks
+
-- `/cmdb-audit naming` - Naming conventions
+### Phase 2: Quality Checks
+
+Analyze collected data for these issues by severity:
+
+#### CRITICAL Issues (must fix immediately)
+
+| Check | Detection |
+|-------|-----------|
+| VMs without cluster | `cluster` field is null AND `site` field is null |
+| Devices without site | `site` field is null |
+| Active devices without primary IP | `status=active` AND `primary_ip4` is null AND `primary_ip6` is null |
+
+#### HIGH Issues (should fix soon)
+
+| Check | Detection |
+|-------|-----------|
+| VMs without site | VM has no site (neither direct nor via cluster.site) |
+| VMs without tenant | `tenant` field is null |
+| Devices without platform | `platform` field is null |
+| Clusters not scoped to site | `site` field is null on cluster |
+| VMs without role | `role` field is null |
+
+#### MEDIUM Issues (plan to address)
+
+| Check | Detection |
+|-------|-----------|
+| Inconsistent naming | Names don't match patterns: devices=`{role}-{site}-{num}`, VMs=`{env}-{app}-{num}` |
+| Role fragmentation | More than 10 device roles with <3 assignments each |
+| Missing tags on production | Active resources without any tags |
+| Mixed naming separators | Some names use `_`, others use `-` |
+
+#### LOW Issues (informational)
+
+| Check | Detection |
+|-------|-----------|
+| Docker containers as VMs | Cluster type is "Docker Compose" - document this modeling choice |
+| VMs without description | `description` field is empty |
+| Sites without physical address | `physical_address` is empty |
+| Devices without serial | `serial` field is empty |
+
+### Phase 3: Naming Convention Analysis
+
+For naming scope, analyze patterns:
+
+1. **Extract naming patterns** from existing objects
+2. **Identify dominant patterns** (most common conventions)
+3. **Flag outliers** that don't match dominant patterns
+4. **Suggest standardization** based on best practices
+
+**Expected Patterns:**
+- Devices: `{role}-{location}-{number}` (e.g., `web-dc1-01`)
+- VMs: `{prefix}_{service}` or `{env}-{app}-{number}` (e.g., `prod-api-01`)
+- Clusters: `{site}-{type}` (e.g., `home-docker`)
+
+### Phase 4: Role Analysis
+
+For roles scope, analyze fragmentation:
+
+1. **List all device roles** with assignment counts
+2. **Identify single-use roles** (only 1 device/VM)
+3. **Identify similar roles** that could be consolidated
+4. **Suggest consolidation** based on patterns
+
+**Red Flags:**
+- More than 15 highly specific roles
+- Roles with technology in name (use platform instead)
+- Roles that duplicate functionality
+
+### Phase 5: Report Generation
+
+Present findings in this structure:
+
+```markdown
+## CMDB Data Quality Audit Report
+
+**Generated:** [timestamp]
+**Scope:** [scope parameter]
+
+### Summary
+
+| Metric | Count |
+|--------|-------|
+| Total VMs | X |
+| Total Devices | Y |
+| Total Clusters | Z |
+| **Total Issues** | **N** |
+
+| Severity | Count |
+|----------|-------|
+| Critical | A |
+| High | B |
+| Medium | C |
+| Low | D |
+
+### Critical Issues
+
+[List each with specific object names and IDs]
+
+**Example:**
+- VM `HotServ` (ID: 1) - No cluster or site assignment
+- Device `server-01` (ID: 5) - No site assignment
+
+### High Issues
+
+[List each with specific object names]
+
+### Medium Issues
+
+[Grouped by category with counts]
+
+### Recommendations
+
+1. **[Most impactful fix]** - affects N objects
+2. **[Second priority]** - affects M objects
+...
+
+### Quick Fixes
+
+Commands to fix common issues:
+
+```
+# Assign site to VM
+virt_update_vm id=X site=Y
+
+# Assign platform to device
+dcim_update_device id=X platform=Y
+```
+
+### Next Steps
+
+- Run `/cmdb-register` to properly register new machines
+- Use `/cmdb-sync` to update existing registrations
+- Consider bulk updates via NetBox web UI for >10 items
+```
+
+## Scope-Specific Instructions
+
+### For `vms` scope:
+Focus only on Virtual Machine checks. Skip device and role analysis.
+
+### For `devices` scope:
+Focus only on Device checks. Skip VM and cluster analysis.
+
+### For `naming` scope:
+Focus on naming convention analysis across all objects. Generate detailed pattern report.
+
+### For `roles` scope:
+Focus on role fragmentation analysis. Generate consolidation recommendations.
 
 ## User Request
 

plugins/cmdb-assistant/commands/cmdb-device.md

@@ -1,11 +1,18 @@
 # CMDB Device Management
 
-Manage network devices in NetBox.
+## Visual Output
 
-## Skills to Load
+When executing this command, display the plugin header:
 
-- `skills/visual-header.md`
+```
-- `skills/mcp-tools-reference.md`
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Device Management                           │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the operation.
+
+Manage network devices in NetBox - create, view, update, or delete.
 
 ## Usage
 
@@ -15,40 +22,42 @@ Manage network devices in NetBox.
 
 ## Instructions
 
-Execute `skills/visual-header.md` with context "Device Management".
+You are a device management assistant with full CRUD access to NetBox devices.
 
 ### Actions
 
 **List/View:**
-- `list` or `show all` - List all devices: `dcim_list_devices`
+- `list` or `show all` - List all devices using `dcim_list_devices`
-- `show <name>` - Get device details: `dcim_get_device`
+- `show <name>` - Get device details using `dcim_list_devices` with name filter, then `dcim_get_device`
-- `at <site>` - List devices at site
+- `at <site>` - List devices at a specific site
 
 **Create:**
-- `create <name>` - Create new device
+- `create <name>` - Create a new device
 - Required: name, device_type, role, site
-- Use `dcim_list_device_types`, `dcim_list_device_roles`, `dcim_list_sites` to find IDs
+- Use `dcim_list_device_types`, `dcim_list_device_roles`, `dcim_list_sites` to help user find IDs
+- Then use `dcim_create_device`
 
 **Update:**
 - `update <name>` - Update device properties
-- Get device ID first, then use `dcim_update_device`
+- First get the device ID, then use `dcim_update_device`
 
 **Delete:**
-- `delete <name>` - Delete device (ask confirmation first)
+- `delete <name>` - Delete a device (ask for confirmation first)
+- Use `dcim_delete_device`
 
 ### Related Operations
 
 After creating a device, offer to:
-- Add interfaces: `dcim_create_interface`
+- Add interfaces with `dcim_create_interface`
-- Assign IP addresses: `ipam_create_ip_address`
+- Assign IP addresses with `ipam_create_ip_address`
-- Add to rack: `dcim_update_device`
+- Add to a rack with `dcim_update_device`
 
 ## Examples
 
-- `/cmdb-device list`
+- `/cmdb-device list` - Show all devices
-- `/cmdb-device show core-router-01`
+- `/cmdb-device show core-router-01` - Get details for specific device
-- `/cmdb-device create web-server-03`
+- `/cmdb-device create web-server-03` - Create a new device
-- `/cmdb-device at headquarters`
+- `/cmdb-device at headquarters` - List devices at headquarters site
 
 ## User Request
 

plugins/cmdb-assistant/commands/cmdb-ip.md

@@ -1,13 +1,19 @@
 # CMDB IP Management
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · IP Management                               │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the operation.
+
 Manage IP addresses and prefixes in NetBox.
 
-## Skills to Load
-
-- `skills/visual-header.md`
-- `skills/ip-management.md`
-- `skills/mcp-tools-reference.md`
-
 ## Usage
 
 ```
@@ -16,36 +22,43 @@ Manage IP addresses and prefixes in NetBox.
 
 ## Instructions
 
-Execute `skills/visual-header.md` with context "IP Management".
+You are an IP address management (IPAM) assistant with access to NetBox.
-
-Execute operations from `skills/ip-management.md`.
 
 ### Actions
 
 **Prefixes:**
-- `prefixes` - List all prefixes
+- `prefixes` - List all prefixes using `ipam_list_prefixes`
-- `prefix <cidr>` - Get prefix details
+- `prefix <cidr>` - Get prefix details or find prefix containing address
-- `available in <prefix>` - Show available IPs
+- `available in <prefix>` - Show available IPs in a prefix using `ipam_list_available_ips`
-- `create prefix <cidr>` - Create new prefix
+- `create prefix <cidr>` - Create new prefix using `ipam_create_prefix`
 
 **IP Addresses:**
-- `list` - List all IP addresses
+- `list` - List all IP addresses using `ipam_list_ip_addresses`
 - `show <address>` - Get IP details
-- `allocate from <prefix>` - Auto-allocate next available
+- `allocate from <prefix>` - Auto-allocate next available IP using `ipam_create_available_ip`
-- `create <address>` - Create specific IP
+- `create <address>` - Create specific IP using `ipam_create_ip_address`
-- `assign <ip> to <device> <interface>` - Assign IP to interface
+- `assign <ip> to <device>` - Assign IP to device interface
 
-**VLANs and VRFs:**
+**VLANs:**
-- `vlans` - List VLANs
+- `vlans` - List VLANs using `ipam_list_vlans`
 - `vlan <id>` - Get VLAN details
-- `vrfs` - List VRFs
+
+**VRFs:**
+- `vrfs` - List VRFs using `ipam_list_vrfs`
+
+### Workflow Examples
+
+**Allocate IP to new server:**
+1. Find available IPs in target prefix
+2. Create the IP address
+3. Assign to device interface
 
 ## Examples
 
-- `/cmdb-ip prefixes`
+- `/cmdb-ip prefixes` - List all prefixes
-- `/cmdb-ip available in 10.0.1.0/24`
+- `/cmdb-ip available in 10.0.1.0/24` - Show available IPs
-- `/cmdb-ip allocate from 10.0.1.0/24`
+- `/cmdb-ip allocate from 10.0.1.0/24` - Get next available IP
-- `/cmdb-ip assign 10.0.1.50/24 to web-server-01 eth0`
+- `/cmdb-ip assign 10.0.1.50/24 to web-server-01 eth0` - Assign IP to interface
 
 ## User Request
 

plugins/cmdb-assistant/commands/cmdb-register.md

@@ -4,15 +4,19 @@ description: Register the current machine into NetBox with all running applicati
 
 # CMDB Machine Registration
 
-Register the current machine into NetBox, including hardware info, network interfaces, and running applications.
+## Visual Output
 
-## Skills to Load
+When executing this command, display the plugin header:
 
-- `skills/visual-header.md`
+```
-- `skills/device-registration.md`
+┌──────────────────────────────────────────────────────────────────┐
-- `skills/system-discovery.md`
+│  🖥️ CMDB-ASSISTANT · Machine Registration                        │
-- `skills/netbox-patterns/SKILL.md`
+└──────────────────────────────────────────────────────────────────┘
-- `skills/mcp-tools-reference.md`
+```
+
+Then proceed with the registration.
+
+Register the current machine into NetBox, including hardware info, network interfaces, and running applications (Docker containers, services).
 
 ## Usage
 
@@ -27,24 +31,303 @@ Register the current machine into NetBox, including hardware info, network inter
 
 ## Instructions
 
-Execute `skills/visual-header.md` with context "Machine Registration".
+You are registering the current machine into NetBox. This is a multi-phase process that discovers local system information and creates corresponding NetBox objects.
 
-Execute `skills/device-registration.md` which covers:
+**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference.
-1. System discovery via Bash (use `skills/system-discovery.md`)
+
-2. Pre-registration checks (device exists?, site?, platform?, role?)
+### Phase 1: System Discovery (via Bash)
-3. Device creation via MCP
+
-4. Interface and IP creation
+Gather system information using these commands:
-5. Container registration (if Docker found)
+
-6. Journal entry documentation
+#### 1.1 Basic Device Info
+
+```bash
+# Hostname
+hostname
+
+# OS/Platform info
+cat /etc/os-release 2>/dev/null || uname -a
+
+# Hardware model (varies by system)
+# Raspberry Pi:
+cat /proc/device-tree/model 2>/dev/null || echo "Unknown"
+
+# x86 systems:
+cat /sys/class/dmi/id/product_name 2>/dev/null || echo "Unknown"
+
+# Serial number
+# Raspberry Pi:
+cat /proc/device-tree/serial-number 2>/dev/null || cat /proc/cpuinfo | grep Serial | cut -d: -f2 | tr -d ' ' 2>/dev/null
+
+# x86 systems:
+cat /sys/class/dmi/id/product_serial 2>/dev/null || echo "Unknown"
+
+# CPU info
+nproc
+
+# Memory (MB)
+free -m | awk '/Mem:/ {print $2}'
+
+# Disk (GB, root filesystem)
+df -BG / | awk 'NR==2 {print $2}' | tr -d 'G'
+```
+
+#### 1.2 Network Interfaces
+
+```bash
+# Get interfaces with IPs (JSON format)
+ip -j addr show 2>/dev/null || ip addr show
+
+# Get default gateway interface
+ip route | grep default | awk '{print $5}' | head -1
+
+# Get MAC addresses
+ip -j link show 2>/dev/null || ip link show
+```
+
+#### 1.3 Running Applications
+
+```bash
+# Docker containers (if docker available)
+docker ps --format '{"name":"{{.Names}}","image":"{{.Image}}","status":"{{.Status}}","ports":"{{.Ports}}"}' 2>/dev/null || echo "Docker not available"
+
+# Docker Compose projects (check common locations)
+find ~/apps /home/*/apps -name "docker-compose.yml" -o -name "docker-compose.yaml" 2>/dev/null | head -20
+
+# Systemd services (running)
+systemctl list-units --type=service --state=running --no-pager --plain 2>/dev/null | grep -v "^UNIT" | head -30
+```
+
+### Phase 2: Pre-Registration Checks (via MCP)
+
+Before creating objects, verify prerequisites:
+
+#### 2.1 Check if Device Already Exists
+
+```
+dcim_list_devices name=<hostname>
+```
+
+**If device exists:**
+- Inform user and suggest `/cmdb-sync` instead
+- Ask if they want to proceed with re-registration (will update existing)
+
+#### 2.2 Verify/Create Site
+
+If `--site` provided:
+```
+dcim_list_sites name=<site-name>
+```
+
+If site doesn't exist, ask user if they want to create it.
+
+If no site provided, list available sites and ask user to choose:
+```
+dcim_list_sites
+```
+
+#### 2.3 Verify/Create Platform
+
+Based on OS detected, check if platform exists:
+```
+dcim_list_platforms name=<platform-name>
+```
+
+**Platform naming:**
+- `Raspberry Pi OS (Bookworm)` for Raspberry Pi
+- `Ubuntu 24.04 LTS` for Ubuntu
+- `Debian 12` for Debian
+- Use format: `{OS Name} {Version}`
+
+If platform doesn't exist, create it:
+```
+dcim_create_platform name=<platform-name> slug=<slug>
+```
+
+#### 2.4 Verify/Create Device Role
+
+Based on detected services:
+- If Docker containers found → `Docker Host`
+- If only basic services → `Server`
+- If specific role specified → Use that
+
+```
+dcim_list_device_roles name=<role-name>
+```
+
+### Phase 3: Device Registration (via MCP)
+
+#### 3.1 Get/Create Manufacturer and Device Type
+
+For Raspberry Pi:
+```
+dcim_list_manufacturers name="Raspberry Pi Foundation"
+dcim_list_device_types manufacturer_id=X model="Raspberry Pi 4 Model B"
+```
+
+Create if not exists.
+
+For generic x86:
+```
+dcim_list_manufacturers name=<detected-manufacturer>
+```
+
+#### 3.2 Create Device
+
+```
+dcim_create_device
+  name=<hostname>
+  device_type=<device_type_id>
+  role=<role_id>
+  site=<site_id>
+  platform=<platform_id>
+  tenant=<tenant_id>  # if provided
+  serial=<serial>
+  description="Registered via cmdb-assistant"
+```
+
+#### 3.3 Create Interfaces
+
+For each network interface discovered:
+```
+dcim_create_interface
+  device=<device_id>
+  name=<interface_name>  # eth0, wlan0, tailscale0, etc.
+  type=<type>            # 1000base-t, virtual, other
+  mac_address=<mac>
+  enabled=true
+```
+
+**Interface type mapping:**
+- `eth*`, `enp*` → `1000base-t`
+- `wlan*` → `ieee802.11ax` (or appropriate wifi type)
+- `tailscale*`, `docker*`, `br-*` → `virtual`
+- `lo` → skip (loopback)
+
+#### 3.4 Create IP Addresses
+
+For each IP on each interface:
+```
+ipam_create_ip_address
+  address=<ip/prefix>    # e.g., "192.168.1.100/24"
+  assigned_object_type="dcim.interface"
+  assigned_object_id=<interface_id>
+  status="active"
+  description="Discovered via cmdb-register"
+```
+
+#### 3.5 Set Primary IP
+
+Identify primary IP (interface with default route):
+```
+dcim_update_device
+  id=<device_id>
+  primary_ip4=<primary_ip_id>
+```
+
+### Phase 4: Container Registration (via MCP)
+
+If Docker containers were discovered:
+
+#### 4.1 Create/Get Cluster Type
+
+```
+virt_list_cluster_types name="Docker Compose"
+```
+
+Create if not exists:
+```
+virt_create_cluster_type name="Docker Compose" slug="docker-compose"
+```
+
+#### 4.2 Create Cluster
+
+For each Docker Compose project directory found:
+```
+virt_create_cluster
+  name=<project-name>  # e.g., "apps-hotport"
+  type=<cluster_type_id>
+  site=<site_id>
+  description="Docker Compose stack on <hostname>"
+```
+
+#### 4.3 Create VMs for Containers
+
+For each running container:
+```
+virt_create_vm
+  name=<container_name>
+  cluster=<cluster_id>
+  site=<site_id>
+  role=<role_id>        # Map container function to role
+  status="active"
+  vcpus=<cpu_shares>    # Default 1.0 if unknown
+  memory=<memory_mb>    # Default 256 if unknown
+  disk=<disk_gb>        # Default 5 if unknown
+  description=<container purpose>
+  comments=<image, ports, volumes info>
+```
+
+**Container role mapping:**
+- `*caddy*`, `*nginx*`, `*traefik*` → "Reverse Proxy"
+- `*db*`, `*postgres*`, `*mysql*`, `*redis*` → "Database"
+- `*webui*`, `*frontend*` → "Web Application"
+- Others → Infer from image name or use generic "Container"
+
+### Phase 5: Documentation
+
+#### 5.1 Add Journal Entry
+
+```
+extras_create_journal_entry
+  assigned_object_type="dcim.device"
+  assigned_object_id=<device_id>
+  comments="Device registered via /cmdb-register command\n\nDiscovered:\n- X network interfaces\n- Y IP addresses\n- Z Docker containers"
+```
+
+### Phase 6: Summary Report
+
+Present registration summary:
+
+```markdown
+## Machine Registration Complete
+
+### Device Created
+- **Name:** <hostname>
+- **Site:** <site>
+- **Platform:** <platform>
+- **Role:** <role>
+- **ID:** <device_id>
+- **URL:** https://netbox.example.com/dcim/devices/<id>/
+
+### Network Interfaces
+| Interface | Type | MAC | IP Address |
+|-----------|------|-----|------------|
+| eth0 | 1000base-t | aa:bb:cc:dd:ee:ff | 192.168.1.100/24 |
+| tailscale0 | virtual | - | 100.x.x.x/32 |
+
+### Primary IP: 192.168.1.100
+
+### Docker Containers Registered (if applicable)
+**Cluster:** <cluster_name> (ID: <cluster_id>)
+
+| Container | Role | vCPUs | Memory | Status |
+|-----------|------|-------|--------|--------|
+| media_jellyfin | Media Server | 2.0 | 2048MB | Active |
+| media_sonarr | Media Management | 1.0 | 512MB | Active |
+
+### Next Steps
+- Run `/cmdb-sync` periodically to keep data current
+- Run `/cmdb-audit` to check data quality
+- Add tags for classification (env:*, team:*, etc.)
+```
 
 ## Error Handling
 
-| Error | Action |
+- **Device already exists:** Suggest `/cmdb-sync` or ask to proceed
-|-------|--------|
+- **Site not found:** List available sites, offer to create new
-| Device already exists | Suggest `/cmdb-sync` or ask to proceed |
+- **Docker not available:** Skip container registration, note in summary
-| Site not found | List available sites, offer to create new |
+- **Permission denied:** Note which operations failed, suggest fixes
-| Docker not available | Skip container registration, note in summary |
-| Permission denied | Note which operations failed, suggest fixes |
 
 ## User Request
 

plugins/cmdb-assistant/commands/cmdb-site.md

@@ -1,12 +1,19 @@
 # CMDB Site Management
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Site Management                             │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the operation.
+
 Manage sites and locations in NetBox.
 
-## Skills to Load
-
-- `skills/visual-header.md`
-- `skills/mcp-tools-reference.md`
-
 ## Usage
 
 ```
@@ -15,35 +22,46 @@ Manage sites and locations in NetBox.
 
 ## Instructions
 
-Execute `skills/visual-header.md` with context "Site Management".
+You are a site/location management assistant with access to NetBox.
 
 ### Actions
 
 **Sites:**
-- `list` - List all sites: `dcim_list_sites`
+- `list` - List all sites using `dcim_list_sites`
-- `show <name>` - Get site details: `dcim_get_site`
+- `show <name>` - Get site details using `dcim_get_site`
-- `create <name>` - Create new site: `dcim_create_site`
+- `create <name>` - Create new site using `dcim_create_site`
-- `update <name>` - Update site: `dcim_update_site`
+- `update <name>` - Update site using `dcim_update_site`
 - `delete <name>` - Delete site (with confirmation)
 
-**Locations:**
+**Locations (within sites):**
-- `locations at <site>` - List locations: `dcim_list_locations`
+- `locations at <site>` - List locations using `dcim_list_locations`
-- `create location <name> at <site>` - Create location
+- `create location <name> at <site>` - Create location using `dcim_create_location`
 
 **Racks:**
-- `racks at <site>` - List racks: `dcim_list_racks`
+- `racks at <site>` - List racks using `dcim_list_racks`
-- `create rack <name> at <site>` - Create rack
+- `create rack <name> at <site>` - Create rack using `dcim_create_rack`
 
 **Regions:**
-- `regions` - List regions: `dcim_list_regions`
+- `regions` - List regions using `dcim_list_regions`
-- `create region <name>` - Create region
+- `create region <name>` - Create region using `dcim_create_region`
+
+### Site Properties
+
+When creating/updating sites:
+- name (required)
+- slug (required, auto-generated if not provided)
+- status: active, planned, staging, decommissioning, retired
+- region: parent region ID
+- facility: datacenter/building name
+- physical_address, shipping_address
+- time_zone
 
 ## Examples
 
-- `/cmdb-site list`
+- `/cmdb-site list` - Show all sites
-- `/cmdb-site show headquarters`
+- `/cmdb-site show headquarters` - Get HQ site details
-- `/cmdb-site create branch-office-nyc`
+- `/cmdb-site create branch-office-nyc` - Create new site
-- `/cmdb-site racks at headquarters`
+- `/cmdb-site racks at headquarters` - List racks at HQ
 
 ## User Request
 

plugins/cmdb-assistant/commands/cmdb-sync.md

@@ -4,14 +4,19 @@ description: Synchronize current machine state with existing NetBox record
 
 # CMDB Machine Sync
 
-Update an existing NetBox device record with the current machine state.
+## Visual Output
 
-## Skills to Load
+When executing this command, display the plugin header:
 
-- `skills/visual-header.md`
+```
-- `skills/sync-workflow.md`
+┌──────────────────────────────────────────────────────────────────┐
-- `skills/system-discovery.md`
+│  🖥️ CMDB-ASSISTANT · Machine Sync                                │
-- `skills/mcp-tools-reference.md`
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the synchronization.
+
+Update an existing NetBox device record with the current machine state. Compares local system information with NetBox and applies changes.
 
 ## Usage
 
@@ -25,32 +30,318 @@ Update an existing NetBox device record with the current machine state.
 
 ## Instructions
 
-Execute `skills/visual-header.md` with context "Machine Sync".
+You are synchronizing the current machine's state with its NetBox record. This involves comparing current system state with stored data and updating differences.
 
-Execute `skills/sync-workflow.md` which covers:
+**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference.
-1. Device lookup via MCP
-2. Current state discovery via Bash
-3. Comparison of NetBox vs local state
-4. Diff report generation
-5. User confirmation (unless dry-run)
-6. Apply updates via MCP
-7. Journal entry creation
 
-## Modes
+### Phase 1: Device Lookup (via MCP)
 
-| Mode | Behavior |
+First, find the existing device record:
-|------|----------|
+
-| Default | Show diff, ask confirmation, apply changes |
+```bash
-| `--dry-run` | Show diff only, no changes applied |
+# Get current hostname
-| `--full` | Skip confirmation, update all fields |
+hostname
+```
+
+```
+dcim_list_devices name=<hostname>
+```
+
+**If device not found:**
+- Inform user: "Device '<hostname>' not found in NetBox"
+- Suggest: "Run `/cmdb-register` to register this machine first"
+- Exit sync
+
+**If device found:**
+- Store device ID and all current field values
+- Fetch interfaces: `dcim_list_interfaces device_id=<device_id>`
+- Fetch IPs: `ipam_list_ip_addresses device_id=<device_id>`
+
+Also check for associated clusters/VMs:
+```
+virt_list_clusters  # Look for cluster associated with this device
+virt_list_vms cluster=<cluster_id>  # If cluster found
+```
+
+### Phase 2: Current State Discovery (via Bash)
+
+Gather current system information (same as `/cmdb-register`):
+
+```bash
+# Device info
+hostname
+cat /etc/os-release 2>/dev/null || uname -a
+nproc
+free -m | awk '/Mem:/ {print $2}'
+df -BG / | awk 'NR==2 {print $2}' | tr -d 'G'
+
+# Network interfaces with IPs
+ip -j addr show 2>/dev/null || ip addr show
+
+# Docker containers
+docker ps --format '{"name":"{{.Names}}","image":"{{.Image}}","status":"{{.Status}}"}' 2>/dev/null || echo "[]"
+```
+
+### Phase 3: Comparison
+
+Compare discovered state with NetBox record:
+
+#### 3.1 Device Attributes
+
+| Field | Compare |
+|-------|---------|
+| Platform | OS version changed? |
+| Status | Still active? |
+| Serial | Match? |
+| Description | Keep existing |
+
+#### 3.2 Network Interfaces
+
+| Change Type | Detection |
+|-------------|-----------|
+| New interface | Interface exists locally but not in NetBox |
+| Removed interface | Interface in NetBox but not locally |
+| Changed MAC | MAC address different |
+| Interface type | Type mismatch |
+
+#### 3.3 IP Addresses
+
+| Change Type | Detection |
+|-------------|-----------|
+| New IP | IP exists locally but not in NetBox |
+| Removed IP | IP in NetBox but not locally (on this device) |
+| Primary IP changed | Default route interface changed |
+
+#### 3.4 Docker Containers
+
+| Change Type | Detection |
+|-------------|-----------|
+| New container | Container running locally but no VM in cluster |
+| Stopped container | VM exists but container not running |
+| Resource change | vCPUs/memory different (if trackable) |
+
+### Phase 4: Diff Report
+
+Present changes to user:
+
+```markdown
+## Sync Diff Report
+
+**Device:** <hostname> (ID: <device_id>)
+**NetBox URL:** https://netbox.example.com/dcim/devices/<id>/
+
+### Device Attributes
+| Field | NetBox Value | Current Value | Action |
+|-------|--------------|---------------|--------|
+| Platform | Ubuntu 22.04 | Ubuntu 24.04 | UPDATE |
+| Status | active | active | - |
+
+### Network Interfaces
+
+#### New Interfaces (will create)
+| Interface | Type | MAC | IPs |
+|-----------|------|-----|-----|
+| tailscale0 | virtual | - | 100.x.x.x/32 |
+
+#### Removed Interfaces (will mark offline)
+| Interface | Type | Reason |
+|-----------|------|--------|
+| eth1 | 1000base-t | Not found locally |
+
+#### Changed Interfaces
+| Interface | Field | Old | New |
+|-----------|-------|-----|-----|
+| eth0 | mac_address | aa:bb:cc:00:00:00 | aa:bb:cc:11:11:11 |
+
+### IP Addresses
+
+#### New IPs (will create)
+- 192.168.1.150/24 on eth0
+
+#### Removed IPs (will unassign)
+- 192.168.1.100/24 from eth0
+
+### Docker Containers
+
+#### New Containers (will create VMs)
+| Container | Image | Role |
+|-----------|-------|------|
+| media_lidarr | linuxserver/lidarr | Media Management |
+
+#### Stopped Containers (will mark offline)
+| Container | Last Status |
+|-----------|-------------|
+| media_bazarr | Exited |
+
+### Summary
+- **Updates:** X
+- **Creates:** Y
+- **Removals/Offline:** Z
+```
+
+### Phase 5: User Confirmation
+
+If not `--dry-run`:
+
+```
+The following changes will be applied:
+- Update device platform to "Ubuntu 24.04"
+- Create interface "tailscale0"
+- Create IP "100.x.x.x/32" on tailscale0
+- Create VM "media_lidarr" in cluster
+- Mark VM "media_bazarr" as offline
+
+Proceed with sync? [Y/n]
+```
+
+**Use AskUserQuestion** to get confirmation.
+
+### Phase 6: Apply Updates (via MCP)
+
+Only if user confirms (or `--full` specified):
+
+#### 6.1 Device Updates
+
+```
+dcim_update_device
+  id=<device_id>
+  platform=<new_platform_id>
+  # ... other changed fields
+```
+
+#### 6.2 Interface Updates
+
+**For new interfaces:**
+```
+dcim_create_interface
+  device=<device_id>
+  name=<interface_name>
+  type=<type>
+  mac_address=<mac>
+  enabled=true
+```
+
+**For removed interfaces:**
+```
+dcim_update_interface
+  id=<interface_id>
+  enabled=false
+  description="Marked offline by cmdb-sync - interface no longer present"
+```
+
+**For changed interfaces:**
+```
+dcim_update_interface
+  id=<interface_id>
+  mac_address=<new_mac>
+```
+
+#### 6.3 IP Address Updates
+
+**For new IPs:**
+```
+ipam_create_ip_address
+  address=<ip/prefix>
+  assigned_object_type="dcim.interface"
+  assigned_object_id=<interface_id>
+  status="active"
+```
+
+**For removed IPs:**
+```
+ipam_update_ip_address
+  id=<ip_id>
+  assigned_object_type=null
+  assigned_object_id=null
+  description="Unassigned by cmdb-sync"
+```
+
+#### 6.4 Primary IP Update
+
+If primary IP changed:
+```
+dcim_update_device
+  id=<device_id>
+  primary_ip4=<new_primary_ip_id>
+```
+
+#### 6.5 Container/VM Updates
+
+**For new containers:**
+```
+virt_create_vm
+  name=<container_name>
+  cluster=<cluster_id>
+  status="active"
+  # ... other fields
+```
+
+**For stopped containers:**
+```
+virt_update_vm
+  id=<vm_id>
+  status="offline"
+  description="Container stopped - detected by cmdb-sync"
+```
+
+### Phase 7: Journal Entry
+
+Document the sync:
+
+```
+extras_create_journal_entry
+  assigned_object_type="dcim.device"
+  assigned_object_id=<device_id>
+  comments="Device synced via /cmdb-sync command\n\nChanges applied:\n- <list of changes>"
+```
+
+### Phase 8: Summary Report
+
+```markdown
+## Sync Complete
+
+**Device:** <hostname>
+**Sync Time:** <timestamp>
+
+### Changes Applied
+- Updated platform: Ubuntu 22.04 → Ubuntu 24.04
+- Created interface: tailscale0 (ID: X)
+- Created IP: 100.x.x.x/32 (ID: Y)
+- Created VM: media_lidarr (ID: Z)
+- Marked VM offline: media_bazarr (ID: W)
+
+### Current State
+- **Interfaces:** 4 (3 active, 1 offline)
+- **IP Addresses:** 5
+- **Containers/VMs:** 8 (7 active, 1 offline)
+
+### Next Sync
+Run `/cmdb-sync` again after:
+- Adding/removing Docker containers
+- Changing network configuration
+- OS upgrades
+```
+
+## Dry Run Mode
+
+If `--dry-run` specified:
+- Complete Phase 1-4 (lookup, discovery, compare, diff report)
+- Skip Phase 5-8 (no confirmation, no updates, no journal)
+- End with: "Dry run complete. No changes applied. Run without --dry-run to apply."
+
+## Full Sync Mode
+
+If `--full` specified:
+- Skip user confirmation
+- Update all fields even if unchanged (force refresh)
+- Useful for ensuring NetBox matches current state exactly
 
 ## Error Handling
 
-| Error | Action |
+- **Device not found:** Suggest `/cmdb-register`
-|-------|--------|
+- **Permission denied on updates:** Note which failed, continue with others
-| Device not found | Suggest `/cmdb-register` |
+- **Cluster not found:** Offer to create or skip container sync
-| Permission denied | Note which failed, continue others |
+- **API errors:** Log error, continue with remaining updates
-| Cluster not found | Offer to create or skip container sync |
 
 ## User Request
 

plugins/cmdb-assistant/commands/cmdb-topology.md

@@ -4,14 +4,20 @@ description: Generate infrastructure topology diagrams from NetBox data
 
 # CMDB Topology Visualization
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Topology                                    │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the visualization.
+
 Generate Mermaid diagrams showing infrastructure topology from NetBox.
 
-## Skills to Load
-
-- `skills/visual-header.md`
-- `skills/topology-generation.md`
-- `skills/mcp-tools-reference.md`
-
 ## Usage
 
 ```
@@ -20,34 +26,168 @@ Generate Mermaid diagrams showing infrastructure topology from NetBox.
 
 **Views:**
 - `rack <rack-name>` - Rack elevation showing devices and positions
-- `network [site]` - Network topology showing device connections
+- `network [site]` - Network topology showing device connections via cables
 - `site <site-name>` - Site overview with racks and device counts
 - `full` - Full infrastructure overview
 
 ## Instructions
 
-Execute `skills/visual-header.md` with context "Topology".
+You are a topology visualization assistant that queries NetBox and generates Mermaid diagrams.
 
-Execute `skills/topology-generation.md` which covers:
+### View: Rack Elevation
-- Data collection via MCP for each view type
-- Mermaid diagram generation with proper shapes
-- Legend and data notes
 
-## Output Format
+Generate a rack view showing devices and their positions.
+
+**Data Collection:**
+1. Use `dcim_list_racks` to find the rack by name
+2. Use `dcim_list_devices` with `rack_id` filter to get devices in rack
+3. For each device, note: `position`, `u_height`, `face`, `name`, `role`
+
+**Mermaid Output:**
+
+```mermaid
+graph TB
+    subgraph rack["Rack: <rack-name> (U<height>)"]
+        direction TB
+        u42["U42: empty"]
+        u41["U41: empty"]
+        u40["U40: server-01 (Server)"]
+        u39["U39: server-01 (cont.)"]
+        u38["U38: switch-01 (Switch)"]
+        %% ... continue for all units
+    end
+```
+
+**For devices spanning multiple U:**
+- Mark the top U with device name and role
+- Mark subsequent Us as "(cont.)" for the same device
+- Empty Us should show "empty"
+
+### View: Network Topology
+
+Generate a network diagram showing device connections.
+
+**Data Collection:**
+1. Use `dcim_list_sites` if no site specified (get all)
+2. Use `dcim_list_devices` with optional `site_id` filter
+3. Use `dcim_list_cables` to get all connections
+4. Use `dcim_list_interfaces` for each device to understand port names
+
+**Mermaid Output:**
+
+```mermaid
+graph TD
+    subgraph site1["Site: Home"]
+        router1[("core-router-01<br/>Router")]
+        switch1[["dist-switch-01<br/>Switch"]]
+        server1["web-server-01<br/>Server"]
+        server2["db-server-01<br/>Server"]
+    end
+
+    router1 -->|"eth0 - eth1"| switch1
+    switch1 -->|"gi0/1 - eth0"| server1
+    switch1 -->|"gi0/2 - eth0"| server2
+```
+
+**Node shapes by role:**
+- Router: `[(" ")]` (cylinder/database shape)
+- Switch: `[[ ]]` (double brackets)
+- Server: `[ ]` (rectangle)
+- Firewall: `{{ }}` (hexagon)
+- Other: `[ ]` (rectangle)
+
+**Edge labels:** Show interface names on both ends (A-side - B-side)
+
+### View: Site Overview
+
+Generate a site-level view showing racks and summary counts.
+
+**Data Collection:**
+1. Use `dcim_get_site` to get site details
+2. Use `dcim_list_racks` with `site_id` filter
+3. Use `dcim_list_devices` with `site_id` filter for counts per rack
+
+**Mermaid Output:**
+
+```mermaid
+graph TB
+    subgraph site["Site: Headquarters"]
+        subgraph row1["Row 1"]
+            rack1["Rack A1<br/>12/42 U used<br/>5 devices"]
+            rack2["Rack A2<br/>20/42 U used<br/>8 devices"]
+        end
+        subgraph row2["Row 2"]
+            rack3["Rack B1<br/>8/42 U used<br/>3 devices"]
+        end
+    end
+```
+
+### View: Full Infrastructure
+
+Generate a high-level view of all sites and their relationships.
+
+**Data Collection:**
+1. Use `dcim_list_regions` to get hierarchy
+2. Use `dcim_list_sites` to get all sites
+3. Use `dcim_list_devices` with status filter for counts
+
+**Mermaid Output:**
+
+```mermaid
+graph TB
+    subgraph region1["Region: Americas"]
+        site1["Headquarters<br/>3 racks, 25 devices"]
+        site2["Branch Office<br/>1 rack, 5 devices"]
+    end
+    subgraph region2["Region: Europe"]
+        site3["EU Datacenter<br/>10 racks, 100 devices"]
+    end
+
+    site1 -.->|"WAN Link"| site3
+```
+
+### Output Format
 
 Always provide:
-1. **Summary** - Brief description
+
-2. **Mermaid Code Block** - The diagram
+1. **Summary** - Brief description of what the diagram shows
-3. **Legend** - Shape explanations
+2. **Mermaid Code Block** - The diagram code in a fenced code block
-4. **Data Notes** - Quality issues found
+3. **Legend** - Explanation of shapes and colors used
+4. **Data Notes** - Any data quality issues (e.g., devices without position, missing cables)
+
+**Example Output:**
+
+```markdown
+## Network Topology: Home Site
+
+This diagram shows the network connections between 4 devices at the Home site.
+
+```mermaid
+graph TD
+    router1[("core-router<br/>Router")]
+    switch1[["main-switch<br/>Switch"]]
+    server1["homelab-01<br/>Server"]
+
+    router1 -->|"eth0 - gi0/24"| switch1
+    switch1 -->|"gi0/1 - eth0"| server1
+```
+
+**Legend:**
+- Cylinder shape: Routers
+- Double brackets: Switches
+- Rectangle: Servers
+
+**Data Notes:**
+- 1 device (nas-01) has no cable connections documented
+```
 
 ## Examples
 
-- `/cmdb-topology rack server-rack-01` - Rack elevation
+- `/cmdb-topology rack server-rack-01` - Show devices in server-rack-01
-- `/cmdb-topology network` - All network connections
+- `/cmdb-topology network` - Show all network connections
-- `/cmdb-topology network Home` - Network for Home site
+- `/cmdb-topology network Home` - Show network topology for Home site only
-- `/cmdb-topology site Headquarters` - Site overview
+- `/cmdb-topology site Headquarters` - Show rack overview for Headquarters
-- `/cmdb-topology full` - Full infrastructure
+- `/cmdb-topology full` - Show full infrastructure overview
 
 ## User Request
 

plugins/cmdb-assistant/commands/initial-setup.md

@@ -1,74 +1,176 @@
 ---
-description: Interactive setup wizard for cmdb-assistant plugin
+description: Interactive setup wizard for cmdb-assistant plugin - configures NetBox MCP server
 ---
 
 # CMDB Assistant Setup Wizard
 
-Configure the cmdb-assistant plugin with NetBox integration.
+## Visual Output
 
-## Skills to Load
+When executing this command, display the plugin header:
 
-- `skills/visual-header.md`
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Setup Wizard                                │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the setup.
+
+This command sets up the cmdb-assistant plugin with NetBox integration.
 
 ## Important Context
 
-- **Uses Bash, Read, Write, AskUserQuestion tools** - NOT MCP tools
+- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools
-- **MCP tools unavailable until after setup + session restart**
+- **MCP tools won't work until after setup + session restart**
+- **Uses NetBox MCP server (separate from Gitea MCP)**
 
-## Usage
+---
 
-```
+## Phase 1: Environment Validation
-/initial-setup
-```
 
-## Instructions
+### Step 1.1: Check Python Version
-
-Execute `skills/visual-header.md` with context "Setup Wizard".
-
-### Phase 1: Environment Validation
 
 ```bash
 python3 --version
 ```
-If below 3.10, stop and inform user.
 
-### Phase 2: MCP Server Setup
+If below 3.10, stop setup and inform user.
 
-1. Locate NetBox MCP server in marketplace
+---
-2. Check virtual environment exists
-3. Create venv if missing: `python3 -m venv .venv && pip install -r requirements.txt`
 
-### Phase 3: System Configuration
+## Phase 2: MCP Server Setup
 
-1. Create config directory: `mkdir -p ~/.config/claude`
+### Step 2.1: Locate NetBox MCP Server
-2. Check `~/.config/claude/netbox.env` exists
-3. If missing, ask user for NetBox API URL (must include `/api`)
-4. Create config file with placeholder token
-5. Instruct user to add API token manually
 
-### Phase 4: Validation
+```bash
-
+find ~/.claude ~/.config/claude -name "mcp_server" -path "*netbox*" 2>/dev/null | head -5
-1. Test API connection if token was added
-2. Report result (200=success, 403=invalid token)
-3. Display completion summary
-4. Remind user to restart session for MCP tools
-
-## Completion Summary
-
-```
-CMDB-ASSISTANT SETUP COMPLETE
-MCP Server (NetBox):   Ready
-System Config:         ~/.config/claude/netbox.env
-
-Restart your Claude Code session for MCP tools.
-
-After restart, try:
-- /cmdb-device <hostname>
-- /cmdb-ip <address>
-- /cmdb-site <name>
-- /cmdb-search <query>
 ```
 
-## User Request
+If not found, ask user for marketplace location.
 
-$ARGUMENTS
+### Step 2.2: Check Virtual Environment
+
+```bash
+ls -la /path/to/mcp-servers/netbox/.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/netbox && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate
+```
+
+---
+
+## Phase 3: System Configuration
+
+### Step 3.1: Create Config Directory
+
+```bash
+mkdir -p ~/.config/claude
+```
+
+### Step 3.2: Check NetBox Configuration
+
+```bash
+cat ~/.config/claude/netbox.env 2>/dev/null || echo "FILE_NOT_FOUND"
+```
+
+**If file exists with valid values:** Skip to Phase 4.
+**If missing or has placeholders:** Continue.
+
+### Step 3.3: Gather NetBox Information
+
+Use AskUserQuestion:
+- Question: "What is your NetBox API URL? (e.g., https://netbox.company.com/api)"
+- Header: "NetBox URL"
+- Options:
+  - "Other (I'll provide the URL)"
+
+Ask user to provide the URL.
+
+**Important:** The URL must include `/api` at the end. If the user provides a URL without `/api`, append it automatically.
+
+### Step 3.4: Create Configuration File
+
+```bash
+cat > ~/.config/claude/netbox.env << 'EOF'
+# NetBox API Configuration
+# Generated by cmdb-assistant /initial-setup
+
+NETBOX_API_URL=<USER_PROVIDED_URL>
+NETBOX_API_TOKEN=PASTE_YOUR_TOKEN_HERE
+EOF
+chmod 600 ~/.config/claude/netbox.env
+```
+
+### Step 3.5: Token Instructions
+
+---
+
+**Action Required: Add Your NetBox API Token**
+
+I've created `~/.config/claude/netbox.env` but you need to add your API token manually.
+
+**Steps:**
+1. Open: `nano ~/.config/claude/netbox.env`
+2. Generate token in NetBox: Admin → API Tokens → Add Token
+3. Replace `PASTE_YOUR_TOKEN_HERE` with your token
+4. Save the file
+
+---
+
+Use AskUserQuestion:
+- Question: "Have you added your NetBox token?"
+- Header: "Token"
+- Options:
+  - "Yes, I've added the token"
+  - "Skip for now"
+
+---
+
+## Phase 4: Validation
+
+### Step 4.1: Test Configuration (if token was added)
+
+```bash
+source ~/.config/claude/netbox.env && curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Token $NETBOX_API_TOKEN" "$NETBOX_API_URL/"
+```
+
+**Note:** The URL already includes `/api`, so we just append `/` for the root API endpoint.
+
+Report result:
+- 200: Success
+- 403: Invalid token
+- Other: Connection issue
+
+### Step 4.2: Summary
+
+```
+╔════════════════════════════════════════════════════════════╗
+║              CMDB-ASSISTANT SETUP COMPLETE                 ║
+╠════════════════════════════════════════════════════════════╣
+║ MCP Server (NetBox):   ✓ Ready                             ║
+║ System Config:         ✓ ~/.config/claude/netbox.env       ║
+╚════════════════════════════════════════════════════════════╝
+```
+
+### Step 4.3: Session Restart Notice
+
+---
+
+**⚠️ Session Restart Required**
+
+Restart your Claude Code session for MCP tools to become available.
+
+**After restart, you can:**
+- Run `/cmdb-device <hostname>` to look up a device
+- Run `/cmdb-ip <address>` to look up an IP address
+- Run `/cmdb-site <name>` to look up a site
+- Run `/cmdb-search <query>` for general search
+
+---
+
+## Note on Project Configuration
+
+cmdb-assistant does not require project-level configuration. The NetBox connection is system-wide and not tied to specific repositories.

plugins/cmdb-assistant/commands/ip-conflicts.md

@@ -4,14 +4,20 @@ description: Detect IP address conflicts and overlapping prefixes in NetBox
 
 # CMDB IP Conflict Detection
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · IP Conflict Detection                       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the analysis.
+
 Scan NetBox IPAM data to identify IP address conflicts and overlapping prefixes.
 
-## Skills to Load
-
-- `skills/visual-header.md`
-- `skills/ip-management.md`
-- `skills/mcp-tools-reference.md`
-
 ## Usage
 
 ```
@@ -27,31 +33,205 @@ Scan NetBox IPAM data to identify IP address conflicts and overlapping prefixes.
 
 ## Instructions
 
-Execute `skills/visual-header.md` with context "IP Conflict Detection".
+You are an IP conflict detection specialist that analyzes NetBox IPAM data for conflicts and issues.
 
-Execute conflict detection from `skills/ip-management.md`:
+### Conflict Types to Detect
 
-1. **Data Collection** - Fetch IPs, prefixes, VRFs via MCP
+#### 1. Duplicate IP Addresses
-2. **Duplicate Detection** - Group by address+VRF, flag >1 record
-3. **Overlap Detection** - Compare prefixes pairwise using CIDR math
-4. **Orphan IP Detection** - Find IPs without containing prefix
-5. **Generate Report** - Use template from skill
 
-## Conflict Types
+Multiple IP address records with the same address (within same VRF).
 
-| Type | Severity |
+**Detection:**
-|------|----------|
+1. Use `ipam_list_ip_addresses` to get all addresses
-| Duplicate IP (same interface type) | CRITICAL |
+2. Group by address + VRF combination
-| Duplicate IP (different roles) | HIGH |
+3. Flag groups with more than one record
-| Overlapping prefixes (same status) | HIGH |
+
-| Overlapping prefixes (container ok) | LOW |
+**Exception:** Anycast addresses may legitimately appear multiple times - check the `role` field for "anycast".
-| Orphan IP | MEDIUM |
+
+#### 2. Overlapping Prefixes
+
+Prefixes that contain the same address space (within same VRF).
+
+**Detection:**
+1. Use `ipam_list_prefixes` to get all prefixes
+2. For each prefix pair in the same VRF, check if one contains the other
+3. Legitimate hierarchies should have proper parent-child relationships
+
+**Legitimate Overlaps:**
+- Parent/child prefix hierarchy (e.g., 10.0.0.0/8 contains 10.0.1.0/24)
+- Different VRFs (isolated routing tables)
+- Marked as "container" status
+
+#### 3. IPs Outside Their Prefix
+
+IP addresses that don't fall within any defined prefix.
+
+**Detection:**
+1. For each IP address, find the most specific prefix that contains it
+2. Flag IPs with no matching prefix
+
+#### 4. Prefix Overlap Across VRFs (Informational)
+
+Same prefix appearing in multiple VRFs - not necessarily a conflict, but worth noting.
+
+### MCP Tools
+
+- `ipam_list_ip_addresses` - Get all IP addresses with filters:
+  - `address` - Filter by specific address
+  - `vrf_id` - Filter by VRF
+  - `parent` - Filter by parent prefix
+  - `status` - Filter by status
+
+- `ipam_list_prefixes` - Get all prefixes with filters:
+  - `prefix` - Filter by prefix CIDR
+  - `vrf_id` - Filter by VRF
+  - `within` - Find prefixes within a parent
+  - `contains` - Find prefixes containing an address
+
+- `ipam_list_vrfs` - List VRFs for context
+- `ipam_get_ip_address` - Get detailed IP info including assigned device/interface
+- `ipam_get_prefix` - Get detailed prefix info
+
+### Workflow
+
+1. **Data Collection**
+   - Fetch all IP addresses (or filtered set)
+   - Fetch all prefixes (or filtered set)
+   - Fetch VRFs for context
+
+2. **Duplicate Detection**
+   - Build address map: `{address+vrf: [records]}`
+   - Filter for entries with >1 record
+
+3. **Overlap Detection**
+   - For each VRF, compare prefixes pairwise
+   - Check using CIDR math: does prefix A contain prefix B or vice versa?
+   - Ignore legitimate hierarchies (status=container)
+
+4. **Orphan IP Detection**
+   - For each IP, find containing prefix
+   - Flag IPs with no prefix match
+
+5. **Generate Report**
+
+### Report Format
+
+```markdown
+## IP Conflict Detection Report
+
+**Generated:** [timestamp]
+**Scope:** [scope parameter]
+
+### Summary
+
+| Check | Status | Count |
+|-------|--------|-------|
+| Duplicate IPs | [PASS/FAIL] | X |
+| Overlapping Prefixes | [PASS/FAIL] | Y |
+| Orphan IPs | [PASS/FAIL] | Z |
+| Total Issues | - | N |
+
+### Critical Issues
+
+#### Duplicate IP Addresses
+
+| Address | VRF | Count | Assigned To |
+|---------|-----|-------|-------------|
+| 10.0.1.50/24 | Global | 2 | server-01 (eth0), server-02 (eth0) |
+| 192.168.1.100/24 | Global | 2 | router-01 (gi0/1), switch-01 (vlan10) |
+
+**Impact:** IP conflicts cause network connectivity issues. Devices will have intermittent connectivity.
+
+**Resolution:**
+- Determine which device should have the IP
+- Update or remove the duplicate assignment
+- Consider IP reservation to prevent future conflicts
+
+#### Overlapping Prefixes
+
+| Prefix 1 | Prefix 2 | VRF | Type |
+|----------|----------|-----|------|
+| 10.0.0.0/24 | 10.0.0.0/25 | Global | Unstructured overlap |
+| 192.168.0.0/16 | 192.168.1.0/24 | Production | Missing container flag |
+
+**Impact:** Overlapping prefixes can cause routing ambiguity and IP management confusion.
+
+**Resolution:**
+- For legitimate hierarchies: Mark parent prefix as status="container"
+- For accidental overlaps: Consolidate or re-address one prefix
+
+### Warnings
+
+#### IPs Without Prefix
+
+| Address | VRF | Assigned To | Nearest Prefix |
+|---------|-----|-------------|----------------|
+| 172.16.5.10/24 | Global | server-03 (eth0) | None found |
+
+**Impact:** IPs without a prefix bypass IPAM allocation controls.
+
+**Resolution:**
+- Create appropriate prefix to contain the IP
+- Or update IP to correct address within existing prefix
+
+### Informational
+
+#### Same Prefix in Multiple VRFs
+
+| Prefix | VRFs | Purpose |
+|--------|------|---------|
+| 10.0.0.0/24 | Global, DMZ, Internal | [Check if intentional] |
+
+### Statistics
+
+| Metric | Value |
+|--------|-------|
+| Total IP Addresses | X |
+| Total Prefixes | Y |
+| Total VRFs | Z |
+| Utilization (IPs/Prefix space) | W% |
+
+### Remediation Commands
+
+```
+# Remove duplicate IP (keep server-01's assignment)
+ipam_delete_ip_address id=123
+
+# Mark prefix as container
+ipam_update_prefix id=456 status=container
+
+# Create missing prefix for orphan IP
+ipam_create_prefix prefix=172.16.5.0/24 status=active
+```
+```
+
+### CIDR Math Reference
+
+For overlap detection, use these rules:
+- Prefix A **contains** Prefix B if: A.network <= B.network AND A.broadcast >= B.broadcast
+- Two prefixes **overlap** if: A.network <= B.broadcast AND B.network <= A.broadcast
+
+**Example:**
+- 10.0.0.0/8 contains 10.0.1.0/24 (legitimate hierarchy)
+- 10.0.0.0/24 and 10.0.0.128/25 overlap (10.0.0.128/25 is within 10.0.0.0/24)
+
+### Severity Levels
+
+| Issue | Severity | Description |
+|-------|----------|-------------|
+| Duplicate IP (same interface type) | CRITICAL | Active conflict, causes outages |
+| Duplicate IP (different roles) | HIGH | Potential conflict |
+| Overlapping prefixes (same status) | HIGH | IPAM management issue |
+| Overlapping prefixes (container ok) | LOW | May need status update |
+| Orphan IP | MEDIUM | Bypasses IPAM controls |
 
 ## Examples
 
-- `/ip-conflicts` - Full scan
+- `/ip-conflicts` - Full scan for all conflicts
-- `/ip-conflicts addresses` - Duplicate IPs only
+- `/ip-conflicts addresses` - Check only for duplicate IPs
-- `/ip-conflicts vrf Production` - Scan specific VRF
+- `/ip-conflicts prefixes` - Check only for overlapping prefixes
+- `/ip-conflicts vrf Production` - Scan only Production VRF
+- `/ip-conflicts prefix 10.0.0.0/8` - Scan within specific prefix range
 
 ## User Request
 

plugins/cmdb-assistant/hooks/hooks.json

@@ -2,13 +2,8 @@
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "",
+        "type": "command",
-        "hooks": [
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/startup-check.sh"
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/startup-check.sh"
-          }
-        ]
       }
     ],
     "PreToolUse": [

plugins/cmdb-assistant/hooks/startup-check.sh

@@ -25,24 +25,11 @@ if [[ -z "${NETBOX_API_URL:-}" ]] || [[ -z "${NETBOX_API_TOKEN:-}" ]]; then
     exit 0
 fi
 
-# Helper function to make authenticated API calls
-# Token passed via curl config to avoid exposure in process listings
-netbox_curl() {
-    local url="$1"
-    curl -s -K - <<EOF 2>/dev/null
--H "Authorization: Token ${NETBOX_API_TOKEN}"
--H "Accept: application/json"
-url = "${url}"
-EOF
-}
-
 # Quick API connectivity test (5s timeout)
-HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 5 -K - <<EOF 2>/dev/null || echo "000"
+HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 5 \
--H "Authorization: Token ${NETBOX_API_TOKEN}"
+    -H "Authorization: Token $NETBOX_API_TOKEN" \
--H "Accept: application/json"
+    -H "Accept: application/json" \
-url = "${NETBOX_API_URL}/"
+    "${NETBOX_API_URL}/" 2>/dev/null || echo "000")
-EOF
-)
 
 if [[ "$HTTP_CODE" == "000" ]]; then
     echo "$PREFIX NetBox API unreachable (timeout/connection error)"
@@ -53,12 +40,10 @@ elif [[ "$HTTP_CODE" != "200" ]]; then
 fi
 
 # Check for VMs without site assignment (data quality)
-VMS_RESPONSE=$(curl -s -m 5 -K - <<EOF 2>/dev/null || echo '{"count":0}'
+VMS_RESPONSE=$(curl -s -m 5 \
--H "Authorization: Token ${NETBOX_API_TOKEN}"
+    -H "Authorization: Token $NETBOX_API_TOKEN" \
--H "Accept: application/json"
+    -H "Accept: application/json" \
-url = "${NETBOX_API_URL}/virtualization/virtual-machines/?site__isnull=true&limit=1"
+    "${NETBOX_API_URL}/virtualization/virtual-machines/?site__isnull=true&limit=1" 2>/dev/null || echo '{"count":0}')
-EOF
-)
 
 VMS_NO_SITE=$(echo "$VMS_RESPONSE" | grep -o '"count":[0-9]*' | cut -d: -f2 || echo "0")
 
@@ -67,12 +52,10 @@ if [[ "$VMS_NO_SITE" -gt 0 ]]; then
 fi
 
 # Check for devices without platform
-DEVICES_RESPONSE=$(curl -s -m 5 -K - <<EOF 2>/dev/null || echo '{"count":0}'
+DEVICES_RESPONSE=$(curl -s -m 5 \
--H "Authorization: Token ${NETBOX_API_TOKEN}"
+    -H "Authorization: Token $NETBOX_API_TOKEN" \
--H "Accept: application/json"
+    -H "Accept: application/json" \
-url = "${NETBOX_API_URL}/dcim/devices/?platform__isnull=true&limit=1"
+    "${NETBOX_API_URL}/dcim/devices/?platform__isnull=true&limit=1" 2>/dev/null || echo '{"count":0}')
-EOF
-)
 
 DEVICES_NO_PLATFORM=$(echo "$DEVICES_RESPONSE" | grep -o '"count":[0-9]*' | cut -d: -f2 || echo "0")
 

plugins/cmdb-assistant/mcp-servers/netbox

@@ -0,0 +1 @@
+../../../mcp-servers/netbox

plugins/cmdb-assistant/skills/audit-workflow.md

@@ -1,163 +0,0 @@
-# Audit Workflow Skill
-
-How to audit NetBox data quality.
-
-## Prerequisites
-
-Load these skills:
-- `netbox-patterns` - Best practices reference
-- `mcp-tools-reference` - MCP tool reference
-
-## Data Collection
-
-```
-virt_list_vms
-dcim_list_devices
-virt_list_clusters
-dcim_list_sites
-tenancy_list_tenants
-dcim_list_device_roles
-dcim_list_platforms
-```
-
-## Quality Checks by Severity
-
-### CRITICAL (must fix immediately)
-
-| Check | Detection |
-|-------|-----------|
-| VMs without cluster | `cluster` is null AND `site` is null |
-| Devices without site | `site` is null |
-| Active devices without primary IP | `status=active` AND `primary_ip4` is null AND `primary_ip6` is null |
-
-### HIGH (should fix soon)
-
-| Check | Detection |
-|-------|-----------|
-| VMs without site | No site (neither direct nor via cluster.site) |
-| VMs without tenant | `tenant` is null |
-| Devices without platform | `platform` is null |
-| Clusters not scoped to site | `site` is null on cluster |
-| VMs without role | `role` is null |
-
-### MEDIUM (plan to address)
-
-| Check | Detection |
-|-------|-----------|
-| Inconsistent naming | Names don't match patterns |
-| Role fragmentation | >10 device roles with <3 assignments each |
-| Missing tags on production | Active resources without tags |
-| Mixed naming separators | Some `_`, others `-` |
-
-### LOW (informational)
-
-| Check | Detection |
-|-------|-----------|
-| Docker containers as VMs | Cluster type is "Docker Compose" |
-| VMs without description | `description` is empty |
-| Sites without physical address | `physical_address` is empty |
-| Devices without serial | `serial` is empty |
-
-## Naming Convention Analysis
-
-### Expected Patterns
-
-| Object Type | Pattern | Example |
-|-------------|---------|---------|
-| Devices | `{role}-{location}-{number}` | `web-dc1-01` |
-| VMs | `{env}-{app}-{number}` | `prod-api-01` |
-| Clusters | `{site}-{type}` | `home-docker` |
-
-### Analysis Steps
-
-1. Extract naming patterns from existing objects
-2. Identify dominant patterns (most common)
-3. Flag outliers that don't match
-4. Suggest standardization
-
-## Role Fragmentation Analysis
-
-### Red Flags
-
-- More than 15 highly specific roles
-- Roles with technology in name (use platform instead)
-- Roles that duplicate functionality
-- Single-use roles (only 1 device/VM)
-
-### Recommended Consolidation
-
-Use general roles + platform/tags for specificity:
-- Instead of `nginx-web-server`, use `web-server` + platform `nginx`
-
-## Report Template
-
-```markdown
-## CMDB Data Quality Audit Report
-
-**Generated:** [timestamp]
-**Scope:** [scope parameter]
-
-### Summary
-
-| Metric | Count |
-|--------|-------|
-| Total VMs | X |
-| Total Devices | Y |
-| Total Clusters | Z |
-| **Total Issues** | **N** |
-
-| Severity | Count |
-|----------|-------|
-| Critical | A |
-| High | B |
-| Medium | C |
-| Low | D |
-
-### Critical Issues
-
-[List each with specific object names and IDs]
-
-- VM `HotServ` (ID: 1) - No cluster or site assignment
-- Device `server-01` (ID: 5) - No site assignment
-
-### High Issues
-
-[List each with specific object names]
-
-### Medium Issues
-
-[Grouped by category with counts]
-
-### Recommendations
-
-1. **[Most impactful fix]** - affects N objects
-2. **[Second priority]** - affects M objects
-
-### Quick Fixes
-
-Commands to fix common issues:
-
-```
-# Assign site to VM
-virt_update_vm id=X site=Y
-
-# Assign platform to device
-dcim_update_device id=X platform=Y
-```
-
-### Next Steps
-
-- Run `/cmdb-register` to properly register new machines
-- Use `/cmdb-sync` to update existing registrations
-- Consider bulk updates via NetBox web UI for >10 items
-```
-
-## Scope-Specific Focus
-
-| Scope | Focus |
-|-------|-------|
-| `all` | Full audit across all categories |
-| `vms` | Virtual Machine checks only |
-| `devices` | Device checks only |
-| `naming` | Naming convention analysis |
-| `roles` | Role fragmentation analysis |

plugins/cmdb-assistant/skills/change-audit.md

@@ -1,130 +0,0 @@
-# Change Audit Skill
-
-Audit NetBox changes for tracking and compliance.
-
-## Prerequisites
-
-Load skill: `mcp-tools-reference`
-
-## MCP Tools
-
-| Tool | Purpose | Parameters |
-|------|---------|------------|
-| `extras_list_object_changes` | List changes | `user_id`, `changed_object_type`, `action` |
-| `extras_get_object_change` | Get change details | `id` |
-
-## Common Object Types
-
-| Category | Object Types |
-|----------|--------------|
-| DCIM | `dcim.device`, `dcim.interface`, `dcim.site`, `dcim.rack`, `dcim.cable` |
-| IPAM | `ipam.ipaddress`, `ipam.prefix`, `ipam.vlan`, `ipam.vrf` |
-| Virtualization | `virtualization.virtualmachine`, `virtualization.cluster` |
-| Tenancy | `tenancy.tenant`, `tenancy.contact` |
-
-## Audit Workflow
-
-1. **Parse user request** - Determine filters
-2. **Query object changes** - `extras_list_object_changes`
-3. **Enrich data** - Fetch detailed records if needed
-4. **Analyze patterns** - Identify bulk operations, unusual activity
-5. **Generate report** - Structured format
-
-## Report Template
-
-```markdown
-## NetBox Change Audit Report
-
-**Generated:** [timestamp]
-**Period:** [date range or "All time"]
-**Filters:** [applied filters]
-
-### Summary
-
-| Metric | Count |
-|--------|-------|
-| Total Changes | X |
-| Creates | Y |
-| Updates | Z |
-| Deletes | W |
-| Unique Users | N |
-| Object Types | M |
-
-### Changes by Action
-
-#### Created Objects (Y)
-
-| Time | User | Object Type | Object | Details |
-|------|------|-------------|--------|---------|
-| 2024-01-15 14:30 | admin | dcim.device | server-01 | Created device |
-
-#### Updated Objects (Z)
-
-| Time | User | Object Type | Object | Changed Fields |
-|------|------|-------------|--------|----------------|
-| 2024-01-15 15:00 | john | ipam.ipaddress | 10.0.1.50/24 | status, description |
-
-#### Deleted Objects (W)
-
-| Time | User | Object Type | Object | Details |
-|------|------|-------------|--------|---------|
-| 2024-01-14 09:00 | admin | dcim.interface | eth2 | Removed from server-01 |
-
-### Changes by User
-
-| User | Creates | Updates | Deletes | Total |
-|------|---------|---------|---------|-------|
-| admin | 5 | 10 | 2 | 17 |
-| john | 3 | 8 | 0 | 11 |
-
-### Changes by Object Type
-
-| Object Type | Creates | Updates | Deletes | Total |
-|-------------|---------|---------|---------|-------|
-| dcim.device | 2 | 5 | 0 | 7 |
-| ipam.ipaddress | 4 | 3 | 1 | 8 |
-
-### Timeline
-
-```
-2024-01-15: ######## 8 changes
-2024-01-14: ####     4 changes
-2024-01-13: ##       2 changes
-```
-
-### Notable Patterns
-
-- **Bulk operations:** [Many changes in short time]
-- **Unusual activity:** [Unexpected deletions, after-hours changes]
-- **Missing audit trail:** [Expected changes not logged]
-
-### Recommendations
-
-1. [Security or process recommendations based on findings]
-```
-
-## Enriching Change Details
-
-For detailed audit, use `extras_get_object_change` to see:
-- `prechange_data` - Object state before change
-- `postchange_data` - Object state after change
-- `request_id` - Links related changes in same request
-
-## Security Audit Mode
-
-When user asks for "security audit" or "compliance report":
-
-1. Focus on deletions and permission-sensitive changes
-2. Highlight changes to critical objects (firewalls, VRFs, prefixes)
-3. Flag changes outside business hours
-4. Identify users with high change counts
-
-## Filter Examples
-
-| Request | Filter |
-|---------|--------|
-| Recent changes | None (last 24 hours default) |
-| Last 7 days | Filter by `time` field |
-| By user | `user_id=<id>` |
-| Device changes | `changed_object_type=dcim.device` |
-| All deletions | `action=delete` |

plugins/cmdb-assistant/skills/device-registration.md

@@ -1,177 +0,0 @@
-# Device Registration Skill
-
-How to register devices into NetBox.
-
-## Prerequisites
-
-Load these skills:
-- `system-discovery` - Bash commands for gathering system info
-- `netbox-patterns` - Best practices for data quality
-- `mcp-tools-reference` - MCP tool reference
-
-## Registration Workflow
-
-### Phase 1: System Discovery
-
-Use commands from `system-discovery` skill to gather:
-- Hostname, OS, hardware model, serial number
-- CPU, memory, disk
-- Network interfaces with IPs
-- Running Docker containers
-
-### Phase 2: Pre-Registration Checks
-
-1. **Check if device exists:**
-   ```
-   dcim_list_devices name=<hostname>
-   ```
-   If exists, suggest `/cmdb-sync` instead.
-
-2. **Verify/Create site:**
-   ```
-   dcim_list_sites name=<site-name>
-   ```
-   If not found, list available sites or offer to create.
-
-3. **Verify/Create platform:**
-   ```
-   dcim_list_platforms name=<platform-name>
-   ```
-   Create if not exists with `dcim_create_platform`.
-
-4. **Verify/Create device role:**
-   ```
-   dcim_list_device_roles name=<role-name>
-   ```
-
-### Phase 3: Device Creation
-
-1. **Get/Create manufacturer and device type:**
-   ```
-   dcim_list_manufacturers name="<manufacturer>"
-   dcim_list_device_types manufacturer_id=X model="<model>"
-   ```
-
-2. **Create device:**
-   ```
-   dcim_create_device
-     name=<hostname>
-     device_type=<device_type_id>
-     role=<role_id>
-     site=<site_id>
-     platform=<platform_id>
-     tenant=<tenant_id>  # if provided
-     serial=<serial>
-     description="Registered via cmdb-assistant"
-   ```
-
-3. **Create interfaces:**
-   For each network interface:
-   ```
-   dcim_create_interface
-     device=<device_id>
-     name=<interface_name>
-     type=<type>
-     mac_address=<mac>
-     enabled=true
-   ```
-
-4. **Create IP addresses:**
-   For each IP:
-   ```
-   ipam_create_ip_address
-     address=<ip/prefix>
-     assigned_object_type="dcim.interface"
-     assigned_object_id=<interface_id>
-     status="active"
-   ```
-
-5. **Set primary IP:**
-   ```
-   dcim_update_device
-     id=<device_id>
-     primary_ip4=<primary_ip_id>
-   ```
-
-### Phase 4: Container Registration (if Docker)
-
-1. **Create/Get cluster type:**
-   ```
-   virt_list_cluster_types name="Docker Compose"
-   virt_create_cluster_type name="Docker Compose" slug="docker-compose"
-   ```
-
-2. **Create cluster:**
-   ```
-   virt_create_cluster
-     name=<project-name>
-     type=<cluster_type_id>
-     site=<site_id>
-     description="Docker Compose stack on <hostname>"
-   ```
-
-3. **Create VMs for containers:**
-   For each running container:
-   ```
-   virt_create_vm
-     name=<container_name>
-     cluster=<cluster_id>
-     site=<site_id>
-     role=<role_id>
-     status="active"
-     vcpus=<cpu_shares>
-     memory=<memory_mb>
-     disk=<disk_gb>
-   ```
-
-### Phase 5: Documentation
-
-Add journal entry:
-```
-extras_create_journal_entry
-  assigned_object_type="dcim.device"
-  assigned_object_id=<device_id>
-  comments="Device registered via /cmdb-register command\n\nDiscovered:\n- X network interfaces\n- Y IP addresses\n- Z Docker containers"
-```
-
-## Summary Report Template
-
-```markdown
-## Machine Registration Complete
-
-### Device Created
-- **Name:** <hostname>
-- **Site:** <site>
-- **Platform:** <platform>
-- **Role:** <role>
-- **ID:** <device_id>
-- **URL:** https://netbox.example.com/dcim/devices/<id>/
-
-### Network Interfaces
-| Interface | Type | MAC | IP Address |
-|-----------|------|-----|------------|
-| eth0 | 1000base-t | aa:bb:cc:dd:ee:ff | 192.168.1.100/24 |
-
-### Primary IP: 192.168.1.100
-
-### Docker Containers Registered (if applicable)
-**Cluster:** <cluster_name> (ID: <cluster_id>)
-
-| Container | Role | vCPUs | Memory | Status |
-|-----------|------|-------|--------|--------|
-| media_jellyfin | Media Server | 2.0 | 2048MB | Active |
-
-### Next Steps
-- Run `/cmdb-sync` periodically to keep data current
-- Run `/cmdb-audit` to check data quality
-- Add tags for classification
-```
-
-## Error Handling
-
-| Error | Action |
-|-------|--------|
-| Device already exists | Suggest `/cmdb-sync` or ask to proceed |
-| Site not found | List available sites, offer to create new |
-| Docker not available | Skip container registration, note in summary |
-| Permission denied | Note which operations failed, suggest fixes |

plugins/cmdb-assistant/skills/ip-management.md

@@ -1,162 +0,0 @@
-# IP Management Skill
-
-IP address and prefix management in NetBox.
-
-## Prerequisites
-
-Load skill: `mcp-tools-reference`
-
-## IPAM Operations
-
-### Prefix Management
-
-| Action | Tool | Key Parameters |
-|--------|------|----------------|
-| List prefixes | `ipam_list_prefixes` | `prefix`, `vrf_id`, `within`, `contains` |
-| Get details | `ipam_get_prefix` | `id` |
-| Find available child | `ipam_list_available_prefixes` | `prefix_id` |
-| Create prefix | `ipam_create_prefix` | `prefix`, `status`, `site`, `vrf` |
-| Allocate child | `ipam_create_available_prefix` | `prefix_id`, `prefix_length` |
-
-### IP Address Management
-
-| Action | Tool | Key Parameters |
-|--------|------|----------------|
-| List IPs | `ipam_list_ip_addresses` | `address`, `vrf_id`, `device_id` |
-| Get details | `ipam_get_ip_address` | `id` |
-| Find available | `ipam_list_available_ips` | `prefix_id` |
-| Create IP | `ipam_create_ip_address` | `address`, `assigned_object_type`, `assigned_object_id` |
-| Allocate next | `ipam_create_available_ip` | `prefix_id` |
-| Assign to interface | `ipam_update_ip_address` | `id`, `assigned_object_id` |
-
-### VLAN and VRF
-
-| Action | Tool |
-|--------|------|
-| List VLANs | `ipam_list_vlans` |
-| Get VLAN | `ipam_get_vlan` |
-| Create VLAN | `ipam_create_vlan` |
-| List VRFs | `ipam_list_vrfs` |
-| Get VRF | `ipam_get_vrf` |
-
-## IP Allocation Workflow
-
-1. **Find available IPs in target prefix:**
-   ```
-   ipam_list_available_ips prefix_id=<id>
-   ```
-
-2. **Create the IP address:**
-   ```
-   ipam_create_ip_address
-     address=<ip/prefix>
-     assigned_object_type="dcim.interface"
-     assigned_object_id=<interface_id>
-     status="active"
-   ```
-
-3. **Set as primary (if needed):**
-   ```
-   dcim_update_device id=<device_id> primary_ip4=<ip_id>
-   ```
-
-## IP Conflict Detection
-
-### Conflict Types
-
-1. **Duplicate IP Addresses**
-   - Multiple records with same address in same VRF
-   - Exception: Anycast addresses (check `role` field)
-
-2. **Overlapping Prefixes**
-   - Prefixes containing same address space in same VRF
-   - Legitimate: Parent/child hierarchy, different VRFs, "container" status
-
-3. **IPs Outside Prefix**
-   - IP addresses not within any defined prefix
-
-4. **Same Prefix in Multiple VRFs** (informational)
-
-### Detection Workflow
-
-1. **Duplicate Detection:**
-   - Get all addresses: `ipam_list_ip_addresses`
-   - Group by address + VRF
-   - Flag groups with >1 record
-
-2. **Overlap Detection:**
-   - Get all prefixes: `ipam_list_prefixes`
-   - For each VRF, compare prefixes pairwise
-   - Check if prefix A contains prefix B or vice versa
-   - Ignore legitimate hierarchies (status=container)
-
-3. **Orphan IP Detection:**
-   - For each IP, find containing prefix
-   - Flag IPs with no prefix match
-
-### CIDR Math Rules
-
-- Prefix A **contains** Prefix B if: `A.network <= B.network AND A.broadcast >= B.broadcast`
-- Two prefixes **overlap** if: `A.network <= B.broadcast AND B.network <= A.broadcast`
-
-### Severity Levels
-
-| Issue | Severity |
-|-------|----------|
-| Duplicate IP (same interface type) | CRITICAL |
-| Duplicate IP (different roles) | HIGH |
-| Overlapping prefixes (same status) | HIGH |
-| Overlapping prefixes (container ok) | LOW |
-| Orphan IP | MEDIUM |
-
-## Conflict Report Template
-
-```markdown
-## IP Conflict Detection Report
-
-**Generated:** [timestamp]
-**Scope:** [scope parameter]
-
-### Summary
-
-| Check | Status | Count |
-|-------|--------|-------|
-| Duplicate IPs | [PASS/FAIL] | X |
-| Overlapping Prefixes | [PASS/FAIL] | Y |
-| Orphan IPs | [PASS/FAIL] | Z |
-
-### Critical Issues
-
-#### Duplicate IP Addresses
-
-| Address | VRF | Count | Assigned To |
-|---------|-----|-------|-------------|
-| 10.0.1.50/24 | Global | 2 | server-01, server-02 |
-
-**Resolution:**
-- Determine which device should have the IP
-- Update or remove the duplicate
-
-#### Overlapping Prefixes
-
-| Prefix 1 | Prefix 2 | VRF | Type |
-|----------|----------|-----|------|
-| 10.0.0.0/24 | 10.0.0.0/25 | Global | Unstructured |
-
-**Resolution:**
-- For legitimate hierarchies: Mark parent as status="container"
-- For accidental: Consolidate or re-address
-
-### Remediation Commands
-
-```
-# Remove duplicate IP
-ipam_delete_ip_address id=123
-
-# Mark prefix as container
-ipam_update_prefix id=456 status=container
-
-# Create missing prefix
-ipam_create_prefix prefix=172.16.5.0/24 status=active
-```
-```

plugins/cmdb-assistant/skills/mcp-tools-reference.md

@@ -1,281 +0,0 @@
-# NetBox MCP Tools Reference
-
-Complete reference for NetBox MCP tools organized by category.
-
-## DCIM (Data Center Infrastructure Management)
-
-### Sites and Locations
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `dcim_list_sites` | List all sites | `name`, `status`, `region_id` |
-| `dcim_get_site` | Get site details | `id` |
-| `dcim_create_site` | Create new site | `name`, `slug`, `status` |
-| `dcim_update_site` | Update site | `id`, fields to update |
-| `dcim_delete_site` | Delete site | `id` |
-| `dcim_list_locations` | List locations within sites | `site_id`, `parent_id` |
-| `dcim_get_location` | Get location details | `id` |
-| `dcim_create_location` | Create location | `name`, `slug`, `site` |
-| `dcim_update_location` | Update location | `id`, fields to update |
-| `dcim_delete_location` | Delete location | `id` |
-| `dcim_list_regions` | List regions | `name` |
-| `dcim_get_region` | Get region details | `id` |
-| `dcim_create_region` | Create region | `name`, `slug` |
-| `dcim_update_region` | Update region | `id`, fields to update |
-| `dcim_delete_region` | Delete region | `id` |
-
-### Racks
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `dcim_list_racks` | List racks | `site_id`, `location_id`, `name` |
-| `dcim_get_rack` | Get rack details | `id` |
-| `dcim_create_rack` | Create rack | `name`, `site`, `u_height` |
-| `dcim_update_rack` | Update rack | `id`, fields to update |
-| `dcim_delete_rack` | Delete rack | `id` |
-
-### Devices
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `dcim_list_devices` | List devices | `name`, `site_id`, `role_id`, `status` |
-| `dcim_get_device` | Get device details | `id` |
-| `dcim_create_device` | Create device | `name`, `device_type`, `role`, `site` |
-| `dcim_update_device` | Update device | `id`, `primary_ip4`, etc. |
-| `dcim_delete_device` | Delete device | `id` |
-
-### Device Types and Roles
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `dcim_list_device_types` | List device types | `manufacturer_id`, `model` |
-| `dcim_get_device_type` | Get type details | `id` |
-| `dcim_create_device_type` | Create device type | `manufacturer`, `model`, `slug` |
-| `dcim_update_device_type` | Update device type | `id`, fields |
-| `dcim_delete_device_type` | Delete device type | `id` |
-| `dcim_list_device_roles` | List device roles | `name` |
-| `dcim_get_device_role` | Get role details | `id` |
-| `dcim_create_device_role` | Create device role | `name`, `slug` |
-| `dcim_update_device_role` | Update device role | `id`, fields |
-| `dcim_delete_device_role` | Delete device role | `id` |
-
-### Manufacturers and Platforms
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `dcim_list_manufacturers` | List manufacturers | `name` |
-| `dcim_get_manufacturer` | Get manufacturer details | `id` |
-| `dcim_create_manufacturer` | Create manufacturer | `name`, `slug` |
-| `dcim_update_manufacturer` | Update manufacturer | `id`, fields |
-| `dcim_delete_manufacturer` | Delete manufacturer | `id` |
-| `dcim_list_platforms` | List platforms | `name` |
-| `dcim_get_platform` | Get platform details | `id` |
-| `dcim_create_platform` | Create platform | `name`, `slug` |
-| `dcim_update_platform` | Update platform | `id`, fields |
-| `dcim_delete_platform` | Delete platform | `id` |
-
-### Interfaces and Cables
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `dcim_list_interfaces` | List interfaces | `device_id`, `name`, `type` |
-| `dcim_get_interface` | Get interface details | `id` |
-| `dcim_create_interface` | Create interface | `device`, `name`, `type` |
-| `dcim_update_interface` | Update interface | `id`, `enabled`, `mac_address` |
-| `dcim_delete_interface` | Delete interface | `id` |
-| `dcim_list_cables` | List cables | `device_id`, `site_id` |
-| `dcim_get_cable` | Get cable details | `id` |
-| `dcim_create_cable` | Create cable | `a_terminations`, `b_terminations` |
-| `dcim_update_cable` | Update cable | `id`, fields |
-| `dcim_delete_cable` | Delete cable | `id` |
-
-### Power
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `dcim_list_power_panels` | List power panels | `site_id` |
-| `dcim_get_power_panel` | Get panel details | `id` |
-| `dcim_create_power_panel` | Create power panel | `name`, `site` |
-| `dcim_list_power_feeds` | List power feeds | `power_panel_id` |
-| `dcim_get_power_feed` | Get feed details | `id` |
-| `dcim_create_power_feed` | Create power feed | `name`, `power_panel`, `supply` |
-
-### Other DCIM
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `dcim_list_virtual_chassis` | List virtual chassis | (varies) |
-| `dcim_get_virtual_chassis` | Get virtual chassis | `id` |
-| `dcim_list_inventory_items` | List inventory items | `device_id` |
-| `dcim_get_inventory_item` | Get inventory item | `id` |
-
-## IPAM (IP Address Management)
-
-### Prefixes
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `ipam_list_prefixes` | List prefixes | `prefix`, `vrf_id`, `within`, `contains` |
-| `ipam_get_prefix` | Get prefix details | `id` |
-| `ipam_create_prefix` | Create prefix | `prefix`, `status`, `site`, `vrf` |
-| `ipam_update_prefix` | Update prefix | `id`, `status`, etc. |
-| `ipam_delete_prefix` | Delete prefix | `id` |
-| `ipam_list_available_prefixes` | List available child prefixes | `prefix_id` |
-| `ipam_create_available_prefix` | Allocate from parent | `prefix_id`, `prefix_length` |
-
-### IP Addresses
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `ipam_list_ip_addresses` | List IP addresses | `address`, `vrf_id`, `device_id`, `status` |
-| `ipam_get_ip_address` | Get IP details | `id` |
-| `ipam_create_ip_address` | Create IP address | `address`, `assigned_object_type`, `assigned_object_id` |
-| `ipam_update_ip_address` | Update IP address | `id`, `status`, etc. |
-| `ipam_delete_ip_address` | Delete IP address | `id` |
-| `ipam_list_available_ips` | List available IPs in prefix | `prefix_id` |
-| `ipam_create_available_ip` | Allocate next available | `prefix_id` |
-
-### VLANs and VRFs
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `ipam_list_vlans` | List VLANs | `vid`, `name`, `site_id` |
-| `ipam_get_vlan` | Get VLAN details | `id` |
-| `ipam_create_vlan` | Create VLAN | `vid`, `name`, `site` |
-| `ipam_update_vlan` | Update VLAN | `id`, fields |
-| `ipam_delete_vlan` | Delete VLAN | `id` |
-| `ipam_list_vlan_groups` | List VLAN groups | `site_id` |
-| `ipam_get_vlan_group` | Get VLAN group | `id` |
-| `ipam_create_vlan_group` | Create VLAN group | `name`, `slug`, `scope_type` |
-| `ipam_list_vrfs` | List VRFs | `name` |
-| `ipam_get_vrf` | Get VRF details | `id` |
-| `ipam_create_vrf` | Create VRF | `name`, `rd` |
-| `ipam_update_vrf` | Update VRF | `id`, fields |
-| `ipam_delete_vrf` | Delete VRF | `id` |
-
-### Other IPAM
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `ipam_list_asns` | List ASNs | (varies) |
-| `ipam_get_asn` | Get ASN details | `id` |
-| `ipam_create_asn` | Create ASN | `asn`, `rir` |
-| `ipam_list_rirs` | List RIRs | `name` |
-| `ipam_get_rir` | Get RIR details | `id` |
-| `ipam_list_aggregates` | List aggregates | `prefix`, `rir_id` |
-| `ipam_get_aggregate` | Get aggregate | `id` |
-| `ipam_create_aggregate` | Create aggregate | `prefix`, `rir` |
-| `ipam_list_services` | List services | `device_id`, `name` |
-| `ipam_get_service` | Get service details | `id` |
-| `ipam_create_service` | Create service | `name`, `ports`, `protocol` |
-
-## Virtualization
-
-### Clusters
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `virt_list_cluster_types` | List cluster types | `name` |
-| `virt_get_cluster_type` | Get cluster type | `id` |
-| `virt_create_cluster_type` | Create cluster type | `name`, `slug` |
-| `virt_list_cluster_groups` | List cluster groups | `name` |
-| `virt_get_cluster_group` | Get cluster group | `id` |
-| `virt_create_cluster_group` | Create cluster group | `name`, `slug` |
-| `virt_list_clusters` | List clusters | `name`, `site_id`, `type_id` |
-| `virt_get_cluster` | Get cluster details | `id` |
-| `virt_create_cluster` | Create cluster | `name`, `type`, `site` |
-| `virt_update_cluster` | Update cluster | `id`, fields |
-| `virt_delete_cluster` | Delete cluster | `id` |
-
-### Virtual Machines
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `virt_list_vms` | List VMs | `name`, `cluster_id`, `site_id`, `status` |
-| `virt_get_vm` | Get VM details | `id` |
-| `virt_create_vm` | Create VM | `name`, `cluster`, `site`, `status` |
-| `virt_update_vm` | Update VM | `id`, `status`, etc. |
-| `virt_delete_vm` | Delete VM | `id` |
-| `virt_list_vm_ifaces` | List VM interfaces | `virtual_machine_id` |
-| `virt_get_vm_iface` | Get VM interface | `id` |
-| `virt_create_vm_iface` | Create VM interface | `virtual_machine`, `name` |
-
-## Circuits
-
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `circuits_list_providers` | List providers | `name` |
-| `circuits_get_provider` | Get provider | `id` |
-| `circuits_create_provider` | Create provider | `name`, `slug` |
-| `circuits_update_provider` | Update provider | `id`, fields |
-| `circuits_delete_provider` | Delete provider | `id` |
-| `circ_list_types` | List circuit types | `name` |
-| `circ_get_type` | Get circuit type | `id` |
-| `circ_create_type` | Create circuit type | `name`, `slug` |
-| `circuits_list_circuits` | List circuits | `provider_id`, `type_id` |
-| `circuits_get_circuit` | Get circuit | `id` |
-| `circuits_create_circuit` | Create circuit | `cid`, `provider`, `type` |
-| `circuits_update_circuit` | Update circuit | `id`, fields |
-| `circuits_delete_circuit` | Delete circuit | `id` |
-| `circ_list_terminations` | List terminations | `circuit_id` |
-| `circ_get_termination` | Get termination | `id` |
-| `circ_create_termination` | Create termination | `circuit`, `site`, `term_side` |
-
-## Tenancy
-
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `tenancy_list_tenant_groups` | List tenant groups | `name` |
-| `tenancy_get_tenant_group` | Get tenant group | `id` |
-| `tenancy_create_tenant_group` | Create tenant group | `name`, `slug` |
-| `tenancy_list_tenants` | List tenants | `name`, `group_id` |
-| `tenancy_get_tenant` | Get tenant | `id` |
-| `tenancy_create_tenant` | Create tenant | `name`, `slug` |
-| `tenancy_update_tenant` | Update tenant | `id`, fields |
-| `tenancy_delete_tenant` | Delete tenant | `id` |
-| `tenancy_list_contacts` | List contacts | `name` |
-| `tenancy_get_contact` | Get contact | `id` |
-| `tenancy_create_contact` | Create contact | `name` |
-
-## VPN
-
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `vpn_list_tunnels` | List VPN tunnels | `name` |
-| `vpn_get_tunnel` | Get tunnel | `id` |
-| `vpn_create_tunnel` | Create tunnel | `name`, `status` |
-| `vpn_list_l2vpns` | List L2VPNs | `name` |
-| `vpn_get_l2vpn` | Get L2VPN | `id` |
-| `vpn_create_l2vpn` | Create L2VPN | `name`, `type` |
-| `vpn_list_ike_policies` | List IKE policies | (varies) |
-| `vpn_list_ipsec_policies` | List IPSec policies | (varies) |
-| `vpn_list_ipsec_profiles` | List IPSec profiles | (varies) |
-
-## Wireless
-
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `wlan_list_groups` | List WLAN groups | `name` |
-| `wlan_get_group` | Get WLAN group | `id` |
-| `wlan_create_group` | Create WLAN group | `name`, `slug` |
-| `wlan_list_lans` | List WLANs | `ssid` |
-| `wlan_get_lan` | Get WLAN | `id` |
-| `wlan_create_lan` | Create WLAN | `ssid`, `group` |
-| `wlan_list_links` | List wireless links | (varies) |
-| `wlan_get_link` | Get wireless link | `id` |
-
-## Extras
-
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `extras_list_tags` | List tags | `name` |
-| `extras_get_tag` | Get tag | `id` |
-| `extras_create_tag` | Create tag | `name`, `slug`, `color` |
-| `extras_update_tag` | Update tag | `id`, fields |
-| `extras_delete_tag` | Delete tag | `id` |
-| `extras_list_custom_fields` | List custom fields | `name` |
-| `extras_get_custom_field` | Get custom field | `id` |
-| `extras_list_webhooks` | List webhooks | `name` |
-| `extras_get_webhook` | Get webhook | `id` |
-| `extras_list_journal_entries` | List journal entries | `assigned_object_type`, `assigned_object_id` |
-| `extras_get_journal_entry` | Get journal entry | `id` |
-| `extras_create_journal_entry` | Create journal entry | `assigned_object_type`, `assigned_object_id`, `comments` |
-| `extras_list_object_changes` | List audit log | `user_id`, `changed_object_type`, `action` |
-| `extras_get_object_change` | Get change details | `id` |
-| `extras_list_config_contexts` | List config contexts | `name` |
-| `extras_get_config_context` | Get config context | `id` |
-
-## Common Object Types for Filtering
-
-| Category | Object Types |
-|----------|--------------|
-| DCIM | `dcim.device`, `dcim.interface`, `dcim.site`, `dcim.rack`, `dcim.cable` |
-| IPAM | `ipam.ipaddress`, `ipam.prefix`, `ipam.vlan`, `ipam.vrf` |
-| Virtualization | `virtualization.virtualmachine`, `virtualization.cluster` |
-| Tenancy | `tenancy.tenant`, `tenancy.contact` |

plugins/cmdb-assistant/skills/sync-workflow.md

@@ -1,191 +0,0 @@
-# Sync Workflow Skill
-
-How to synchronize machine state with NetBox.
-
-## Prerequisites
-
-Load these skills:
-- `system-discovery` - Bash commands for system info
-- `mcp-tools-reference` - MCP tool reference
-
-## Sync Workflow
-
-### Phase 1: Device Lookup
-
-```
-dcim_list_devices name=<hostname>
-```
-
-If not found, suggest `/cmdb-register` first.
-
-If found:
-- Store device ID and current field values
-- Fetch interfaces: `dcim_list_interfaces device_id=<device_id>`
-- Fetch IPs: `ipam_list_ip_addresses device_id=<device_id>`
-- Check clusters/VMs: `virt_list_clusters`, `virt_list_vms cluster=<cluster_id>`
-
-### Phase 2: Current State Discovery
-
-Use commands from `system-discovery` skill.
-
-### Phase 3: Comparison
-
-#### Device Attributes
-| Field | Compare |
-|-------|---------|
-| Platform | OS version changed? |
-| Status | Still active? |
-| Serial | Match? |
-| Description | Keep existing |
-
-#### Network Interfaces
-| Change Type | Detection |
-|-------------|-----------|
-| New interface | Exists locally but not in NetBox |
-| Removed interface | In NetBox but not locally |
-| Changed MAC | MAC address different |
-| Interface type | Type mismatch |
-
-#### IP Addresses
-| Change Type | Detection |
-|-------------|-----------|
-| New IP | Exists locally but not in NetBox |
-| Removed IP | In NetBox but not locally |
-| Primary IP changed | Default route interface changed |
-
-#### Docker Containers
-| Change Type | Detection |
-|-------------|-----------|
-| New container | Running locally but no VM in cluster |
-| Stopped container | VM exists but container not running |
-| Resource change | vCPUs/memory different |
-
-### Phase 4: Diff Report
-
-```markdown
-## Sync Diff Report
-
-**Device:** <hostname> (ID: <device_id>)
-**NetBox URL:** https://netbox.example.com/dcim/devices/<id>/
-
-### Device Attributes
-| Field | NetBox Value | Current Value | Action |
-|-------|--------------|---------------|--------|
-| Platform | Ubuntu 22.04 | Ubuntu 24.04 | UPDATE |
-
-### Network Interfaces
-
-#### New Interfaces (will create)
-| Interface | Type | MAC | IPs |
-|-----------|------|-----|-----|
-| tailscale0 | virtual | - | 100.x.x.x/32 |
-
-#### Removed Interfaces (will mark offline)
-| Interface | Type | Reason |
-|-----------|------|--------|
-| eth1 | 1000base-t | Not found locally |
-
-#### Changed Interfaces
-| Interface | Field | Old | New |
-|-----------|-------|-----|-----|
-| eth0 | mac_address | aa:bb:cc:00:00:00 | aa:bb:cc:11:11:11 |
-
-### IP Addresses
-
-#### New IPs (will create)
-- 192.168.1.150/24 on eth0
-
-#### Removed IPs (will unassign)
-- 192.168.1.100/24 from eth0
-
-### Docker Containers
-
-#### New Containers (will create VMs)
-| Container | Image | Role |
-|-----------|-------|------|
-| media_lidarr | linuxserver/lidarr | Media Management |
-
-### Summary
-- **Updates:** X
-- **Creates:** Y
-- **Removals/Offline:** Z
-```
-
-### Phase 5: Apply Updates
-
-#### Device Updates
-```
-dcim_update_device id=<device_id> platform=<new_platform_id>
-```
-
-#### Interface Updates
-New:
-```
-dcim_create_interface device=<device_id> name=<name> type=<type>
-```
-
-Removed (mark offline):
-```
-dcim_update_interface id=<id> enabled=false description="Marked offline by cmdb-sync"
-```
-
-Changed:
-```
-dcim_update_interface id=<id> mac_address=<new_mac>
-```
-
-#### IP Address Updates
-New:
-```
-ipam_create_ip_address address=<ip/prefix> assigned_object_type="dcim.interface" assigned_object_id=<id>
-```
-
-Removed (unassign):
-```
-ipam_update_ip_address id=<id> assigned_object_type=null assigned_object_id=null
-```
-
-#### Primary IP Update
-```
-dcim_update_device id=<device_id> primary_ip4=<new_primary_ip_id>
-```
-
-#### Container/VM Updates
-New:
-```
-virt_create_vm name=<name> cluster=<cluster_id> status="active"
-```
-
-Stopped:
-```
-virt_update_vm id=<id> status="offline"
-```
-
-### Phase 6: Journal Entry
-
-```
-extras_create_journal_entry
-  assigned_object_type="dcim.device"
-  assigned_object_id=<device_id>
-  comments="Device synced via /cmdb-sync command\n\nChanges applied:\n- <list>"
-```
-
-## Sync Modes
-
-### Dry Run Mode
-- Complete phases 1-4 (lookup, discovery, compare, diff report)
-- Skip phases 5-6 (no updates, no journal)
-- End with: "Dry run complete. No changes applied."
-
-### Full Sync Mode
-- Skip user confirmation
-- Update all fields even if unchanged (force refresh)
-
-## Error Handling
-
-| Error | Action |
-|-------|--------|
-| Device not found | Suggest `/cmdb-register` |
-| Permission denied | Note which failed, continue others |
-| Cluster not found | Offer to create or skip container sync |
-| API errors | Log error, continue with remaining |

plugins/cmdb-assistant/skills/system-discovery.md

@@ -1,101 +0,0 @@
-# System Discovery Skill
-
-Bash commands for gathering system information from the current machine.
-
-## Basic Device Information
-
-```bash
-# Hostname
-hostname
-
-# OS/Platform info
-cat /etc/os-release 2>/dev/null || uname -a
-
-# Hardware model - Raspberry Pi
-cat /proc/device-tree/model 2>/dev/null || echo "Unknown"
-
-# Hardware model - x86 systems
-cat /sys/class/dmi/id/product_name 2>/dev/null || echo "Unknown"
-
-# Serial number - Raspberry Pi
-cat /proc/device-tree/serial-number 2>/dev/null || cat /proc/cpuinfo | grep Serial | cut -d: -f2 | tr -d ' ' 2>/dev/null
-
-# Serial number - x86 systems
-cat /sys/class/dmi/id/product_serial 2>/dev/null || echo "Unknown"
-
-# CPU count
-nproc
-
-# Memory in MB
-free -m | awk '/Mem:/ {print $2}'
-
-# Disk size in GB (root filesystem)
-df -BG / | awk 'NR==2 {print $2}' | tr -d 'G'
-```
-
-## Network Interfaces
-
-```bash
-# Get interfaces with IPs (JSON format)
-ip -j addr show 2>/dev/null || ip addr show
-
-# Get default gateway interface
-ip route | grep default | awk '{print $5}' | head -1
-
-# Get MAC addresses
-ip -j link show 2>/dev/null || ip link show
-```
-
-## Running Applications
-
-```bash
-# Docker containers (JSON format)
-docker ps --format '{"name":"{{.Names}}","image":"{{.Image}}","status":"{{.Status}}","ports":"{{.Ports}}"}' 2>/dev/null || echo "Docker not available"
-
-# Docker Compose projects (find compose files)
-find ~/apps /home/*/apps -name "docker-compose.yml" -o -name "docker-compose.yaml" 2>/dev/null | head -20
-
-# Running systemd services
-systemctl list-units --type=service --state=running --no-pager --plain 2>/dev/null | grep -v "^UNIT" | head -30
-```
-
-## Interface Type Mapping
-
-| Interface Pattern | NetBox Type |
-|-------------------|-------------|
-| `eth*`, `enp*` | `1000base-t` |
-| `wlan*` | `ieee802.11ax` |
-| `tailscale*`, `docker*`, `br-*` | `virtual` |
-| `lo` | Skip (loopback) |
-
-## Platform Detection
-
-Based on OS detected, determine platform name:
-
-| OS Detection | Platform Name |
-|--------------|---------------|
-| Raspberry Pi OS | `Raspberry Pi OS (Bookworm)` |
-| Ubuntu | `Ubuntu {version} LTS` |
-| Debian | `Debian {version}` |
-| Default | `{OS Name} {Version}` |
-
-## Device Role Auto-Detection
-
-Based on detected services:
-
-| Detection | Suggested Role |
-|-----------|----------------|
-| Docker containers found | `Docker Host` |
-| Only basic services | `Server` |
-| Specific role specified | Use specified |
-
-## Container Role Mapping
-
-Map container names/images to roles:
-
-| Container Pattern | Role |
-|-------------------|------|
-| `*caddy*`, `*nginx*`, `*traefik*` | Reverse Proxy |
-| `*db*`, `*postgres*`, `*mysql*`, `*redis*` | Database |
-| `*webui*`, `*frontend*` | Web Application |
-| Others | Infer from image or use "Container" |

plugins/cmdb-assistant/skills/topology-generation.md

@@ -1,155 +0,0 @@
-# Topology Generation Skill
-
-Generate Mermaid diagrams from NetBox data.
-
-## Prerequisites
-
-Load skill: `mcp-tools-reference`
-
-## View: Rack Elevation
-
-### Data Collection
-
-1. Find rack: `dcim_list_racks name=<name>`
-2. Get devices: `dcim_list_devices rack_id=<id>`
-3. Note for each: `position`, `u_height`, `face`, `name`, `role`
-
-### Mermaid Template
-
-```mermaid
-graph TB
-    subgraph rack["Rack: <rack-name> (U<height>)"]
-        direction TB
-        u42["U42: empty"]
-        u41["U41: empty"]
-        u40["U40: server-01 (Server)"]
-        u39["U39: server-01 (cont.)"]
-        u38["U38: switch-01 (Switch)"]
-    end
-```
-
-### Rules
-
-- Mark top U with device name and role
-- Mark subsequent Us as "(cont.)" for multi-U devices
-- Empty Us show "empty"
-
-## View: Network Topology
-
-### Data Collection
-
-1. List sites: `dcim_list_sites`
-2. List devices: `dcim_list_devices site_id=<id>`
-3. List cables: `dcim_list_cables`
-4. List interfaces: `dcim_list_interfaces device_id=<id>`
-
-### Mermaid Template
-
-```mermaid
-graph TD
-    subgraph site1["Site: Home"]
-        router1[("core-router-01<br/>Router")]
-        switch1[["dist-switch-01<br/>Switch"]]
-        server1["web-server-01<br/>Server"]
-        server2["db-server-01<br/>Server"]
-    end
-
-    router1 -->|"eth0 - eth1"| switch1
-    switch1 -->|"gi0/1 - eth0"| server1
-    switch1 -->|"gi0/2 - eth0"| server2
-```
-
-### Node Shapes by Role
-
-| Role | Shape | Mermaid Syntax |
-|------|-------|----------------|
-| Router | Cylinder | `[(" ")]` |
-| Switch | Double brackets | `[[ ]]` |
-| Server | Rectangle | `[ ]` |
-| Firewall | Hexagon | `{{ }}` |
-| Other | Rectangle | `[ ]` |
-
-### Edge Labels
-
-Show interface names: `A-side - B-side`
-
-## View: Site Overview
-
-### Data Collection
-
-1. Get site: `dcim_get_site id=<id>`
-2. List racks: `dcim_list_racks site_id=<id>`
-3. Count devices per rack: `dcim_list_devices rack_id=<id>`
-
-### Mermaid Template
-
-```mermaid
-graph TB
-    subgraph site["Site: Headquarters"]
-        subgraph row1["Row 1"]
-            rack1["Rack A1<br/>12/42 U used<br/>5 devices"]
-            rack2["Rack A2<br/>20/42 U used<br/>8 devices"]
-        end
-        subgraph row2["Row 2"]
-            rack3["Rack B1<br/>8/42 U used<br/>3 devices"]
-        end
-    end
-```
-
-## View: Full Infrastructure
-
-### Data Collection
-
-1. List regions: `dcim_list_regions`
-2. List sites: `dcim_list_sites`
-3. Count devices: `dcim_list_devices status=active`
-
-### Mermaid Template
-
-```mermaid
-graph TB
-    subgraph region1["Region: Americas"]
-        site1["Headquarters<br/>3 racks, 25 devices"]
-        site2["Branch Office<br/>1 rack, 5 devices"]
-    end
-    subgraph region2["Region: Europe"]
-        site3["EU Datacenter<br/>10 racks, 100 devices"]
-    end
-
-    site1 -.->|"WAN Link"| site3
-```
-
-## Output Format
-
-Always provide:
-
-1. **Summary** - Brief description of diagram content
-2. **Mermaid Code Block** - The diagram code
-3. **Legend** - Explanation of shapes and colors
-4. **Data Notes** - Any data quality issues
-
-### Example Output
-
-```markdown
-## Network Topology: Home Site
-
-This diagram shows network connections between 4 devices at Home site.
-
-```mermaid
-graph TD
-    router1[("core-router<br/>Router")]
-    switch1[["main-switch<br/>Switch"]]
-    server1["homelab-01<br/>Server"]
-
-    router1 -->|"eth0 - gi0/24"| switch1
-    switch1 -->|"gi0/1 - eth0"| server1
-```
-
-**Legend:**
-- Cylinder shape: Routers
-- Double brackets: Switches
-- Rectangle: Servers
-
-**Data Notes:**
-- 1 device (nas-01) has no cable connections documented
-```

plugins/cmdb-assistant/skills/visual-header.md

@@ -1,32 +0,0 @@
-# Visual Header Skill
-
-Standard visual header for cmdb-assistant commands.
-
-## Header Template
-
-```
-+----------------------------------------------------------------------+
-|  CMDB-ASSISTANT - [Context]                                          |
-+----------------------------------------------------------------------+
-```
-
-## Context Values by Command
-
-| Command | Context |
-|---------|---------|
-| `/cmdb-search` | Search |
-| `/cmdb-device` | Device Management |
-| `/cmdb-ip` | IP Management |
-| `/cmdb-site` | Site Management |
-| `/cmdb-audit` | Data Quality Audit |
-| `/cmdb-register` | Machine Registration |
-| `/cmdb-sync` | Machine Sync |
-| `/cmdb-topology` | Topology |
-| `/change-audit` | Change Audit |
-| `/ip-conflicts` | IP Conflict Detection |
-| `/initial-setup` | Setup Wizard |
-| Agent mode | Infrastructure Management |
-
-## Usage
-
-Display header at the start of every command response before proceeding with the operation.

plugins/code-sentinel/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "code-sentinel",
   "description": "Security scanning and code refactoring tools",
-  "version": "1.0.1",
+  "version": "1.0.0",
   "author": {
     "name": "Leo Miranda",
     "email": "leobmiranda@gmail.com"

plugins/code-sentinel/README.md

@@ -0,0 +1,47 @@
+# code-sentinel
+
+Security scanning and code refactoring tools for Claude Code projects.
+
+## Features
+
+### Security Scanning
+- **PreToolUse Hook**: Catches vulnerabilities BEFORE code is written
+- **Full Audit**: `/security-scan` for comprehensive project review
+- **Pattern Detection**: SQL injection, XSS, command injection, secrets, and more
+
+### Refactoring
+- **Pattern Library**: Extract method, simplify conditionals, modernize syntax
+- **Safe Transforms**: Preview changes before applying
+- **Reference Updates**: Automatically updates all call sites
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/security-scan` | Full project security audit |
+| `/refactor <target>` | Apply refactoring with pattern |
+| `/refactor-dry <target>` | Preview opportunities without changes |
+
+## Hooks
+
+- **PreToolUse (Write\|Edit)**: Scans code for security patterns before writing
+
+## Security Patterns Detected
+
+| Category | Examples |
+|----------|----------|
+| Injection | SQL, Command, Code (eval), XSS |
+| Secrets | Hardcoded API keys, passwords |
+| Deserialization | Pickle, unsafe YAML |
+| Path Traversal | Unsanitized file paths |
+
+## Installation
+
+```bash
+/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git
+/plugin install code-sentinel
+```
+
+## Integration
+
+See claude-md-integration.md for CLAUDE.md additions.

plugins/code-sentinel/agents/security-reviewer.md

@@ -1,5 +1,4 @@
 ---
-name: security-reviewer
 description: Security-focused code review agent
 ---
 

plugins/code-sentinel/commands/refactor-dry.md

@@ -8,12 +8,16 @@ Analyze and preview refactoring opportunities without making changes.
 
 ## Visual Output
 
+When executing this command, display the plugin header:
+
 ```
-+----------------------------------------------------------------------+
+┌──────────────────────────────────────────────────────────────────┐
-|  CODE-SENTINEL - Refactor Preview                                    |
+│  🔒 CODE-SENTINEL · Refactor Preview                             │
-+----------------------------------------------------------------------+
+└──────────────────────────────────────────────────────────────────┘
 ```
 
+Then proceed with the analysis.
+
 ## Usage
 ```
 /refactor-dry <target> [--all]
@@ -22,31 +26,44 @@ Analyze and preview refactoring opportunities without making changes.
 **Target:** File path, function name, or "." for current file
 **--all:** Show all opportunities, not just recommended
 
-## Skills to Load
-
-- skills/refactoring-patterns.md
-- skills/dry-run-workflow.md
-
 ## Process
 
-1. **Scan Target** - Analyze code using patterns from skill
+1. **Scan Target**
-2. **Score Opportunities** - Rate by Impact/Risk/Effort (see dry-run-workflow skill)
+   Analyze code for refactoring opportunities.
-3. **Output** - Group by recommended vs optional
 
-## Output Format
+2. **Score Opportunities**
+   Each opportunity rated by:
+   - Impact (how much it improves code)
+   - Risk (likelihood of breaking something)
+   - Effort (complexity of the refactoring)
 
+3. **Output**
 ```
-## Refactoring Opportunities: <target>
+## Refactoring Opportunities: src/handlers.py
 
 ### Recommended (High Impact, Low Risk)
-1. **pattern** at lines X-Y
-   - Impact: High | Risk: Low
-   - Run: `/refactor <target> --pattern=<pattern>`
 
-### Optional
+1. **extract-method** at lines 45-67
-- Lower priority items
+   - Extract order validation logic
+   - Impact: High (reduces complexity from 12 to 4)
+   - Risk: Low (pure function, no side effects)
+   - Run: `/refactor src/handlers.py:45 --pattern=extract-method`
+
+2. **use-dataclass** for OrderInput class
+   - Convert to dataclass with validation
+   - Impact: Medium (reduces boilerplate)
+   - Risk: Low
+   - Run: `/refactor src/models.py:OrderInput --pattern=use-dataclass`
+
+### Optional (Consider Later)
+
+3. **use-fstring** at 12 locations
+   - Modernize string formatting
+   - Impact: Low (readability only)
+   - Risk: None
 
 ### Summary
-- X recommended, Y optional
+- 2 recommended refactorings
-- Estimated complexity reduction: Z%
+- 1 optional improvement
+- Estimated complexity reduction: 35%
 ```

plugins/code-sentinel/commands/refactor.md

@@ -8,12 +8,16 @@ Apply refactoring transformations to specified code.
 
 ## Visual Output
 
+When executing this command, display the plugin header:
+
 ```
-+----------------------------------------------------------------------+
+┌──────────────────────────────────────────────────────────────────┐
-|  CODE-SENTINEL - Refactor                                            |
+│  🔒 CODE-SENTINEL · Refactor                                     │
-+----------------------------------------------------------------------+
+└──────────────────────────────────────────────────────────────────┘
 ```
 
+Then proceed with the refactoring workflow.
+
 ## Usage
 ```
 /refactor <target> [--pattern=<pattern>]
@@ -22,31 +26,68 @@ Apply refactoring transformations to specified code.
 **Target:** File path, function name, or "." for current context
 **Pattern:** Specific refactoring pattern (optional)
 
-## Skills to Load
+## Available Patterns
 
-- skills/refactoring-patterns.md
+### Structure
+| Pattern | Description |
+|---------|-------------|
+| `extract-method` | Extract code block into named function |
+| `extract-class` | Move related methods to new class |
+| `inline` | Inline trivial function/variable |
+| `rename` | Rename with all references updated |
+| `move` | Move function/class to different module |
+
+### Simplification
+| Pattern | Description |
+|---------|-------------|
+| `simplify-conditional` | Flatten nested if/else |
+| `remove-dead-code` | Delete unreachable code |
+| `consolidate-duplicate` | Merge duplicate code blocks |
+| `decompose-conditional` | Break complex conditions into named parts |
+
+### Modernization
+| Pattern | Description |
+|---------|-------------|
+| `use-comprehension` | Convert loops to list/dict comprehensions |
+| `use-pathlib` | Replace os.path with pathlib |
+| `use-fstring` | Convert .format() to f-strings |
+| `use-typing` | Add type hints |
+| `use-dataclass` | Convert class to dataclass |
 
 ## Process
 
-1. **Analyze Target** - Parse code, identify opportunities from skill, check dependencies
+1. **Analyze Target**
-2. **Propose Changes** - Show before/after diff, explain improvement, list affected files
+   - Parse code structure
-3. **Apply (with confirmation)** - Make changes, update references, run tests
+   - Identify refactoring opportunities
+   - Check for side effects and dependencies
 
-## Output Format
+2. **Propose Changes**
+   - Show before/after diff
+   - Explain the improvement
+   - List affected files/references
 
+3. **Apply (with confirmation)**
+   - Make changes
+   - Update all references
+   - Run existing tests if available
+
+4. **Output**
 ```
-## Refactoring: <pattern>
+## Refactoring: extract-method
 
 ### Target
-<file>:<function> (lines X-Y)
+src/handlers.py:create_order (lines 45-89)
 
 ### Changes
-- Change description
+- Extracted validation logic → validate_order_input()
+- Extracted pricing logic → calculate_order_total()
+- Original function now 15 lines (was 44)
 
 ### Files Modified
-- file1.py
+- src/handlers.py
+- tests/test_handlers.py (updated calls)
 
 ### Metrics
-- Cyclomatic complexity: X -> Y
+- Cyclomatic complexity: 12 → 4
-- Function length: X -> Y lines
+- Function length: 44 → 15 lines
 ```

plugins/code-sentinel/commands/security-scan.md

@@ -8,34 +8,61 @@ Comprehensive security audit of the project.
 
 ## Visual Output
 
+When executing this command, display the plugin header:
+
 ```
-+----------------------------------------------------------------------+
+┌──────────────────────────────────────────────────────────────────┐
-|  CODE-SENTINEL - Security Scan                                       |
+│  🔒 CODE-SENTINEL · Security Scan                                │
-+----------------------------------------------------------------------+
+└──────────────────────────────────────────────────────────────────┘
 ```
 
-## Skills to Load
+Then proceed with the scan workflow.
-
-- skills/security-patterns/SKILL.md
 
 ## Process
 
-1. **File Discovery** - Scan: .py, .js, .ts, .jsx, .tsx, .go, .rs, .java, .rb, .php, .sh
+1. **File Discovery**
-2. **Pattern Detection** - Apply patterns from skill (Critical/High/Medium severity)
+   Scan all code files: .py, .js, .ts, .jsx, .tsx, .go, .rs, .java, .rb, .php, .sh
-3. **Report** - Group by severity, include code snippets and fixes
 
-## Output Format
+2. **Pattern Detection**
 
+   ### Critical Vulnerabilities
+   | Pattern | Risk | Detection |
+   |---------|------|-----------|
+   | SQL Injection | High | String concat in SQL queries |
+   | Command Injection | High | shell=True, os.system with vars |
+   | XSS | High | innerHTML with user input |
+   | Code Injection | Critical | eval/exec with external input |
+   | Deserialization | Critical | pickle.loads, yaml.load unsafe |
+   | Path Traversal | High | File ops without sanitization |
+   | Hardcoded Secrets | High | API keys, passwords in code |
+   | SSRF | Medium | URL from user input in requests |
+
+   ### Code Quality Issues
+   | Pattern | Risk | Detection |
+   |---------|------|-----------|
+   | Broad Exceptions | Low | `except:` or `except Exception:` |
+   | Debug Statements | Low | print/console.log with data |
+   | TODO/FIXME Security | Medium | Comments mentioning security |
+   | Deprecated Functions | Medium | Known insecure functions |
+
+3. **Output Format**
 ```
 ## Security Scan Report
 
 ### Critical (Immediate Action Required)
-[red] file:line - Vulnerability Type
+🔴 src/db.py:45 - SQL Injection
-   Code: `problematic code`
+   Code: `f"SELECT * FROM users WHERE id = {user_id}"`
-   Fix: Recommended solution
+   Fix: Use parameterized query: `cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))`
 
-### High / Medium / Low
+### High
-[Similar format]
+🟠 config.py:12 - Hardcoded Secret
+   Code: `API_KEY = "sk-1234..."`
+   Fix: Use environment variable: `API_KEY = os.environ.get("API_KEY")`
+
+### Medium
+🟡 utils.py:78 - Broad Exception
+   Code: `except:`
+   Fix: Catch specific exceptions
 
 ### Summary
 - Critical: X (must fix before deploy)
@@ -43,8 +70,7 @@ Comprehensive security audit of the project.
 - Medium: X (improve when possible)
 ```
 
-## Exit Guidance
+4. **Exit Code Guidance**
-
+   - Critical findings: Recommend blocking merge/deploy
-- Critical findings: Block merge/deploy
+   - High findings: Recommend fixing before release
-- High findings: Fix before release
+   - Medium/Low: Informational
-- Medium/Low: Informational

plugins/code-sentinel/skills/dry-run-workflow.md

@@ -1,99 +0,0 @@
----
-description: Workflow for previewing changes safely before applying them
----
-
-# Dry Run Workflow Skill
-
-## Overview
-
-Dry run mode analyzes code and shows proposed changes without modifying files. Essential for reviewing impact before committing to changes.
-
-## Opportunity Scoring
-
-Rate each refactoring opportunity on three dimensions:
-
-### Impact Score (1-5)
-| Score | Meaning | Example |
-|-------|---------|---------|
-| 5 | Major improvement | Cyclomatic complexity 15 -> 3 |
-| 4 | Significant improvement | Function 50 lines -> 15 lines |
-| 3 | Moderate improvement | Better naming, clearer structure |
-| 2 | Minor improvement | Code style modernization |
-| 1 | Cosmetic only | Formatting changes |
-
-### Risk Score (1-5)
-| Score | Meaning | Example |
-|-------|---------|---------|
-| 5 | Very high risk | Changes to core business logic |
-| 4 | High risk | Modifies shared utilities |
-| 3 | Moderate risk | Changes function signatures |
-| 2 | Low risk | Internal implementation only |
-| 1 | Minimal risk | Pure functions, no side effects |
-
-### Effort Score (1-5)
-| Score | Meaning | Example |
-|-------|---------|---------|
-| 5 | Major effort | Requires architecture changes |
-| 4 | Significant effort | Many files affected |
-| 3 | Moderate effort | Multiple related changes |
-| 2 | Low effort | Single file, clear scope |
-| 1 | Trivial | Automated transformation |
-
-## Priority Calculation
-
-```
-Priority = (Impact * 2) - Risk - (Effort * 0.5)
-```
-
-| Priority Range | Recommendation |
-|---------------|----------------|
-| > 5 | Recommended - do it |
-| 3-5 | Optional - consider it |
-| < 3 | Skip - not worth it |
-
-## Output Format
-
-### Recommended Section
-High impact, low risk opportunities:
-```
-1. **pattern-name** at file:lines
-   - Description of the change
-   - Impact: High/Medium/Low (specific metric improvement)
-   - Risk: Low/Medium/High (why)
-   - Run: `/refactor <target> --pattern=<pattern>`
-```
-
-### Optional Section
-Lower priority opportunities grouped by type.
-
-### Summary
-- Count of recommended vs optional
-- Estimated overall improvement percentage
-- Any blockers or dependencies
-
-## Dependency Detection
-
-Before recommending changes, check for:
-
-1. **Test Coverage** - Does this code have tests?
-2. **Usage Scope** - Is it used elsewhere?
-3. **Side Effects** - Does it modify external state?
-4. **Breaking Changes** - Will it change public API?
-
-Flag dependencies in output:
-```
-Note: This refactoring requires updating 3 callers:
-  - src/api/handlers.py:45
-  - src/cli/commands.py:78
-  - tests/test_handlers.py:23
-```
-
-## Safety Checklist
-
-Before recommending any change:
-
-- [ ] All affected code locations identified
-- [ ] No breaking API changes without flag
-- [ ] Test coverage assessed
-- [ ] Side effects documented
-- [ ] Rollback path clear (git)

plugins/code-sentinel/skills/refactoring-patterns.md

@@ -1,119 +0,0 @@
----
-description: Code refactoring patterns and techniques for improving structure and maintainability
----
-
-# Refactoring Patterns Skill
-
-## Structure Patterns
-
-| Pattern | Description | When to Use |
-|---------|-------------|-------------|
-| `extract-method` | Extract code block into named function | Long functions, repeated logic |
-| `extract-class` | Move related methods to new class | Class doing too much |
-| `inline` | Inline trivial function/variable | Over-abstracted code |
-| `rename` | Rename with all references updated | Unclear naming |
-| `move` | Move function/class to different module | Misplaced code |
-
-### extract-method Example
-```python
-# BEFORE
-def process_order(order):
-    # Validate (extract this)
-    if not order.items:
-        raise ValueError("Empty order")
-    if order.total < 0:
-        raise ValueError("Invalid total")
-    # Process
-    for item in order.items:
-        inventory.reserve(item)
-    return create_invoice(order)
-
-# AFTER
-def validate_order(order):
-    if not order.items:
-        raise ValueError("Empty order")
-    if order.total < 0:
-        raise ValueError("Invalid total")
-
-def process_order(order):
-    validate_order(order)
-    for item in order.items:
-        inventory.reserve(item)
-    return create_invoice(order)
-```
-
-## Simplification Patterns
-
-| Pattern | Description | When to Use |
-|---------|-------------|-------------|
-| `simplify-conditional` | Flatten nested if/else | Deep nesting (>3 levels) |
-| `remove-dead-code` | Delete unreachable code | After refactoring |
-| `consolidate-duplicate` | Merge duplicate code blocks | DRY violations |
-| `decompose-conditional` | Break complex conditions into named parts | Long boolean expressions |
-
-### simplify-conditional Example
-```python
-# BEFORE
-if user:
-    if user.active:
-        if user.has_permission:
-            do_action()
-
-# AFTER (guard clauses)
-if not user:
-    return
-if not user.active:
-    return
-if not user.has_permission:
-    return
-do_action()
-```
-
-## Modernization Patterns
-
-| Pattern | Description | When to Use |
-|---------|-------------|-------------|
-| `use-comprehension` | Convert loops to list/dict comprehensions | Simple transformations |
-| `use-pathlib` | Replace os.path with pathlib | File path operations |
-| `use-fstring` | Convert .format() to f-strings | String formatting |
-| `use-typing` | Add type hints | Public APIs, complex functions |
-| `use-dataclass` | Convert class to dataclass | Data-holding classes |
-
-### use-dataclass Example
-```python
-# BEFORE
-class User:
-    def __init__(self, name, email, age):
-        self.name = name
-        self.email = email
-        self.age = age
-
-# AFTER
-@dataclass
-class User:
-    name: str
-    email: str
-    age: int
-```
-
-## Code Smell Detection
-
-| Smell | Indicators | Suggested Pattern |
-|-------|------------|-------------------|
-| Long Method | >20 lines, multiple responsibilities | extract-method |
-| Large Class | >10 methods, low cohesion | extract-class |
-| Primitive Obsession | Many related primitives | use-dataclass |
-| Nested Conditionals | >3 nesting levels | simplify-conditional |
-| Duplicate Code | Copy-pasted blocks | consolidate-duplicate |
-| Dead Code | Unreachable branches | remove-dead-code |
-
-## Metrics
-
-After refactoring, measure improvement:
-
-| Metric | Good Target | Tool |
-|--------|-------------|------|
-| Cyclomatic Complexity | <10 per function | radon, lizard |
-| Function Length | <25 lines | manual count |
-| Class Cohesion | LCOM <0.5 | pylint |
-| Duplication | <3% | jscpd, radon |

plugins/contract-validator/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-validator",
-  "version": "1.1.0",
+  "version": "1.0.0",
   "description": "Cross-plugin compatibility validation and Claude.md agent verification",
   "author": {
     "name": "Leo Miranda",
@@ -17,5 +17,6 @@
     "interfaces",
     "cross-plugin"
   ],
-  "commands": ["./commands/"]
+  "commands": ["./commands/"],
+  "mcpServers": ["./.mcp.json"]
 }

plugins/contract-validator/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "contract-validator": {
+      "type": "stdio",
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/contract-validator/run.sh",
+      "args": []
+    }
+  }
+}

plugins/contract-validator/README.md

@@ -0,0 +1,169 @@
+# 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

plugins/contract-validator/agents/agent-check.md

@@ -1,8 +1,3 @@
----
-name: agent-check
-description: Agent definition validator for quick verification
----
-
 # Agent Check Agent
 
 You are an agent definition validator. Your role is to verify that a specific agent's tool references and data flow are valid.

plugins/contract-validator/commands/check-agent.md

@@ -1,10 +1,18 @@
 # /check-agent - Validate Agent Definition
 
-## Skills to Load
+## Visual Output
-- skills/visual-output.md
+
-- skills/interface-parsing.md
+When executing this command, display the plugin header:
-- skills/validation-rules.md
+
-- skills/mcp-tools-reference.md
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ✅ CONTRACT-VALIDATOR · Agent Check                              │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the validation.
+
+Validate a single agent's tool references and data flow.
 
 ## Usage
 
@@ -14,26 +22,30 @@
 
 ## Parameters
 
-- `agent_name` (required): Agent to validate (e.g., "Planner", "Orchestrator")
+- `agent_name` (required): Name of the agent to validate (e.g., "Planner", "Orchestrator")
-- `claude_md_path` (optional): Path to CLAUDE.md. Defaults to `./CLAUDE.md`
+- `claude_md_path` (optional): Path to CLAUDE.md file. Defaults to `./CLAUDE.md`
 
 ## Workflow
 
-1. **Display header** per `skills/visual-output.md`
+1. **Parse agent definition**:
+   - Locate agent in CLAUDE.md (Four-Agent Model table or Agents section)
+   - Extract responsibilities, tool references, workflow steps
 
-2. **Parse agent** per `skills/interface-parsing.md`
+2. **Validate tool references**:
-   - Use `parse_claude_md_agents` to extract agent definition
+   - Check each referenced tool exists in available plugins
-   - Get responsibilities, tool references, workflow steps
+   - Report missing or misspelled tool names
+   - Suggest corrections for common mistakes
 
-3. **Validate** per `skills/validation-rules.md`
+3. **Validate data flow**:
-   - Use `validate_agent_refs` - check all tools exist
+   - Analyze sequence of tools in agent workflow
-   - Use `validate_data_flow` - verify producer/consumer order
+   - Verify data producers precede data consumers
+   - Check for orphaned data references
 
 4. **Report findings**:
-   - Tool references found
+   - List all tool references found
-   - Missing tools (with suggestions)
+   - List any missing tools
-   - Data flow issues
+   - Data flow validation results
-   - Recommendations
+   - Suggestions for improvement
 
 ## Examples
 
@@ -42,3 +54,10 @@
 /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

plugins/contract-validator/commands/dependency-graph.md

@@ -1,11 +1,18 @@
 # /dependency-graph - Generate Dependency Visualization
 
-## Skills to Load
+## Visual Output
-- skills/visual-output.md
+
-- skills/plugin-discovery.md
+When executing this command, display the plugin header:
-- skills/interface-parsing.md
+
-- skills/dependency-analysis.md
+```
-- skills/mcp-tools-reference.md
+┌──────────────────────────────────────────────────────────────────┐
+│  ✅ CONTRACT-VALIDATOR · Dependency Graph                         │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the visualization.
+
+Generate a Mermaid flowchart showing plugin dependencies, data flows, and tool relationships.
 
 ## Usage
 
@@ -21,35 +28,236 @@
 
 ## Workflow
 
-1. **Display header** per `skills/visual-output.md`
+1. **Discover plugins**:
+   - Scan plugins directory for all plugins with `.claude-plugin/` marker
+   - Parse each plugin's README.md to extract interface
+   - Parse CLAUDE.md for agent definitions and tool sequences
 
-2. **Discover plugins** per `skills/plugin-discovery.md`
+2. **Analyze dependencies**:
+   - Identify shared MCP servers (plugins using same server)
+   - Detect tool dependencies (which plugins produce vs consume data)
+   - Find agent tool references across plugins
+   - Categorize as required (ERROR if missing) or optional (WARNING if missing)
 
-3. **Parse interfaces** per `skills/interface-parsing.md`
+3. **Build dependency graph**:
-   - Use `parse_plugin_interface` for each plugin
+   - Create nodes for each plugin
-   - Use `parse_claude_md_agents` for CLAUDE.md
+   - Create edges for:
+     - Shared MCP servers (bidirectional)
+     - Data producers -> consumers (directional)
+     - Agent tool dependencies (directional)
+   - Mark edges as optional or required
 
-4. **Analyze dependencies** per `skills/dependency-analysis.md`
+4. **Generate Mermaid output**:
-   - Identify shared MCP servers
+   - Create flowchart diagram syntax
-   - Detect data producers/consumers
+   - Style required dependencies with solid lines
-   - Categorize as required or optional
+   - Style optional dependencies with dashed lines
+   - Group by MCP server or data flow
 
-5. **Generate output**:
+## Output Format
-   - Mermaid: Create flowchart TD diagram with styled edges
+
-   - Text: Create text summary with counts and lists
+### Mermaid (default)
+
+```mermaid
+flowchart TD
+    subgraph mcp_gitea["MCP: gitea"]
+        projman["projman"]
+        pr-review["pr-review"]
+    end
+
+    subgraph mcp_data["MCP: data-platform"]
+        data-platform["data-platform"]
+    end
+
+    subgraph mcp_viz["MCP: viz-platform"]
+        viz-platform["viz-platform"]
+    end
+
+    %% Data flow dependencies
+    data-platform -->|"data_ref (required)"| viz-platform
+
+    %% Optional dependencies
+    projman -.->|"lessons (optional)"| pr-review
+
+    %% Styling
+    classDef required stroke:#e74c3c,stroke-width:2px
+    classDef optional stroke:#f39c12,stroke-dasharray:5 5
+```
+
+### Text Format
+
+```
+DEPENDENCY GRAPH
+================
+
+Plugins: 12
+MCP Servers: 4
+Dependencies: 8 (5 required, 3 optional)
+
+MCP Server Groups:
+  gitea: projman, pr-review
+  data-platform: data-platform
+  viz-platform: viz-platform
+  netbox: cmdb-assistant
+
+Data Flow Dependencies:
+  data-platform -> viz-platform (data_ref) [REQUIRED]
+  data-platform -> data-platform (data_ref) [INTERNAL]
+
+Cross-Plugin Tool Usage:
+  projman.Planner uses: create_issue, search_lessons
+  pr-review.reviewer uses: get_pr_diff, create_pr_review
+```
+
+## Dependency Types
+
+| Type | Line Style | Meaning |
+|------|------------|---------|
+| Required | Solid (`-->`) | Plugin cannot function without this dependency |
+| Optional | Dashed (`-.->`) | Plugin works but with reduced functionality |
+| Internal | Dotted (`...>`) | Self-dependency within same plugin |
+| Shared MCP | Double (`==>`) | Plugins share same MCP server instance |
+
+## Known Data Flow Patterns
+
+The command recognizes these producer/consumer relationships:
+
+### Data Producers
+- `read_csv`, `read_parquet`, `read_json` - File loaders
+- `pg_query`, `pg_execute` - Database queries
+- `filter`, `select`, `groupby`, `join` - Transformations
+
+### Data Consumers
+- `describe`, `head`, `tail` - Data inspection
+- `to_csv`, `to_parquet` - File writers
+- `chart_create` - Visualization
+
+### Cross-Plugin Flows
+- `data-platform` produces `data_ref` -> `viz-platform` consumes for charts
+- `projman` produces issues -> `pr-review` references in reviews
+- `gitea` wiki -> `projman` lessons learned
 
 ## Examples
 
+### Basic Usage
+
 ```
 /dependency-graph
+```
+
+Generates Mermaid diagram for current marketplace.
+
+### With Tool Details
+
+```
 /dependency-graph --show-tools
+```
+
+Includes individual tool nodes showing which tools each plugin provides.
+
+### Text Summary
+
+```
 /dependency-graph --format text
+```
+
+Outputs text-based summary suitable for CLAUDE.md inclusion.
+
+### Specific Path
+
+```
 /dependency-graph ~/claude-plugins-work
 ```
 
-## Integration
+Analyze marketplace at specified path.
 
-Use with `/validate-contracts`:
+## Integration with Other Commands
-1. Run `/dependency-graph` to visualize
+
-2. Run `/validate-contracts` to find issues
+Use with `/validate-contracts` to:
-3. Fix and regenerate
+1. Run `/dependency-graph` to visualize relationships
+2. Run `/validate-contracts` to find issues in those relationships
+3. Fix issues and regenerate graph to verify
+
+## Available Tools
+
+Use these MCP tools:
+- `parse_plugin_interface` - Extract interface from plugin README.md
+- `parse_claude_md_agents` - Extract agents and their tool sequences
+- `generate_compatibility_report` - Get full interface data (JSON format for analysis)
+- `validate_data_flow` - Verify data producer/consumer relationships
+
+## Implementation Notes
+
+### Detecting Shared MCP Servers
+
+Check each plugin's `.mcp.json` file for server definitions:
+
+```bash
+# List all .mcp.json files in plugins
+find plugins/ -name ".mcp.json" -exec cat {} \;
+```
+
+Plugins with identical MCP server names share that server.
+
+### Identifying Data Flows
+
+1. Parse tool categories from README.md
+2. Map known producer tools to their output types
+3. Map known consumer tools to their input requirements
+4. Create edges where outputs match inputs
+
+### Optional vs Required
+
+- **Required**: Consumer tool has no default/fallback behavior
+- **Optional**: Consumer works without producer (e.g., lessons search returns empty)
+
+Determination is based on:
+- Issue severity from `validate_data_flow` (ERROR = required, WARNING = optional)
+- Tool documentation stating "requires" vs "uses if available"
+
+## Sample Output
+
+For the leo-claude-mktplace:
+
+```mermaid
+flowchart TD
+    subgraph gitea_mcp["Shared MCP: gitea"]
+        projman["projman<br/>14 commands"]
+        pr-review["pr-review<br/>6 commands"]
+    end
+
+    subgraph netbox_mcp["Shared MCP: netbox"]
+        cmdb-assistant["cmdb-assistant<br/>3 commands"]
+    end
+
+    subgraph data_mcp["Shared MCP: data-platform"]
+        data-platform["data-platform<br/>7 commands"]
+    end
+
+    subgraph viz_mcp["Shared MCP: viz-platform"]
+        viz-platform["viz-platform<br/>7 commands"]
+    end
+
+    subgraph standalone["Standalone Plugins"]
+        doc-guardian["doc-guardian"]
+        code-sentinel["code-sentinel"]
+        clarity-assist["clarity-assist"]
+        git-flow["git-flow"]
+        claude-config-maintainer["claude-config-maintainer"]
+        contract-validator["contract-validator"]
+    end
+
+    %% Data flow: data-platform -> viz-platform
+    data-platform -->|"data_ref"| viz-platform
+
+    %% Cross-plugin: projman lessons -> pr-review context
+    projman -.->|"lessons"| pr-review
+
+    %% Styling
+    classDef mcpGroup fill:#e8f4fd,stroke:#2196f3
+    classDef standalone fill:#f5f5f5,stroke:#9e9e9e
+    classDef required stroke:#e74c3c,stroke-width:2px
+    classDef optional stroke:#f39c12,stroke-dasharray:5 5
+
+    class gitea_mcp,netbox_mcp,data_mcp,viz_mcp mcpGroup
+    class standalone standalone
+```

plugins/contract-validator/commands/initial-setup.md

@@ -1,49 +1,164 @@
 ---
-description: Interactive setup wizard for contract-validator plugin
+description: Interactive setup wizard for contract-validator plugin - verifies MCP server and shows capabilities
 ---
 
-# /initial-setup - Contract-Validator Setup Wizard
+# Contract-Validator Setup Wizard
 
-## Skills to Load
+## Visual Output
-- skills/visual-output.md
-- skills/mcp-tools-reference.md
 
-**Important:** This command uses Bash, Read, Write tools - NOT MCP tools (they work only after setup + restart).
+When executing this command, display the plugin header:
 
-## Workflow
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ✅ CONTRACT-VALIDATOR · Setup Wizard                             │
+└──────────────────────────────────────────────────────────────────┘
+```
 
-1. **Display header** per `skills/visual-output.md`
+Then proceed with the setup.
 
-2. **Check Python version**:
+This command sets up the contract-validator plugin for cross-plugin compatibility validation.
-   ```bash
-   python3 --version
-   ```
-   Requires 3.10+. Stop if below.
 
-3. **Locate MCP server**:
+## Important Context
-   - Installed: `~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/contract-validator/`
-   - Source: `~/claude-plugins-work/mcp-servers/contract-validator/`
 
-4. **Check/create venv**:
+- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools
-   ```bash
+- **MCP tools won't work until after setup + session restart**
-   ls .venv/bin/python || (python3 -m venv .venv && .venv/bin/pip install -r requirements.txt)
+- **No external credentials required** - this plugin validates local files only
-   ```
 
-5. **Verify MCP server**:
+---
-   ```bash
-   .venv/bin/python -c "from mcp_server.server import ContractValidatorMCPServer; print('OK')"
-   ```
 
-6. **Display success** per `skills/visual-output.md`
+## Phase 1: Environment Validation
 
-7. **Inform user**: Session restart required for MCP tools.
+### Step 1.1: Check Python Version
 
-## Post-Setup Commands
+```bash
+python3 --version
+```
 
-- `/validate-contracts` - Full marketplace validation
+Requires Python 3.10+. If below, stop setup and inform user:
-- `/check-agent` - Validate single agent
+```
-- `/list-interfaces` - Show all plugin interfaces
+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 reads plugin manifests and README files directly - no credentials needed.
+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/`

plugins/contract-validator/commands/list-interfaces.md

@@ -1,10 +1,18 @@
 # /list-interfaces - Show Plugin Interfaces
 
-## Skills to Load
+## Visual Output
-- skills/visual-output.md
+
-- skills/plugin-discovery.md
+When executing this command, display the plugin header:
-- skills/interface-parsing.md
+
-- skills/mcp-tools-reference.md
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ✅ CONTRACT-VALIDATOR · List Interfaces                         │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the interface listing.
+
+Display what each plugin in the marketplace produces and accepts.
 
 ## Usage
 
@@ -18,25 +26,35 @@
 
 ## Workflow
 
-1. **Display header** per `skills/visual-output.md`
+1. **Discover plugins**:
+   - Scan plugins directory for all plugins with `.claude-plugin/` marker
+   - Read each plugin's README.md
 
-2. **Discover plugins** per `skills/plugin-discovery.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. **Parse interfaces** per `skills/interface-parsing.md`
+3. **Display summary**:
-   - Use `parse_plugin_interface` for each plugin README.md
+   - Table of plugins with command/agent/tool counts
-   - Extract commands, agents, tools
+   - Detailed breakdown per plugin
+   - Tool categories and their contents
 
-4. **Display summary table**:
+## Output Format
-   ```
-   | Plugin      | Commands | Agents | Tools |
-   |-------------|----------|--------|-------|
-   | projman     | 12       | 4      | 26    |
-   ```
 
-5. **Display per-plugin details**:
+```
-   - List of commands
+| Plugin      | Commands | Agents | Tools |
-   - List of agents
+|-------------|----------|--------|-------|
-   - Tool categories
+| 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
 
@@ -44,3 +62,9 @@
 /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)

plugins/contract-validator/commands/validate-contracts.md

@@ -1,11 +1,18 @@
 # /validate-contracts - Full Contract Validation
 
-## Skills to Load
+## Visual Output
-- skills/visual-output.md
+
-- skills/plugin-discovery.md
+When executing this command, display the plugin header:
-- skills/interface-parsing.md
+
-- skills/validation-rules.md
+```
-- skills/mcp-tools-reference.md
+┌──────────────────────────────────────────────────────────────────┐
+│  ✅ CONTRACT-VALIDATOR · Full Validation                         │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the validation.
+
+Run comprehensive cross-plugin compatibility validation for the entire marketplace.
 
 ## Usage
 
@@ -19,23 +26,25 @@
 
 ## Workflow
 
-1. **Display header** per `skills/visual-output.md`
+1. **Discover plugins**:
+   - Scan plugins directory for all plugins with `.claude-plugin/` marker
+   - Parse each plugin's README.md to extract interface
 
-2. **Discover plugins** per `skills/plugin-discovery.md`
+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. **Parse interfaces** per `skills/interface-parsing.md`
+3. **Validate CLAUDE.md agents**:
-   - Use `parse_plugin_interface` for each plugin
+   - Parse agent definitions from CLAUDE.md
+   - Validate all tool references exist
+   - Check data flow through agent sequences
 
-4. **Run validations** per `skills/validation-rules.md`
+4. **Generate report**:
-   - Use `validate_compatibility` for pairwise checks
+   - Summary statistics (plugins, commands, tools, issues)
-   - Use `validate_agent_refs` for CLAUDE.md agents
+   - Detailed findings by severity (error, warning, info)
-   - Use `validate_data_flow` for data sequences
+   - Actionable suggestions for each issue
-   - Use `validate_workflow_integration` for domain plugin advisory interfaces
-
-5. **Generate report**:
-   - Use `generate_compatibility_report` for full report
-   - Use `list_issues` to filter by severity
-   - Display summary and actionable suggestions
 
 ## Examples
 
@@ -43,3 +52,11 @@
 /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

plugins/contract-validator/hooks/hooks.json

@@ -2,13 +2,8 @@
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "",
+        "type": "command",
-        "hooks": [
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/auto-validate.sh"
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/auto-validate.sh"
-          }
-        ]
       }
     ],
     "PostToolUse": [

plugins/contract-validator/mcp-servers/contract-validator

@@ -0,0 +1 @@
+../../../mcp-servers/contract-validator

plugins/contract-validator/skills/dependency-analysis.md

@@ -1,57 +0,0 @@
-# Skill: Dependency Analysis
-
-Analyze dependencies between plugins including shared MCP servers and data flows.
-
-## Dependency Types
-
-| Type | Line Style | Meaning |
-|------|------------|---------|
-| Required | Solid (`-->`) | Plugin cannot function without this |
-| Optional | Dashed (`-.->`) | Plugin works with reduced functionality |
-| Internal | Dotted (`...>`) | Self-dependency within same plugin |
-| Shared MCP | Double (`==>`) | Plugins share same MCP server instance |
-
-## Shared MCP Server Detection
-
-Check each plugin's `.mcp.json` for server definitions. Plugins with identical MCP server names share that server.
-
-**Common shared servers:**
-- `gitea` - Used by projman, pr-review
-- `netbox` - Used by cmdb-assistant
-- `data-platform` - Used by data-platform
-- `viz-platform` - Used by viz-platform
-
-## Data Flow Patterns
-
-### Data Producers
-- `read_csv`, `read_parquet`, `read_json` - File loaders
-- `pg_query`, `pg_execute` - Database queries
-- `filter`, `select`, `groupby`, `join` - Transformations
-
-### Data Consumers
-- `describe`, `head`, `tail` - Data inspection
-- `to_csv`, `to_parquet` - File writers
-- `chart_create` - Visualization
-
-### Cross-Plugin Flows
-| Producer | Consumer | Data Type |
-|----------|----------|-----------|
-| data-platform | viz-platform | `data_ref` |
-| projman | pr-review | issues/lessons |
-| gitea wiki | projman | lessons learned |
-
-## Required vs Optional
-
-- **Required**: Consumer has no default/fallback (ERROR if missing)
-- **Optional**: Consumer works without producer (WARNING if missing)
-
-Determined by:
-- Issue severity from `validate_data_flow`
-- Tool docs stating "requires" vs "uses if available"
-
-## MCP Tools
-
-| Tool | Purpose |
-|------|---------|
-| `validate_data_flow` | Verify producer/consumer relationships |
-| `generate_compatibility_report` | Get full dependency data |

plugins/contract-validator/skills/interface-parsing.md

@@ -1,52 +0,0 @@
-# Skill: Interface Parsing
-
-Parse plugin interfaces from README.md and agent definitions from CLAUDE.md.
-
-## Interface Components
-
-| Component | Source | Description |
-|-----------|--------|-------------|
-| Commands | README.md | Slash commands offered by plugin |
-| Agents | README.md, CLAUDE.md | Autonomous agents defined |
-| Tools | README.md | MCP tools provided |
-| Categories | README.md | Tool groupings and features |
-
-## Parsing README.md
-
-Extract from these sections:
-
-1. **Commands section**: Look for tables with `| Command |` or lists of `/command-name`
-2. **Tools section**: Look for tables with `| Tool |` or code blocks with tool names
-3. **Agents section**: Look for "Four-Agent Model" or "Agents" headings
-
-## Parsing CLAUDE.md
-
-Extract agent definitions from:
-
-1. **Four-Agent Model table**: `| Agent | Personality | Responsibilities |`
-2. **Agent sections**: Headings like `### Planner Agent` or `## Agents`
-3. **Tool sequences**: Lists of tools in workflow steps
-
-## Agent Definition Structure
-
-```yaml
-agent:
-  name: "Planner"
-  personality: "Thoughtful, methodical"
-  responsibilities:
-    - "Sprint planning"
-    - "Architecture analysis"
-  tools:
-    - "create_issue"
-    - "search_lessons"
-  workflow:
-    - step: "Analyze requirements"
-      tools: ["list_issues", "get_issue"]
-```
-
-## MCP Tools
-
-| Tool | Purpose |
-|------|---------|
-| `parse_plugin_interface` | Extract interface from README.md |
-| `parse_claude_md_agents` | Extract agents and tool sequences from CLAUDE.md |

plugins/contract-validator/skills/mcp-tools-reference.md

@@ -1,69 +0,0 @@
-# Skill: MCP Tools Reference
-
-Available MCP tools for contract-validator operations.
-
-## Tool Categories
-
-### Parse Tools
-| Tool | Description |
-|------|-------------|
-| `parse_plugin_interface` | Extract interface from plugin README.md |
-| `parse_claude_md_agents` | Extract agents and tool sequences from CLAUDE.md |
-
-### Validation Tools
-| Tool | Description |
-|------|-------------|
-| `validate_compatibility` | Check two plugins for conflicts |
-| `validate_agent_refs` | Check agent tool references exist |
-| `validate_data_flow` | Verify data flow through agent sequence |
-| `validate_workflow_integration` | Check domain plugin exposes required advisory interfaces |
-
-### Report Tools
-| Tool | Description |
-|------|-------------|
-| `generate_compatibility_report` | Generate full marketplace report (JSON) |
-| `list_issues` | Filter issues by severity or type |
-
-## Tool Usage Patterns
-
-### Full Marketplace Validation
-```
-1. generate_compatibility_report(marketplace_path)
-2. list_issues(severity="ERROR")  # Get critical issues
-3. list_issues(severity="WARNING")  # Get warnings
-```
-
-### Single Agent Check
-```
-1. parse_claude_md_agents(claude_md_path)
-2. validate_agent_refs(agent_name, agents_data)
-3. validate_data_flow(agent_workflow)
-```
-
-### Interface Listing
-```
-1. For each plugin:
-   parse_plugin_interface(readme_path)
-2. Aggregate results into summary table
-```
-
-### Dependency Graph
-```
-1. generate_compatibility_report(marketplace_path)
-2. validate_data_flow(cross_plugin_flows)
-3. Build Mermaid diagram from results
-```
-
-### Workflow Integration Check
-```
-1. validate_workflow_integration(plugin_path, domain_label)  # Check single domain plugin
-2. For each domain in domain-consultation.md detection rules:
-     validate_workflow_integration(domain_plugin_path, domain_label)
-```
-
-## Error Handling
-
-If MCP tools fail:
-1. Check if `/initial-setup` has been run
-2. Verify session was restarted after setup
-3. Check MCP server venv exists and is valid

plugins/contract-validator/skills/plugin-discovery.md

@@ -1,42 +0,0 @@
-# Skill: Plugin Discovery
-
-Discover plugins in a marketplace by scanning for `.claude-plugin/` markers.
-
-## Discovery Process
-
-1. **Identify marketplace root**:
-   - Use provided path or default to current project root
-   - Look for `plugins/` subdirectory
-
-2. **Scan for plugins**:
-   - Find all directories containing `.claude-plugin/plugin.json`
-   - Each is a valid plugin
-
-3. **Build plugin list**:
-   - Extract plugin name from directory name
-   - Record path to plugin root
-
-## Standard Paths
-
-| Context | Path |
-|---------|------|
-| Installed | `~/.claude/plugins/marketplaces/leo-claude-mktplace/plugins/` |
-| Source | `~/claude-plugins-work/plugins/` |
-
-## Expected Structure
-
-```
-plugins/
-  plugin-name/
-    .claude-plugin/
-      plugin.json       # Required marker
-    commands/           # Command definitions
-    agents/             # Agent definitions (optional)
-    hooks/              # Hook definitions (optional)
-    skills/             # Skill files (optional)
-    README.md           # Interface documentation
-```
-
-## MCP Tool
-
-Use `parse_plugin_interface` with each discovered plugin's README.md path.

plugins/contract-validator/skills/validation-rules.md

@@ -1,67 +0,0 @@
-# Skill: Validation Rules
-
-Rules for validating plugin compatibility and agent definitions.
-
-## Compatibility Checks
-
-### 1. Command Name Conflicts
-- No two plugins should have identical command names
-- Severity: ERROR
-
-### 2. Tool Name Overlaps
-- Tools with same name must have same signature
-- Severity: WARNING (may be intentional aliasing)
-
-### 3. Interface Mismatches
-- Producer output types must match consumer input types
-- Severity: ERROR
-
-## Agent Validation
-
-### Tool Reference Check
-1. Parse agent's tool references from workflow steps
-2. Verify each tool exists in available plugins
-3. Report missing or misspelled tool names
-4. Suggest corrections for common mistakes
-
-### Data Flow Validation
-1. Analyze sequence of tools in agent workflow
-2. Verify data producers precede data consumers
-3. Check for orphaned data references
-4. Ensure required data is available at each step
-
-### Workflow Integration Checks
-1. Gate command exists in plugin's commands/ directory
-2. Gate command produces binary PASS/FAIL output
-3. Review command exists (WARNING if missing, not ERROR)
-4. Advisory agent exists referencing the domain label
-- Severity: ERROR for missing gate, WARNING for missing review/agent
-
-## Severity Levels
-
-| Level | Meaning | Action |
-|-------|---------|--------|
-| ERROR | Will cause runtime failures | Must fix |
-| WARNING | May cause issues | Review needed |
-| INFO | Informational only | No action required |
-
-## Common Issues
-
-| Issue | Cause | Fix |
-|-------|-------|-----|
-| Missing tool | Typo or plugin not installed | Check spelling, install plugin |
-| Data flow gap | Producer not called before consumer | Reorder workflow steps |
-| Name conflict | Two plugins use same command | Rename one command |
-| Orphan reference | Data produced but never consumed | Remove or use the data |
-| Missing gate command | Domain plugin lacks /X-gate command | Create commands/{domain}-gate.md |
-| Missing advisory agent | Domain plugin has no reviewer agent | Create agents/{domain}-advisor.md |
-
-## MCP Tools
-
-| Tool | Purpose |
-|------|---------|
-| `validate_compatibility` | Check two plugins for conflicts |
-| `validate_agent_refs` | Check agent tool references |
-| `validate_data_flow` | Verify data flow sequences |
-| `validate_workflow_integration` | Check domain plugin advisory interfaces |
-| `list_issues` | Filter issues by severity or type |

plugins/contract-validator/skills/visual-output.md

@@ -1,88 +0,0 @@
-# Skill: Visual Output
-
-Standard visual formatting for contract-validator commands.
-
-## Command Header
-
-Display at the start of every command:
-
-```
-+----------------------------------------------------------------------+
-|  CONTRACT-VALIDATOR - [Command Name]                                 |
-+----------------------------------------------------------------------+
-```
-
-## Result Boxes
-
-### Success Box
-```
-+====================================================================+
-|          CONTRACT-VALIDATOR [ACTION] COMPLETE                       |
-+====================================================================+
-| Item 1:          [checkmark] Status                                 |
-| Item 2:          [checkmark] Status                                 |
-+====================================================================+
-```
-
-### Error Box
-```
-+====================================================================+
-|          CONTRACT-VALIDATOR [ACTION] FAILED                         |
-+====================================================================+
-| Error:           [description]                                      |
-| Suggestion:      [fix]                                              |
-+====================================================================+
-```
-
-## Summary Tables
-
-### Plugin Summary
-```
-| Plugin      | Commands | Agents | Tools |
-|-------------|----------|--------|-------|
-| projman     | 12       | 4      | 26    |
-| data-platform| 7       | 2      | 32    |
-```
-
-### Issue Summary
-```
-| Severity | Count |
-|----------|-------|
-| ERROR    | 2     |
-| WARNING  | 5     |
-| INFO     | 8     |
-```
-
-## Mermaid Diagrams
-
-For dependency graphs, use flowchart TD format:
-
-```mermaid
-flowchart TD
-    subgraph group_name["Group Label"]
-        node1["Plugin Name"]
-    end
-
-    node1 -->|"label"| node2
-    node1 -.->|"optional"| node3
-
-    classDef required stroke:#e74c3c,stroke-width:2px
-    classDef optional stroke:#f39c12,stroke-dasharray:5 5
-```
-
-## Text Format Alternative
-
-For non-graphical output:
-
-```
-DEPENDENCY GRAPH
-================
-
-Plugins: 12
-MCP Servers: 4
-Dependencies: 8 (5 required, 3 optional)
-
-MCP Server Groups:
-  gitea: projman, pr-review
-  data-platform: data-platform
-```

plugins/data-platform/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "data-platform",
-  "version": "1.3.0",
+  "version": "1.0.0",
   "description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
   "author": {
     "name": "Leo Miranda",
@@ -18,5 +18,6 @@
     "etl",
     "dataframe"
   ],
-  "commands": ["./commands/"]
+  "commands": ["./commands/"],
+  "mcpServers": ["./.mcp.json"]
 }

plugins/data-platform/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "data-platform": {
+      "type": "stdio",
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/data-platform/run.sh",
+      "args": []
+    }
+  }
+}

plugins/data-platform/README.md

@@ -0,0 +1,122 @@
+# data-platform Plugin
+
+Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration for Claude Code.
+
+## Features
+
+- **pandas Operations**: Load, transform, and export DataFrames with persistent data_ref system
+- **PostgreSQL/PostGIS**: Database queries with connection pooling and spatial data support
+- **dbt Integration**: Build tool wrapper with pre-execution validation
+
+## Installation
+
+This plugin is part of the leo-claude-mktplace. Install via:
+
+```bash
+# From marketplace
+claude plugins install leo-claude-mktplace/data-platform
+
+# Setup MCP server venv
+cd ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/data-platform
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Configuration
+
+### PostgreSQL (Optional)
+
+Create `~/.config/claude/postgres.env`:
+
+```env
+POSTGRES_URL=postgresql://user:password@host:5432/database
+```
+
+### dbt (Optional)
+
+Add to project `.env`:
+
+```env
+DBT_PROJECT_DIR=/path/to/dbt/project
+DBT_PROFILES_DIR=~/.dbt
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/initial-setup` | Interactive setup wizard for PostgreSQL and dbt configuration |
+| `/ingest` | Load data from files or database |
+| `/profile` | Generate data profile and statistics |
+| `/data-quality` | Data quality assessment with pass/warn/fail scoring |
+| `/schema` | Show database/DataFrame schema |
+| `/explain` | Explain dbt model lineage |
+| `/lineage` | Visualize data dependencies (ASCII) |
+| `/lineage-viz` | Generate Mermaid flowchart for dbt lineage |
+| `/run` | Execute dbt models |
+| `/dbt-test` | Run dbt tests with formatted results |
+
+## Agents
+
+| Agent | Description |
+|-------|-------------|
+| `data-ingestion` | Data loading and transformation specialist |
+| `data-analysis` | Exploration and profiling specialist |
+
+## data_ref System
+
+All DataFrame operations use a `data_ref` system for persistence:
+
+```
+# Load returns a reference
+read_csv("data.csv") → {"data_ref": "sales_data"}
+
+# Use reference in subsequent operations
+filter("sales_data", "amount > 100") → {"data_ref": "sales_data_filtered"}
+describe("sales_data_filtered") → {statistics}
+```
+
+## Example Workflow
+
+```
+/ingest data/sales.csv
+# → Loaded 50,000 rows as "sales_data"
+
+/profile sales_data
+# → Statistical summary, null counts, quality assessment
+
+/schema orders
+# → Column names, types, constraints
+
+/lineage fct_orders
+# → Dependency graph showing upstream/downstream models
+
+/run dim_customers
+# → Pre-validates then executes dbt model
+```
+
+## Tools Summary
+
+### pandas (14 tools)
+`read_csv`, `read_parquet`, `read_json`, `to_csv`, `to_parquet`, `describe`, `head`, `tail`, `filter`, `select`, `groupby`, `join`, `list_data`, `drop_data`
+
+### PostgreSQL (6 tools)
+`pg_connect`, `pg_query`, `pg_execute`, `pg_tables`, `pg_columns`, `pg_schemas`
+
+### PostGIS (4 tools)
+`st_tables`, `st_geometry_type`, `st_srid`, `st_extent`
+
+### dbt (8 tools)
+`dbt_parse`, `dbt_run`, `dbt_test`, `dbt_build`, `dbt_compile`, `dbt_ls`, `dbt_docs_generate`, `dbt_lineage`
+
+## Memory Management
+
+- Default limit: 100,000 rows per DataFrame
+- Configure via `DATA_PLATFORM_MAX_ROWS` environment variable
+- Use `chunk_size` parameter for large files
+- Monitor with `list_data` tool
+
+## SessionStart Hook
+
+On session start, the plugin checks PostgreSQL connectivity and displays a warning if unavailable. This is non-blocking - pandas and dbt tools remain available.

plugins/data-platform/agents/data-advisor.md

@@ -1,320 +0,0 @@
----
-agent: data-advisor
-description: Reviews code for data integrity, schema validity, and dbt compliance using data-platform MCP tools
-triggers:
-  - /data-review command
-  - /data-gate command
-  - projman orchestrator domain gate
----
-
-# Data Advisor Agent
-
-You are a strict data integrity auditor. Your role is to review code for proper schema usage, dbt compliance, lineage integrity, and data quality standards.
-
-## Visual Output Requirements
-
-**MANDATORY: Display header at start of every response.**
-
-```
-+----------------------------------------------------------------------+
-|  DATA-PLATFORM - Data Advisor                                         |
-|  [Target Path]                                                        |
-+----------------------------------------------------------------------+
-```
-
-## Trigger Conditions
-
-Activate this agent when:
-- User runs `/data-review <path>`
-- User runs `/data-gate <path>`
-- Projman orchestrator requests data domain gate check
-- Code review includes database operations, dbt models, or data pipelines
-
-## Skills to Load
-
-- skills/data-integrity-audit.md
-- skills/mcp-tools-reference.md
-
-## Available MCP Tools
-
-### PostgreSQL (Schema Validation)
-
-| Tool | Purpose |
-|------|---------|
-| `pg_connect` | Verify database is reachable |
-| `pg_tables` | List tables, verify existence |
-| `pg_columns` | Get column details, verify types and constraints |
-| `pg_schemas` | List available schemas |
-| `pg_query` | Run diagnostic queries (SELECT only in review context) |
-
-### PostGIS (Spatial Validation)
-
-| Tool | Purpose |
-|------|---------|
-| `st_tables` | List tables with geometry columns |
-| `st_geometry_type` | Verify geometry types |
-| `st_srid` | Verify coordinate reference systems |
-| `st_extent` | Verify spatial extent is reasonable |
-
-### dbt (Project Validation)
-
-| Tool | Purpose |
-|------|---------|
-| `dbt_parse` | Validate project structure (ALWAYS run first) |
-| `dbt_compile` | Verify SQL renders correctly |
-| `dbt_test` | Run data tests |
-| `dbt_build` | Combined run + test |
-| `dbt_ls` | List all resources (models, tests, sources) |
-| `dbt_lineage` | Get model dependency graph |
-| `dbt_docs_generate` | Generate documentation for inspection |
-
-### pandas (Data Validation)
-
-| Tool | Purpose |
-|------|---------|
-| `describe` | Statistical summary for data quality checks |
-| `head` | Preview data for structural verification |
-| `list_data` | Check for stale DataFrames |
-
-## Operating Modes
-
-### Review Mode (default)
-
-Triggered by `/data-review <path>`
-
-**Characteristics:**
-- Produces detailed report with all findings
-- Groups findings by severity (FAIL/WARN/INFO)
-- Includes actionable recommendations with fixes
-- Does NOT block - informational only
-- Shows category compliance status
-
-### Gate Mode
-
-Triggered by `/data-gate <path>` or projman orchestrator domain gate
-
-**Characteristics:**
-- Binary PASS/FAIL output
-- Only reports FAIL-level issues
-- Returns exit status for automation integration
-- Blocks completion on FAIL
-- Compact output for CI/CD pipelines
-
-## Audit Workflow
-
-### 1. Receive Target Path
-
-Accept file or directory path from command invocation.
-
-### 2. Determine Scope
-
-Analyze target to identify what type of data work is present:
-
-| Pattern | Type | Checks to Run |
-|---------|------|---------------|
-| `dbt_project.yml` present | dbt project | Full dbt validation |
-| `*.sql` files in dbt path | dbt models | Model compilation, lineage |
-| `*.py` with `pg_query`/`pg_execute` | Database operations | Schema validation |
-| `schema.yml` files | dbt schemas | Schema drift detection |
-| Migration files (`*_migration.sql`) | Schema changes | Full PostgreSQL + dbt checks |
-
-### 3. Run Database Checks (if applicable)
-
-```
-1. pg_connect → verify database reachable
-   If fails: WARN, continue with file-based checks
-
-2. pg_tables → verify expected tables exist
-   If missing: FAIL
-
-3. pg_columns on affected tables → verify types
-   If mismatch: FAIL
-```
-
-### 4. Run dbt Checks (if applicable)
-
-```
-1. dbt_parse → validate project
-   If fails: FAIL immediately (project broken)
-
-2. dbt_ls → catalog all resources
-   Record models, tests, sources
-
-3. dbt_lineage on target models → check integrity
-   Orphaned refs: FAIL
-
-4. dbt_compile on target models → verify SQL
-   Compilation errors: FAIL
-
-5. dbt_test --select <targets> → run tests
-   Test failures: FAIL
-
-6. Cross-reference tests → models without tests
-   Missing tests: WARN
-```
-
-### 5. Run PostGIS Checks (if applicable)
-
-```
-1. st_tables → list spatial tables
-   If none found: skip PostGIS checks
-
-2. st_srid → verify SRID correct
-   Unexpected SRID: FAIL
-
-3. st_geometry_type → verify expected types
-   Wrong type: WARN
-
-4. st_extent → sanity check bounding box
-   Unreasonable extent: FAIL
-```
-
-### 6. Scan Python Code (manual patterns)
-
-For Python files with database operations:
-
-| Pattern | Issue | Severity |
-|---------|-------|----------|
-| `f"SELECT * FROM {table}"` | SQL injection risk | WARN |
-| `f"INSERT INTO {table}"` | Unparameterized mutation | WARN |
-| `pg_execute` without WHERE in DELETE/UPDATE | Dangerous mutation | WARN |
-| Hardcoded connection strings | Credential exposure | WARN |
-
-### 7. Generate Report
-
-Output format depends on operating mode (see templates in `skills/data-integrity-audit.md`).
-
-## Report Formats
-
-### Gate Mode Output
-
-**PASS:**
-```
-DATA GATE: PASS
-No blocking data integrity violations found.
-```
-
-**FAIL:**
-```
-DATA GATE: FAIL
-
-Blocking Issues (2):
-1. dbt/models/staging/stg_census.sql - Compilation error: column 'census_yr' not found
-   Fix: Column was renamed to 'census_year' in source table. Update model.
-
-2. portfolio_app/toronto/loaders/census.py:67 - References table 'census_raw' which does not exist
-   Fix: Table was renamed to 'census_demographics' in migration 003.
-
-Run /data-review for full audit report.
-```
-
-### Review Mode Output
-
-```
-+----------------------------------------------------------------------+
-|  DATA-PLATFORM - Data Integrity Audit                                 |
-|  /path/to/project                                                     |
-+----------------------------------------------------------------------+
-
-Target: /path/to/project
-Scope: 12 files scanned, 8 models checked, 3 tables verified
-
-FINDINGS
-
-FAIL (2)
-  1. [dbt/models/staging/stg_census.sql] Compilation error
-     Error: column 'census_yr' does not exist
-     Fix: Column was renamed to 'census_year'. Update SELECT clause.
-
-  2. [portfolio_app/loaders/census.py:67] Missing table reference
-     Error: Table 'census_raw' does not exist
-     Fix: Table renamed to 'census_demographics' in migration 003.
-
-WARN (3)
-  1. [dbt/models/marts/dim_neighbourhoods.sql] Missing dbt test
-     Issue: No unique test on neighbourhood_id
-     Suggestion: Add unique test to schema.yml
-
-  2. [portfolio_app/toronto/queries.py:45] Hardcoded SQL
-     Issue: f"SELECT * FROM {table_name}" without parameterization
-     Suggestion: Use parameterized queries
-
-  3. [dbt/models/staging/stg_legacy.sql] Orphaned model
-     Issue: No downstream consumers or exposures
-     Suggestion: Remove if unused or add to exposure
-
-INFO (1)
-  1. [dbt/models/marts/fct_demographics.sql] Documentation gap
-     Note: Model description missing in schema.yml
-     Suggestion: Add description for discoverability
-
-SUMMARY
-  Schema:   2 issues
-  Lineage:  Intact
-  dbt:      1 failure
-  PostGIS:  Not applicable
-
-VERDICT: FAIL (2 blocking issues)
-```
-
-## Severity Definitions
-
-| Level | Criteria | Action Required |
-|-------|----------|-----------------|
-| **FAIL** | dbt parse/compile fails, missing tables/columns, type mismatches, broken lineage, invalid SRID | Must fix before completion |
-| **WARN** | Missing tests, hardcoded SQL, schema drift, orphaned models | Should fix |
-| **INFO** | Documentation gaps, optimization opportunities | Consider for improvement |
-
-## Error Handling
-
-| Error | Response |
-|-------|----------|
-| Database not reachable | WARN: "PostgreSQL unavailable, skipping schema checks" - continue |
-| No dbt_project.yml | Skip dbt checks silently - not an error |
-| No PostGIS tables | Skip PostGIS checks silently - not an error |
-| MCP tool fails | WARN: "Tool {name} failed: {error}" - continue with remaining |
-| Empty path | PASS: "No data artifacts found in target path" |
-| Invalid path | Error: "Path not found: {path}" |
-
-## Integration with projman
-
-When called as a domain gate by projman orchestrator:
-
-1. Receive path from orchestrator (changed files for the issue)
-2. Determine what type of data work changed
-3. Run audit in gate mode
-4. Return structured result:
-   ```
-   Gate: data
-   Status: PASS | FAIL
-   Blocking: N issues
-   Summary: Brief description
-   ```
-5. Orchestrator decides whether to proceed based on gate status
-
-## Example Interactions
-
-**User**: `/data-review dbt/models/staging/`
-**Agent**:
-1. Scans all .sql files in staging/
-2. Runs dbt_parse to validate project
-3. Runs dbt_compile on each model
-4. Checks lineage for orphaned refs
-5. Cross-references test coverage
-6. Returns detailed report
-
-**User**: `/data-gate portfolio_app/toronto/`
-**Agent**:
-1. Scans for Python files with pg_query/pg_execute
-2. Checks if referenced tables exist
-3. Validates column types
-4. Returns PASS if clean, FAIL with blocking issues if not
-5. Compact output for automation
-
-## Communication Style
-
-Technical and precise. Report findings with exact locations, specific violations, and actionable fixes:
-
-- "Table `census_demographics` column `population` is `varchar(50)` in PostgreSQL but referenced as `integer` in `stg_census.sql` line 14. This will cause a runtime cast error."
-- "Model `dim_neighbourhoods` has no `unique` test on `neighbourhood_id`. Add to `schema.yml` to prevent duplicates."
-- "Spatial extent for `toronto_boundaries` shows global coordinates (-180 to 180). Expected Toronto bbox (~-79.6 to -79.1 longitude). Likely missing ST_Transform or wrong SRID on import."

plugins/data-platform/agents/data-analysis.md

@@ -1,8 +1,3 @@
----
-name: data-analysis
-description: Data analysis specialist for exploration and profiling
----
-
 # Data Analysis Agent
 
 You are a data analysis specialist. Your role is to help users explore, profile, and understand their data.

plugins/data-platform/commands/data-gate.md

@@ -1,104 +0,0 @@
----
-description: Data integrity compliance gate (pass/fail) for sprint execution
-arguments:
-  - name: path
-    description: File or directory to validate
-    required: true
----
-
-# /data-gate
-
-Binary pass/fail validation for data integrity compliance. Used by projman orchestrator during sprint execution to gate issue completion.
-
-## Usage
-
-```
-/data-gate <path>
-```
-
-**Examples:**
-```
-/data-gate ./dbt/models/staging/
-/data-gate ./portfolio_app/toronto/parsers/
-/data-gate ./dbt/
-```
-
-## What It Does
-
-1. **Activates** the `data-advisor` agent in gate mode
-2. **Loads** the `skills/data-integrity-audit.md` skill
-3. **Determines scope** from target path:
-   - dbt project directory: full dbt validation (parse, compile, test, lineage)
-   - Python files with database operations: schema validation
-   - SQL files: dbt model validation
-   - Mixed: all applicable checks
-4. **Checks only FAIL-level violations:**
-   - dbt parse failures (project broken)
-   - dbt compilation errors (SQL invalid)
-   - Missing tables/columns referenced in code
-   - Data type mismatches that cause runtime errors
-   - Broken lineage (orphaned model references)
-   - PostGIS SRID mismatches
-5. **Returns binary result:**
-   - `PASS` - No blocking violations found
-   - `FAIL` - One or more blocking violations
-
-## Output
-
-### On PASS
-```
-DATA GATE: PASS
-No blocking data integrity violations found.
-```
-
-### On FAIL
-```
-DATA GATE: FAIL
-
-Blocking Issues (2):
-1. dbt/models/staging/stg_census.sql - Compilation error: column 'census_yr' not found
-   Fix: Column was renamed to 'census_year' in source table. Update model.
-
-2. portfolio_app/toronto/loaders/census.py:67 - References table 'census_raw' which does not exist
-   Fix: Table was renamed to 'census_demographics' in migration 003.
-
-Run /data-review for full audit report.
-```
-
-## Integration with projman
-
-This command is automatically invoked by the projman orchestrator when:
-
-1. An issue has the `Domain/Data` label
-2. The orchestrator is about to mark the issue as complete
-3. The orchestrator passes the path of changed files
-
-**Gate behavior:**
-- PASS: Issue can be marked complete
-- FAIL: Issue stays open, blocker comment added with failure details
-
-## Differences from /data-review
-
-| Aspect | /data-gate | /data-review |
-|--------|------------|--------------|
-| Output | Binary PASS/FAIL | Detailed report with all severities |
-| Severity | FAIL only | FAIL + WARN + INFO |
-| Purpose | Automation gate | Human review |
-| Verbosity | Minimal | Comprehensive |
-| Speed | Skips INFO checks | Full scan |
-
-## When to Use
-
-- **Sprint execution**: Automatic quality gates via projman
-- **CI/CD pipelines**: Automated data integrity checks
-- **Quick validation**: Fast pass/fail without full report
-- **Pre-merge checks**: Verify data changes before integration
-
-For detailed findings including warnings and suggestions, use `/data-review` instead.
-
-## Requirements
-
-- data-platform MCP server must be running
-- For dbt checks: dbt project must be configured (auto-detected via `dbt_project.yml`)
-- For PostgreSQL checks: connection configured in `~/.config/claude/postgres.env`
-- If database or dbt unavailable: applicable checks skipped with warning (non-blocking degradation)

plugins/data-platform/commands/data-quality.md

@@ -1,13 +1,18 @@
 # /data-quality - Data Quality Assessment
 
-## Skills to Load
-- skills/data-profiling.md
-- skills/mcp-tools-reference.md
-- skills/visual-header.md
-
 ## Visual Output
 
-Display header: `DATA-PLATFORM - Data Quality`
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📊 DATA-PLATFORM · Data Quality                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the assessment.
+
+Comprehensive data quality check for DataFrames with pass/warn/fail scoring.
 
 ## Usage
 
@@ -17,18 +22,72 @@ Display header: `DATA-PLATFORM - Data Quality`
 
 ## Workflow
 
-Execute `skills/data-profiling.md` quality assessment:
+1. **Get data reference**:
+   - If no data_ref provided, use `list_data` to show available options
+   - Validate the data_ref exists
 
-1. **Get data reference**: Use `list_data` if none provided
+2. **Null analysis**:
-2. **Run quality checks**: Nulls, duplicates, types, outliers
+   - Calculate null percentage per column
-3. **Calculate score**: Apply weighted scoring formula
+   - **PASS**: < 5% nulls
-4. **Generate report**: Issues and recommendations
+   - **WARN**: 5-20% nulls
+   - **FAIL**: > 20% nulls
+
+3. **Duplicate detection**:
+   - Check for fully duplicated rows
+   - **PASS**: 0% duplicates
+   - **WARN**: < 1% duplicates
+   - **FAIL**: >= 1% duplicates
+
+4. **Type consistency**:
+   - Identify mixed-type columns (object columns with mixed content)
+   - Flag columns that could be numeric but contain strings
+   - **PASS**: All columns have consistent types
+   - **FAIL**: Mixed types detected
+
+5. **Outlier detection** (numeric columns):
+   - Use IQR method (values beyond 1.5 * IQR)
+   - Report percentage of outliers per column
+   - **PASS**: < 1% outliers
+   - **WARN**: 1-5% outliers
+   - **FAIL**: > 5% outliers
+
+6. **Generate quality report**:
+   - Overall quality score (0-100)
+   - Per-column breakdown
+   - Recommendations for remediation
+
+## Report Format
+
+```
+=== Data Quality Report ===
+Dataset: sales_data
+Rows: 10,000 | Columns: 15
+Overall Score: 82/100 [PASS]
+
+--- Column Analysis ---
+| Column       | Nulls | Dups | Type     | Outliers | Status |
+|--------------|-------|------|----------|----------|--------|
+| customer_id  | 0.0%  | -    | int64    | 0.2%     | PASS   |
+| email        | 2.3%  | -    | object   | -        | PASS   |
+| amount       | 15.2% | -    | float64  | 3.1%     | WARN   |
+| created_at   | 0.0%  | -    | datetime | -        | PASS   |
+
+--- Issues Found ---
+[WARN] Column 'amount': 15.2% null values (threshold: 5%)
+[WARN] Column 'amount': 3.1% outliers detected
+[FAIL] 1.2% duplicate rows detected (12 rows)
+
+--- Recommendations ---
+1. Investigate null values in 'amount' column
+2. Review outliers in 'amount' - may be data entry errors
+3. Remove or deduplicate 12 duplicate rows
+```
 
 ## Options
 
 | Flag | Description |
 |------|-------------|
-| `--strict` | Stricter thresholds (WARN at 1%, FAIL at 5% nulls) |
+| `--strict` | Use stricter thresholds (WARN at 1% nulls, FAIL at 5%) |
 
 ## Examples
 
@@ -37,12 +96,20 @@ Execute `skills/data-profiling.md` quality assessment:
 /data-quality df_customers --strict
 ```
 
-## Quality Thresholds
+## Scoring
 
-See `skills/data-profiling.md` for detailed thresholds and scoring.
+| Component | Weight | Scoring |
+|-----------|--------|---------|
+| Nulls | 30% | 100 - (avg_null_pct * 2) |
+| Duplicates | 20% | 100 - (dup_pct * 50) |
+| Type consistency | 25% | 100 if clean, 0 if mixed |
+| Outliers | 25% | 100 - (avg_outlier_pct * 10) |
 
-## Required MCP Tools
+Final score: Weighted average, capped at 0-100
 
-- `describe` - Get statistical summary
+## Available Tools
+
+Use these MCP tools:
+- `describe` - Get statistical summary (for outlier detection)
 - `head` - Preview data
 - `list_data` - List available DataFrames

plugins/data-platform/commands/data-review.md

@@ -1,149 +0,0 @@
----
-description: Audit data integrity, schema validity, and dbt compliance
-arguments:
-  - name: path
-    description: File, directory, or dbt project to audit
-    required: true
----
-
-# /data-review
-
-Comprehensive data integrity audit producing a detailed report with findings at all severity levels. For human review and standalone codebase auditing.
-
-## Usage
-
-```
-/data-review <path>
-```
-
-**Examples:**
-```
-/data-review ./dbt/
-/data-review ./portfolio_app/toronto/
-/data-review ./dbt/models/marts/
-```
-
-## What It Does
-
-1. **Activates** the `data-advisor` agent in review mode
-2. **Scans target path** to determine scope:
-   - Identifies dbt project files (.sql models, schema.yml, sources.yml)
-   - Identifies Python files with database operations
-   - Identifies migration files
-   - Identifies PostGIS usage
-3. **Runs all check categories:**
-   - Schema validity (PostgreSQL tables, columns, types)
-   - dbt project health (parse, compile, test, lineage)
-   - PostGIS compliance (SRID, geometry types, extent)
-   - Data type consistency
-   - Code patterns (unsafe SQL, hardcoded queries)
-4. **Produces detailed report** with all severity levels (FAIL, WARN, INFO)
-5. **Provides actionable recommendations** for each finding
-
-## Output Format
-
-```
-+----------------------------------------------------------------------+
-|  DATA-PLATFORM - Data Integrity Audit                                 |
-|  /path/to/project                                                     |
-+----------------------------------------------------------------------+
-
-Target: /path/to/project
-Scope: N files scanned, N models checked, N tables verified
-
-FINDINGS
-
-FAIL (N)
-  1. [location] violation description
-     Fix: actionable fix
-
-WARN (N)
-  1. [location] warning description
-     Suggestion: improvement suggestion
-
-INFO (N)
-  1. [location] info description
-     Note: context
-
-SUMMARY
-  Schema:   Valid | N issues
-  Lineage:  Intact | N orphaned
-  dbt:      Passes | N failures
-  PostGIS:  Valid | N issues | Not applicable
-
-VERDICT: PASS | FAIL (N blocking issues)
-```
-
-## When to Use
-
-### Before Sprint Planning
-Audit data layer health to identify tech debt and inform sprint scope.
-```
-/data-review ./dbt/
-```
-
-### During Code Review
-Get detailed data integrity findings alongside code review comments.
-```
-/data-review ./dbt/models/staging/stg_new_source.sql
-```
-
-### After Migrations
-Verify schema changes didn't break anything downstream.
-```
-/data-review ./migrations/
-```
-
-### Periodic Health Checks
-Regular data infrastructure audits for proactive maintenance.
-```
-/data-review ./data_pipeline/
-```
-
-### New Project Onboarding
-Understand the current state of data architecture.
-```
-/data-review .
-```
-
-## Severity Levels
-
-| Level | Meaning | Gate Impact |
-|-------|---------|-------------|
-| **FAIL** | Blocking issues that will cause runtime errors | Would block `/data-gate` |
-| **WARN** | Quality issues that should be addressed | Does not block gate |
-| **INFO** | Suggestions for improvement | Does not block gate |
-
-## Differences from /data-gate
-
-`/data-review` gives you the full picture. `/data-gate` gives the orchestrator a yes/no.
-
-| Aspect | /data-gate | /data-review |
-|--------|------------|--------------|
-| Output | Binary PASS/FAIL | Detailed report |
-| Severity | FAIL only | FAIL + WARN + INFO |
-| Purpose | Automation | Human review |
-| Verbosity | Minimal | Comprehensive |
-| Speed | Fast (skips INFO) | Thorough |
-
-Use `/data-review` when you want to understand.
-Use `/data-gate` when you want to automate.
-
-## Requirements
-
-- data-platform MCP server must be running
-- For dbt checks: dbt project must be configured (auto-detected via `dbt_project.yml`)
-- For PostgreSQL checks: connection configured in `~/.config/claude/postgres.env`
-
-**Graceful degradation:** If database or dbt unavailable, applicable checks are skipped with a note in the report rather than failing entirely.
-
-## Skills Used
-
-- `skills/data-integrity-audit.md` - Audit rules and patterns
-- `skills/mcp-tools-reference.md` - MCP tool reference
-
-## Related Commands
-
-- `/data-gate` - Binary pass/fail for automation
-- `/lineage` - Visualize dbt model dependencies
-- `/schema` - Explore database schema

plugins/data-platform/commands/dbt-test.md

@@ -1,13 +1,18 @@
 # /dbt-test - Run dbt Tests
 
-## Skills to Load
-- skills/dbt-workflow.md
-- skills/mcp-tools-reference.md
-- skills/visual-header.md
-
 ## Visual Output
 
-Display header: `DATA-PLATFORM - dbt Tests`
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📊 DATA-PLATFORM · dbt Tests                                     │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the tests.
+
+Execute dbt tests with formatted pass/fail results.
 
 ## Usage
 
@@ -17,17 +22,75 @@ Display header: `DATA-PLATFORM - dbt Tests`
 
 ## Workflow
 
-Execute `skills/dbt-workflow.md` test workflow:
+1. **Pre-validation** (MANDATORY):
+   - Use `dbt_parse` to validate project first
+   - If validation fails, show errors and STOP
 
-1. **Pre-validation** (MANDATORY): Run `dbt_parse` first
+2. **Execute tests**:
-2. **Execute tests**: Use `dbt_test` with selection
+   - Use `dbt_test` with provided selection
-3. **Format results**: Group by test type, show pass/fail/warn counts
+   - Capture all test results
+
+3. **Format results**:
+   - Group by test type (schema vs. data)
+   - Show pass/fail status with counts
+   - Display failure details
+
+## Report Format
+
+```
+=== dbt Test Results ===
+Project: my_project
+Selection: tag:critical
+
+--- Summary ---
+Total: 24 tests
+PASS:  22 (92%)
+FAIL:  1  (4%)
+WARN:  1  (4%)
+SKIP:  0  (0%)
+
+--- Schema Tests (18) ---
+[PASS] unique_dim_customers_customer_id
+[PASS] not_null_dim_customers_customer_id
+[PASS] not_null_dim_customers_email
+[PASS] accepted_values_dim_customers_status
+[FAIL] relationships_fct_orders_customer_id
+
+--- Data Tests (6) ---
+[PASS] assert_positive_order_amounts
+[PASS] assert_valid_dates
+[WARN] assert_recent_orders (threshold: 7 days)
+
+--- Failure Details ---
+Test: relationships_fct_orders_customer_id
+Type: schema (relationships)
+Model: fct_orders
+Message: 15 records failed referential integrity check
+Query: SELECT * FROM fct_orders WHERE customer_id NOT IN (SELECT customer_id FROM dim_customers)
+
+--- Warning Details ---
+Test: assert_recent_orders
+Type: data
+Message: No orders in last 7 days (expected for dev environment)
+Severity: warn
+```
+
+## Selection Syntax
+
+| Pattern | Meaning |
+|---------|---------|
+| (none) | Run all tests |
+| `model_name` | Tests for specific model |
+| `+model_name` | Tests for model and upstream |
+| `tag:critical` | Tests with tag |
+| `test_type:schema` | Only schema tests |
+| `test_type:data` | Only data tests |
 
 ## Options
 
 | Flag | Description |
 |------|-------------|
-| `--warn-only` | Treat failures as warnings |
+| `--warn-only` | Treat failures as warnings (don't fail CI) |
 
 ## Examples
 
@@ -35,9 +98,34 @@ Execute `skills/dbt-workflow.md` test workflow:
 /dbt-test                          # Run all tests
 /dbt-test dim_customers            # Tests for specific model
 /dbt-test tag:critical             # Run critical tests only
+/dbt-test +fct_orders              # Test model and its upstream
 ```
 
-## Required MCP Tools
+## Test Types
 
+### Schema Tests
+Built-in tests defined in `schema.yml`:
+- `unique` - No duplicate values
+- `not_null` - No null values
+- `accepted_values` - Value in allowed list
+- `relationships` - Foreign key integrity
+
+### Data Tests
+Custom SQL tests in `tests/` directory:
+- Return rows that fail the assertion
+- Zero rows = pass, any rows = fail
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All tests passed |
+| 1 | One or more tests failed |
+| 2 | dbt error (parse failure, etc.) |
+
+## Available Tools
+
+Use these MCP tools:
 - `dbt_parse` - Pre-validation (ALWAYS RUN FIRST)
 - `dbt_test` - Execute tests (REQUIRED)
+- `dbt_build` - Alternative: run + test together