Merge pull request 'feat: Token consumption overhaul - lean/full profile switching' (#429) from feat/token-consumption-overhaul into development

Reviewed-on: #429

.claude-plugin/marketplace-full.json

@@ -0,0 +1,205 @@
+{
+  "name": "leo-claude-mktplace",
+  "owner": {
+    "name": "Leo Miranda",
+    "email": "leobmiranda@gmail.com"
+  },
+  "metadata": {
+    "description": "Project management plugins with Gitea and NetBox integrations",
+    "version": "7.0.0"
+  },
+  "plugins": [
+    {
+      "name": "projman",
+      "version": "3.4.0",
+      "description": "Sprint planning and project management with Gitea integration",
+      "source": "./plugins/projman",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"],
+      "category": "development",
+      "tags": ["sprint", "agile", "gitea", "project-management"],
+      "license": "MIT"
+    },
+    {
+      "name": "doc-guardian",
+      "version": "1.1.0",
+      "description": "Automatic documentation drift detection and synchronization",
+      "source": "./plugins/doc-guardian",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "productivity",
+      "tags": ["documentation", "drift-detection", "sync"],
+      "license": "MIT"
+    },
+    {
+      "name": "code-sentinel",
+      "version": "1.0.1",
+      "description": "Security scanning and code refactoring tools",
+      "source": "./plugins/code-sentinel",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/code-sentinel/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "security",
+      "tags": ["security-scan", "refactoring", "vulnerabilities"],
+      "license": "MIT"
+    },
+    {
+      "name": "project-hygiene",
+      "version": "0.1.0",
+      "description": "Post-task cleanup hook that removes temp files and manages orphaned files",
+      "source": "./plugins/project-hygiene",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/project-hygiene/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "productivity",
+      "tags": ["cleanup", "automation", "hygiene"],
+      "license": "MIT"
+    },
+    {
+      "name": "cmdb-assistant",
+      "version": "1.2.0",
+      "description": "NetBox CMDB integration with data quality validation and machine registration",
+      "source": "./plugins/cmdb-assistant",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"],
+      "category": "infrastructure",
+      "tags": ["cmdb", "netbox", "dcim", "ipam", "data-quality", "validation"],
+      "license": "MIT"
+    },
+    {
+      "name": "claude-config-maintainer",
+      "version": "1.2.0",
+      "description": "CLAUDE.md and settings.local.json optimization for Claude Code projects",
+      "source": "./plugins/claude-config-maintainer",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"
+    },
+    {
+      "name": "clarity-assist",
+      "version": "1.2.0",
+      "description": "Prompt optimization and requirement clarification with ND-friendly accommodations",
+      "source": "./plugins/clarity-assist",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"
+    },
+    {
+      "name": "git-flow",
+      "version": "1.2.0",
+      "description": "Git workflow automation with intelligent commit messages and branch management",
+      "source": "./plugins/git-flow",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"
+    },
+    {
+      "name": "pr-review",
+      "version": "1.1.0",
+      "description": "Multi-agent pull request review with confidence scoring and actionable feedback",
+      "source": "./plugins/pr-review",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"],
+      "category": "development",
+      "tags": ["code-review", "pull-requests", "security", "quality"],
+      "license": "MIT"
+    },
+    {
+      "name": "data-platform",
+      "version": "1.3.0",
+      "description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
+      "source": "./plugins/data-platform",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"],
+      "category": "data",
+      "tags": ["pandas", "postgresql", "postgis", "dbt", "data-engineering", "etl"],
+      "license": "MIT"
+    },
+    {
+      "name": "viz-platform",
+      "version": "1.1.0",
+      "description": "Visualization tools with Dash Mantine Components validation, Plotly charts, and theming",
+      "source": "./plugins/viz-platform",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"],
+      "category": "visualization",
+      "tags": ["dash", "plotly", "mantine", "charts", "dashboards", "theming", "dmc"],
+      "license": "MIT"
+    },
+    {
+      "name": "contract-validator",
+      "version": "1.2.0",
+      "description": "Cross-plugin compatibility validation and Claude.md agent verification",
+      "source": "./plugins/contract-validator",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"],
+      "category": "development",
+      "tags": ["validation", "contracts", "compatibility", "agents", "interfaces", "cross-plugin"],
+      "license": "MIT"
+    }
+  ]
+}

.claude-plugin/marketplace-lean.json

@@ -0,0 +1,109 @@
+{
+  "name": "leo-claude-mktplace",
+  "owner": {
+    "name": "Leo Miranda",
+    "email": "leobmiranda@gmail.com"
+  },
+  "metadata": {
+    "description": "Project management plugins with Gitea and NetBox integrations",
+    "version": "7.0.0"
+  },
+  "plugins": [
+    {
+      "name": "projman",
+      "version": "3.4.0",
+      "description": "Sprint planning and project management with Gitea integration",
+      "source": "./plugins/projman",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"],
+      "category": "development",
+      "tags": ["sprint", "agile", "gitea", "project-management"],
+      "license": "MIT"
+    },
+    {
+      "name": "git-flow",
+      "version": "1.2.0",
+      "description": "Git workflow automation with intelligent commit messages and branch management",
+      "source": "./plugins/git-flow",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"
+    },
+    {
+      "name": "pr-review",
+      "version": "1.1.0",
+      "description": "Multi-agent pull request review with confidence scoring and actionable feedback",
+      "source": "./plugins/pr-review",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"],
+      "category": "development",
+      "tags": ["code-review", "pull-requests", "security", "quality"],
+      "license": "MIT"
+    },
+    {
+      "name": "clarity-assist",
+      "version": "1.2.0",
+      "description": "Prompt optimization and requirement clarification with ND-friendly accommodations",
+      "source": "./plugins/clarity-assist",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"
+    },
+    {
+      "name": "code-sentinel",
+      "version": "1.0.1",
+      "description": "Security scanning and code refactoring tools",
+      "source": "./plugins/code-sentinel",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/code-sentinel/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "security",
+      "tags": ["security-scan", "refactoring", "vulnerabilities"],
+      "license": "MIT"
+    },
+    {
+      "name": "doc-guardian",
+      "version": "1.1.0",
+      "description": "Automatic documentation drift detection and synchronization",
+      "source": "./plugins/doc-guardian",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "hooks": ["./hooks/hooks.json"],
+      "category": "productivity",
+      "tags": ["documentation", "drift-detection", "sync"],
+      "license": "MIT"
+    }
+  ]
+}

.claude-plugin/marketplace.json

@@ -6,12 +6,12 @@
   },
   "metadata": {
     "description": "Project management plugins with Gitea and NetBox integrations",
-    "version": "5.1.0"
+    "version": "7.0.0"
   },
   "plugins": [
     {
       "name": "projman",
-      "version": "3.2.0",
+      "version": "3.4.0",
       "description": "Sprint planning and project management with Gitea integration",
       "source": "./plugins/projman",
       "author": {
@@ -20,30 +20,62 @@
       },
       "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",
-      "mcpServers": ["./.mcp.json"],
+      "hooks": ["./hooks/hooks.json"],
       "category": "development",
       "tags": ["sprint", "agile", "gitea", "project-management"],
       "license": "MIT"
     },
     {
-      "name": "doc-guardian",
-      "version": "1.0.0",
-      "description": "Automatic documentation drift detection and synchronization",
-      "source": "./plugins/doc-guardian",
+      "name": "git-flow",
+      "version": "1.2.0",
+      "description": "Git workflow automation with intelligent commit messages and branch management",
+      "source": "./plugins/git-flow",
       "author": {
         "name": "Leo Miranda",
         "email": "leobmiranda@gmail.com"
       },
-      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md",
+      "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"
+    },
+    {
+      "name": "pr-review",
+      "version": "1.1.0",
+      "description": "Multi-agent pull request review with confidence scoring and actionable feedback",
+      "source": "./plugins/pr-review",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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"],
+      "category": "development",
+      "tags": ["code-review", "pull-requests", "security", "quality"],
+      "license": "MIT"
+    },
+    {
+      "name": "clarity-assist",
+      "version": "1.2.0",
+      "description": "Prompt optimization and requirement clarification with ND-friendly accommodations",
+      "source": "./plugins/clarity-assist",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "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": ["documentation", "drift-detection", "sync"],
+      "tags": ["prompts", "requirements", "clarification", "nd-friendly"],
       "license": "MIT"
     },
     {
       "name": "code-sentinel",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "description": "Security scanning and code refactoring tools",
       "source": "./plugins/code-sentinel",
       "author": {
@@ -58,144 +90,19 @@
       "license": "MIT"
     },
     {
-      "name": "project-hygiene",
-      "version": "0.1.0",
-      "description": "Post-task cleanup hook that removes temp files and manages orphaned files",
-      "source": "./plugins/project-hygiene",
+      "name": "doc-guardian",
+      "version": "1.1.0",
+      "description": "Automatic documentation drift detection and synchronization",
+      "source": "./plugins/doc-guardian",
       "author": {
         "name": "Leo Miranda",
         "email": "leobmiranda@gmail.com"
       },
-      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/project-hygiene/README.md",
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md",
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
       "hooks": ["./hooks/hooks.json"],
       "category": "productivity",
-      "tags": ["cleanup", "automation", "hygiene"],
-      "license": "MIT"
-    },
-    {
-      "name": "cmdb-assistant",
-      "version": "1.1.0",
-      "description": "NetBox CMDB integration with data quality validation and machine registration",
-      "source": "./plugins/cmdb-assistant",
-      "author": {
-        "name": "Leo Miranda",
-        "email": "leobmiranda@gmail.com"
-      },
-      "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",
-      "mcpServers": ["./.mcp.json"],
-      "category": "infrastructure",
-      "tags": ["cmdb", "netbox", "dcim", "ipam", "data-quality", "validation"],
-      "license": "MIT"
-    },
-    {
-      "name": "claude-config-maintainer",
-      "version": "1.0.0",
-      "description": "CLAUDE.md optimization and maintenance for Claude Code projects",
-      "source": "./plugins/claude-config-maintainer",
-      "author": {
-        "name": "Leo Miranda",
-        "email": "leobmiranda@gmail.com"
-      },
-      "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",
-      "category": "development",
-      "tags": ["claude-md", "configuration", "optimization"],
-      "license": "MIT"
-    },
-    {
-      "name": "clarity-assist",
-      "version": "1.0.0",
-      "description": "Prompt optimization and requirement clarification with ND-friendly accommodations",
-      "source": "./plugins/clarity-assist",
-      "author": {
-        "name": "Leo Miranda",
-        "email": "leobmiranda@gmail.com"
-      },
-      "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",
-      "category": "productivity",
-      "tags": ["prompts", "requirements", "clarification", "nd-friendly"],
-      "license": "MIT"
-    },
-    {
-      "name": "git-flow",
-      "version": "1.0.0",
-      "description": "Git workflow automation with intelligent commit messages and branch management",
-      "source": "./plugins/git-flow",
-      "author": {
-        "name": "Leo Miranda",
-        "email": "leobmiranda@gmail.com"
-      },
-      "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",
-      "category": "development",
-      "tags": ["git", "workflow", "commits", "branching"],
-      "license": "MIT"
-    },
-    {
-      "name": "pr-review",
-      "version": "1.0.0",
-      "description": "Multi-agent pull request review with confidence scoring and actionable feedback",
-      "source": "./plugins/pr-review",
-      "author": {
-        "name": "Leo Miranda",
-        "email": "leobmiranda@gmail.com"
-      },
-      "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",
-      "mcpServers": ["./.mcp.json"],
-      "category": "development",
-      "tags": ["code-review", "pull-requests", "security", "quality"],
-      "license": "MIT"
-    },
-    {
-      "name": "data-platform",
-      "version": "1.0.0",
-      "description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
-      "source": "./plugins/data-platform",
-      "author": {
-        "name": "Leo Miranda",
-        "email": "leobmiranda@gmail.com"
-      },
-      "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",
-      "mcpServers": ["./.mcp.json"],
-      "category": "data",
-      "tags": ["pandas", "postgresql", "postgis", "dbt", "data-engineering", "etl"],
-      "license": "MIT"
-    },
-    {
-      "name": "viz-platform",
-      "version": "1.0.0",
-      "description": "Visualization tools with Dash Mantine Components validation, Plotly charts, and theming",
-      "source": "./plugins/viz-platform",
-      "author": {
-        "name": "Leo Miranda",
-        "email": "leobmiranda@gmail.com"
-      },
-      "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",
-      "mcpServers": ["./.mcp.json"],
-      "category": "visualization",
-      "tags": ["dash", "plotly", "mantine", "charts", "dashboards", "theming", "dmc"],
-      "license": "MIT"
-    },
-    {
-      "name": "contract-validator",
-      "version": "1.0.0",
-      "description": "Cross-plugin compatibility validation and Claude.md agent verification",
-      "source": "./plugins/contract-validator",
-      "author": {
-        "name": "Leo Miranda",
-        "email": "leobmiranda@gmail.com"
-      },
-      "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",
-      "mcpServers": ["./.mcp.json"],
-      "category": "development",
-      "tags": ["validation", "contracts", "compatibility", "agents", "interfaces", "cross-plugin"],
+      "tags": ["documentation", "drift-detection", "sync"],
       "license": "MIT"
     }
   ]

.claude/backups/CLAUDE.md.2026-01-22_132037

@@ -0,0 +1,249 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+## Project Overview
+
+**Repository:** leo-claude-mktplace
+**Version:** 3.0.1
+**Status:** Production Ready
+
+A plugin marketplace for Claude Code containing:
+
+| Plugin | Description | Version |
+|--------|-------------|---------|
+| `projman` | Sprint planning and project management with Gitea integration | 3.0.0 |
+| `git-flow` | Git workflow automation with smart commits and branch management | 1.0.0 |
+| `pr-review` | Multi-agent PR review with confidence scoring | 1.0.0 |
+| `clarity-assist` | Prompt optimization with ND-friendly accommodations | 1.0.0 |
+| `doc-guardian` | Automatic documentation drift detection and synchronization | 1.0.0 |
+| `code-sentinel` | Security scanning and code refactoring tools | 1.0.0 |
+| `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 1.0.0 |
+| `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 1.0.0 |
+| `project-hygiene` | Post-task cleanup automation via hooks | 0.1.0 |
+
+## Quick Start
+
+```bash
+# Validate marketplace compliance
+./scripts/validate-marketplace.sh
+
+# Setup commands (in a target project with plugin installed)
+/initial-setup    # First time: full setup wizard
+/project-init     # New project: quick config
+/project-sync     # After repo move: sync config
+
+# Run projman commands
+/sprint-plan      # Start sprint planning
+/sprint-status    # Check progress
+/review           # Pre-close code quality review
+/test-check       # Verify tests before close
+/sprint-close     # Complete sprint
+```
+
+## Repository Structure
+
+```
+leo-claude-mktplace/
+├── .claude-plugin/
+│   └── marketplace.json          # Marketplace manifest
+├── mcp-servers/                  # SHARED MCP servers (v3.0.0+)
+│   ├── gitea/                    # Gitea MCP (issues, PRs, wiki)
+│   └── netbox/                   # NetBox MCP (CMDB)
+├── plugins/
+│   ├── projman/                  # Sprint management
+│   │   ├── .claude-plugin/plugin.json
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/gitea -> ../../../mcp-servers/gitea  # SYMLINK
+│   │   ├── commands/             # 12 commands (incl. setup)
+│   │   ├── hooks/                # SessionStart mismatch detection
+│   │   ├── agents/               # 4 agents
+│   │   └── 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
+│   │   ├── .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 (NEW v3.0.0)
+│   │   ├── .claude-plugin/plugin.json
+│   │   ├── commands/             # 2 commands
+│   │   └── agents/
+│   ├── doc-guardian/             # Documentation drift detection
+│   ├── code-sentinel/            # Security scanning & refactoring
+│   ├── claude-config-maintainer/
+│   ├── cmdb-assistant/
+│   └── project-hygiene/
+├── scripts/
+│   ├── setup.sh, post-update.sh
+│   └── validate-marketplace.sh   # Marketplace compliance validation
+└── docs/
+    ├── CANONICAL-PATHS.md        # Single source of truth for paths
+    └── 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.)
+
+### 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)
+
+| Agent | Personality | Responsibilities |
+|-------|-------------|------------------|
+| **Planner** | Thoughtful, methodical | Sprint planning, architecture analysis, issue creation, lesson search |
+| **Orchestrator** | Concise, action-oriented | Sprint execution, parallel batching, Git operations, lesson capture |
+| **Executor** | Implementation-focused | Code implementation, branch management, MR creation |
+| **Code Reviewer** | Thorough, practical | Pre-close quality review, security scan, test verification |
+
+### MCP Server Tools (Gitea)
+
+| Category | Tools |
+|----------|-------|
+| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment` |
+| Labels | `get_labels`, `suggest_labels`, `create_label` |
+| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone` |
+| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `get_execution_order` |
+| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_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` *(NEW v3.0.0)* |
+| Validation | `validate_repo_org`, `get_branch_protection` |
+
+### Hybrid Configuration
+
+| Level | Location | Purpose |
+|-------|----------|---------|
+| System | `~/.config/claude/gitea.env` | Credentials (GITEA_API_URL, GITEA_API_TOKEN) |
+| Project | `.env` in project root | Repository specification (GITEA_ORG, GITEA_REPO) |
+
+**Note:** `GITEA_ORG` is at project level since different projects may belong to different organizations.
+
+### Branch-Aware Security
+
+| Branch Pattern | Mode | Capabilities |
+|----------------|------|--------------|
+| `development`, `feat/*` | Development | Full access |
+| `staging` | Staging | Read-only code, can create issues |
+| `main`, `master` | Production | Read-only, emergency only |
+
+## Label Taxonomy
+
+43 labels total: 27 organization + 16 repository
+
+**Organization:** Agent/2, Complexity/3, Efforts/5, Priority/4, Risk/3, Source/4, Type/6
+**Repository:** Component/9, Tech/7
+
+Sync with `/labels-sync` command.
+
+## Lessons Learned System
+
+Stored in Gitea Wiki under `lessons-learned/sprints/`.
+
+**Workflow:**
+1. Orchestrator captures at sprint close via MCP tools
+2. Planner searches at sprint start using `search_lessons`
+3. Tags enable cross-project discovery
+
+## Common Operations
+
+### Adding a New Plugin
+
+1. Create `plugins/{name}/.claude-plugin/plugin.json`
+2. Add entry to `.claude-plugin/marketplace.json` with category, tags, license
+3. Create `README.md` and `claude-md-integration.md`
+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 `plugins/projman/README.md`
+3. Update marketplace description if significant
+
+### Validation
+
+```bash
+./scripts/validate-marketplace.sh  # Validates all manifests
+```
+
+## Path Verification Protocol
+
+**Before creating any file:**
+
+1. Read `docs/CANONICAL-PATHS.md`
+2. List all paths to be created/modified
+3. Verify each against canonical paths
+4. If not in canonical paths, STOP and ask
+
+## Documentation Index
+
+| Document | Purpose |
+|----------|---------|
+| `docs/CANONICAL-PATHS.md` | **Single source of truth** for paths |
+| `docs/COMMANDS-CHEATSHEET.md` | All commands quick reference with workflow examples |
+| `docs/CONFIGURATION.md` | Centralized setup guide |
+| `docs/UPDATING.md` | Update guide for the marketplace |
+| `plugins/projman/CONFIGURATION.md` | Quick reference (links to central) |
+| `plugins/projman/README.md` | Projman full documentation |
+
+## Versioning and Changelog Rules
+
+### Version Display
+**The marketplace version is displayed ONLY in the main `README.md` title.**
+
+- Format: `# Leo Claude Marketplace - vX.Y.Z`
+- Do NOT add version numbers to individual plugin documentation titles
+- Do NOT add version numbers to configuration guides
+- Do NOT add version numbers to CLAUDE.md or other docs
+
+### Changelog Maintenance (MANDATORY)
+**`CHANGELOG.md` is the authoritative source for version history.**
+
+When releasing a new version:
+1. Update main `README.md` title with new version
+2. Update `CHANGELOG.md` with:
+   - Version number and date: `## [X.Y.Z] - YYYY-MM-DD`
+   - **Added**: New features, commands, files
+   - **Changed**: Modifications to existing functionality
+   - **Fixed**: Bug fixes
+   - **Removed**: Deleted features, files, deprecated items
+3. Update `marketplace.json` metadata version
+4. Update plugin `plugin.json` versions if plugin-specific changes
+
+### Version Format
+- Follow [Semantic Versioning](https://semver.org/): MAJOR.MINOR.PATCH
+- MAJOR: Breaking changes
+- MINOR: New features, backward compatible
+- PATCH: Bug fixes, minor improvements
+
+---
+
+**Last Updated:** 2026-01-20

.doc-guardian-queue

@@ -0,0 +1,65 @@
+# Doc Guardian Queue - cleared after sync on 2026-02-02
+2026-02-02T11:41:00 | .claude-plugin | /home/lmiranda/claude-plugins-work/.claude-plugin/marketplace.json | CLAUDE.md .claude-plugin/marketplace.json
+2026-02-02T13:35:48 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/sprint-approval.md | README.md
+2026-02-02T13:36:03 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-start.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-02T13:36:16 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/orchestrator.md | README.md CLAUDE.md
+2026-02-02T13:39:07 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/rfc.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-02T13:39:15 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/setup.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-02T13:39:32 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/rfc-workflow.md | README.md
+2026-02-02T13:43:14 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/rfc-templates.md | README.md
+2026-02-02T13:44:55 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/sprint-lifecycle.md | README.md
+2026-02-02T13:45:04 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/label-taxonomy/labels-reference.md | README.md
+2026-02-02T13:45:14 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-plan.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-02T13:45:48 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/review.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-02T13:46:07 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-close.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-02T13:46:21 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-status.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-02T13:46:38 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/planner.md | README.md CLAUDE.md
+2026-02-02T13:46:57 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/code-reviewer.md | README.md CLAUDE.md
+2026-02-02T13:49:13 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/design-gate.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-02T13:49:24 | commands | /home/lmiranda/claude-plugins-work/plugins/data-platform/commands/data-gate.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-02T13:49:35 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/domain-consultation.md | README.md
+2026-02-02T13:50:04 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/validation_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-02T13:50:59 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/server.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-02T13:51:32 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_validation_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-02T13:51:49 | skills | /home/lmiranda/claude-plugins-work/plugins/contract-validator/skills/validation-rules.md | README.md
+2026-02-02T13:52:07 | skills | /home/lmiranda/claude-plugins-work/plugins/contract-validator/skills/mcp-tools-reference.md | README.md
+2026-02-02T13:59:09 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/progress-tracking.md | README.md
+2026-02-02T14:01:34 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/test.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:08:38 | commands | /home/lmiranda/claude-plugins-work/plugins/git-flow/commands/git-commit.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:08:39 | commands | /home/lmiranda/claude-plugins-work/plugins/git-flow/commands/git-commit-push.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:08:40 | commands | /home/lmiranda/claude-plugins-work/plugins/git-flow/commands/git-commit-merge.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:08:41 | commands | /home/lmiranda/claude-plugins-work/plugins/git-flow/commands/git-commit-sync.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:08:49 | commands | /home/lmiranda/claude-plugins-work/plugins/cmdb-assistant/commands/cmdb-setup.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:08:50 | commands | /home/lmiranda/claude-plugins-work/plugins/pr-review/commands/project-init.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:08:51 | skills | /home/lmiranda/claude-plugins-work/plugins/cmdb-assistant/skills/visual-header.md | README.md
+2026-02-03T21:08:51 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/pm-review.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:08:53 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/pm-test.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:08:54 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/review-checklist.md | README.md
+2026-02-03T21:08:55 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/visual-output.md | README.md
+2026-02-03T21:08:58 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/setup-workflows.md | README.md
+2026-02-03T21:08:59 | skills | /home/lmiranda/claude-plugins-work/plugins/git-flow/skills/sync-workflow.md | README.md
+2026-02-03T21:09:00 | skills | /home/lmiranda/claude-plugins-work/plugins/git-flow/skills/commit-conventions.md | README.md
+2026-02-03T21:09:00 | skills | /home/lmiranda/claude-plugins-work/plugins/git-flow/skills/merge-workflow.md | README.md
+2026-02-03T21:09:08 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/pm-setup.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:08 | commands | /home/lmiranda/claude-plugins-work/plugins/data-platform/commands/data-setup.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:10 | commands | /home/lmiranda/claude-plugins-work/plugins/data-platform/commands/data-run.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:10 | commands | /home/lmiranda/claude-plugins-work/plugins/contract-validator/commands/cv-setup.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:11 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/pm-debug.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:13 | agents | /home/lmiranda/claude-plugins-work/plugins/contract-validator/agents/full-validation.md | README.md CLAUDE.md
+2026-02-03T21:09:14 | commands | /home/lmiranda/claude-plugins-work/plugins/data-platform/commands/data-ingest.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:18 | commands | /home/lmiranda/claude-plugins-work/plugins/data-platform/commands/data-profile.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:18 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/viz-setup.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:20 | commands | /home/lmiranda/claude-plugins-work/plugins/data-platform/commands/data-schema.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:20 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/viz-theme.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:23 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/viz-theme-new.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:24 | commands | /home/lmiranda/claude-plugins-work/plugins/data-platform/commands/data-explain.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:26 | commands | /home/lmiranda/claude-plugins-work/plugins/data-platform/commands/data-lineage.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:26 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/viz-theme-css.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:29 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/viz-chart.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:32 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/viz-chart-export.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:33 | commands | /home/lmiranda/claude-plugins-work/plugins/data-platform/commands/data-review.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:35 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/viz-dashboard.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:38 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/viz-component.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:40 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/viz-breakpoints.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:09:46 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/design-review.md | docs/COMMANDS-CHEATSHEET.md README.md
+2026-02-03T21:10:22 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/accessibility-check.md | docs/COMMANDS-CHEATSHEET.md README.md

.env

@@ -0,0 +1 @@
+GITEA_REPO=personal-projects/leo-claude-mktplace

.gitignore

@@ -84,6 +84,13 @@ Thumbs.db
 # Claude Code
 .claude/settings.local.json
 .claude/history/
+.claude/backups/
+
+# Doc Guardian transient files
+.doc-guardian-queue
+
+# Development convenience links
+.marketplaces-link
 
 # Logs
 logs/
@@ -125,4 +132,5 @@ site/
 *credentials*
 *secret*
 *token*
+!**/token-budget-report.md
 !.gitkeep

.mcp-full.json

@@ -0,0 +1,24 @@
+{
+  "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": []
+    }
+  }
+}

.mcp-lean.json

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

.mcp.json

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

CHANGELOG.md

@@ -8,6 +8,635 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+- **marketplace:** Lean/full profile switching to reduce token overhead
+  - New script: `scripts/switch-profile.sh` to toggle between profiles
+  - Lean profile: 6 plugins (projman, git-flow, pr-review, clarity-assist, code-sentinel, doc-guardian)
+  - Lean MCP: gitea only (reduces ~12k tokens of MCP server overhead)
+  - Full profile: all 12 plugins and 5 MCP servers
+  - New files: `.mcp-lean.json`, `.mcp-full.json`, `marketplace-lean.json`, `marketplace-full.json`
+  - Default is now lean profile for reduced daily overhead
+- **projman:** Token usage estimation reporting at sprint workflow boundaries
+  - New skill: `token-budget-report.md` with MCP overhead and skill loading estimation model
+  - Token report displayed at end of `/sprint-plan` and `/sprint-close`
+  - On-demand via `/sprint-status --tokens`
+  - Helps identify which phases and components consume the most context budget
+
+### Changed
+
+- **projman:** `/sprint-status` now uses conditional skill loading for reduced token overhead
+  - Only loads `mcp-tools-reference.md` by default (~1.5k tokens vs ~5k)
+  - `--diagram` flag loads `dependency-management.md` and `progress-tracking.md`
+  - `--tokens` flag loads `token-budget-report.md`
+  - Estimated savings: ~3.5k tokens per status check
+
+### Fixed
+
+- **docs:** Stale command references in data-platform visual-header.md and viz-platform claude-md-integration.md updated to v7.0.0 namespaced names
+- **docs:** git-flow visual-header.md and git-status.md quick actions updated to namespaced commands
+- **docs:** projman/CONFIGURATION.md and docs/DEBUGGING-CHECKLIST.md updated with correct command names
+
+---
+
+## [7.0.0] - 2026-02-03
+
+### BREAKING CHANGES
+
+#### Command Namespace Rename
+
+All generic command names are now prefixed with their plugin's namespace to eliminate collisions across the marketplace. This is a **breaking change** for consuming projects — update your CLAUDE.md integration snippets.
+
+**Full Rename Map:**
+
+| Plugin | Old | New |
+|--------|-----|-----|
+| projman | `/setup` | `/pm-setup` |
+| projman | `/review` | `/pm-review` |
+| projman | `/test` | `/pm-test` |
+| projman | `/debug` | `/pm-debug` |
+| git-flow | `/commit` | `/git-commit` |
+| git-flow | `/commit-push` | `/git-commit-push` |
+| git-flow | `/commit-merge` | `/git-commit-merge` |
+| git-flow | `/commit-sync` | `/git-commit-sync` |
+| pr-review | `/initial-setup` | `/pr-setup` |
+| cmdb-assistant | `/initial-setup` | `/cmdb-setup` |
+| data-platform | `/initial-setup` | `/data-setup` |
+| data-platform | `/run` | `/data-run` |
+| data-platform | `/ingest` | `/data-ingest` |
+| data-platform | `/profile` | `/data-profile` |
+| data-platform | `/schema` | `/data-schema` |
+| data-platform | `/explain` | `/data-explain` |
+| data-platform | `/lineage` | `/data-lineage` |
+| viz-platform | `/initial-setup` | `/viz-setup` |
+| viz-platform | `/theme` | `/viz-theme` |
+| viz-platform | `/theme-new` | `/viz-theme-new` |
+| viz-platform | `/theme-css` | `/viz-theme-css` |
+| viz-platform | `/chart` | `/viz-chart` |
+| viz-platform | `/chart-export` | `/viz-chart-export` |
+| viz-platform | `/dashboard` | `/viz-dashboard` |
+| viz-platform | `/component` | `/viz-component` |
+| viz-platform | `/breakpoints` | `/viz-breakpoints` |
+| contract-validator | `/initial-setup` | `/cv-setup` |
+
+**Migration:** Update your project's CLAUDE.md integration snippets to use the new command names. Run `/plugin list` to verify installed plugins are using v7.0.0+.
+
+**Unchanged:** Commands already using plugin-namespaced prefixes (`/sprint-*`, `/cmdb-*`, `/labels-sync`, `/branch-*`, `/git-status`, `/git-config`, `/pr-review`, `/pr-summary`, `/pr-findings`, `/pr-diff`, `/project-init`, `/project-sync`, `/config-*`, `/design-*`, `/data-quality`, `/data-review`, `/data-gate`, `/lineage-viz`, `/dbt-test`, `/accessibility-check`, `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/dependency-graph`, `/doc-audit`, `/doc-sync`, `/security-scan`, `/refactor`, `/refactor-dry`, `/clarify`, `/suggest-version`, `/proposal-status`, `/rfc`, `/change-audit`, `/ip-conflicts`) are **not affected**.
+
+### Added
+
+#### Plan-Then-Batch Skill Optimization (projman)
+
+New execution pattern that separates cognitive work from mechanical API operations, reducing skill-related token consumption by ~76-83% during sprint workflows.
+
+- **`skills/batch-execution.md`** — New skill defining the plan-then-batch protocol:
+  - Phase 1: Cognitive work with all skills loaded
+  - Phase 2: Execution manifest (structured plan of all API operations)
+  - Phase 3: Batch execute API calls using only frontmatter skills
+  - Phase 4: Batch report with success/failure summary
+  - Error handling: continue on individual failures, report at end
+
+- **Frontmatter skill promotion:**
+  - Planner agent: `mcp-tools-reference` and `batch-execution` promoted to frontmatter (auto-injected, zero re-read cost)
+  - Orchestrator agent: same promotion
+  - Eliminates per-operation skill file re-reads during API execution loops
+
+- **Phase-based skill loading:**
+  - Planner: 3 phases (validation → analysis → approval) with explicit "read once" instructions
+  - Orchestrator: 2 phases (startup → dispatch) with same pattern
+  - New `## Skill Loading Protocol` section replaces flat `## Skills to Load` in agent files
+
+### Changed
+
+- **`planning-workflow.md`** — Steps 8-10 restructured:
+  - Step 8: "Draft Issue Specifications" (no API calls — resolve all parameters first)
+  - Step 8a: "Batch Execute Issue Creation" (tight API loop, frontmatter skills only)
+  - Step 9: Merged into Step 8a (dependencies created in batch)
+  - Step 10: Milestone creation moved before batch (must exist for assignment)
+
+- **Agent matrix updated:**
+  - Planner: `body text (14)` → `frontmatter (2) + body text (12)`
+  - Orchestrator: `body text (12)` → `frontmatter (2) + body text (10)`
+
+- **`docs/CONFIGURATION.md`** — New "Phase-Based Skill Loading" subsection documenting the pattern
+
+### Token Impact
+
+| Scenario | Before | After | Savings |
+|----------|--------|-------|---------|
+| 6-issue sprint (planning) | ~23,800 lines | ~5,600 lines | ~76% |
+| 10-issue sprint (planning) | ~35,000 lines | ~7,000 lines | ~80% |
+| 8-issue status updates (orchestrator) | ~9,600 lines | ~1,600 lines | ~83% |
+
+---
+
+## [5.10.0] - 2026-02-03
+
+### Added
+
+#### NetBox MCP Server: Module-Based Tool Filtering
+
+Environment-variable-driven module filtering to reduce token consumption:
+
+- **New config option**: `NETBOX_ENABLED_MODULES` in `~/.config/claude/netbox.env`
+- **Token savings**: ~15,000 tokens (from ~19,810 to ~4,500) with recommended config
+- **Default behavior**: All modules enabled if env var unset (backward compatible)
+- **Startup logging**: Shows enabled modules and tool count on initialization
+- **Routing guard**: Clear error message when calling disabled module's tools
+
+**Recommended configuration for cmdb-assistant users:**
+```bash
+NETBOX_ENABLED_MODULES=dcim,ipam,virtualization,extras
+```
+
+This enables ~43 tools covering all cmdb-assistant commands while staying well below the 25K token warning threshold.
+
+### Fixed
+
+#### cmdb-assistant Documentation: Incorrect Tool Names
+
+Fixed documentation referencing non-existent `virtualization_*` tool names:
+
+| File | Wrong | Correct |
+|------|-------|---------|
+| `claude-md-integration.md` | `virtualization_list_virtual_machines` | `virt_list_vms` |
+| `claude-md-integration.md` | `virtualization_create_virtual_machine` | `virt_create_vm` |
+| `cmdb-search.md` | `virtualization_list_virtual_machines` | `virt_list_vms` |
+
+Also fixed NetBox README.md tool name references for virtualization, wireless, and circuits modules.
+
+#### Gitea MCP Server: Standardized Build Backend
+
+Changed `mcp-servers/gitea/pyproject.toml` from hatchling to setuptools:
+- Matches all other MCP servers (contract-validator, viz-platform, data-platform)
+- Updated license format to PEP 639 compliance
+- Added pytest configuration for consistency
+
+---
+
+## [5.9.0] - 2026-02-03
+
+### Added
+
+#### Plugin Installation Scripts
+New scripts for installing marketplace plugins into consumer projects:
+
+- **`scripts/install-plugin.sh`** — Install a plugin to a consumer project
+  - Adds MCP server entry to target's `.mcp.json` (if plugin has MCP server)
+  - Appends integration snippet to target's `CLAUDE.md`
+  - Idempotent: safe to run multiple times
+  - Validates plugin exists and target path is valid
+
+- **`scripts/uninstall-plugin.sh`** — Remove a plugin from a consumer project
+  - Removes MCP server entry from `.mcp.json`
+  - Removes integration section from `CLAUDE.md`
+
+- **`scripts/list-installed.sh`** — Show installed plugins in a project
+  - Lists fully installed, partially installed, and available plugins
+  - Shows plugin versions and descriptions
+
+**Usage:**
+```bash
+./scripts/install-plugin.sh data-platform ~/projects/personal-portfolio
+./scripts/list-installed.sh ~/projects/personal-portfolio
+./scripts/uninstall-plugin.sh data-platform ~/projects/personal-portfolio
+```
+
+**Documentation:** `docs/CONFIGURATION.md` updated with "Installing Plugins to Consumer Projects" section.
+
+### Fixed
+
+#### Plugin Installation Scripts — MCP Mapping & Section Markers
+
+**MCP Server Mapping:**
+- Added `mcp_servers` field to plugin.json for plugins that use shared MCP servers
+- `projman` and `pr-review` now correctly install `gitea` MCP server
+- `cmdb-assistant` now correctly installs `netbox` MCP server
+- Scripts read MCP server names from plugin.json instead of assuming plugin name = server name
+
+**CLAUDE.md Section Markers:**
+- Install script now wraps integration content with HTML comment markers:
+  `<!-- BEGIN marketplace-plugin: {name} -->` and `<!-- END marketplace-plugin: {name} -->`
+- Uninstall script uses markers for precise section removal (no more code block false positives)
+- Backward compatible: falls back to legacy header detection for pre-marker installations
+
+**Plugins updated with `mcp_servers` field:**
+- `projman` → `["gitea"]`
+- `pr-review` → `["gitea"]`
+- `cmdb-assistant` → `["netbox"]`
+- `data-platform` → `["data-platform"]`
+- `viz-platform` → `["viz-platform"]`
+- `contract-validator` → `["contract-validator"]`
+
+#### Agent Model Selection
+
+Per-agent model selection using Claude Code's now-supported `model` frontmatter field.
+
+- All 25 marketplace agents assigned appropriate model (`sonnet`, `haiku`, or `inherit`)
+- Model assignment based on reasoning depth, tool complexity, and latency requirements
+- Documentation added to `CLAUDE.md` and `docs/CONFIGURATION.md`
+
+**Supported values:** `sonnet` (default), `opus`, `haiku`, `inherit`
+
+**Model assignments:**
+| Model | Agent Types |
+|-------|-------------|
+| sonnet | Planner, Orchestrator, Executor, Code Reviewer, Coordinator, Security Reviewers, Data Advisor, Design Reviewer, etc. |
+| haiku | Maintainability Auditor, Test Validator, Component Check, Theme Setup, Git Assistant, Data Ingestion, Agent Check |
+
+### Fixed
+
+#### Agent Frontmatter Standardization
+
+- Fixed viz-platform and data-platform agents using non-standard `agent:` field (now `name:`)
+- Removed non-standard `triggers:` field from domain agents (trigger info already in agent body)
+- Added missing frontmatter to 13 agents across pr-review, viz-platform, contract-validator, clarity-assist, git-flow, doc-guardian, code-sentinel, cmdb-assistant, and data-platform
+- All 25 agents now have consistent `name`, `description`, and `model` fields
+
+### Changed
+
+#### Agent Frontmatter Hardening v3
+
+Comprehensive agent-level configuration using Claude Code's supported frontmatter fields.
+
+**permissionMode added to all 25 agents:**
+- `bypassPermissions` (1): Executor — full autonomy with code-sentinel + Code Reviewer safety nets
+- `acceptEdits` (7): Orchestrator, Data Ingestion, Theme Setup, Refactor Advisor, Doc Analyzer, Git Assistant, Maintainer
+- `default` (7): Planner, Code Reviewer, Data Advisor, Layout Builder, Full Validation, Clarity Coach, CMDB Assistant
+- `plan` (10): All pr-review agents (5), Data Analysis, Design Reviewer, Component Check, Agent Check, Security Reviewer (code-sentinel)
+
+**disallowedTools added to 12 agents:**
+- All `plan`-mode agents (10) + Code Reviewer + Clarity Coach receive `disallowedTools: Write, Edit, MultiEdit`
+- Enforces read-only contracts at platform level (defense-in-depth with `permissionMode`)
+
+**Model promotions:**
+- Planner: `sonnet` → `opus` (architectural reasoning benefits from deeper analysis)
+- Code Reviewer: `sonnet` → `opus` (quality gate benefits from thorough review)
+
+**skills frontmatter on 3 agents:**
+- Executor: 7 safety-critical skills auto-injected (branch-security, runaway-detection, etc.)
+- Code Reviewer: 4 review skills auto-injected
+- Maintainer: 2 config skills auto-injected
+- Body text `## Skills to Load` removed for these agents to avoid duplication
+
+**Documentation:**
+- `CLAUDE.md` and `docs/CONFIGURATION.md` updated with complete agent configuration matrix
+- New subsections: permissionMode Guide, disallowedTools Guide, skills Frontmatter Guide
+
+---
+
+## [5.8.0] - 2026-02-02
+
+### Added
+
+#### claude-config-maintainer v1.2.0 - Settings Audit Feature
+
+New commands for auditing and optimizing `settings.local.json` permission configurations:
+
+- **`/config-audit-settings`** — Audit `settings.local.json` permissions with 100-point scoring across redundancy, coverage, safety alignment, and profile fit
+- **`/config-optimize-settings`** — Apply permission optimizations with dry-run, named profiles (`conservative`, `reviewed`, `autonomous`), and consolidation modes
+- **`/config-permissions-map`** — Generate Mermaid diagram of review layer coverage and permission gaps
+- **`skills/settings-optimization.md`** — Comprehensive skill for permission pattern analysis, consolidation rules, review-layer-aware recommendations, and named profiles
+
+**Key Features:**
+- Settings Efficiency Score (100 points) alongside existing CLAUDE.md score
+- Review layer verification — agent reads `hooks/hooks.json` from installed plugins before recommending auto-allow patterns
+- Three named profiles: `conservative` (prompts for most writes), `reviewed` (for projects with ≥2 review layers), `autonomous` (sandboxed environments)
+- Pattern consolidation detection: duplicates, subsets, merge candidates, stale entries, conflicts
+
+#### Projman Hardening Sprint
+Targeted improvements to safety gates, command structure, lifecycle tracking, and cross-plugin contracts.
+
+**Sprint Lifecycle State Machine:**
+- New `skills/sprint-lifecycle.md` - defines valid states and transitions via milestone metadata
+- States: idle -> Sprint/Planning -> Sprint/Executing -> Sprint/Reviewing -> idle
+- All sprint commands check and set lifecycle state on entry/exit
+- Out-of-order calls produce warnings with guidance, `--force` override available
+
+**Sprint Dispatch Log:**
+- Orchestrator now maintains a structured dispatch log during execution
+- Records task dispatch, completion, failure, gate checks, and resume events
+- Enables timeline reconstruction after interrupted sessions
+
+**Gate Contract Versioning:**
+- Gate commands (`/design-gate`, `/data-gate`) declare `gate_contract: v1` in frontmatter
+- `domain-consultation.md` Gate Command Reference includes expected contract version
+- `validate_workflow_integration` now checks contract version compatibility
+- Mismatch produces WARNING, missing contract produces INFO suggestion
+
+**Shared Visual Output Skill:**
+- New `skills/visual-output.md` - single source of truth for projman visual headers
+- All 4 agent files reference the skill instead of inline templates
+- Phase Registry maps agents to emoji and phase names
+
+### Changed
+
+**Sprint Approval Gate Hardened:**
+- Approval is now a hard block, not a warning (was "recommended", now required)
+- `--force` flag added to bypass in emergencies (logged to milestone)
+- Consistent language across sprint-approval.md, sprint-start.md, and orchestrator.md
+
+**RFC Commands Normalized:**
+- 5 individual commands (`/rfc-create`, `/rfc-list`, `/rfc-review`, `/rfc-approve`, `/rfc-reject`) consolidated into `/rfc create|list|review|approve|reject`
+- `/clear-cache` absorbed into `/setup --clear-cache`
+- Command count reduced from 17 to 12
+
+**`/test` Command Documentation Expanded:**
+- Sprint integration section (pre-close verification workflow)
+- Concrete usage examples for all modes
+- Edge cases table
+- DO NOT rules for both modes
+
+### Removed
+
+- `plugins/projman/commands/rfc-create.md` (replaced by `/rfc create`)
+- `plugins/projman/commands/rfc-list.md` (replaced by `/rfc list`)
+- `plugins/projman/commands/rfc-review.md` (replaced by `/rfc review`)
+- `plugins/projman/commands/rfc-approve.md` (replaced by `/rfc approve`)
+- `plugins/projman/commands/rfc-reject.md` (replaced by `/rfc reject`)
+- `plugins/projman/commands/clear-cache.md` (replaced by `/setup --clear-cache`)
+
+---
+
+## [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
+
+#### Sprint 6: Visual Branding Overhaul
+Consistent visual headers and progress tracking across all plugins.
+
+**Visual Output Headers (109 files):**
+- **Projman**: Double-line headers (╔═╗) with phase indicators (🎯 PLANNING, ⚡ EXECUTION, 🏁 CLOSING)
+- **Other Plugins**: Single-line headers (┌─┐) with plugin icons
+- **All 23 agents** updated with Visual Output Requirements section
+- **All 86 commands** updated with Visual Output section and header templates
+
+**Plugin Icon Registry:**
+| Plugin | Icon |
+|--------|------|
+| projman | 📋 |
+| code-sentinel | 🔒 |
+| doc-guardian | 📝 |
+| pr-review | 🔍 |
+| clarity-assist | 💬 |
+| git-flow | 🔀 |
+| cmdb-assistant | 🖥️ |
+| data-platform | 📊 |
+| viz-platform | 🎨 |
+| contract-validator | ✅ |
+| claude-config-maintainer | ⚙️ |
+
+**Wiki Branding Specification (4 pages):**
+- [branding/visual-spec](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/branding%2Fvisual-spec) - Central specification
+- [branding/plugin-registry](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/branding%2Fplugin-registry) - Icons and styles
+- [branding/header-templates](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/branding%2Fheader-templates) - Copy-paste templates
+- [branding/progress-templates](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/branding%2Fprogress-templates) - Sprint progress blocks
+
+### Fixed
+- **Docs:** Version sync - CLAUDE.md, marketplace.json, README.md now consistent
+- **Docs:** Added 18 missing commands from Sprint 4 & 5 to README.md and COMMANDS-CHEATSHEET.md
+- **MCP:** Registered `/sprint-diagram` as invokable skill
+
+**Sprint Completed:**
+- Milestone: Sprint 6 - Visual Branding Overhaul (closed 2026-01-28)
+- Issues: #272, #273, #274, #275, #276, #277, #278
+- PRs: #284, #285
+- Wiki: [Sprint 6 Lessons](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/lessons/sprints/sprint-6---visual-branding-and-documentation-maintenance)
+
+---
+
+## [5.2.0] - 2026-01-28
+
+### Added
+
+#### Sprint 5: Documentation (V5.2.0 Plugin Enhancements)
+Documentation and guides for the plugin enhancements initiative.
+
+**git-flow v1.2.0:**
+- **Branching Strategy Guide** (`docs/BRANCHING-STRATEGY.md`) - Complete documentation of `development -> staging -> main` promotion flow with Mermaid diagrams
+
+**clarity-assist v1.2.0:**
+- **ND Support Guide** (`docs/ND-SUPPORT.md`) - Documentation of neurodivergent accommodations, features, and usage examples
+
+**Gitea MCP Server:**
+- **`update_issue` milestone parameter** - Can now assign/change milestones programmatically
+
+**Sprint Completed:**
+- Milestone: Sprint 5 - Documentation (closed 2026-01-28)
+- Issues: #266, #267, #268, #269
+- Wiki: [Change V5.2.0: Plugin Enhancements (Sprint 5 Documentation)](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/Change-V5.2.0%3A-Plugin-Enhancements-%28Sprint-5-Documentation%29)
+
+---
+
+#### Sprint 4: Commands (V5.2.0 Plugin Enhancements)
+Implementation of 18 new user-facing commands across 8 plugins.
+
+**projman v3.3.0:**
+- **`/sprint-diagram`** - Generate Mermaid diagram of sprint issues with dependencies and status
+
+**pr-review v1.1.0:**
+- **`/pr-diff`** - Formatted diff with inline review comments and annotations
+- **Confidence threshold config** - `PR_REVIEW_CONFIDENCE_THRESHOLD` env var (default: 0.7)
+
+**data-platform v1.2.0:**
+- **`/data-quality`** - DataFrame quality checks (nulls, duplicates, types, outliers) with pass/warn/fail scoring
+- **`/lineage-viz`** - dbt lineage visualization as Mermaid diagrams
+- **`/dbt-test`** - Formatted dbt test runner with summary and failure details
+
+**viz-platform v1.1.0:**
+- **`/chart-export`** - Export charts to PNG, SVG, PDF via kaleido
+- **`/accessibility-check`** - Color blind validation (WCAG contrast ratios)
+- **`/breakpoints`** - Responsive layout breakpoint configuration
+- **New MCP tools**: `chart_export`, `accessibility_validate_colors`, `accessibility_validate_theme`, `accessibility_suggest_alternative`, `layout_set_breakpoints`
+- **New dependency**: kaleido>=0.2.1 for chart rendering
+
+**contract-validator v1.2.0:**
+- **`/dependency-graph`** - Mermaid visualization of plugin dependencies with data flow
+
+**doc-guardian v1.1.0:**
+- **`/changelog-gen`** - Generate changelog from conventional commits
+- **`/doc-coverage`** - Documentation coverage metrics by function/class
+- **`/stale-docs`** - Flag documentation behind code changes
+
+**claude-config-maintainer v1.1.0:**
+- **`/config-diff`** - Track CLAUDE.md changes over time with behavioral impact analysis
+- **`/config-lint`** - 31 lint rules for CLAUDE.md (security, structure, content, format, best practices)
+
+**cmdb-assistant v1.2.0:**
+- **`/cmdb-topology`** - Infrastructure topology diagrams (rack, network, site views)
+- **`/change-audit`** - NetBox audit trail queries with filtering
+- **`/ip-conflicts`** - Detect IP conflicts and overlapping prefixes
+
+**Sprint Completed:**
+- Milestone: Sprint 4 - Commands (closed 2026-01-28)
+- Issues: #241-#258 (18/18 closed)
+- Wiki: [Change V5.2.0: Plugin Enhancements (Sprint 4 Commands)](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/Change-V5.2.0%3A-Plugin-Enhancements-%28Sprint-4-Commands%29)
+- Lessons: [Sprint 4 - Plugin Commands Implementation](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/lessons/sprints/sprint-4---plugin-commands-implementation)
+
+### Fixed
+- **MCP:** Project directory detection - all run.sh scripts now capture `CLAUDE_PROJECT_DIR` from PWD before changing directories
+- **Docs:** Added Gitea auto-close behavior and MCP session restart notes to DEBUGGING-CHECKLIST.md
+
+---
+
+#### Sprint 3: Hooks (V5.2.0 Plugin Enhancements)
+Implementation of 6 foundational hooks across 4 plugins.
+
+**git-flow v1.1.0:**
+- **Commit message enforcement hook** - PreToolUse hook validates conventional commit format on all `git commit` commands (not just `/commit`). Blocks invalid commits with format guidance.
+- **Branch name validation hook** - PreToolUse hook validates branch naming on `git checkout -b` and `git switch -c`. Enforces `type/description` format, lowercase, max 50 chars.
+
+**clarity-assist v1.1.0:**
+- **Vagueness detection hook** - UserPromptSubmit hook detects vague prompts and suggests `/clarify` when ambiguity, missing context, or unclear scope detected.
+
+**data-platform v1.1.0:**
+- **Schema diff detection hook** - PostToolUse hook monitors edits to schema files (dbt models, SQL migrations). Warns on breaking changes (column removal, type narrowing, constraint addition).
+
+**contract-validator v1.1.0:**
+- **SessionStart auto-validate hook** - Smart validation that only runs when plugin files changed since last check. Detects interface compatibility issues at session start.
+- **Breaking change detection hook** - PostToolUse hook monitors plugin interface files (README.md, plugin.json). Warns when changes would break consumers.
+
+**Sprint Completed:**
+- Milestone: Sprint 3 - Hooks (closed 2026-01-28)
+- Issues: #225, #226, #227, #228, #229, #230
+- Wiki: [Change V5.2.0: Plugin Enhancements Proposal](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/Change-V5.2.0:-Plugin-Enhancements-Proposal)
+- Lessons: Background agent permissions, agent runaway detection, MCP branch detection bug
+
+### Known Issues
+- **MCP Bug #231:** Branch detection in Gitea MCP runs from installed plugin directory, not user's project directory. Workaround: close issues via Gitea web UI.
+
+---
+
 #### Gitea MCP Server - create_pull_request Tool
 - **`create_pull_request`**: Create new pull requests via MCP
   - Parameters: title, body, head (source branch), base (target branch), labels

CLAUDE.md

@@ -1,6 +1,5 @@
 # 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.**
@@ -9,65 +8,162 @@ This file provides guidance to Claude Code when working with code in this reposi
 - Search ALL locations, not just where you think it is
 - Check cache directories: `~/.claude/plugins/cache/`
 - Check installed: `~/.claude/plugins/marketplaces/`
-- Check source: `~/claude-plugins-work/`
+- Check source directories
 - **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
-- 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.
+- **Do not interpret or summarize unless asked**
 
 **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** `/data-ingest`, `/data-profile`, `/viz-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.0.0
+**Version:** 7.0.0
 **Status:** Production Ready
 
 A plugin marketplace for Claude Code containing:
 
 | Plugin | Description | Version |
 |--------|-------------|---------|
-| `projman` | Sprint planning and project management with Gitea integration | 3.2.0 |
+| `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 |
-| `pr-review` | Multi-agent PR review with confidence scoring | 1.0.0 |
+| `pr-review` | Multi-agent PR review with confidence scoring | 1.1.0 |
 | `clarity-assist` | Prompt optimization with ND-friendly accommodations | 1.0.0 |
 | `doc-guardian` | Automatic documentation drift detection and synchronization | 1.0.0 |
-| `code-sentinel` | Security scanning and code refactoring tools | 1.0.0 |
+| `code-sentinel` | Security scanning and code refactoring tools | 1.0.1 |
 | `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 1.0.0 |
-| `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 1.0.0 |
-| `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 1.0.0 |
-| `viz-platform` | DMC validation, Plotly charts, and theming for dashboards | 1.0.0 |
-| `contract-validator` | Cross-plugin compatibility validation and agent verification | 1.0.0 |
+| `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 1.2.0 |
+| `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 1.3.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 |
 | `project-hygiene` | Post-task cleanup automation via hooks | 0.1.0 |
 
 ## Quick Start
@@ -77,25 +173,33 @@ A plugin marketplace for Claude Code containing:
 ./scripts/validate-marketplace.sh
 
 # After updates
-./scripts/post-update.sh   # Rebuild venvs, verify symlinks
+./scripts/post-update.sh   # Rebuild venvs
 ```
 
-### Plugin Commands by Category
+### Plugin Commands - USE THESE in This Project
 
 | Category | Commands |
 |----------|----------|
-| **Setup** | `/initial-setup`, `/project-init`, `/project-sync` |
-| **Sprint** | `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close` |
-| **Quality** | `/review`, `/test-check`, `/test-gen` |
+| **Setup** | `/pm-setup` (modes: `--full`, `--quick`, `--sync`) |
+| **Sprint** | `/sprint-plan`, `/sprint-start`, `/sprint-status` (with `--diagram`), `/sprint-close` |
+| **Quality** | `/pm-review`, `/pm-test` (modes: `run`, `gen`) |
 | **Versioning** | `/suggest-version` |
-| **PR Review** | `/pr-review:initial-setup`, `/pr-review:project-init` |
-| **Docs** | `/doc-audit`, `/doc-sync` |
+| **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` |
-| **Data** | `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/run` |
-| **Visualization** | `/component`, `/chart`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css` |
-| **Validation** | `/validate-contracts`, `/check-agent`, `/list-interfaces` |
-| **Debug** | `/debug-report`, `/debug-review` |
+| **Config** | `/config-analyze`, `/config-optimize`, `/config-diff`, `/config-lint` |
+| **Validation** | `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/dependency-graph` |
+| **Debug** | `/pm-debug` (modes: `report`, `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** | `/data-ingest`, `/data-profile`, `/data-schema`, `/data-lineage`, `/dbt-test` | pandas, PostgreSQL, dbt |
+| **Visualization** | `/viz-component`, `/viz-chart`, `/viz-dashboard`, `/viz-theme` | Dash, Plotly dashboards |
+| **CMDB** | `/cmdb-search`, `/cmdb-device`, `/cmdb-sync` | NetBox infrastructure |
 
 ## Repository Structure
 
@@ -103,46 +207,40 @@ A plugin marketplace for Claude Code containing:
 leo-claude-mktplace/
 ├── .claude-plugin/
 │   └── marketplace.json          # Marketplace manifest
-├── mcp-servers/                  # SHARED MCP servers (v3.0.0+)
+├── .mcp.json                     # MCP server configuration (all servers)
+├── 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
-│   │   ├── .mcp.json
-│   │   ├── mcp-servers/gitea -> ../../../mcp-servers/gitea  # SYMLINK
-│   │   ├── commands/             # 14 commands (incl. setup, debug, suggest-version)
-│   │   ├── hooks/                # SessionStart: mismatch detection + sprint suggestions
+│   │   ├── commands/             # 12 commands
+│   │   ├── hooks/                # SessionStart: mismatch detection
 │   │   ├── agents/               # 4 agents
-│   │   └── skills/label-taxonomy/
+│   │   └── skills/               # 17 reusable skill files
 │   ├── git-flow/                 # Git workflow automation
 │   │   ├── .claude-plugin/plugin.json
 │   │   ├── commands/             # 8 commands
 │   │   └── agents/
 │   ├── pr-review/                # Multi-agent PR review
 │   │   ├── .claude-plugin/plugin.json
-│   │   ├── .mcp.json
-│   │   ├── mcp-servers/gitea -> ../../../mcp-servers/gitea  # SYMLINK
-│   │   ├── commands/             # 6 commands (incl. setup)
+│   │   ├── commands/             # 6 commands
 │   │   ├── hooks/                # SessionStart mismatch detection
 │   │   └── agents/               # 5 agents
 │   ├── clarity-assist/           # Prompt optimization
 │   │   ├── .claude-plugin/plugin.json
 │   │   ├── commands/             # 2 commands
 │   │   └── agents/
-│   ├── data-platform/            # Data engineering (NEW v4.0.0)
+│   ├── data-platform/            # Data engineering
 │   │   ├── .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 (NEW v4.0.0)
+│   ├── viz-platform/             # Visualization
 │   │   ├── .claude-plugin/plugin.json
-│   │   ├── .mcp.json
-│   │   ├── mcp-servers/          # viz-platform MCP
 │   │   ├── commands/             # 7 commands
 │   │   ├── hooks/                # SessionStart DMC check
 │   │   └── agents/               # 3 agents
@@ -150,6 +248,7 @@ leo-claude-mktplace/
 │   ├── code-sentinel/            # Security scanning & refactoring
 │   ├── claude-config-maintainer/
 │   ├── cmdb-assistant/
+│   ├── contract-validator/
 │   └── project-hygiene/
 ├── scripts/
 │   ├── setup.sh, post-update.sh
@@ -161,40 +260,6 @@ 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)
@@ -206,6 +271,61 @@ leo-claude-mktplace/
 | **Executor** | Implementation-focused | Code implementation, branch management, MR creation |
 | **Code Reviewer** | Thorough, practical | Pre-close quality review, security scan, test verification |
 
+### Agent Frontmatter Configuration
+
+Agents specify their configuration in frontmatter using Claude Code's supported fields. Reference: https://code.claude.com/docs/en/sub-agents
+
+**Supported frontmatter fields:**
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | Yes | — | Unique identifier, lowercase + hyphens |
+| `description` | Yes | — | When Claude should delegate to this subagent |
+| `model` | No | `inherit` | `sonnet`, `opus`, `haiku`, or `inherit` |
+| `permissionMode` | No | `default` | Controls permission prompts: `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` |
+| `disallowedTools` | No | none | Comma-separated tools to remove from agent's toolset |
+| `skills` | No | none | Comma-separated skills auto-injected into context at startup |
+| `hooks` | No | none | Lifecycle hooks scoped to this subagent |
+
+**Complete agent matrix:**
+
+| Plugin | Agent | `model` | `permissionMode` | `disallowedTools` | `skills` |
+|--------|-------|---------|-------------------|--------------------|----------|
+| projman | planner | opus | default | — | frontmatter (2) + body text (12) |
+| projman | orchestrator | sonnet | acceptEdits | — | frontmatter (2) + body text (10) |
+| projman | executor | sonnet | bypassPermissions | — | frontmatter (7) |
+| projman | code-reviewer | opus | default | Write, Edit, MultiEdit | frontmatter (4) |
+| pr-review | coordinator | sonnet | plan | Write, Edit, MultiEdit | — |
+| pr-review | security-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
+| pr-review | performance-analyst | sonnet | plan | Write, Edit, MultiEdit | — |
+| pr-review | maintainability-auditor | haiku | plan | Write, Edit, MultiEdit | — |
+| pr-review | test-validator | haiku | plan | Write, Edit, MultiEdit | — |
+| data-platform | data-advisor | sonnet | default | — | — |
+| data-platform | data-analysis | sonnet | plan | Write, Edit, MultiEdit | — |
+| data-platform | data-ingestion | haiku | acceptEdits | — | — |
+| viz-platform | design-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
+| viz-platform | layout-builder | sonnet | default | — | — |
+| viz-platform | component-check | haiku | plan | Write, Edit, MultiEdit | — |
+| viz-platform | theme-setup | haiku | acceptEdits | — | — |
+| contract-validator | full-validation | sonnet | default | — | — |
+| contract-validator | agent-check | haiku | plan | Write, Edit, MultiEdit | — |
+| code-sentinel | security-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
+| code-sentinel | refactor-advisor | sonnet | acceptEdits | — | — |
+| doc-guardian | doc-analyzer | sonnet | acceptEdits | — | — |
+| clarity-assist | clarity-coach | sonnet | default | Write, Edit, MultiEdit | — |
+| git-flow | git-assistant | haiku | acceptEdits | — | — |
+| claude-config-maintainer | maintainer | sonnet | acceptEdits | — | frontmatter (2) |
+| cmdb-assistant | cmdb-assistant | sonnet | default | — | — |
+
+**Design principles:**
+- `bypassPermissions` is granted to exactly ONE agent (Executor) which has code-sentinel PreToolUse hook + Code Reviewer downstream as safety nets.
+- `plan` mode is assigned to all pure analysis agents (pr-review, read-only validators).
+- `disallowedTools: Write, Edit, MultiEdit` provides defense-in-depth on agents that should never write files.
+- `skills` frontmatter is used for agents with ≤7 skills where guaranteed loading is safety-critical. Agents with 8+ skills use body text `## Skills to Load` for selective loading.
+- `hooks` (agent-scoped) is reserved for future use (v6.0+).
+
+Override any field by editing the agent's `.md` file in `plugins/{plugin}/agents/`.
+
 ### MCP Server Tools (Gitea)
 
 | Category | Tools |
@@ -214,7 +334,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` |
+| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `update_wiki_page`, `create_lesson`, `search_lessons`, `allocate_rfc_number` |
 | **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` |
 
@@ -235,6 +355,20 @@ 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
@@ -259,16 +393,15 @@ 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 `README.md` and `claude-md-integration.md`
-4. If using MCP server, create symlink: `ln -s ../../../mcp-servers/{server} plugins/{name}/mcp-servers/{server}`
+3. Create `claude-md-integration.md`
+4. If using new MCP server, add to root `mcp-servers/` and update `.mcp.json`
 5. Run `./scripts/validate-marketplace.sh`
 6. Update `CHANGELOG.md`
 
 ### Adding a Command to projman
 
 1. Create `plugins/projman/commands/{name}.md`
-2. Update `plugins/projman/README.md`
-3. Update marketplace description if significant
+2. Update marketplace description if significant
 
 ### Validation
 
@@ -295,7 +428,6 @@ 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
 
@@ -317,12 +449,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 | Symlink broken or venv missing | Run `/debug-report` to diagnose |
+| MCP tools not available | Venv missing or .mcp.json misconfigured | Run `/pm-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-review` - Investigate and propose fixes
+- `/pm-debug report` - Run full diagnostics, create issue if needed
+- `/pm-debug review` - Investigate and propose fixes
 
 ## Versioning Workflow
 
@@ -376,4 +508,4 @@ The script will:
 
 ---
 
-**Last Updated:** 2026-01-24
+**Last Updated:** 2026-02-03

README.md

@@ -1,4 +1,4 @@
-# Leo Claude Marketplace - v5.1.0
+# Leo Claude Marketplace - v7.0.0
 
 A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
 
@@ -6,12 +6,13 @@ A collection of Claude Code plugins for project management, infrastructure autom
 
 ### Development & Project Management
 
-#### [projman](./plugins/projman/README.md)
+#### [projman](./plugins/projman)
 **Sprint Planning and Project Management**
 
 AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sprint workflow into a distributable plugin.
 
 - Four-agent model: Planner, Orchestrator, Executor, Code Reviewer
+- Plan-then-batch execution: skills loaded once per phase, API calls batched for ~80% token savings
 - Intelligent label suggestions from 43-label taxonomy
 - Lessons learned capture via Gitea Wiki
 - Native issue dependencies with parallel execution
@@ -19,9 +20,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`, `/initial-setup`, `/project-init`, `/project-sync`, `/review`, `/test-check`, `/test-gen`, `/debug-report`, `/debug-review`
+**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/pm-setup`, `/pm-review`, `/pm-test`, `/pm-debug`, `/suggest-version`, `/proposal-status`, `/rfc`
 
-#### [git-flow](./plugins/git-flow/README.md) *NEW in v3.0.0*
+#### [git-flow](./plugins/git-flow) *NEW in v3.0.0*
 **Git Workflow Automation**
 
 Smart git operations with intelligent commit messages and branch management.
@@ -32,9 +33,9 @@ Smart git operations with intelligent commit messages and branch management.
 - Merge and cleanup automation
 - Protected branch awareness
 
-**Commands:** `/commit`, `/commit-push`, `/commit-merge`, `/commit-sync`, `/branch-start`, `/branch-cleanup`, `/git-status`, `/git-config`
+**Commands:** `/git-commit`, `/git-commit-push`, `/git-commit-merge`, `/git-commit-sync`, `/branch-start`, `/branch-cleanup`, `/git-status`, `/git-config`
 
-#### [pr-review](./plugins/pr-review/README.md) *NEW in v3.0.0*
+#### [pr-review](./plugins/pr-review) *NEW in v3.0.0*
 **Multi-Agent PR Review**
 
 Comprehensive pull request review using specialized agents.
@@ -44,16 +45,16 @@ Comprehensive pull request review using specialized agents.
 - Actionable feedback with suggested fixes
 - Gitea integration for automated review submission
 
-**Commands:** `/pr-review`, `/pr-summary`, `/pr-findings`, `/initial-setup`, `/project-init`, `/project-sync`
+**Commands:** `/pr-review`, `/pr-summary`, `/pr-findings`, `/pr-diff`, `/pr-setup`, `/project-init`, `/project-sync`
 
-#### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md)
-**CLAUDE.md Optimization and Maintenance**
+#### [claude-config-maintainer](./plugins/claude-config-maintainer)
+**CLAUDE.md and Settings Optimization**
 
-Analyze, optimize, and create CLAUDE.md configuration files for Claude Code projects.
+Analyze, optimize, and create CLAUDE.md configuration files. Audit and optimize settings.local.json permissions.
 
-**Commands:** `/config-analyze`, `/config-optimize`, `/config-init`
+**Commands:** `/analyze`, `/optimize`, `/init`, `/config-diff`, `/config-lint`, `/config-audit-settings`, `/config-optimize-settings`, `/config-permissions-map`
 
-#### [contract-validator](./plugins/contract-validator/README.md) *NEW in v5.0.0*
+#### [contract-validator](./plugins/contract-validator) *NEW in v5.0.0*
 **Cross-Plugin Compatibility Validation**
 
 Validate plugin marketplaces for command conflicts, tool overlaps, and broken agent references.
@@ -64,11 +65,11 @@ Validate plugin marketplaces for command conflicts, tool overlaps, and broken ag
 - Data flow validation for agent sequences
 - Markdown or JSON reports with actionable suggestions
 
-**Commands:** `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/initial-setup`
+**Commands:** `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/dependency-graph`, `/cv-setup`
 
 ### Productivity
 
-#### [clarity-assist](./plugins/clarity-assist/README.md) *NEW in v3.0.0*
+#### [clarity-assist](./plugins/clarity-assist) *NEW in v3.0.0*
 **Prompt Optimization with ND Accommodations**
 
 Transform vague requests into clear specifications using structured methodology.
@@ -79,21 +80,21 @@ Transform vague requests into clear specifications using structured methodology.
 
 **Commands:** `/clarify`, `/quick-clarify`
 
-#### [doc-guardian](./plugins/doc-guardian/README.md)
+#### [doc-guardian](./plugins/doc-guardian)
 **Documentation Lifecycle Management**
 
 Automatic documentation drift detection and synchronization.
 
-**Commands:** `/doc-audit`, `/doc-sync`
+**Commands:** `/doc-audit`, `/doc-sync`, `/changelog-gen`, `/doc-coverage`, `/stale-docs`
 
-#### [project-hygiene](./plugins/project-hygiene/README.md)
+#### [project-hygiene](./plugins/project-hygiene)
 **Post-Task Cleanup Automation**
 
 Hook-based cleanup that runs after Claude completes work.
 
 ### Security
 
-#### [code-sentinel](./plugins/code-sentinel/README.md)
+#### [code-sentinel](./plugins/code-sentinel)
 **Security Scanning & Refactoring**
 
 Security vulnerability detection and code refactoring tools.
@@ -102,16 +103,16 @@ Security vulnerability detection and code refactoring tools.
 
 ### Infrastructure
 
-#### [cmdb-assistant](./plugins/cmdb-assistant/README.md)
+#### [cmdb-assistant](./plugins/cmdb-assistant)
 **NetBox CMDB Integration**
 
 Full CRUD operations for network infrastructure management directly from Claude Code.
 
-**Commands:** `/initial-setup`, `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`
+**Commands:** `/cmdb-setup`, `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`, `/cmdb-audit`, `/cmdb-register`, `/cmdb-sync`, `/cmdb-topology`, `/change-audit`, `/ip-conflicts`
 
 ### Data Engineering
 
-#### [data-platform](./plugins/data-platform/README.md) *NEW in v4.0.0*
+#### [data-platform](./plugins/data-platform) *NEW in v4.0.0*
 **pandas, PostgreSQL/PostGIS, and dbt Integration**
 
 Comprehensive data engineering toolkit with persistent DataFrame storage.
@@ -122,11 +123,11 @@ Comprehensive data engineering toolkit with persistent DataFrame storage.
 - 100k row limit with chunking support
 - Auto-detection of dbt projects
 
-**Commands:** `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/run`
+**Commands:** `/data-ingest`, `/data-profile`, `/data-schema`, `/data-explain`, `/data-lineage`, `/lineage-viz`, `/data-run`, `/dbt-test`, `/data-quality`, `/data-review`, `/data-gate`, `/data-setup`
 
 ### Visualization
 
-#### [viz-platform](./plugins/viz-platform/README.md) *NEW in v4.0.0*
+#### [viz-platform](./plugins/viz-platform) *NEW in v4.0.0*
 **Dash Mantine Components Validation and Theming**
 
 Visualization toolkit with version-locked component validation and design token theming.
@@ -138,11 +139,26 @@ 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`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/initial-setup`
+**Commands:** `/viz-chart`, `/viz-chart-export`, `/viz-dashboard`, `/viz-theme`, `/viz-theme-new`, `/viz-theme-css`, `/viz-component`, `/accessibility-check`, `/viz-breakpoints`, `/design-review`, `/design-gate`, `/viz-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** with **symlinks** from plugins that use them.
+MCP servers are **shared at repository root** and configured in `.mcp.json`.
 
 ### Gitea MCP Server (shared)
 
@@ -200,7 +216,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` |
+| Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow`, `validate_workflow_integration` |
 | Report | `generate_compatibility_report`, `list_issues` |
 
 ## Installation
@@ -239,7 +255,7 @@ Add to `.claude/settings.json` in your target project:
 After installing plugins, run the setup wizard:
 
 ```
-/initial-setup
+/pm-setup
 ```
 
 The wizard handles everything:
@@ -297,10 +313,10 @@ After installing plugins, the `/plugin` command may show `(no content)` - this i
 | clarity-assist | `/clarity-assist:clarify` |
 | doc-guardian | `/doc-guardian:doc-audit` |
 | code-sentinel | `/code-sentinel:security-scan` |
-| claude-config-maintainer | `/claude-config-maintainer:config-analyze` |
+| claude-config-maintainer | `/claude-config-maintainer:analyze` |
 | cmdb-assistant | `/cmdb-assistant:cmdb-search` |
-| data-platform | `/data-platform:ingest` |
-| viz-platform | `/viz-platform:chart` |
+| data-platform | `/data-platform:data-ingest` |
+| viz-platform | `/viz-platform:viz-chart` |
 | contract-validator | `/contract-validator:validate-contracts` |
 
 ## Repository Structure

docs/CANONICAL-PATHS.md

@@ -2,7 +2,7 @@
 
 **This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
 
-Last Updated: 2026-01-26 (v5.0.0)
+Last Updated: 2026-01-30 (v5.4.1)
 
 ---
 
@@ -76,9 +76,6 @@ leo-claude-mktplace/
 ├── plugins/                    # ALL plugins
 │   ├── projman/                # Sprint management
 │   │   ├── .claude-plugin/
-│   │   ├── .mcp.json
-│   │   ├── mcp-servers/
-│   │   │   └── gitea -> ../../../mcp-servers/gitea  # SYMLINK
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── skills/
@@ -99,9 +96,6 @@ 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
@@ -114,58 +108,49 @@ leo-claude-mktplace/
 │   │   ├── .claude-plugin/
 │   │   ├── hooks/
 │   │   └── claude-md-integration.md
-│   ├── clarity-assist/         # NEW in v3.0.0
+│   ├── clarity-assist/
 │   │   ├── .claude-plugin/
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── skills/
 │   │   └── claude-md-integration.md
-│   ├── git-flow/               # NEW in v3.0.0
+│   ├── git-flow/
 │   │   ├── .claude-plugin/
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── skills/
 │   │   └── claude-md-integration.md
-│   ├── pr-review/              # NEW in v3.0.0
+│   ├── pr-review/
 │   │   ├── .claude-plugin/
-│   │   ├── .mcp.json
-│   │   ├── mcp-servers/
-│   │   │   └── gitea -> ../../../mcp-servers/gitea  # SYMLINK
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── skills/
 │   │   └── claude-md-integration.md
-│   ├── data-platform/          # NEW in v4.0.0
+│   ├── data-platform/
 │   │   ├── .claude-plugin/
-│   │   ├── .mcp.json
-│   │   ├── mcp-servers/
-│   │   │   └── data-platform -> ../../../mcp-servers/data-platform  # SYMLINK
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── hooks/
 │   │   └── claude-md-integration.md
-│   ├── contract-validator/     # NEW in v5.0.0
+│   ├── contract-validator/
 │   │   ├── .claude-plugin/
-│   │   ├── .mcp.json
-│   │   ├── mcp-servers/
-│   │   │   └── contract-validator -> ../../../mcp-servers/contract-validator  # SYMLINK
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   └── claude-md-integration.md
-│   └── viz-platform/           # NEW in v4.1.0
+│   └── viz-platform/
 │       ├── .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 (rebuild venvs, verify symlinks)
-│   ├── check-venv.sh           # Check if venvs exist (for hooks)
-│   └── validate-marketplace.sh # Marketplace compliance validation
+│   ├── post-update.sh          # Post-update (clear cache, show changelog)
+│   ├── check-venv.sh           # Check if venvs exist (read-only)
+│   ├── validate-marketplace.sh # Marketplace compliance validation
+│   ├── verify-hooks.sh         # Verify all hooks use correct event types
+│   ├── setup-venvs.sh          # Setup MCP server venvs (create only, never delete)
+│   └── release.sh              # Release automation with version bumping
 ├── CLAUDE.md
 ├── README.md
 ├── LICENSE
@@ -185,29 +170,53 @@ 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 .mcp.json | `plugins/{plugin-name}/.mcp.json` | `plugins/projman/.mcp.json` |
+| Plugin skills | `plugins/{plugin-name}/skills/` | `plugins/projman/skills/` |
 | Plugin integration snippet | `plugins/{plugin-name}/claude-md-integration.md` | `plugins/projman/claude-md-integration.md` |
 
-### MCP Server Paths (v3.0.0 Architecture)
+### MCP Server Paths
 
-MCP servers are **shared at repository root** with **symlinks** from plugins.
+MCP servers are **shared at repository root** and configured in `.mcp.json`.
 
 | 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` |
+| MCP venv (local) | `mcp-servers/{server}/.venv/` | `mcp-servers/gitea/.venv/` |
 
-### Symlink Pattern
+**Note:** Plugins do NOT have their own `mcp-servers/` directories. All MCP servers are shared at root and configured via `.mcp.json`.
 
-Plugins that use MCP servers create symlinks:
+### MCP Venv Paths - CRITICAL
+
+**Venvs live in a CACHE directory that SURVIVES marketplace updates.**
+
+When checking for venvs, ALWAYS check in this order:
+
+| Priority | Path | Survives Updates? |
+|----------|------|-------------------|
+| 1 (CHECK FIRST) | `~/.cache/claude-mcp-venvs/leo-claude-mktplace/{server}/.venv/` | YES |
+| 2 (fallback) | `{marketplace}/mcp-servers/{server}/.venv/` | NO |
+
+**Why cache first?**
+- Marketplace directory gets WIPED on every update/reinstall
+- Cache directory SURVIVES updates
+- False "venv missing" errors waste hours of debugging
+
+**Pattern for hooks checking venvs:**
 ```bash
-# From plugin directory
-ln -s ../../../mcp-servers/gitea plugins/projman/mcp-servers/gitea
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/{server}/.venv/bin/python"
+LOCAL_VENV="$MARKETPLACE_ROOT/mcp-servers/{server}/.venv/bin/python"
+
+if [[ -f "$CACHE_VENV" ]]; then
+    VENV_PATH="$CACHE_VENV"
+elif [[ -f "$LOCAL_VENV" ]]; then
+    VENV_PATH="$LOCAL_VENV"
+else
+    echo "venv missing"
+fi
 ```
 
-The symlink target is relative: `../../../mcp-servers/{server}`
+**See lesson learned:** [Startup Hooks Must Check Venv Cache Path First](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/lessons/patterns/startup-hooks-must-check-venv-cache-path-first)
 
 ### Documentation Paths
 
@@ -236,15 +245,12 @@ The symlink target is relative: `../../../mcp-servers/{server}`
 2. Verify each path against patterns in this file
 3. Show verification to user before proceeding
 
-### Relative Path Calculation (v3.0.0)
+### Relative Path Calculation
 
-From `plugins/projman/.mcp.json` to shared `mcp-servers/gitea/`:
+From `.mcp.json` (at root) to `mcp-servers/gitea/`:
 ```
-plugins/projman/.mcp.json
-  → 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
+.mcp.json (at repository root)
+  → Uses absolute installed path: ~/.claude/plugins/marketplaces/.../mcp-servers/gitea/run.sh
 ```
 
 From `.claude-plugin/marketplace.json` to `plugins/projman/`:
@@ -263,30 +269,34 @@ Result: ./plugins/projman
 | Wrong | Why | Correct |
 |-------|-----|---------|
 | `projman/` at root | Plugins go in `plugins/` | `plugins/projman/` |
-| Direct path in .mcp.json to root mcp-servers | Use symlink | Symlink at `plugins/{plugin}/mcp-servers/` |
-| Creating new mcp-servers inside plugins | Use shared + symlink | Symlink to `mcp-servers/` |
-| Hardcoding absolute paths | Breaks portability | Use `${CLAUDE_PLUGIN_ROOT}` |
+| `mcp-servers/` inside plugins | MCP servers are shared at root | Use root `mcp-servers/` |
+| Plugin-level `.mcp.json` | MCP config is at root | Use root `.mcp.json` |
+| Hardcoding absolute paths in source | Breaks portability | Use relative paths or `${CLAUDE_PLUGIN_ROOT}` |
 
 ---
 
-## Architecture Note (v3.0.0)
+## Architecture Note
 
-MCP servers are now **shared at repository root** with **symlinks** from plugins:
+MCP servers are **shared at repository root** and configured in a single `.mcp.json` file.
 
 **Benefits:**
 - Single source of truth for each MCP server
 - Updates apply to all plugins automatically
-- Reduced duplication
-- Symlinks work with Claude Code caching
+- No duplication - clean plugin structure
+- Simple configuration in one place
 
-**Symlink Pattern:**
-```
-plugins/projman/mcp-servers/gitea -> ../../../mcp-servers/gitea
-plugins/cmdb-assistant/mcp-servers/netbox -> ../../../mcp-servers/netbox
-plugins/pr-review/mcp-servers/gitea -> ../../../mcp-servers/gitea
-plugins/data-platform/mcp-servers/data-platform -> ../../../mcp-servers/data-platform
-plugins/viz-platform/mcp-servers/viz-platform -> ../../../mcp-servers/viz-platform
-plugins/contract-validator/mcp-servers/contract-validator -> ../../../mcp-servers/contract-validator
+**Configuration:**
+All MCP servers are defined in `.mcp.json` at repository root:
+```json
+{
+  "mcpServers": {
+    "gitea": { "command": ".../mcp-servers/gitea/run.sh" },
+    "netbox": { "command": ".../mcp-servers/netbox/run.sh" },
+    "data-platform": { "command": ".../mcp-servers/data-platform/run.sh" },
+    "viz-platform": { "command": ".../mcp-servers/viz-platform/run.sh" },
+    "contract-validator": { "command": ".../mcp-servers/contract-validator/run.sh" }
+  }
+}
 ```
 
 ---
@@ -295,6 +305,7 @@ plugins/contract-validator/mcp-servers/contract-validator -> ../../../mcp-server
 
 | 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

@@ -9,39 +9,41 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | Plugin | Command | Auto | Manual | Description |
 |--------|---------|:----:|:------:|-------------|
 | **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 and identify blockers |
-| **projman** | `/review` | | X | Pre-sprint-close code quality review (debug artifacts, security, error handling) |
-| **projman** | `/test-check` | | X | Run tests and verify coverage before sprint close |
+| **projman** | `/sprint-start` | | X | Begin sprint execution with dependency analysis and parallel task coordination (requires approval or `--force`) |
+| **projman** | `/sprint-status` | | X | Check current sprint progress (add `--diagram` for Mermaid visualization) |
+| **projman** | `/pm-review` | | X | Pre-sprint-close code quality review (debug artifacts, security, error handling) |
+| **projman** | `/pm-test` | | X | Run tests (`/pm-test run`) or generate tests (`/pm-test gen <target>`) |
 | **projman** | `/sprint-close` | | X | Complete sprint and capture lessons learned to Gitea Wiki |
 | **projman** | `/labels-sync` | | X | Synchronize label taxonomy from Gitea |
-| **projman** | `/initial-setup` | | X | Full setup wizard: MCP server + system config + project config |
-| **projman** | `/project-init` | | X | Quick project setup (assumes system config exists) |
-| **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** | `/pm-setup` | | X | Auto-detect mode or use `--full`, `--quick`, `--sync`, `--clear-cache` |
+| **projman** | *SessionStart hook* | X | | Detects git remote vs .env mismatch, warns to run `/pm-setup --sync` |
+| **projman** | `/pm-debug` | | X | Diagnostics (`/pm-debug report`) or investigate (`/pm-debug review`) |
 | **projman** | `/suggest-version` | | X | Analyze CHANGELOG and recommend semantic version bump |
-| **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 |
-| **git-flow** | `/commit-sync` | | X | Full sync: commit, push, and sync with upstream/base branch |
+| **projman** | `/proposal-status` | | X | View proposal and implementation hierarchy with status |
+| **projman** | `/rfc` | | X | RFC lifecycle management (`/rfc create\|list\|review\|approve\|reject`) |
+| **git-flow** | `/git-commit` | | X | Create commit with auto-generated conventional message |
+| **git-flow** | `/git-commit-push` | | X | Commit and push to remote in one operation |
+| **git-flow** | `/git-commit-merge` | | X | Commit current changes, then merge into target branch |
+| **git-flow** | `/git-commit-sync` | | X | Full sync: commit, push, and sync with upstream/base branch |
 | **git-flow** | `/branch-start` | | X | Create new feature/fix/chore branch with naming conventions |
 | **git-flow** | `/branch-cleanup` | | X | Remove merged branches locally and optionally on remote |
 | **git-flow** | `/git-status` | | X | Enhanced git status with recommendations |
 | **git-flow** | `/git-config` | | X | Configure git-flow settings for the project |
-| **pr-review** | `/initial-setup` | | X | Setup wizard for pr-review (shares Gitea MCP with projman) |
+| **pr-review** | `/pr-setup` | | X | Setup wizard for pr-review (shares Gitea MCP with projman) |
 | **pr-review** | `/project-init` | | X | Quick project setup for PR reviews |
 | **pr-review** | `/project-sync` | | X | Sync config with git remote after repo move/rename |
 | **pr-review** | *SessionStart hook* | X | | Detects git remote vs .env mismatch |
 | **pr-review** | `/pr-review` | | X | Full multi-agent PR review with confidence scoring |
 | **pr-review** | `/pr-summary` | | X | Quick summary of PR changes |
 | **pr-review** | `/pr-findings` | | X | List and filter review findings by category/severity |
+| **pr-review** | `/pr-diff` | | X | Formatted diff with inline review comments and annotations |
 | **clarity-assist** | `/clarify` | | X | Full 4-D prompt optimization with ND accommodations |
 | **clarity-assist** | `/quick-clarify` | | X | Rapid single-pass clarification for simple requests |
 | **doc-guardian** | `/doc-audit` | | X | Full documentation audit - scans for doc drift |
 | **doc-guardian** | `/doc-sync` | | X | Synchronize pending documentation updates |
+| **doc-guardian** | `/changelog-gen` | | X | Generate changelog from conventional commits |
+| **doc-guardian** | `/doc-coverage` | | X | Documentation coverage metrics by function/class |
+| **doc-guardian** | `/stale-docs` | | X | Flag documentation behind code changes |
 | **doc-guardian** | *PostToolUse hook* | X | | Silently detects doc drift on Write/Edit |
 | **code-sentinel** | `/security-scan` | | X | Full security audit (SQL injection, XSS, secrets, etc.) |
 | **code-sentinel** | `/refactor` | | X | Apply refactoring patterns to improve code |
@@ -50,28 +52,54 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **claude-config-maintainer** | `/config-analyze` | | X | Analyze CLAUDE.md for optimization opportunities |
 | **claude-config-maintainer** | `/config-optimize` | | X | Optimize CLAUDE.md structure with preview/backup |
 | **claude-config-maintainer** | `/config-init` | | X | Initialize new CLAUDE.md for a project |
-| **cmdb-assistant** | `/initial-setup` | | X | Setup wizard for NetBox MCP server |
+| **claude-config-maintainer** | `/config-diff` | | X | Track CLAUDE.md changes over time with behavioral impact |
+| **claude-config-maintainer** | `/config-lint` | | X | Lint CLAUDE.md for anti-patterns and best practices |
+| **claude-config-maintainer** | `/config-audit-settings` | | X | Audit settings.local.json permissions (100-point score) |
+| **claude-config-maintainer** | `/config-optimize-settings` | | X | Optimize permissions (profiles, consolidation, dry-run) |
+| **claude-config-maintainer** | `/config-permissions-map` | | X | Visual review layer + permission coverage map |
+| **cmdb-assistant** | `/cmdb-setup` | | X | Setup wizard for NetBox MCP server |
 | **cmdb-assistant** | `/cmdb-search` | | X | Search NetBox for devices, IPs, sites |
 | **cmdb-assistant** | `/cmdb-device` | | X | Manage network devices (create, view, update, delete) |
 | **cmdb-assistant** | `/cmdb-ip` | | X | Manage IP addresses and prefixes |
 | **cmdb-assistant** | `/cmdb-site` | | X | Manage sites, locations, racks, and regions |
+| **cmdb-assistant** | `/cmdb-audit` | | X | Data quality analysis (VMs, devices, naming, roles) |
+| **cmdb-assistant** | `/cmdb-register` | | X | Register current machine into NetBox with running apps |
+| **cmdb-assistant** | `/cmdb-sync` | | X | Sync machine state with NetBox (detect drift, update) |
+| **cmdb-assistant** | `/cmdb-topology` | | X | Infrastructure topology diagrams (rack, network, site views) |
+| **cmdb-assistant** | `/change-audit` | | X | NetBox audit trail queries with filtering |
+| **cmdb-assistant** | `/ip-conflicts` | | X | Detect IP conflicts and overlapping prefixes |
 | **project-hygiene** | *PostToolUse hook* | X | | Removes temp files, warns about unexpected root files |
-| **data-platform** | `/ingest` | | X | Load data from CSV, Parquet, JSON into DataFrame |
-| **data-platform** | `/profile` | | X | Generate data profiling report with statistics |
-| **data-platform** | `/schema` | | X | Explore database schemas, tables, columns |
-| **data-platform** | `/explain` | | X | Explain query execution plan |
-| **data-platform** | `/lineage` | | X | Show dbt model lineage and dependencies |
-| **data-platform** | `/run` | | X | Run dbt models with validation |
-| **data-platform** | `/initial-setup` | | X | Setup wizard for data-platform MCP servers |
+| **data-platform** | `/data-ingest` | | X | Load data from CSV, Parquet, JSON into DataFrame |
+| **data-platform** | `/data-profile` | | X | Generate data profiling report with statistics |
+| **data-platform** | `/data-schema` | | X | Explore database schemas, tables, columns |
+| **data-platform** | `/data-explain` | | X | Explain query execution plan |
+| **data-platform** | `/data-lineage` | | X | Show dbt model lineage and dependencies |
+| **data-platform** | `/data-run` | | X | Run dbt models with validation |
+| **data-platform** | `/lineage-viz` | | X | dbt lineage visualization as Mermaid diagrams |
+| **data-platform** | `/dbt-test` | | X | Formatted dbt test runner with summary and failure details |
+| **data-platform** | `/data-quality` | | X | DataFrame quality checks (nulls, duplicates, types, outliers) |
+| **data-platform** | `/data-setup` | | X | Setup wizard for data-platform MCP servers |
 | **data-platform** | *SessionStart hook* | X | | Checks PostgreSQL connection (non-blocking warning) |
-| **viz-platform** | `/initial-setup` | | X | Setup wizard for viz-platform MCP server |
-| **viz-platform** | `/chart` | | X | Create Plotly charts with theme integration |
-| **viz-platform** | `/dashboard` | | X | Create dashboard layouts with filters and grids |
-| **viz-platform** | `/theme` | | X | Apply existing theme to visualizations |
-| **viz-platform** | `/theme-new` | | X | Create new custom theme with design tokens |
-| **viz-platform** | `/theme-css` | | X | Export theme as CSS custom properties |
-| **viz-platform** | `/component` | | X | Inspect DMC component props and validation |
+| **viz-platform** | `/viz-setup` | | X | Setup wizard for viz-platform MCP server |
+| **viz-platform** | `/viz-chart` | | X | Create Plotly charts with theme integration |
+| **viz-platform** | `/viz-dashboard` | | X | Create dashboard layouts with filters and grids |
+| **viz-platform** | `/viz-theme` | | X | Apply existing theme to visualizations |
+| **viz-platform** | `/viz-theme-new` | | X | Create new custom theme with design tokens |
+| **viz-platform** | `/viz-theme-css` | | X | Export theme as CSS custom properties |
+| **viz-platform** | `/viz-component` | | X | Inspect DMC component props and validation |
+| **viz-platform** | `/viz-chart-export` | | X | Export charts to PNG, SVG, PDF via kaleido |
+| **viz-platform** | `/accessibility-check` | | X | Color blind validation (WCAG contrast ratios) |
+| **viz-platform** | `/viz-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 |
+| **contract-validator** | `/dependency-graph` | | X | Mermaid visualization of plugin dependencies |
+| **contract-validator** | `/cv-setup` | | X | Setup wizard for contract-validator MCP |
 
 ---
 
@@ -79,7 +107,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
 
 | Category | Plugins | Primary Use |
 |----------|---------|-------------|
-| **Setup** | projman, pr-review, cmdb-assistant, data-platform | `/initial-setup`, `/project-init` |
+| **Setup** | projman, pr-review, cmdb-assistant, data-platform, viz-platform, contract-validator | `/pm-setup`, `/pr-setup`, `/cmdb-setup`, `/data-setup`, `/viz-setup`, `/cv-setup` |
 | **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 |
@@ -87,6 +115,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **Infrastructure** | cmdb-assistant | NetBox CMDB management |
 | **Data Engineering** | data-platform | pandas, PostgreSQL, dbt operations |
 | **Visualization** | viz-platform | DMC validation, Plotly charts, theming |
+| **Validation** | contract-validator | Cross-plugin compatibility checks |
 | **Maintenance** | project-hygiene | Automatic cleanup |
 
 ---
@@ -107,6 +136,22 @@ 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:
@@ -118,10 +163,10 @@ A typical workflow for planning and executing a feature sprint:
 4. /sprint-start             # Begin execution with dependency ordering
 5. /branch-start feat/...    # Create feature branch
    ... implement features ...
-6. /commit                   # Commit with conventional message
-7. /sprint-status            # Check progress mid-sprint
-8. /review                   # Pre-close quality review
-9. /test-check               # Verify test coverage
+6. /git-commit               # Commit with conventional message
+7. /sprint-status --diagram  # Check progress with visualization
+8. /pm-review                # Pre-close quality review
+9. /pm-test run              # Verify test coverage
 10. /sprint-close            # Capture lessons learned
 ```
 
@@ -133,8 +178,8 @@ Quick daily workflow with git-flow:
 1. /git-status               # Check current state
 2. /branch-start fix/...     # Start bugfix branch
    ... make changes ...
-3. /commit                   # Auto-generate commit message
-4. /commit-push              # Push to remote
+3. /git-commit               # Auto-generate commit message
+4. /git-commit-push          # Push to remote
 5. /branch-cleanup           # Clean merged branches
 ```
 
@@ -168,8 +213,8 @@ Safe refactoring with preview:
 1. /refactor-dry             # Preview opportunities
 2. /security-scan            # Baseline security check
 3. /refactor                 # Apply improvements
-4. /test-check               # Verify nothing broke
-5. /commit                   # Commit with descriptive message
+4. /pm-test run              # Verify nothing broke
+5. /git-commit               # Commit with descriptive message
 ```
 
 ### Example 6: Infrastructure Documentation
@@ -188,12 +233,12 @@ Managing infrastructure with CMDB:
 Working with data pipelines:
 
 ```
-1. /ingest file.csv          # Load data into DataFrame
-2. /profile                  # Generate data profiling report
-3. /schema                   # Explore database schemas
-4. /lineage model_name       # View dbt model dependencies
-5. /run model_name           # Execute dbt models
-6. /explain "SELECT ..."     # Analyze query execution plan
+1. /data-ingest file.csv     # Load data into DataFrame
+2. /data-profile             # Generate data profiling report
+3. /data-schema              # Explore database schemas
+4. /data-lineage model_name  # View dbt model dependencies
+5. /data-run model_name      # Execute dbt models
+6. /data-explain "SELECT ..." # Analyze query execution plan
 ```
 
 ### Example 7: First-Time Setup (New Machine)
@@ -201,7 +246,7 @@ Working with data pipelines:
 Setting up the marketplace for the first time:
 
 ```
-1. /initial-setup            # Full setup: MCP + system config + project
+1. /pm-setup --full          # Full setup: MCP + system config + project
    # → Follow prompts for Gitea URL, org
    # → Add token manually when prompted
    # → Confirm repository name
@@ -215,7 +260,7 @@ Setting up the marketplace for the first time:
 Adding a new project when system config exists:
 
 ```
-1. /project-init             # Quick project setup
+1. /pm-setup --quick         # Quick project setup (auto-detected)
    # → Confirms detected repo name
    # → Creates .env
 2. /labels-sync              # Sync Gitea labels
@@ -227,8 +272,8 @@ Adding a new project when system config exists:
 ## Quick Tips
 
 - **Hooks run automatically** - doc-guardian and code-sentinel protect you without manual invocation
-- **Use `/commit` over `git commit`** - generates better commit messages following conventions
-- **Run `/review` before `/sprint-close`** - catches issues before closing the sprint
+- **Use `/git-commit` over `git commit`** - generates better commit messages following conventions
+- **Run `/pm-review` before `/sprint-close`** - catches issues before closing the sprint
 - **Use `/clarify` for vague requests** - especially helpful for complex requirements
 - **`/refactor-dry` is safe** - always preview before applying refactoring changes
 
@@ -245,9 +290,10 @@ Some plugins require MCP server connectivity:
 | cmdb-assistant | NetBox | Infrastructure CMDB |
 | data-platform | pandas, PostgreSQL, dbt | DataFrames, database queries, dbt builds |
 | viz-platform | viz-platform | DMC validation, charts, layouts, themes, pages |
+| contract-validator | contract-validator | Plugin interface parsing, compatibility validation |
 
 Ensure credentials are configured in `~/.config/claude/gitea.env`, `~/.config/claude/netbox.env`, or `~/.config/claude/postgres.env`.
 
 ---
 
-*Last Updated: 2026-01-26*
+*Last Updated: 2026-02-02*

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:**
 
 ```
-/initial-setup
+/pm-setup
 ```
 
-The interactive wizard handles everything except manually adding your API tokens.
+The interactive wizard auto-detects what's needed and handles everything except manually adding your API tokens.
 
 ---
 
@@ -25,7 +25,8 @@ The interactive wizard handles everything except manually adding your API tokens
 └─────────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
-                            /initial-setup
+                             /pm-setup --full
+                         (or /pm-setup auto-detects)
                                     │
      ┌──────────────────────────────┼──────────────────────────────┐
      ▼                              ▼                              ▼
@@ -78,8 +79,8 @@ The interactive wizard handles everything except manually adding your API tokens
                                     │
                     ┌───────────────┴───────────────┐
                     ▼                               ▼
-             /project-init                   /initial-setup
-             (direct path)                   (smart detection)
+            /pm-setup --quick                  /pm-setup
+             (explicit mode)               (auto-detects mode)
                     │                               │
                     │                    ┌──────────┴──────────┐
                     │                    ▼                     ▼
@@ -108,7 +109,7 @@ The interactive wizard handles everything except manually adding your API tokens
 
 ## What Runs Automatically vs User Interaction
 
-### `/initial-setup` - Full Setup
+### `/pm-setup --full` - Full Setup
 
 | Phase | Type | What Happens |
 |-------|------|--------------|
@@ -120,7 +121,7 @@ The interactive wizard handles everything except manually adding your API tokens
 | **6. Project Config** | Automated | Creates `.env` file, checks `.gitignore` |
 | **7. Validation** | Automated | Tests API connectivity, shows summary |
 
-### `/project-init` - Quick Project Setup
+### `/pm-setup --quick` - Quick Project Setup
 
 | Phase | Type | What Happens |
 |-------|------|--------------|
@@ -131,23 +132,25 @@ The interactive wizard handles everything except manually adding your API tokens
 
 ---
 
-## Three Commands for Different Scenarios
+## One Command, Three Modes
 
-| Command | When to Use | What It Does |
-|---------|-------------|--------------|
-| `/initial-setup` | 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) |
-| `/project-sync` | After repo move/rename | Updates .env to match current git remote |
+| Mode | When to Use | What It Does |
+|------|-------------|--------------|
+| `/pm-setup` | Any time | Auto-detects: runs full, quick, or sync as needed |
+| `/pm-setup --full` | First time on a machine | Full setup: MCP server + system config + project config |
+| `/pm-setup --quick` | Starting a new project | Quick setup: project config only (assumes system is ready) |
+| `/pm-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 `/initial-setup` (once per machine)
-2. Start new project → run `/project-init` (once per project)
-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
+1. Install plugin → run `/pm-setup` (auto-runs full mode)
+2. Start new project → run `/pm-setup` (auto-runs quick mode)
+3. Repository moved? → run `/pm-setup` (auto-runs sync mode)
 
 ---
 
@@ -171,8 +174,7 @@ This marketplace uses a **hybrid configuration** approach:
 │                  PROJECT-LEVEL (once per project)              │
 │                  <project-root>/.env                            │
 ├─────────────────────────────────────────────────────────────────┤
-│  GITEA_ORG               │  Organization for this project      │
-│  GITEA_REPO              │  Repository name for this project   │
+│  GITEA_REPO              │  Repository as owner/repo format    │
 │  GIT_WORKFLOW_STYLE      │  (optional) Override system default │
 │  PR_REVIEW_*             │  (optional) PR review settings      │
 └─────────────────────────────────────────────────────────────────┘
@@ -180,7 +182,7 @@ This marketplace uses a **hybrid configuration** approach:
 
 **Benefits:**
 - Single token per service (update once, use everywhere)
-- Easy multi-project setup (just run `/project-init` in each project)
+- Easy multi-project setup (just run `/pm-setup` in each project)
 - Security (tokens never committed to git, never typed into AI chat)
 - Project isolation (each project can override defaults)
 
@@ -188,7 +190,7 @@ This marketplace uses a **hybrid configuration** approach:
 
 ## Prerequisites
 
-Before running `/initial-setup`:
+Before running `/pm-setup`:
 
 1. **Python 3.10+** installed
    ```bash
@@ -211,10 +213,10 @@ Before running `/initial-setup`:
 Run the setup wizard in Claude Code:
 
 ```
-/initial-setup
+/pm-setup
 ```
 
-The wizard will guide you through each step interactively.
+The wizard will guide you through each step interactively and auto-detect the appropriate mode.
 
 **Note:** After first-time setup, you'll need to restart your Claude Code session for MCP tools to become available.
 
@@ -262,8 +264,7 @@ In each project root:
 
 ```bash
 cat > .env << 'EOF'
-GITEA_ORG=your-organization
-GITEA_REPO=your-repo-name
+GITEA_REPO=your-organization/your-repo-name
 EOF
 ```
 
@@ -307,7 +308,7 @@ GITEA_API_TOKEN=your_gitea_token_here
 | `GITEA_API_URL` | Gitea API endpoint (with `/api/v1`) | `https://gitea.example.com/api/v1` |
 | `GITEA_API_TOKEN` | Personal access token | `abc123...` |
 
-**Note:** `GITEA_ORG` is configured at the project level (see below) since different projects may belong to different organizations.
+**Note:** `GITEA_REPO` is configured at the project level in `owner/repo` format since different projects may belong to different organizations.
 
 **Generating a Gitea Token:**
 1. Log into Gitea → **User Icon** → **Settings**
@@ -362,9 +363,8 @@ GIT_CO_AUTHOR=true
 Create `.env` in each project root:
 
 ```bash
-# Required for projman, pr-review
-GITEA_ORG=your-organization
-GITEA_REPO=your-repo-name
+# Required for projman, pr-review (use owner/repo format)
+GITEA_REPO=your-organization/your-repo-name
 
 # Optional: Override git-flow defaults
 GIT_WORKFLOW_STYLE=pr-required
@@ -377,8 +377,7 @@ PR_REVIEW_AUTO_SUBMIT=false
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `GITEA_ORG` | Yes | Gitea organization for this project |
-| `GITEA_REPO` | Yes | Repository name (must match Gitea exactly) |
+| `GITEA_REPO` | Yes | Repository in `owner/repo` format (e.g., `my-org/my-repo`) |
 | `GIT_WORKFLOW_STYLE` | No | Override system default |
 | `PR_REVIEW_*` | No | PR review settings |
 
@@ -386,19 +385,20 @@ PR_REVIEW_AUTO_SUBMIT=false
 
 ## Plugin Configuration Summary
 
-| Plugin | System Config | Project Config | Setup Commands |
-|--------|---------------|----------------|----------------|
-| **projman** | gitea.env | .env (GITEA_ORG, GITEA_REPO) | `/initial-setup`, `/project-init`, `/project-sync` |
-| **pr-review** | gitea.env | .env (GITEA_ORG, GITEA_REPO) | `/initial-setup`, `/project-init`, `/project-sync` |
+| Plugin | System Config | Project Config | Setup Command |
+|--------|---------------|----------------|---------------|
+| **projman** | gitea.env | .env (GITEA_REPO=owner/repo) | `/pm-setup` |
+| **pr-review** | gitea.env | .env (GITEA_REPO=owner/repo) | `/pr-setup` |
 | **git-flow** | git-flow.env (optional) | .env (optional) | None needed |
 | **clarity-assist** | None | None | None needed |
-| **cmdb-assistant** | netbox.env | None | `/initial-setup` |
-| **data-platform** | postgres.env | .env (optional) | `/initial-setup` |
-| **viz-platform** | None | .env (optional DMC_VERSION) | `/initial-setup` |
+| **cmdb-assistant** | netbox.env | None | `/cmdb-setup` |
+| **data-platform** | postgres.env | .env (optional) | `/data-setup` |
+| **viz-platform** | None | .env (optional DMC_VERSION) | `/viz-setup` |
 | **doc-guardian** | None | None | None needed |
 | **code-sentinel** | None | None | None needed |
 | **project-hygiene** | None | None | None needed |
 | **claude-config-maintainer** | None | None | None needed |
+| **contract-validator** | None | None | `/cv-setup` |
 
 ---
 
@@ -406,21 +406,224 @@ 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
-/project-init
+/pm-setup
 ```
 
-**Option 2: Use `/initial-setup` (auto-detects)**
-```
-cd ~/projects/new-project
-/initial-setup
-# → Detects system config exists
-# → Offers "Quick project setup" option
+The command auto-detects that system config exists and runs quick project setup.
+
+---
+
+## Installing Plugins to Consumer Projects
+
+The marketplace provides scripts to install plugins into consumer projects. This sets up the MCP server connections and adds CLAUDE.md integration snippets.
+
+### Install a Plugin
+
+```bash
+cd /path/to/leo-claude-mktplace
+./scripts/install-plugin.sh <plugin-name> <target-project-path>
 ```
 
-Both approaches work. Use `/project-init` when you know the system is already configured.
+**Examples:**
+```bash
+# Install data-platform to a portfolio project
+./scripts/install-plugin.sh data-platform ~/projects/personal-portfolio
+
+# Install multiple plugins
+./scripts/install-plugin.sh viz-platform ~/projects/personal-portfolio
+./scripts/install-plugin.sh projman ~/projects/personal-portfolio
+```
+
+**What it does:**
+1. Validates the plugin exists in the marketplace
+2. Adds MCP server entry to target's `.mcp.json` (if plugin has MCP server)
+3. Appends integration snippet to target's `CLAUDE.md`
+4. Reports changes and lists available commands
+
+**After installation:** Restart your Claude Code session for MCP tools to become available.
+
+### Uninstall a Plugin
+
+```bash
+./scripts/uninstall-plugin.sh <plugin-name> <target-project-path>
+```
+
+Removes the MCP server entry and CLAUDE.md integration section.
+
+### List Installed Plugins
+
+```bash
+./scripts/list-installed.sh <target-project-path>
+```
+
+Shows which marketplace plugins are installed, partially installed, or available.
+
+**Output example:**
+```
+✓ Fully Installed:
+  PLUGIN                   VERSION    DESCRIPTION
+  ------                   -------    -----------
+  data-platform            1.3.0      pandas, PostgreSQL, and dbt integration...
+  viz-platform             1.1.0      DMC validation, Plotly charts, and theming...
+
+○ Available (not installed):
+  projman                  3.4.0      Sprint planning and project management...
+```
+
+### Plugins with MCP Servers
+
+Not all plugins have MCP servers. The install script handles this automatically:
+
+| Plugin | Has MCP Server | Notes |
+|--------|---------------|-------|
+| data-platform | ✓ | pandas, PostgreSQL, dbt tools |
+| viz-platform | ✓ | DMC validation, chart, theme tools |
+| contract-validator | ✓ | Plugin compatibility validation |
+| cmdb-assistant | ✓ (via netbox) | NetBox CMDB tools |
+| projman | ✓ (via gitea) | Issue, wiki, PR tools |
+| pr-review | ✓ (via gitea) | PR review tools |
+| git-flow | ✗ | Commands only |
+| doc-guardian | ✗ | Commands and hooks only |
+| code-sentinel | ✗ | Commands and hooks only |
+| clarity-assist | ✗ | Commands only |
+
+### Script Requirements
+
+- **jq** must be installed (`sudo apt install jq`)
+- Scripts are idempotent (safe to run multiple times)
+
+---
+
+## Agent Frontmatter Configuration
+
+Agents specify their configuration in frontmatter using Claude Code's supported fields. Reference: https://code.claude.com/docs/en/sub-agents
+
+### Supported Frontmatter Fields
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | Yes | — | Unique identifier, lowercase + hyphens |
+| `description` | Yes | — | When Claude should delegate to this subagent |
+| `model` | No | `inherit` | `sonnet`, `opus`, `haiku`, or `inherit` |
+| `permissionMode` | No | `default` | Controls permission prompts: `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` |
+| `disallowedTools` | No | none | Comma-separated tools to remove from agent's toolset |
+| `skills` | No | none | Comma-separated skills auto-injected into context at startup |
+| `hooks` | No | none | Lifecycle hooks scoped to this subagent |
+
+### Complete Agent Matrix
+
+| Plugin | Agent | `model` | `permissionMode` | `disallowedTools` | `skills` |
+|--------|-------|---------|-------------------|--------------------|----------|
+| projman | planner | opus | default | — | frontmatter (2) + body text (12) |
+| projman | orchestrator | sonnet | acceptEdits | — | frontmatter (2) + body text (10) |
+| projman | executor | sonnet | bypassPermissions | — | frontmatter (7) |
+| projman | code-reviewer | opus | default | Write, Edit, MultiEdit | frontmatter (4) |
+| pr-review | coordinator | sonnet | plan | Write, Edit, MultiEdit | — |
+| pr-review | security-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
+| pr-review | performance-analyst | sonnet | plan | Write, Edit, MultiEdit | — |
+| pr-review | maintainability-auditor | haiku | plan | Write, Edit, MultiEdit | — |
+| pr-review | test-validator | haiku | plan | Write, Edit, MultiEdit | — |
+| data-platform | data-advisor | sonnet | default | — | — |
+| data-platform | data-analysis | sonnet | plan | Write, Edit, MultiEdit | — |
+| data-platform | data-ingestion | haiku | acceptEdits | — | — |
+| viz-platform | design-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
+| viz-platform | layout-builder | sonnet | default | — | — |
+| viz-platform | component-check | haiku | plan | Write, Edit, MultiEdit | — |
+| viz-platform | theme-setup | haiku | acceptEdits | — | — |
+| contract-validator | full-validation | sonnet | default | — | — |
+| contract-validator | agent-check | haiku | plan | Write, Edit, MultiEdit | — |
+| code-sentinel | security-reviewer | sonnet | plan | Write, Edit, MultiEdit | — |
+| code-sentinel | refactor-advisor | sonnet | acceptEdits | — | — |
+| doc-guardian | doc-analyzer | sonnet | acceptEdits | — | — |
+| clarity-assist | clarity-coach | sonnet | default | Write, Edit, MultiEdit | — |
+| git-flow | git-assistant | haiku | acceptEdits | — | — |
+| claude-config-maintainer | maintainer | sonnet | acceptEdits | — | frontmatter (2) |
+| cmdb-assistant | cmdb-assistant | sonnet | default | — | — |
+
+### Design Principles
+
+- `bypassPermissions` is granted to exactly ONE agent (Executor) which has code-sentinel PreToolUse hook + Code Reviewer downstream as safety nets.
+- `plan` mode is assigned to all pure analysis agents (pr-review, read-only validators).
+- `disallowedTools: Write, Edit, MultiEdit` provides defense-in-depth on agents that should never write files.
+- `skills` frontmatter is used for agents with ≤7 skills where guaranteed loading is safety-critical. Agents with 8+ skills use body text `## Skills to Load` for selective loading.
+- `hooks` (agent-scoped) is reserved for future use (v6.0+).
+
+Override any field by editing the agent's `.md` file in `plugins/{plugin}/agents/`.
+
+### permissionMode Guide
+
+| Value | Prompts for file ops? | Prompts for Bash? | Prompts for MCP? | Use when |
+|-------|-----------------------|-------------------|-------------------|----------|
+| `default` | Yes | Yes | No (MCP bypasses permissions) | You want full visibility |
+| `acceptEdits` | No | Yes | No | Core job is file read/write, Bash visibility useful |
+| `dontAsk` | No | No (most) | No | Even Bash prompts are friction |
+| `bypassPermissions` | No | No | No | Agent has downstream safety layers |
+| `plan` | N/A (read-only) | N/A (read-only) | No | Pure analysis, no modifications |
+
+### disallowedTools Guide
+
+Use `disallowedTools` to remove specific tools from an agent's toolset. This is a blacklist — the agent inherits all tools from the main thread, then the listed tools are removed.
+
+Prefer `disallowedTools` over `tools` (whitelist) because:
+- New MCP servers are automatically available without updating every agent.
+- Less configuration to maintain.
+- Easier to audit — you only list what's blocked.
+
+Common patterns:
+- `disallowedTools: Write, Edit, MultiEdit` — read-only agent, cannot modify files.
+- `disallowedTools: Bash` — no shell access (rare, most agents need at least read-only Bash).
+
+### skills Frontmatter Guide
+
+The `skills` field auto-injects skill file contents into the agent's context window at startup. The agent does NOT need to read the files — they are already present.
+
+**When to use frontmatter `skills`:**
+- Agent has ≤7 skills.
+- Skills are safety-critical (e.g., `branch-security`, `runaway-detection`).
+- You need guaranteed loading — no risk of the agent skipping a skill.
+
+**When to keep body text `## Skills to Load`:**
+- Agent has 8+ skills (context window cost too high for full injection).
+- Skills are situational — not all needed for every invocation.
+- Agent benefits from selective loading based on the specific task.
+
+Skill names in frontmatter are resolved relative to the plugin's `skills/` directory. Use the filename without the `.md` extension.
+
+### Phase-Based Skill Loading (Body Text)
+
+For agents with 8+ skills, use **phase-based loading** in the agent body text. This structures skill reads into logical phases, with explicit instructions to read each skill exactly once.
+
+**Pattern:**
+
+```markdown
+## Skill Loading Protocol
+
+**Frontmatter skills (auto-injected, always available — DO NOT re-read these):**
+- `skill-a` — description
+- `skill-b` — description
+
+**Phase 1 skills — read ONCE at session start:**
+- skills/validation-skill.md
+- skills/safety-skill.md
+
+**Phase 2 skills — read ONCE when entering main work:**
+- skills/workflow-skill.md
+- skills/domain-skill.md
+
+**CRITICAL: Read each skill file exactly ONCE. Do NOT re-read skill files between MCP API calls.**
+```
+
+**Benefits:**
+- Frontmatter skills (always needed) are auto-injected — zero file read cost
+- Phase skills are read once at the appropriate time — not re-read per API call
+- `batch-execution` skill provides protocol for API-heavy phases
+- ~76-83% reduction in skill-related token consumption for typical sprints
+
+**Currently applied to:**
+- Planner agent: 2 frontmatter + 12 body text (3 phases)
+- Orchestrator agent: 2 frontmatter + 10 body text (2 phases)
 
 ---
 
@@ -428,12 +631,12 @@ Both approaches work. Use `/project-init` when you know the system is already co
 
 ### API Validation
 
-When running `/initial-setup`, `/project-init`, or `/project-sync`, the commands:
+When running `/pm-setup`, the command:
 
-1. **Detect** organization and repository from git remote URL
-2. **Validate** via Gitea API: `GET /api/v1/repos/{org}/{repo}`
-3. **Auto-fill** if repository exists and is accessible (no confirmation needed)
-4. **Ask for confirmation** only if validation fails (404 or permission error)
+1. **Detects** organization and repository from git remote URL
+2. **Validates** via Gitea API: `GET /api/v1/repos/{org}/{repo}`
+3. **Auto-fills** if repository exists and is accessible (no confirmation needed)
+4. **Asks for confirmation** only if validation fails (404 or permission error)
 
 This catches typos and permission issues before saving configuration.
 
@@ -441,9 +644,9 @@ This catches typos and permission issues before saving configuration.
 
 When you start a Claude Code session, a hook automatically:
 
-1. Reads `GITEA_ORG` and `GITEA_REPO` from `.env`
+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 `/project-sync` to update."
+3. **Warns** if mismatch detected: "Repository location mismatch. Run `/pm-setup --sync` to update."
 
 This helps when you:
 - Move a repository to a different organization
@@ -505,9 +708,8 @@ If you get 401, regenerate your token in Gitea.
 # Check venv exists
 ls /path/to/mcp-servers/gitea/.venv
 
-# Reinstall if missing
+# If missing, create venv (do NOT delete existing venvs)
 cd /path/to/mcp-servers/gitea
-rm -rf .venv
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
@@ -520,7 +722,8 @@ deactivate
 # Check project .env
 cat .env
 
-# Verify GITEA_REPO matches the Gitea repository name exactly
+# Verify GITEA_REPO is in owner/repo format and matches Gitea exactly
+# Example: GITEA_REPO=my-org/my-repo
 ```
 
 ---
@@ -538,7 +741,7 @@ cat .env
 
 3. **Never type tokens into AI chat**
    - Always edit config files directly in your editor
-   - The `/initial-setup` wizard respects this
+   - The `/pm-setup` wizard respects this
 
 4. **Rotate tokens periodically**
    - Every 6-12 months

docs/DEBUGGING-CHECKLIST.md

@@ -2,7 +2,7 @@
 
 **Purpose:** Systematic approach to diagnose and fix plugin loading issues.
 
-Last Updated: 2026-01-22
+Last Updated: 2026-01-28
 
 ---
 
@@ -73,25 +73,19 @@ cd $RUNTIME && ./scripts/setup.sh
 
 ---
 
-## Step 4: Verify Symlink Resolution
+## Step 4: Verify MCP Configuration
 
-Plugins use symlinks to shared MCP servers. Verify they resolve correctly:
+Check `.mcp.json` at marketplace root is correctly configured:
 
 ```bash
 RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
 
-# Check symlinks exist and resolve
-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
+# Check .mcp.json exists and has valid content
+cat $RUNTIME/.mcp.json | jq '.mcpServers | keys'
 
-# Should resolve to:
-# $RUNTIME/mcp-servers/gitea
-# $RUNTIME/mcp-servers/netbox
+# Should list: gitea, netbox, data-platform, viz-platform, contract-validator
 ```
 
-**If broken:** Symlinks are relative. If directory structure differs, they'll break.
-
 ---
 
 ## Step 5: Test MCP Server Startup
@@ -128,7 +122,7 @@ cat ~/.config/claude/netbox.env
 
 # Project-level config (in target project)
 cat /path/to/project/.env
-# Should contain: GITEA_ORG, GITEA_REPO
+# Should contain: GITEA_REPO=owner/repo (e.g., my-org/my-repo)
 ```
 
 ---
@@ -165,10 +159,8 @@ 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=== Symlinks ==="
-[ -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=== MCP Configuration ==="
+[ -f "$RUNTIME/.mcp.json" ] && echo ".mcp.json: OK" || echo ".mcp.json: MISSING"
 
 echo -e "\n=== Config Files ==="
 [ -f ~/.config/claude/gitea.env ] && echo "gitea.env: OK" || echo "gitea.env: MISSING"
@@ -182,10 +174,51 @@ echo -e "\n=== Config Files ==="
 | Issue | Symptom | Fix |
 |-------|---------|-----|
 | Missing venvs | "X MCP servers failed" | `cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh` |
-| Broken symlinks | MCP tools not available | Reinstall marketplace or manually recreate symlinks |
+| Missing .mcp.json | MCP tools not available | Check `.mcp.json` exists at marketplace root |
 | 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) |
+| Gitea issues not closing | Merged to non-default branch | Manually close issues (see below) |
+| MCP changes not taking effect | Session caching | Restart Claude Code session (see below) |
+
+### Gitea Auto-Close Behavior
+
+**Issue:** Using `Closes #XX` or `Fixes #XX` in commit/PR messages does NOT auto-close issues when merging to `development`.
+
+**Root Cause:** Gitea only auto-closes issues when merging to the **default branch** (typically `main` or `master`). Merging to `development`, `staging`, or any other branch will NOT trigger auto-close.
+
+**Workaround:**
+1. Use the Gitea MCP tool to manually close issues after merging to development:
+   ```
+   mcp__plugin_projman_gitea__update_issue(issue_number=XX, state="closed")
+   ```
+2. Or close issues via the Gitea web UI
+3. The auto-close keywords will still work when the changes are eventually merged to `main`
+
+**Recommendation:** Include the `Closes #XX` keywords in commits anyway - they'll work when the final merge to `main` happens.
+
+### MCP Session Restart Requirement
+
+**Issue:** Changes to MCP servers, hooks, or plugin configuration don't take effect immediately.
+
+**Root Cause:** Claude Code loads MCP tools and plugin configuration at session start. These are cached in session memory and not reloaded dynamically.
+
+**What requires a session restart:**
+- MCP server code changes (Python files in `mcp-servers/`)
+- Changes to `.mcp.json` files
+- Changes to `hooks/hooks.json`
+- Changes to `plugin.json`
+- Adding new MCP tools or modifying tool signatures
+
+**What does NOT require a restart:**
+- Command/skill markdown files (`.md`) - these are read on invocation
+- Agent markdown files - read when agent is invoked
+
+**Correct workflow after plugin changes:**
+1. Make changes to source files
+2. Run `./scripts/verify-hooks.sh` to validate
+3. Inform user: "Please restart Claude Code for changes to take effect"
+4. **Do NOT clear cache mid-session** - see "Cache Clearing" section
 
 ---
 
@@ -246,8 +279,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-review` - Investigate existing diagnostic issues and propose fixes
+- `/pm-debug report` - Run full diagnostics, create issue if problems found
+- `/pm-debug review` - Investigate existing diagnostic issues and propose fixes
 
 ---
 

docs/UPDATING.md

@@ -46,9 +46,9 @@ cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh
 
 ## After Updating: Re-run Setup if Needed
 
-### When to Re-run `/initial-setup`
+### When to Re-run Setup
 
-You typically **don't need** to re-run setup after updates. However, re-run if:
+You typically **don't need** to re-run setup after updates. However, re-run your plugin's setup command (e.g., `/pm-setup`, `/pr-setup`, `/cmdb-setup`) if:
 
 - Changelog mentions **new required environment variables**
 - Changelog mentions **breaking changes** to configuration
@@ -97,7 +97,7 @@ When updating, review if changes affect the setup workflow:
 
 1. **Check for setup command changes:**
    ```bash
-   git diff HEAD~1 plugins/*/commands/initial-setup.md
+   git diff HEAD~1 plugins/*/commands/*-setup.md
    git diff HEAD~1 plugins/*/commands/project-init.md
    git diff HEAD~1 plugins/*/commands/project-sync.md
    ```
@@ -114,7 +114,7 @@ When updating, review if changes affect the setup workflow:
 
 **If setup commands changed:**
 - Review what's new (new validation steps, new prompts, etc.)
-- Consider re-running `/initial-setup` or `/project-init` to benefit from improvements
+- Consider re-running your plugin's setup command or `/project-init` to benefit from improvements
 - Existing configurations remain valid unless changelog notes breaking changes
 
 **If hooks changed:**
@@ -132,10 +132,8 @@ When updating, review if changes affect the setup workflow:
 ### Dependencies fail to install
 
 ```bash
-# Rebuild virtual environment
+# Install missing dependencies (do NOT delete .venv)
 cd mcp-servers/gitea
-rm -rf .venv
-python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
 deactivate
@@ -144,7 +142,7 @@ deactivate
 ### Configuration no longer works
 
 1. Check CHANGELOG.md for breaking changes
-2. Run `/initial-setup` to re-validate and fix configuration
+2. Run your plugin's setup command (e.g., `/pm-setup`) to re-validate and fix configuration
 3. Compare your config files with documentation in `docs/CONFIGURATION.md`
 
 ### MCP server won't start after update
@@ -164,7 +162,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, the symlinks won't resolve. Run setup.sh as shown above.
+3. If missing, run setup.sh as shown above.
 4. Restart Claude Code session
 5. Check logs for specific errors
 

mcp-servers/contract-validator/.doc-guardian-queue

@@ -0,0 +1,20 @@
+2026-01-26T14:36:42 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T14:37:38 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T14:37:48 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T14:38:05 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T14:38:55 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T14:39:35 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T14:40:19 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T15:02:30 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T15:02:37 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_parse_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T15:03:41 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_report_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-02T10:56:19 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/validation_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-02T10:57:49 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_validation_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-02T10:58:22 | skills | /home/lmiranda/claude-plugins-work/plugins/contract-validator/skills/mcp-tools-reference.md | README.md
+2026-02-02T10:58:38 | skills | /home/lmiranda/claude-plugins-work/plugins/contract-validator/skills/validation-rules.md | README.md
+2026-02-02T10:59:13 | .claude-plugin | /home/lmiranda/claude-plugins-work/.claude-plugin/marketplace.json | CLAUDE.md .claude-plugin/marketplace.json
+2026-02-02T13:55:33 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/visual-output.md | README.md
+2026-02-02T13:55:41 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/planner.md | README.md CLAUDE.md
+2026-02-02T13:55:55 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/orchestrator.md | README.md CLAUDE.md
+2026-02-02T13:56:14 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/executor.md | README.md CLAUDE.md
+2026-02-02T13:56:34 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/code-reviewer.md | README.md CLAUDE.md

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

@@ -131,6 +131,28 @@ 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. Also checks gate contract version compatibility.",
+                    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"
+                            },
+                            "expected_contract": {
+                                "type": "string",
+                                "description": "Expected contract version (e.g., 'v1'). If provided, validates the gate command's contract matches."
+                            }
+                        },
+                        "required": ["plugin_path", "domain_label"]
+                    }
+                ),
                 # Report tools (to be implemented in #188)
                 Tool(
                     name="generate_compatibility_report",
@@ -198,6 +220,8 @@ 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":
@@ -241,6 +265,17 @@ 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,
+        expected_contract: str = None
+    ) -> dict:
+        """Validate domain plugin exposes required advisory interfaces"""
+        return await self.validation_tools.validate_workflow_integration(
+            plugin_path, domain_label, expected_contract
+        )
+
     # 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,6 +26,7 @@ class IssueType(str, Enum):
     OPTIONAL_DEPENDENCY = "optional_dependency"
     UNDECLARED_OUTPUT = "undeclared_output"
     INVALID_SEQUENCE = "invalid_sequence"
+    MISSING_INTEGRATION = "missing_integration"
 
 
 class ValidationIssue(BaseModel):
@@ -65,6 +66,18 @@ 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
+    gate_contract: Optional[str] = None  # Contract version declared by gate command
+    review_command_found: bool
+    advisory_agent_found: bool
+    issues: list[ValidationIssue] = []
+
+
 class ValidationTools:
     """Tools for validating plugin compatibility and agent references"""
 
@@ -336,3 +349,145 @@ class ValidationTools:
         )
 
         return result.model_dump()
+
+    async def validate_workflow_integration(
+        self,
+        plugin_path: str,
+        domain_label: str,
+        expected_contract: Optional[str] = None
+    ) -> dict:
+        """
+        Validate that a domain plugin exposes required advisory interfaces.
+
+        Checks for:
+        - Gate command (e.g., /design-gate, /data-gate) - REQUIRED
+        - Gate contract version (gate_contract in frontmatter) - INFO if missing
+        - 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)
+            expected_contract: Expected contract version (e.g., 'v1'). If provided,
+                              validates the gate command's contract matches.
+
+        Returns:
+            Validation result with found interfaces and issues
+        """
+        import re
+
+        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_contract = None
+        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
+                        # Parse frontmatter for gate_contract
+                        frontmatter_match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+                        if frontmatter_match:
+                            frontmatter = frontmatter_match.group(1)
+                            contract_match = re.search(r'gate_contract:\s*(\S+)', frontmatter)
+                            if contract_match:
+                                gate_contract = contract_match.group(1)
+                        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}'"
+            ))
+
+        # Check gate contract version
+        if gate_command_found:
+            if not gate_contract:
+                issues.append(ValidationIssue(
+                    severity=IssueSeverity.INFO,
+                    issue_type=IssueType.MISSING_INTEGRATION,
+                    message=f"Gate command does not declare a contract version",
+                    location=str(commands_dir),
+                    suggestion="Consider adding `gate_contract: v1` to frontmatter for version tracking"
+                ))
+            elif expected_contract and gate_contract != expected_contract:
+                issues.append(ValidationIssue(
+                    severity=IssueSeverity.WARNING,
+                    issue_type=IssueType.INTERFACE_MISMATCH,
+                    message=f"Contract version mismatch: gate declares {gate_contract}, projman expects {expected_contract}",
+                    location=str(commands_dir),
+                    suggestion=f"Update domain-consultation.md Gate Command Reference table to {gate_contract}, or update gate command to {expected_contract}"
+                ))
+
+        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,
+            gate_contract=gate_contract,
+            review_command_found=review_command_found,
+            advisory_agent_found=advisory_agent_found,
+            issues=issues
+        )
+
+        return result.model_dump()

mcp-servers/contract-validator/run.sh

@@ -1,4 +1,8 @@
 #!/bin/bash
+# Capture original working directory before any cd operations
+# This should be the user's project directory when launched by Claude Code
+export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/contract-validator/.venv"
 LOCAL_VENV="$SCRIPT_DIR/.venv"

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

@@ -254,3 +254,261 @@ 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
+    # May have INFO issue about missing contract version (not an error/warning)
+    error_or_warning = [i for i in result["issues"]
+                        if i["severity"].value in ("error", "warning")]
+    assert len(error_or_warning) == 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()
+
+
+# --- Gate Contract Version Tests ---
+
+@pytest.fixture
+def domain_plugin_with_contract(tmp_path):
+    """Create domain plugin with gate_contract: v1 in frontmatter"""
+    plugin_dir = tmp_path / "viz-platform-versioned"
+    plugin_dir.mkdir()
+    (plugin_dir / ".claude-plugin").mkdir()
+    (plugin_dir / "commands").mkdir()
+    (plugin_dir / "agents").mkdir()
+
+    # Gate command with gate_contract in frontmatter
+    gate_cmd = plugin_dir / "commands" / "design-gate.md"
+    gate_cmd.write_text("""---
+description: Design system compliance gate (pass/fail)
+gate_contract: v1
+---
+
+# /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 for Domain/Viz issues.
+""")
+
+    return str(plugin_dir)
+
+
+@pytest.mark.asyncio
+async def test_validate_workflow_contract_match(validation_tools, domain_plugin_with_contract):
+    """Test that matching expected_contract produces no warning"""
+    result = await validation_tools.validate_workflow_integration(
+        domain_plugin_with_contract,
+        "Domain/Viz",
+        expected_contract="v1"
+    )
+
+    assert "error" not in result
+    assert result["valid"] is True
+    assert result["gate_contract"] == "v1"
+
+    # Should have no warnings about contract mismatch
+    warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
+    contract_warnings = [i for i in warning_issues if "contract" in i["message"].lower()]
+    assert len(contract_warnings) == 0
+
+
+@pytest.mark.asyncio
+async def test_validate_workflow_contract_mismatch(validation_tools, domain_plugin_with_contract):
+    """Test that mismatched expected_contract produces WARNING"""
+    result = await validation_tools.validate_workflow_integration(
+        domain_plugin_with_contract,
+        "Domain/Viz",
+        expected_contract="v2"  # Gate has v1
+    )
+
+    assert "error" not in result
+    assert result["valid"] is True  # Contract mismatch doesn't affect validity
+    assert result["gate_contract"] == "v1"
+
+    # Should have warning about contract mismatch
+    warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
+    contract_warnings = [i for i in warning_issues if "contract" in i["message"].lower()]
+    assert len(contract_warnings) == 1
+    assert "mismatch" in contract_warnings[0]["message"].lower()
+    assert "v1" in contract_warnings[0]["message"]
+    assert "v2" in contract_warnings[0]["message"]
+
+
+@pytest.mark.asyncio
+async def test_validate_workflow_no_contract(validation_tools, domain_plugin_complete):
+    """Test that missing gate_contract produces INFO suggestion"""
+    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_contract"] is None
+
+    # Should have info issue about missing contract
+    info_issues = [i for i in result["issues"] if i["severity"].value == "info"]
+    contract_info = [i for i in info_issues if "contract" in i["message"].lower()]
+    assert len(contract_info) == 1
+    assert "does not declare" in contract_info[0]["message"].lower()

mcp-servers/data-platform/run.sh

@@ -1,4 +1,8 @@
 #!/bin/bash
+# Capture original working directory before any cd operations
+# This should be the user's project directory when launched by Claude Code
+export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/data-platform/.venv"
 LOCAL_VENV="$SCRIPT_DIR/.venv"

mcp-servers/gitea/.doc-guardian-queue

@@ -0,0 +1,6 @@
+2026-02-03T14:09:25 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/gitea/tests/test_config.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-03T14:09:33 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/gitea/tests/test_gitea_client.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-03T14:10:22 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/gitea/tests/test_issues.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-03T14:17:12 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/gitea/README.md | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-03T14:18:27 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/gitea/CHANGELOG.md | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-02-03T14:18:41 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/gitea/TESTING.md | docs/COMMANDS-CHEATSHEET.md CLAUDE.md

mcp-servers/gitea/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to the Gitea MCP Server will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.3.0] - 2026-02-03
+
+### Added
+- Pull request tools (7 tools):
+  - `list_pull_requests` - List PRs from repository
+  - `get_pull_request` - Get specific PR details
+  - `get_pr_diff` - Get PR diff content
+  - `get_pr_comments` - Get comments on a PR
+  - `create_pr_review` - Create PR review (approve/request changes/comment)
+  - `add_pr_comment` - Add comment to PR
+  - `create_pull_request` - Create new pull request
+- Label creation tools (3 tools):
+  - `create_label` - Create repo-level label
+  - `create_org_label` - Create organization-level label
+  - `create_label_smart` - Auto-detect org vs repo for label creation
+- Validation tools (2 tools):
+  - `validate_repo_org` - Check if repo belongs to organization
+  - `get_branch_protection` - Get branch protection rules
+
+### Changed
+- Total tools increased from 20 to 36
+- Updated test suite to 64 tests (was 42)
+
+### Fixed
+- Test fixtures updated to use `owner/repo` format
+- Fixed aggregate_issues tests to pass required `org` argument
+
+## [1.2.0] - 2026-01-28
+
+### Added
+- Milestone management tools (5 tools):
+  - `list_milestones` - List all milestones
+  - `get_milestone` - Get specific milestone
+  - `create_milestone` - Create new milestone
+  - `update_milestone` - Update existing milestone
+  - `delete_milestone` - Delete a milestone
+- Issue dependency tools (4 tools):
+  - `list_issue_dependencies` - List blocking issues
+  - `create_issue_dependency` - Create dependency between issues
+  - `remove_issue_dependency` - Remove dependency
+  - `get_execution_order` - Calculate parallelizable execution order
+
+## [1.1.0] - 2026-01-21
+
+### Added
+- Wiki and lessons learned tools (7 tools):
+  - `list_wiki_pages` - List all wiki pages
+  - `get_wiki_page` - Get specific wiki page content
+  - `create_wiki_page` - Create new wiki page
+  - `update_wiki_page` - Update existing wiki page
+  - `create_lesson` - Create lessons learned entry
+  - `search_lessons` - Search lessons by query/tags
+  - `allocate_rfc_number` - Get next available RFC number
+- Automatic git remote URL detection for repository configuration
+- Support for SSH, HTTPS, and HTTP git URL formats
+
+### Changed
+- Configuration now uses `owner/repo` format exclusively
+- Removed separate `GITEA_OWNER` configuration (now derived from repo path)
+
+## [1.0.0] - 2025-01-06
+
+### Added
+- Initial release with 8 core tools:
+  - `list_issues` - List issues from repository
+  - `get_issue` - Get specific issue details
+  - `create_issue` - Create new issue with labels
+  - `update_issue` - Update existing issue
+  - `add_comment` - Add comment to issue
+  - `get_labels` - Get all labels (org + repo)
+  - `suggest_labels` - Intelligent label suggestion
+  - `aggregate_issues` - Cross-repository issue aggregation (PMO mode)
+- Hybrid configuration system (system + project level)
+- Branch-aware security model
+- Mode detection (project vs company/PMO)
+- 42 unit tests with mocks
+- Comprehensive documentation
+
+[Unreleased]: https://github.com/owner/repo/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/owner/repo/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/owner/repo/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/owner/repo/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/owner/repo/releases/tag/v1.0.0

mcp-servers/gitea/README.md

@@ -19,8 +19,9 @@ The Gitea MCP Server provides Claude Code with direct access to Gitea for issue
 - **Hybrid Configuration**: System-level credentials + project-level paths
 - **PMO Support**: Multi-repository aggregation for organization-wide views
 
-### Tools Provided
+### Tools Provided (36 total)
 
+#### Issue Management (6 tools)
 | Tool | Description | Mode |
 |------|-------------|------|
 | `list_issues` | List issues from repository | Both |
@@ -28,9 +29,61 @@ The Gitea MCP Server provides Claude Code with direct access to Gitea for issue
 | `create_issue` | Create new issue with labels | Both |
 | `update_issue` | Update existing issue | Both |
 | `add_comment` | Add comment to issue | Both |
+| `aggregate_issues` | Cross-repository issue aggregation | PMO Only |
+
+#### Label Management (5 tools)
+| Tool | Description | Mode |
+|------|-------------|------|
 | `get_labels` | Get all labels (org + repo) | Both |
 | `suggest_labels` | Intelligent label suggestion | Both |
-| `aggregate_issues` | Cross-repository issue aggregation | PMO Only |
+| `create_label` | Create repo-level label | Both |
+| `create_org_label` | Create organization-level label | Both |
+| `create_label_smart` | Auto-detect org vs repo for label creation | Both |
+
+#### Wiki & Lessons Learned (7 tools)
+| Tool | Description | Mode |
+|------|-------------|------|
+| `list_wiki_pages` | List all wiki pages | Both |
+| `get_wiki_page` | Get specific wiki page content | Both |
+| `create_wiki_page` | Create new wiki page | Both |
+| `update_wiki_page` | Update existing wiki page | Both |
+| `create_lesson` | Create lessons learned entry | Both |
+| `search_lessons` | Search lessons by query/tags | Both |
+| `allocate_rfc_number` | Get next available RFC number | Both |
+
+#### Milestone Management (5 tools)
+| Tool | Description | Mode |
+|------|-------------|------|
+| `list_milestones` | List all milestones | Both |
+| `get_milestone` | Get specific milestone | Both |
+| `create_milestone` | Create new milestone | Both |
+| `update_milestone` | Update existing milestone | Both |
+| `delete_milestone` | Delete a milestone | Both |
+
+#### Issue Dependencies (4 tools)
+| Tool | Description | Mode |
+|------|-------------|------|
+| `list_issue_dependencies` | List blocking issues | Both |
+| `create_issue_dependency` | Create dependency between issues | Both |
+| `remove_issue_dependency` | Remove dependency | Both |
+| `get_execution_order` | Calculate parallelizable execution order | Both |
+
+#### Pull Request Tools (7 tools)
+| Tool | Description | Mode |
+|------|-------------|------|
+| `list_pull_requests` | List PRs from repository | Both |
+| `get_pull_request` | Get specific PR details | Both |
+| `get_pr_diff` | Get PR diff content | Both |
+| `get_pr_comments` | Get comments on a PR | Both |
+| `create_pr_review` | Create PR review (approve/request changes) | Both |
+| `add_pr_comment` | Add comment to PR | Both |
+| `create_pull_request` | Create new pull request | Both |
+
+#### Validation Tools (2 tools)
+| Tool | Description | Mode |
+|------|-------------|------|
+| `validate_repo_org` | Check if repo belongs to organization | Both |
+| `get_branch_protection` | Get branch protection rules | Both |
 
 ## Architecture
 
@@ -40,15 +93,20 @@ The Gitea MCP Server provides Claude Code with direct access to Gitea for issue
 mcp-servers/gitea/
 ├── .venv/                      # Python virtual environment
 ├── requirements.txt            # Python dependencies
+├── run.sh                      # Entry point script
 ├── mcp_server/
 │   ├── __init__.py
-│   ├── server.py              # MCP server entry point
-│   ├── config.py              # Configuration loader
+│   ├── server.py              # MCP server entry point (36 tools)
+│   ├── config.py              # Configuration loader with auto-detection
 │   ├── gitea_client.py        # Gitea API client
 │   └── tools/
 │       ├── __init__.py
-│       ├── issues.py          # Issue tools
-│       └── labels.py          # Label tools
+│       ├── issues.py          # Issue management tools
+│       ├── labels.py          # Label management tools
+│       ├── wiki.py            # Wiki & lessons learned tools
+│       ├── milestones.py      # Milestone management tools
+│       ├── dependencies.py    # Issue dependency tools
+│       └── pull_requests.py   # Pull request tools
 ├── tests/
 │   ├── __init__.py
 │   ├── test_config.py
@@ -56,7 +114,8 @@ mcp-servers/gitea/
 │   ├── test_issues.py
 │   └── test_labels.py
 ├── README.md                   # This file
-└── TESTING.md                  # Testing instructions
+├── TESTING.md                  # Testing instructions
+└── CHANGELOG.md                # Version history
 ```
 
 ### Mode Detection
@@ -111,7 +170,6 @@ mkdir -p ~/.config/claude
 cat > ~/.config/claude/gitea.env << EOF
 GITEA_API_URL=https://gitea.example.com/api/v1
 GITEA_API_TOKEN=your_gitea_token_here
-GITEA_OWNER=bandit
 EOF
 
 chmod 600 ~/.config/claude/gitea.env
@@ -137,14 +195,34 @@ For company/PMO mode, omit the `.env` file or don't set `GITEA_REPO`.
 **Required Variables**:
 - `GITEA_API_URL` - Gitea API endpoint (e.g., `https://gitea.example.com/api/v1`)
 - `GITEA_API_TOKEN` - Personal access token with repo permissions
-- `GITEA_OWNER` - Organization or user name (e.g., `bandit`)
 
 ### Project-Level Configuration
 
 **File**: `<project-root>/.env`
 
 **Optional Variables**:
-- `GITEA_REPO` - Repository name (enables project mode)
+- `GITEA_REPO` - Repository in `owner/repo` format (enables project mode)
+
+### Automatic Repository Detection
+
+If `GITEA_REPO` is not set, the server auto-detects the repository from your git remote:
+
+**Supported URL Formats**:
+- SSH: `ssh://git@gitea.example.com:22/owner/repo.git`
+- SSH short: `git@gitea.example.com:owner/repo.git`
+- HTTPS: `https://gitea.example.com/owner/repo.git`
+- HTTP: `http://gitea.example.com/owner/repo.git`
+
+The repository is extracted as `owner/repo` format automatically.
+
+### Project Directory Detection
+
+The server finds your project directory using these strategies (in order):
+
+1. `CLAUDE_PROJECT_DIR` environment variable (highest priority)
+2. `PWD` environment variable (if `.git` or `.env` present)
+3. Current working directory (if `.git` or `.env` present)
+4. Falls back to company/PMO mode if no project found
 
 ### Generating Gitea API Token
 
@@ -220,13 +298,13 @@ suggestions = await label_tools.suggest_labels(context)
 
 ### Unit Tests
 
-Run all 42 unit tests with mocks:
+Run all 64 unit tests with mocks:
 
 ```bash
 pytest tests/ -v
 ```
 
-Expected: `42 passed in 0.57s`
+Expected: `64 passed`
 
 ### Integration Tests
 
@@ -327,11 +405,15 @@ See [TESTING.md](./TESTING.md#troubleshooting) for more details.
 
 ### Project Structure
 
-- `config.py` - Hybrid configuration loader with mode detection
+- `config.py` - Hybrid configuration loader with auto-detection
 - `gitea_client.py` - Synchronous Gitea API client using requests
-- `tools/issues.py` - Async wrappers with branch detection
-- `tools/labels.py` - Label management and suggestion
-- `server.py` - MCP server with JSON-RPC 2.0 over stdio
+- `tools/issues.py` - Issue management with branch detection
+- `tools/labels.py` - Label management and intelligent suggestions
+- `tools/wiki.py` - Wiki pages and lessons learned
+- `tools/milestones.py` - Milestone CRUD operations
+- `tools/dependencies.py` - Issue dependency tracking
+- `tools/pull_requests.py` - PR review and management
+- `server.py` - MCP server with 36 tools over JSON-RPC 2.0 stdio
 
 ### Adding New Tools
 
@@ -374,18 +456,14 @@ def list_issues(self, state='open', labels=None, repo=None):
 
 ## Changelog
 
-### v1.0.0 (2025-01-06) - Phase 1 Complete
+See [CHANGELOG.md](./CHANGELOG.md) for full version history.
 
-✅ Initial implementation:
-- Configuration management (hybrid system + project)
-- Gitea API client with all CRUD operations
-- MCP server with 8 tools
-- Issue tools with branch detection
-- Label tools with intelligent suggestions
-- Mode detection (project vs company)
-- Branch-aware security model
-- 42 unit tests (100% passing)
-- Comprehensive documentation
+### Recent Updates
+
+- **v1.3.0** - Pull request tools (7 tools), label creation tools (3)
+- **v1.2.0** - Milestone management (5 tools), issue dependencies (4 tools)
+- **v1.1.0** - Wiki & lessons learned system (7 tools)
+- **v1.0.0** - Initial release with core issue/label tools (8 tools)
 
 ## License
 
@@ -407,6 +485,6 @@ For issues or questions:
 ---
 
 **Built for**: Leo Claude Marketplace - Project Management Plugins
-**Phase**: 1 (Complete)
+**Tools**: 36
 **Status**: ✅ Production Ready
-**Last Updated**: 2025-01-06
+**Last Updated**: 2026-02-03

mcp-servers/gitea/TESTING.md

@@ -28,7 +28,7 @@ source .venv/bin/activate  # Linux/Mac
 
 ### Running All Tests
 
-Run all 42 unit tests:
+Run all 64 unit tests:
 
 ```bash
 pytest tests/ -v
@@ -36,7 +36,7 @@ pytest tests/ -v
 
 Expected output:
 ```
-============================== 42 passed in 0.57s ==============================
+============================== 64 passed ==============================
 ```
 
 ### Running Specific Test Files
@@ -532,7 +532,7 @@ python -m mcp_server.server
 
 After completing all tests, verify:
 
-- ✅ All 42 unit tests pass
+- ✅ All 64 unit tests pass
 - ✅ MCP server starts without errors
 - ✅ Configuration loads correctly
 - ✅ Gitea API client connects successfully
@@ -548,7 +548,7 @@ After completing all tests, verify:
 
 Phase 1 is complete when:
 
-1. **All unit tests pass** (42/42)
+1. **All unit tests pass** (64/64)
 2. **MCP server starts without errors**
 3. **Can list issues from Gitea**
 4. **Can create issues with labels** (in development mode)

mcp-servers/gitea/mcp_server/__init__.py

@@ -0,0 +1,30 @@
+"""
+Gitea MCP Server package.
+
+Provides MCP tools for Gitea integration via JSON-RPC 2.0.
+
+For external consumers (e.g., HTTP transport), use:
+    from mcp_server import get_tool_definitions, create_tool_dispatcher, GiteaClient
+
+    # Get tool schemas
+    tools = get_tool_definitions()
+
+    # Create dispatcher bound to a client
+    client = GiteaClient()
+    dispatch = create_tool_dispatcher(client)
+    result = await dispatch("list_issues", {"state": "open"})
+"""
+
+__version__ = "1.0.0"
+
+from .tool_registry import get_tool_definitions, create_tool_dispatcher
+from .gitea_client import GiteaClient
+from .config import GiteaConfig
+
+__all__ = [
+    "__version__",
+    "get_tool_definitions",
+    "create_tool_dispatcher",
+    "GiteaClient",
+    "GiteaConfig",
+]

mcp-servers/gitea/mcp_server/gitea_client.py

@@ -53,6 +53,7 @@ class GiteaClient:
         self,
         state: str = 'open',
         labels: Optional[List[str]] = None,
+        milestone: Optional[str] = None,
         repo: Optional[str] = None
     ) -> List[Dict]:
         """
@@ -61,6 +62,7 @@ class GiteaClient:
         Args:
             state: Issue state (open, closed, all)
             labels: Filter by labels
+            milestone: Filter by milestone title (exact match)
             repo: Repository in 'owner/repo' format
 
         Returns:
@@ -71,6 +73,8 @@ class GiteaClient:
         params = {'state': state}
         if labels:
             params['labels'] = ','.join(labels)
+        if milestone:
+            params['milestones'] = milestone
         logger.info(f"Listing issues from {owner}/{target_repo} with state={state}")
         response = self.session.get(url, params=params)
         response.raise_for_status()
@@ -135,9 +139,24 @@ class GiteaClient:
         body: Optional[str] = None,
         state: Optional[str] = None,
         labels: Optional[List[str]] = None,
+        milestone: Optional[int] = None,
         repo: Optional[str] = None
     ) -> Dict:
-        """Update existing issue. Repo must be 'owner/repo' format."""
+        """
+        Update existing issue.
+
+        Args:
+            issue_number: Issue number to update
+            title: New title (optional)
+            body: New body (optional)
+            state: New state - 'open' or 'closed' (optional)
+            labels: New labels (optional)
+            milestone: Milestone ID to assign (optional)
+            repo: Repository in 'owner/repo' format
+
+        Returns:
+            Updated issue dictionary
+        """
         owner, target_repo = self._parse_repo(repo)
         url = f"{self.base_url}/repos/{owner}/{target_repo}/issues/{issue_number}"
         data = {}
@@ -149,6 +168,8 @@ class GiteaClient:
             data['state'] = state
         if labels is not None:
             data['labels'] = labels
+        if milestone is not None:
+            data['milestone'] = milestone
         logger.info(f"Updating issue #{issue_number} in {owner}/{target_repo}")
         response = self.session.patch(url, json=data)
         response.raise_for_status()

mcp-servers/gitea/mcp_server/server.py

@@ -5,19 +5,13 @@ Provides Gitea tools to Claude Code via JSON-RPC 2.0 over stdio.
 """
 import asyncio
 import logging
-import json
 from mcp.server import Server
 from mcp.server.stdio import stdio_server
 from mcp.types import Tool, TextContent
 
 from .config import GiteaConfig
 from .gitea_client import GiteaClient
-from .tools.issues import IssueTools
-from .tools.labels import LabelTools
-from .tools.wiki import WikiTools
-from .tools.milestones import MilestoneTools
-from .tools.dependencies import DependencyTools
-from .tools.pull_requests import PullRequestTools
+from .tool_registry import get_tool_definitions, create_tool_dispatcher
 
 # Suppress noisy MCP validation warnings on stderr
 logging.basicConfig(level=logging.INFO)
@@ -33,12 +27,7 @@ class GiteaMCPServer:
         self.server = Server("gitea-mcp")
         self.config = None
         self.client = None
-        self.issue_tools = None
-        self.label_tools = None
-        self.wiki_tools = None
-        self.milestone_tools = None
-        self.dependency_tools = None
-        self.pr_tools = None
+        self._dispatcher = None
 
     async def initialize(self):
         """
@@ -52,12 +41,7 @@ class GiteaMCPServer:
             self.config = config_loader.load()
 
             self.client = GiteaClient()
-            self.issue_tools = IssueTools(self.client)
-            self.label_tools = LabelTools(self.client)
-            self.wiki_tools = WikiTools(self.client)
-            self.milestone_tools = MilestoneTools(self.client)
-            self.dependency_tools = DependencyTools(self.client)
-            self.pr_tools = PullRequestTools(self.client)
+            self._dispatcher = create_tool_dispatcher(self.client)
 
             logger.info(f"Gitea MCP Server initialized in {self.config['mode']} mode")
         except Exception as e:
@@ -70,817 +54,7 @@ class GiteaMCPServer:
         @self.server.list_tools()
         async def list_tools() -> list[Tool]:
             """Return list of available tools"""
-            return [
-                Tool(
-                    name="list_issues",
-                    description="List issues from Gitea repository",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "state": {
-                                "type": "string",
-                                "enum": ["open", "closed", "all"],
-                                "default": "open",
-                                "description": "Issue state filter"
-                            },
-                            "labels": {
-                                "type": "array",
-                                "items": {"type": "string"},
-                                "description": "Filter by labels"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (for PMO mode)"
-                            }
-                        }
-                    }
-                ),
-                Tool(
-                    name="get_issue",
-                    description="Get specific issue details",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "issue_number": {
-                                "type": "integer",
-                                "description": "Issue number"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (for PMO mode)"
-                            }
-                        },
-                        "required": ["issue_number"]
-                    }
-                ),
-                Tool(
-                    name="create_issue",
-                    description="Create a new issue in Gitea",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "title": {
-                                "type": "string",
-                                "description": "Issue title"
-                            },
-                            "body": {
-                                "type": "string",
-                                "description": "Issue description"
-                            },
-                            "labels": {
-                                "type": "array",
-                                "items": {"type": "string"},
-                                "description": "List of label names"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (for PMO mode)"
-                            }
-                        },
-                        "required": ["title", "body"]
-                    }
-                ),
-                Tool(
-                    name="update_issue",
-                    description="Update existing issue",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "issue_number": {
-                                "type": "integer",
-                                "description": "Issue number"
-                            },
-                            "title": {
-                                "type": "string",
-                                "description": "New title"
-                            },
-                            "body": {
-                                "type": "string",
-                                "description": "New body"
-                            },
-                            "state": {
-                                "type": "string",
-                                "enum": ["open", "closed"],
-                                "description": "New state"
-                            },
-                            "labels": {
-                                "type": "array",
-                                "items": {"type": "string"},
-                                "description": "New labels"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (for PMO mode)"
-                            }
-                        },
-                        "required": ["issue_number"]
-                    }
-                ),
-                Tool(
-                    name="add_comment",
-                    description="Add comment to issue",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "issue_number": {
-                                "type": "integer",
-                                "description": "Issue number"
-                            },
-                            "comment": {
-                                "type": "string",
-                                "description": "Comment text"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (for PMO mode)"
-                            }
-                        },
-                        "required": ["issue_number", "comment"]
-                    }
-                ),
-                Tool(
-                    name="get_labels",
-                    description="Get all available labels (org + repo)",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (for PMO mode)"
-                            }
-                        }
-                    }
-                ),
-                Tool(
-                    name="suggest_labels",
-                    description="Analyze context and suggest appropriate labels",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "context": {
-                                "type": "string",
-                                "description": "Issue title + description or sprint context"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["context"]
-                    }
-                ),
-                Tool(
-                    name="aggregate_issues",
-                    description="Fetch issues across all repositories (PMO mode)",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "org": {
-                                "type": "string",
-                                "description": "Organization name (e.g. 'bandit')"
-                            },
-                            "state": {
-                                "type": "string",
-                                "enum": ["open", "closed", "all"],
-                                "default": "open",
-                                "description": "Issue state filter"
-                            },
-                            "labels": {
-                                "type": "array",
-                                "items": {"type": "string"},
-                                "description": "Filter by labels"
-                            }
-                        },
-                        "required": ["org"]
-                    }
-                ),
-                # Wiki Tools (Lessons Learned)
-                Tool(
-                    name="list_wiki_pages",
-                    description="List all wiki pages in repository",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        }
-                    }
-                ),
-                Tool(
-                    name="get_wiki_page",
-                    description="Get a specific wiki page by name",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "page_name": {
-                                "type": "string",
-                                "description": "Wiki page name/path"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["page_name"]
-                    }
-                ),
-                Tool(
-                    name="create_wiki_page",
-                    description="Create a new wiki page",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "title": {
-                                "type": "string",
-                                "description": "Page title/name"
-                            },
-                            "content": {
-                                "type": "string",
-                                "description": "Page content (markdown)"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["title", "content"]
-                    }
-                ),
-                Tool(
-                    name="update_wiki_page",
-                    description="Update an existing wiki page",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "page_name": {
-                                "type": "string",
-                                "description": "Wiki page name/path"
-                            },
-                            "content": {
-                                "type": "string",
-                                "description": "New page content (markdown)"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["page_name", "content"]
-                    }
-                ),
-                Tool(
-                    name="create_lesson",
-                    description="Create a lessons learned entry in the wiki",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "title": {
-                                "type": "string",
-                                "description": "Lesson title (e.g., 'Sprint 16 - Prevent Infinite Loops')"
-                            },
-                            "content": {
-                                "type": "string",
-                                "description": "Lesson content (markdown with context, problem, solution, prevention)"
-                            },
-                            "tags": {
-                                "type": "array",
-                                "items": {"type": "string"},
-                                "description": "Tags for categorization"
-                            },
-                            "category": {
-                                "type": "string",
-                                "default": "sprints",
-                                "description": "Category (sprints, patterns, architecture, etc.)"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["title", "content", "tags"]
-                    }
-                ),
-                Tool(
-                    name="search_lessons",
-                    description="Search lessons learned from previous sprints",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "query": {
-                                "type": "string",
-                                "description": "Search query (optional)"
-                            },
-                            "tags": {
-                                "type": "array",
-                                "items": {"type": "string"},
-                                "description": "Tags to filter by (optional)"
-                            },
-                            "limit": {
-                                "type": "integer",
-                                "default": 20,
-                                "description": "Maximum results"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        }
-                    }
-                ),
-                # Milestone Tools
-                Tool(
-                    name="list_milestones",
-                    description="List all milestones in repository",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "state": {
-                                "type": "string",
-                                "enum": ["open", "closed", "all"],
-                                "default": "open",
-                                "description": "Milestone state filter"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        }
-                    }
-                ),
-                Tool(
-                    name="get_milestone",
-                    description="Get a specific milestone by ID",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "milestone_id": {
-                                "type": "integer",
-                                "description": "Milestone ID"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["milestone_id"]
-                    }
-                ),
-                Tool(
-                    name="create_milestone",
-                    description="Create a new milestone",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "title": {
-                                "type": "string",
-                                "description": "Milestone title"
-                            },
-                            "description": {
-                                "type": "string",
-                                "description": "Milestone description"
-                            },
-                            "due_on": {
-                                "type": "string",
-                                "description": "Due date (ISO 8601 format)"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["title"]
-                    }
-                ),
-                Tool(
-                    name="update_milestone",
-                    description="Update an existing milestone",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "milestone_id": {
-                                "type": "integer",
-                                "description": "Milestone ID"
-                            },
-                            "title": {
-                                "type": "string",
-                                "description": "New title"
-                            },
-                            "description": {
-                                "type": "string",
-                                "description": "New description"
-                            },
-                            "state": {
-                                "type": "string",
-                                "enum": ["open", "closed"],
-                                "description": "New state"
-                            },
-                            "due_on": {
-                                "type": "string",
-                                "description": "New due date"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["milestone_id"]
-                    }
-                ),
-                Tool(
-                    name="delete_milestone",
-                    description="Delete a milestone",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "milestone_id": {
-                                "type": "integer",
-                                "description": "Milestone ID"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["milestone_id"]
-                    }
-                ),
-                # Dependency Tools
-                Tool(
-                    name="list_issue_dependencies",
-                    description="List all dependencies for an issue (issues that block this one)",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "issue_number": {
-                                "type": "integer",
-                                "description": "Issue number"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["issue_number"]
-                    }
-                ),
-                Tool(
-                    name="create_issue_dependency",
-                    description="Create a dependency (issue depends on another issue)",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "issue_number": {
-                                "type": "integer",
-                                "description": "Issue that will depend on another"
-                            },
-                            "depends_on": {
-                                "type": "integer",
-                                "description": "Issue that blocks issue_number"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["issue_number", "depends_on"]
-                    }
-                ),
-                Tool(
-                    name="remove_issue_dependency",
-                    description="Remove a dependency between issues",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "issue_number": {
-                                "type": "integer",
-                                "description": "Issue that depends on another"
-                            },
-                            "depends_on": {
-                                "type": "integer",
-                                "description": "Issue being depended on"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["issue_number", "depends_on"]
-                    }
-                ),
-                Tool(
-                    name="get_execution_order",
-                    description="Get parallelizable execution order for issues based on dependencies",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "issue_numbers": {
-                                "type": "array",
-                                "items": {"type": "integer"},
-                                "description": "List of issue numbers to analyze"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["issue_numbers"]
-                    }
-                ),
-                # Validation Tools
-                Tool(
-                    name="validate_repo_org",
-                    description="Check if repository belongs to an organization",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        }
-                    }
-                ),
-                Tool(
-                    name="get_branch_protection",
-                    description="Get branch protection rules",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "branch": {
-                                "type": "string",
-                                "description": "Branch name"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["branch"]
-                    }
-                ),
-                Tool(
-                    name="create_label",
-                    description="Create a new label in the repository (for repo-specific labels like Component/*, Tech/*)",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "name": {
-                                "type": "string",
-                                "description": "Label name (e.g., 'Component/Backend', 'Tech/Python')"
-                            },
-                            "color": {
-                                "type": "string",
-                                "description": "Label color (hex code)"
-                            },
-                            "description": {
-                                "type": "string",
-                                "description": "Label description"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["name", "color"]
-                    }
-                ),
-                Tool(
-                    name="create_org_label",
-                    description="Create a new label at organization level (for workflow labels like Type/*, Priority/*, Complexity/*, Effort/*)",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "org": {
-                                "type": "string",
-                                "description": "Organization name"
-                            },
-                            "name": {
-                                "type": "string",
-                                "description": "Label name (e.g., 'Type/Bug', 'Priority/High')"
-                            },
-                            "color": {
-                                "type": "string",
-                                "description": "Label color (hex code)"
-                            },
-                            "description": {
-                                "type": "string",
-                                "description": "Label description"
-                            }
-                        },
-                        "required": ["org", "name", "color"]
-                    }
-                ),
-                Tool(
-                    name="create_label_smart",
-                    description="Create a label at the appropriate level (org or repo) based on category. Org: Type/*, Priority/*, Complexity/*, Effort/*, Risk/*, Source/*, Agent/*. Repo: Component/*, Tech/*",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "name": {
-                                "type": "string",
-                                "description": "Label name (e.g., 'Type/Bug', 'Component/Backend')"
-                            },
-                            "color": {
-                                "type": "string",
-                                "description": "Label color (hex code)"
-                            },
-                            "description": {
-                                "type": "string",
-                                "description": "Label description"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["name", "color"]
-                    }
-                ),
-                # Pull Request Tools
-                Tool(
-                    name="list_pull_requests",
-                    description="List pull requests from repository",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "state": {
-                                "type": "string",
-                                "enum": ["open", "closed", "all"],
-                                "default": "open",
-                                "description": "PR state filter"
-                            },
-                            "sort": {
-                                "type": "string",
-                                "enum": ["oldest", "recentupdate", "leastupdate", "mostcomment", "leastcomment", "priority"],
-                                "default": "recentupdate",
-                                "description": "Sort order"
-                            },
-                            "labels": {
-                                "type": "array",
-                                "items": {"type": "string"},
-                                "description": "Filter by labels"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        }
-                    }
-                ),
-                Tool(
-                    name="get_pull_request",
-                    description="Get specific pull request details",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "pr_number": {
-                                "type": "integer",
-                                "description": "Pull request number"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["pr_number"]
-                    }
-                ),
-                Tool(
-                    name="get_pr_diff",
-                    description="Get the diff for a pull request",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "pr_number": {
-                                "type": "integer",
-                                "description": "Pull request number"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["pr_number"]
-                    }
-                ),
-                Tool(
-                    name="get_pr_comments",
-                    description="Get comments on a pull request",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "pr_number": {
-                                "type": "integer",
-                                "description": "Pull request number"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["pr_number"]
-                    }
-                ),
-                Tool(
-                    name="create_pr_review",
-                    description="Create a review on a pull request (approve, request changes, or comment)",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "pr_number": {
-                                "type": "integer",
-                                "description": "Pull request number"
-                            },
-                            "body": {
-                                "type": "string",
-                                "description": "Review body/summary"
-                            },
-                            "event": {
-                                "type": "string",
-                                "enum": ["APPROVE", "REQUEST_CHANGES", "COMMENT"],
-                                "default": "COMMENT",
-                                "description": "Review action"
-                            },
-                            "comments": {
-                                "type": "array",
-                                "items": {
-                                    "type": "object",
-                                    "properties": {
-                                        "path": {"type": "string"},
-                                        "position": {"type": "integer"},
-                                        "body": {"type": "string"}
-                                    }
-                                },
-                                "description": "Optional inline comments"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["pr_number", "body"]
-                    }
-                ),
-                Tool(
-                    name="add_pr_comment",
-                    description="Add a general comment to a pull request",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "pr_number": {
-                                "type": "integer",
-                                "description": "Pull request number"
-                            },
-                            "body": {
-                                "type": "string",
-                                "description": "Comment text"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["pr_number", "body"]
-                    }
-                ),
-                Tool(
-                    name="create_pull_request",
-                    description="Create a new pull request",
-                    inputSchema={
-                        "type": "object",
-                        "properties": {
-                            "title": {
-                                "type": "string",
-                                "description": "PR title"
-                            },
-                            "body": {
-                                "type": "string",
-                                "description": "PR description/body"
-                            },
-                            "head": {
-                                "type": "string",
-                                "description": "Source branch name (the branch with changes)"
-                            },
-                            "base": {
-                                "type": "string",
-                                "description": "Target branch name (the branch to merge into)"
-                            },
-                            "labels": {
-                                "type": "array",
-                                "items": {"type": "string"},
-                                "description": "Optional list of label names"
-                            },
-                            "repo": {
-                                "type": "string",
-                                "description": "Repository name (owner/repo format)"
-                            }
-                        },
-                        "required": ["title", "body", "head", "base"]
-                    }
-                )
-            ]
+            return get_tool_definitions()
 
         @self.server.call_tool()
         async def call_tool(name: str, arguments: dict) -> list[TextContent]:
@@ -894,122 +68,7 @@ class GiteaMCPServer:
             Returns:
                 List of TextContent with results
             """
-            try:
-                # Route to appropriate tool handler
-                if name == "list_issues":
-                    result = await self.issue_tools.list_issues(**arguments)
-                elif name == "get_issue":
-                    result = await self.issue_tools.get_issue(**arguments)
-                elif name == "create_issue":
-                    result = await self.issue_tools.create_issue(**arguments)
-                elif name == "update_issue":
-                    result = await self.issue_tools.update_issue(**arguments)
-                elif name == "add_comment":
-                    result = await self.issue_tools.add_comment(**arguments)
-                elif name == "get_labels":
-                    result = await self.label_tools.get_labels(**arguments)
-                elif name == "suggest_labels":
-                    result = await self.label_tools.suggest_labels(**arguments)
-                elif name == "aggregate_issues":
-                    result = await self.issue_tools.aggregate_issues(**arguments)
-                # Wiki tools
-                elif name == "list_wiki_pages":
-                    result = await self.wiki_tools.list_wiki_pages(**arguments)
-                elif name == "get_wiki_page":
-                    result = await self.wiki_tools.get_wiki_page(**arguments)
-                elif name == "create_wiki_page":
-                    result = await self.wiki_tools.create_wiki_page(**arguments)
-                elif name == "update_wiki_page":
-                    result = await self.wiki_tools.update_wiki_page(**arguments)
-                elif name == "create_lesson":
-                    result = await self.wiki_tools.create_lesson(**arguments)
-                elif name == "search_lessons":
-                    tags = arguments.get('tags')
-                    result = await self.wiki_tools.search_lessons(
-                        query=arguments.get('query'),
-                        tags=tags,
-                        limit=arguments.get('limit', 20),
-                        repo=arguments.get('repo')
-                    )
-                # Milestone tools
-                elif name == "list_milestones":
-                    result = await self.milestone_tools.list_milestones(**arguments)
-                elif name == "get_milestone":
-                    result = await self.milestone_tools.get_milestone(**arguments)
-                elif name == "create_milestone":
-                    result = await self.milestone_tools.create_milestone(**arguments)
-                elif name == "update_milestone":
-                    result = await self.milestone_tools.update_milestone(**arguments)
-                elif name == "delete_milestone":
-                    result = await self.milestone_tools.delete_milestone(**arguments)
-                # Dependency tools
-                elif name == "list_issue_dependencies":
-                    result = await self.dependency_tools.list_issue_dependencies(**arguments)
-                elif name == "create_issue_dependency":
-                    result = await self.dependency_tools.create_issue_dependency(**arguments)
-                elif name == "remove_issue_dependency":
-                    result = await self.dependency_tools.remove_issue_dependency(**arguments)
-                elif name == "get_execution_order":
-                    result = await self.dependency_tools.get_execution_order(**arguments)
-                # Validation tools
-                elif name == "validate_repo_org":
-                    is_org = self.client.is_org_repo(arguments.get('repo'))
-                    result = {'is_organization': is_org}
-                elif name == "get_branch_protection":
-                    result = self.client.get_branch_protection(
-                        arguments['branch'],
-                        arguments.get('repo')
-                    )
-                elif name == "create_label":
-                    result = self.client.create_label(
-                        arguments['name'],
-                        arguments['color'],
-                        arguments.get('description'),
-                        arguments.get('repo')
-                    )
-                elif name == "create_org_label":
-                    result = self.client.create_org_label(
-                        arguments['org'],
-                        arguments['name'],
-                        arguments['color'],
-                        arguments.get('description')
-                    )
-                elif name == "create_label_smart":
-                    result = await self.label_tools.create_label_smart(
-                        arguments['name'],
-                        arguments['color'],
-                        arguments.get('description'),
-                        arguments.get('repo')
-                    )
-                # Pull Request tools
-                elif name == "list_pull_requests":
-                    result = await self.pr_tools.list_pull_requests(**arguments)
-                elif name == "get_pull_request":
-                    result = await self.pr_tools.get_pull_request(**arguments)
-                elif name == "get_pr_diff":
-                    result = await self.pr_tools.get_pr_diff(**arguments)
-                elif name == "get_pr_comments":
-                    result = await self.pr_tools.get_pr_comments(**arguments)
-                elif name == "create_pr_review":
-                    result = await self.pr_tools.create_pr_review(**arguments)
-                elif name == "add_pr_comment":
-                    result = await self.pr_tools.add_pr_comment(**arguments)
-                elif name == "create_pull_request":
-                    result = await self.pr_tools.create_pull_request(**arguments)
-                else:
-                    raise ValueError(f"Unknown tool: {name}")
-
-                return [TextContent(
-                    type="text",
-                    text=json.dumps(result, indent=2)
-                )]
-
-            except Exception as e:
-                logger.error(f"Tool {name} failed: {e}")
-                return [TextContent(
-                    type="text",
-                    text=f"Error: {str(e)}"
-                )]
+            return await self._dispatcher(name, arguments)
 
     async def run(self):
         """Run the MCP server"""

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

@@ -7,6 +7,7 @@ Provides async wrappers for issue CRUD operations with:
 - Comprehensive error handling
 """
 import asyncio
+import os
 import subprocess
 import logging
 from typing import List, Dict, Optional
@@ -27,19 +28,34 @@ class IssueTools:
         """
         self.gitea = gitea_client
 
+    def _get_project_directory(self) -> Optional[str]:
+        """
+        Get the user's project directory from environment.
+
+        Returns:
+            Project directory path or None if not set
+        """
+        return os.environ.get('CLAUDE_PROJECT_DIR')
+
     def _get_current_branch(self) -> str:
         """
-        Get current git branch.
+        Get current git branch from user's project directory.
+
+        Uses CLAUDE_PROJECT_DIR environment variable to determine the correct
+        directory for git operations, avoiding the bug where git runs from
+        the installed plugin directory instead of the user's project.
 
         Returns:
             Current branch name or 'unknown' if not in a git repo
         """
         try:
+            project_dir = self._get_project_directory()
             result = subprocess.run(
                 ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
                 capture_output=True,
                 text=True,
-                check=True
+                check=True,
+                cwd=project_dir  # Run git in project directory, not plugin directory
             )
             return result.stdout.strip()
         except subprocess.CalledProcessError:
@@ -82,6 +98,7 @@ class IssueTools:
         self,
         state: str = 'open',
         labels: Optional[List[str]] = None,
+        milestone: Optional[str] = None,
         repo: Optional[str] = None
     ) -> List[Dict]:
         """
@@ -90,6 +107,7 @@ class IssueTools:
         Args:
             state: Issue state (open, closed, all)
             labels: Filter by labels
+            milestone: Filter by milestone title (exact match)
             repo: Override configured repo (for PMO multi-repo)
 
         Returns:
@@ -108,7 +126,7 @@ class IssueTools:
         loop = asyncio.get_event_loop()
         return await loop.run_in_executor(
             None,
-            lambda: self.gitea.list_issues(state, labels, repo)
+            lambda: self.gitea.list_issues(state, labels, milestone, repo)
         )
 
     async def get_issue(
@@ -184,6 +202,7 @@ class IssueTools:
         body: Optional[str] = None,
         state: Optional[str] = None,
         labels: Optional[List[str]] = None,
+        milestone: Optional[int] = None,
         repo: Optional[str] = None
     ) -> Dict:
         """
@@ -195,6 +214,7 @@ class IssueTools:
             body: New body (optional)
             state: New state - 'open' or 'closed' (optional)
             labels: New labels (optional)
+            milestone: Milestone ID to assign (optional)
             repo: Override configured repo (for PMO multi-repo)
 
         Returns:
@@ -213,7 +233,7 @@ class IssueTools:
         loop = asyncio.get_event_loop()
         return await loop.run_in_executor(
             None,
-            lambda: self.gitea.update_issue(issue_number, title, body, state, labels, repo)
+            lambda: self.gitea.update_issue(issue_number, title, body, state, labels, milestone, repo)
         )
 
     async def add_comment(

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

@@ -7,6 +7,7 @@ Provides async wrappers for PR operations with:
 - Comprehensive error handling
 """
 import asyncio
+import os
 import subprocess
 import logging
 from typing import List, Dict, Optional
@@ -27,19 +28,34 @@ class PullRequestTools:
         """
         self.gitea = gitea_client
 
+    def _get_project_directory(self) -> Optional[str]:
+        """
+        Get the user's project directory from environment.
+
+        Returns:
+            Project directory path or None if not set
+        """
+        return os.environ.get('CLAUDE_PROJECT_DIR')
+
     def _get_current_branch(self) -> str:
         """
-        Get current git branch.
+        Get current git branch from user's project directory.
+
+        Uses CLAUDE_PROJECT_DIR environment variable to determine the correct
+        directory for git operations, avoiding the bug where git runs from
+        the installed plugin directory instead of the user's project.
 
         Returns:
             Current branch name or 'unknown' if not in a git repo
         """
         try:
+            project_dir = self._get_project_directory()
             result = subprocess.run(
                 ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
                 capture_output=True,
                 text=True,
-                check=True
+                check=True,
+                cwd=project_dir  # Run git in project directory, not plugin directory
             )
             return result.stdout.strip()
         except subprocess.CalledProcessError:

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

@@ -4,9 +4,11 @@ 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)
@@ -147,3 +149,39 @@ 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/gitea/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gitea-mcp-server"
+version = "1.0.0"
+description = "MCP Server for Gitea integration - provides issue, label, wiki, milestone, dependency, and PR tools"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    { name = "Leo Miranda" }
+]
+keywords = ["mcp", "gitea", "claude", "tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=0.9.0",
+    "python-dotenv>=1.0.0",
+    "requests>=2.31.0",
+    "pydantic>=2.5.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.4.3",
+    "pytest-asyncio>=0.23.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["mcp_server*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

mcp-servers/gitea/run.sh

@@ -1,4 +1,8 @@
 #!/bin/bash
+# Capture original working directory before any cd operations
+# This should be the user's project directory when launched by Claude Code
+export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/gitea/.venv"
 LOCAL_VENV="$SCRIPT_DIR/.venv"

mcp-servers/gitea/tests/test_config.py

@@ -28,7 +28,6 @@ def test_load_system_config(tmp_path, monkeypatch):
 
     assert result['api_url'] == 'https://test.com/api/v1'
     assert result['api_token'] == 'test_token'
-    assert result['owner'] == 'test_owner'
     assert result['mode'] == 'company'  # No repo specified
     assert result['repo'] is None
 

mcp-servers/gitea/tests/test_gitea_client.py

@@ -14,8 +14,7 @@ def mock_config():
         mock_instance.load.return_value = {
             'api_url': 'https://test.com/api/v1',
             'api_token': 'test_token',
-            'owner': 'test_owner',
-            'repo': 'test_repo',
+            'repo': 'test_owner/test_repo',  # Combined owner/repo format
             'mode': 'project'
         }
         yield mock_cfg
@@ -31,8 +30,7 @@ def test_client_initialization(gitea_client):
     """Test client initializes with correct configuration"""
     assert gitea_client.base_url == 'https://test.com/api/v1'
     assert gitea_client.token == 'test_token'
-    assert gitea_client.owner == 'test_owner'
-    assert gitea_client.repo == 'test_repo'
+    assert gitea_client.repo == 'test_owner/test_repo'  # Combined format
     assert gitea_client.mode == 'project'
     assert 'Authorization' in gitea_client.session.headers
     assert gitea_client.session.headers['Authorization'] == 'token test_token'
@@ -92,15 +90,20 @@ def test_create_issue(gitea_client):
     }
     mock_response.raise_for_status = Mock()
 
-    with patch.object(gitea_client.session, 'post', return_value=mock_response):
-        issue = gitea_client.create_issue(
-            title='New Issue',
-            body='Issue body',
-            labels=['Type/Bug']
-        )
+    # Mock is_org_repo to avoid network call during label resolution
+    with patch.object(gitea_client, 'is_org_repo', return_value=True):
+        # Mock get_org_labels and get_labels for label resolution
+        with patch.object(gitea_client, 'get_org_labels', return_value=[{'name': 'Type/Bug', 'id': 1}]):
+            with patch.object(gitea_client, 'get_labels', return_value=[]):
+                with patch.object(gitea_client.session, 'post', return_value=mock_response):
+                    issue = gitea_client.create_issue(
+                        title='New Issue',
+                        body='Issue body',
+                        labels=['Type/Bug']
+                    )
 
-        assert issue['title'] == 'New Issue'
-        gitea_client.session.post.assert_called_once()
+                    assert issue['title'] == 'New Issue'
+                    gitea_client.session.post.assert_called_once()
 
 
 def test_update_issue(gitea_client):
@@ -161,7 +164,7 @@ def test_get_org_labels(gitea_client):
     mock_response.raise_for_status = Mock()
 
     with patch.object(gitea_client.session, 'get', return_value=mock_response):
-        labels = gitea_client.get_org_labels()
+        labels = gitea_client.get_org_labels(org='test_owner')
 
         assert len(labels) == 2
 
@@ -176,7 +179,7 @@ def test_list_repos(gitea_client):
     mock_response.raise_for_status = Mock()
 
     with patch.object(gitea_client.session, 'get', return_value=mock_response):
-        repos = gitea_client.list_repos()
+        repos = gitea_client.list_repos(org='test_owner')
 
         assert len(repos) == 2
         assert repos[0]['name'] == 'repo1'
@@ -196,7 +199,7 @@ def test_aggregate_issues(gitea_client):
         [{'number': 2, 'title': 'Issue 2'}]   # repo2
     ])
 
-    aggregated = gitea_client.aggregate_issues(state='open')
+    aggregated = gitea_client.aggregate_issues(org='test_owner', state='open')
 
     assert 'repo1' in aggregated
     assert 'repo2' in aggregated
@@ -205,14 +208,13 @@ def test_aggregate_issues(gitea_client):
 
 
 def test_no_repo_specified_error(gitea_client):
-    """Test error when repository not specified"""
+    """Test error when repository not specified or invalid format"""
     # Create client without repo
     with patch('mcp_server.gitea_client.GiteaConfig') as mock_cfg:
         mock_instance = mock_cfg.return_value
         mock_instance.load.return_value = {
             'api_url': 'https://test.com/api/v1',
             'api_token': 'test_token',
-            'owner': 'test_owner',
             'repo': None,  # No repo
             'mode': 'company'
         }
@@ -221,7 +223,7 @@ def test_no_repo_specified_error(gitea_client):
         with pytest.raises(ValueError) as exc_info:
             client.list_issues()
 
-        assert "Repository not specified" in str(exc_info.value)
+        assert "Use 'owner/repo' format" in str(exc_info.value)
 
 
 # ========================================

mcp-servers/gitea/tests/test_issues.py

@@ -119,22 +119,26 @@ async def test_aggregate_issues_company_mode(issue_tools):
             'repo2': [{'number': 2}]
         })
 
-        aggregated = await issue_tools.aggregate_issues()
+        aggregated = await issue_tools.aggregate_issues(org='test_owner')
 
         assert 'repo1' in aggregated
         assert 'repo2' in aggregated
 
 
 @pytest.mark.asyncio
-async def test_aggregate_issues_project_mode_error(issue_tools):
-    """Test that aggregate_issues fails in project mode"""
+async def test_aggregate_issues_project_mode(issue_tools):
+    """Test that aggregate_issues works in project mode with org argument"""
     issue_tools.gitea.mode = 'project'
 
     with patch.object(issue_tools, '_get_current_branch', return_value='development'):
-        with pytest.raises(ValueError) as exc_info:
-            await issue_tools.aggregate_issues()
+        issue_tools.gitea.aggregate_issues = Mock(return_value={
+            'repo1': [{'number': 1}]
+        })
 
-        assert "only available in company mode" in str(exc_info.value)
+        # aggregate_issues now works in any mode when org is provided
+        aggregated = await issue_tools.aggregate_issues(org='test_owner')
+
+        assert 'repo1' in aggregated
 
 
 def test_branch_detection():

mcp-servers/netbox/README.md

@@ -79,6 +79,69 @@ Add to your Claude Code MCP configuration (`~/.config/claude/mcp.json` or projec
 1. **System-level** (`~/.config/claude/netbox.env`): Credentials and defaults
 2. **Project-level** (`.env` in current directory): Optional overrides
 
+## Module Filtering (Token Optimization)
+
+By default, the NetBox MCP server registers all 182 tools across 8 modules, consuming ~19,810 tokens of context. For most workflows, you only need a subset of modules.
+
+### Configuration
+
+Add `NETBOX_ENABLED_MODULES` to your `~/.config/claude/netbox.env`:
+
+```bash
+# Enable only specific modules (comma-separated)
+NETBOX_ENABLED_MODULES=dcim,ipam,virtualization,extras
+```
+
+If unset, all modules are enabled (backward compatible).
+
+### Available Modules
+
+| Module | Tool Count | Description | cmdb-assistant Commands |
+|--------|------------|-------------|------------------------|
+| `dcim` | ~60 | Sites, devices, racks, interfaces, cables | `/cmdb-device`, `/cmdb-site`, `/cmdb-search`, `/cmdb-topology` |
+| `ipam` | ~40 | IP addresses, prefixes, VLANs, VRFs | `/cmdb-ip`, `/ip-conflicts`, `/cmdb-search` |
+| `virtualization` | ~20 | Clusters, VMs, VM interfaces | `/cmdb-search`, `/cmdb-audit`, `/cmdb-register` |
+| `extras` | ~12 | Tags, journal entries, audit log | `/change-audit`, `/cmdb-register` |
+| `circuits` | ~15 | Providers, circuits, terminations | — |
+| `tenancy` | ~12 | Tenants, contacts | — |
+| `vpn` | ~15 | Tunnels, IKE/IPSec policies, L2VPN | — |
+| `wireless` | ~8 | Wireless LANs, links, groups | — |
+
+### Recommended Configurations
+
+**For cmdb-assistant users** (~43 tools, ~4,500 tokens):
+```bash
+NETBOX_ENABLED_MODULES=dcim,ipam,virtualization,extras
+```
+
+**Basic infrastructure** (~100 tools):
+```bash
+NETBOX_ENABLED_MODULES=dcim,ipam
+```
+
+**Full CMDB** (all modules, ~182 tools):
+```bash
+# Omit NETBOX_ENABLED_MODULES or set to all modules
+NETBOX_ENABLED_MODULES=dcim,ipam,circuits,virtualization,tenancy,vpn,wireless,extras
+```
+
+### Startup Logging
+
+On startup, the server logs enabled modules and tool count:
+
+```
+NetBox MCP Server initialized: 43 tools registered (modules: dcim, extras, ipam, virtualization)
+```
+
+### Disabled Tool Behavior
+
+Calling a tool from a disabled module returns a clear error:
+
+```
+Tool 'circuits_list_circuits' is not available (module 'circuits' not enabled).
+Enabled modules: dcim, extras, ipam, virtualization
+```
+
 ## Available Tools
 
 ### DCIM (Data Center Infrastructure Management)
@@ -128,18 +191,18 @@ Add to your Claude Code MCP configuration (`~/.config/claude/mcp.json` or projec
 | `circuits_create_provider` | Create a provider |
 | `circuits_list_circuits` | List circuits |
 | `circuits_create_circuit` | Create a circuit |
-| `circuits_list_circuit_terminations` | List terminations |
+| `circ_list_terminations` | List terminations |
 | ... and more |
 
 ### Virtualization
 
 | Tool | Description |
 |------|-------------|
-| `virtualization_list_clusters` | List clusters |
-| `virtualization_create_cluster` | Create a cluster |
-| `virtualization_list_virtual_machines` | List VMs |
-| `virtualization_create_virtual_machine` | Create a VM |
-| `virtualization_list_vm_interfaces` | List VM interfaces |
+| `virt_list_clusters` | List clusters |
+| `virt_create_cluster` | Create a cluster |
+| `virt_list_vms` | List VMs |
+| `virt_create_vm` | Create a VM |
+| `virt_list_vm_ifaces` | List VM interfaces |
 | ... and more |
 
 ### Tenancy
@@ -167,9 +230,9 @@ Add to your Claude Code MCP configuration (`~/.config/claude/mcp.json` or projec
 
 | Tool | Description |
 |------|-------------|
-| `wireless_list_wireless_lans` | List wireless LANs |
-| `wireless_create_wireless_lan` | Create a WLAN |
-| `wireless_list_wireless_links` | List wireless links |
+| `wlan_list_lans` | List wireless LANs |
+| `wlan_create_lan` | Create a WLAN |
+| `wlan_list_links` | List wireless links |
 | ... and more |
 
 ### Extras

mcp-servers/netbox/mcp_server/config.py

@@ -9,11 +9,17 @@ from pathlib import Path
 from dotenv import load_dotenv
 import os
 import logging
-from typing import Dict, Optional
+from typing import Dict, List, Optional, Set
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
+# All available NetBox modules
+ALL_MODULES = frozenset([
+    'dcim', 'ipam', 'circuits', 'virtualization',
+    'tenancy', 'vpn', 'wireless', 'extras'
+])
+
 
 class NetBoxConfig:
     """Configuration loader for NetBox MCP Server"""
@@ -23,6 +29,7 @@ class NetBoxConfig:
         self.api_token: Optional[str] = None
         self.verify_ssl: bool = True
         self.timeout: int = 30
+        self.enabled_modules: Set[str] = set(ALL_MODULES)
 
     def load(self) -> Dict[str, any]:
         """
@@ -73,6 +80,9 @@ class NetBoxConfig:
             self.timeout = 30
             logger.warning(f"Invalid NETBOX_TIMEOUT value '{timeout_str}', using default 30")
 
+        # Module filtering
+        self.enabled_modules = self._load_enabled_modules()
+
         # Validate required variables
         self._validate()
 
@@ -84,7 +94,8 @@ class NetBoxConfig:
             'api_url': self.api_url,
             'api_token': self.api_token,
             'verify_ssl': self.verify_ssl,
-            'timeout': self.timeout
+            'timeout': self.timeout,
+            'enabled_modules': self.enabled_modules
         }
 
     def _validate(self) -> None:
@@ -106,3 +117,40 @@ class NetBoxConfig:
                 f"Missing required configuration: {', '.join(missing)}\n"
                 "Check your ~/.config/claude/netbox.env file"
             )
+
+    def _load_enabled_modules(self) -> Set[str]:
+        """
+        Load enabled modules from NETBOX_ENABLED_MODULES environment variable.
+
+        Format: Comma-separated list of module names.
+        Example: NETBOX_ENABLED_MODULES=dcim,ipam,virtualization,extras
+
+        Returns:
+            Set of enabled module names. If env var is unset/empty, returns all modules.
+        """
+        modules_str = os.getenv('NETBOX_ENABLED_MODULES', '').strip()
+
+        if not modules_str:
+            logger.info("NETBOX_ENABLED_MODULES not set, all modules enabled (default)")
+            return set(ALL_MODULES)
+
+        # Parse comma-separated list, strip whitespace
+        requested = {m.strip().lower() for m in modules_str.split(',') if m.strip()}
+
+        # Validate module names
+        invalid = requested - ALL_MODULES
+        if invalid:
+            logger.warning(
+                f"Unknown modules in NETBOX_ENABLED_MODULES: {', '.join(sorted(invalid))}. "
+                f"Valid modules: {', '.join(sorted(ALL_MODULES))}"
+            )
+
+        # Return only valid modules
+        enabled = requested & ALL_MODULES
+
+        if not enabled:
+            logger.warning("No valid modules enabled, falling back to all modules")
+            return set(ALL_MODULES)
+
+        logger.info(f"Enabled modules: {', '.join(sorted(enabled))}")
+        return enabled

mcp-servers/netbox/mcp_server/server.py

@@ -8,11 +8,12 @@ Tenancy, VPN, Wireless, and Extras.
 import asyncio
 import logging
 import json
+from typing import Optional, Set
 from mcp.server import Server
 from mcp.server.stdio import stdio_server
 from mcp.types import Tool, TextContent
 
-from .config import NetBoxConfig
+from .config import NetBoxConfig, ALL_MODULES
 from .netbox_client import NetBoxClient
 from .tools.dcim import DCIMTools
 from .tools.ipam import IPAMTools
@@ -1453,6 +1454,49 @@ TOOL_NAME_MAP = {
 }
 
 
+# Map tool name prefixes to module names.
+# This handles both full prefixes and shortened prefixes used in TOOL_NAME_MAP.
+PREFIX_TO_MODULE = {
+    'dcim': 'dcim',
+    'ipam': 'ipam',
+    'circuits': 'circuits',
+    'circ': 'circuits',           # Shortened prefix
+    'virtualization': 'virtualization',
+    'virt': 'virtualization',     # Shortened prefix
+    'tenancy': 'tenancy',
+    'vpn': 'vpn',
+    'wireless': 'wireless',
+    'wlan': 'wireless',           # Shortened prefix
+    'extras': 'extras',
+}
+
+
+def _get_tool_module(tool_name: str) -> Optional[str]:
+    """
+    Determine which module a tool belongs to.
+
+    Checks TOOL_NAME_MAP first for shortened names, then falls back to prefix extraction.
+
+    Args:
+        tool_name: The tool name (e.g., 'dcim_list_devices', 'virt_list_vms')
+
+    Returns:
+        Module name (e.g., 'dcim', 'virtualization') or None if unknown
+    """
+    # Check mapped short names first
+    if tool_name in TOOL_NAME_MAP:
+        category, _ = TOOL_NAME_MAP[tool_name]
+        return category
+
+    # Fall back to prefix extraction
+    parts = tool_name.split('_', 1)
+    if len(parts) < 2:
+        return None
+
+    prefix = parts[0]
+    return PREFIX_TO_MODULE.get(prefix)
+
+
 class NetBoxMCPServer:
     """MCP Server for NetBox integration"""
 
@@ -1460,6 +1504,8 @@ class NetBoxMCPServer:
         self.server = Server("netbox-mcp")
         self.config = None
         self.client = None
+        self.enabled_modules: Set[str] = set(ALL_MODULES)
+        # Tool instances - only instantiated for enabled modules
         self.dcim_tools = None
         self.ipam_tools = None
         self.circuits_tools = None
@@ -1474,18 +1520,39 @@ class NetBoxMCPServer:
         try:
             config_loader = NetBoxConfig()
             self.config = config_loader.load()
+            self.enabled_modules = self.config['enabled_modules']
 
             self.client = NetBoxClient()
-            self.dcim_tools = DCIMTools(self.client)
-            self.ipam_tools = IPAMTools(self.client)
-            self.circuits_tools = CircuitsTools(self.client)
-            self.virtualization_tools = VirtualizationTools(self.client)
-            self.tenancy_tools = TenancyTools(self.client)
-            self.vpn_tools = VPNTools(self.client)
-            self.wireless_tools = WirelessTools(self.client)
-            self.extras_tools = ExtrasTools(self.client)
 
-            logger.info(f"NetBox MCP Server initialized for {self.config['api_url']}")
+            # Conditionally instantiate tool classes for enabled modules only
+            if 'dcim' in self.enabled_modules:
+                self.dcim_tools = DCIMTools(self.client)
+            if 'ipam' in self.enabled_modules:
+                self.ipam_tools = IPAMTools(self.client)
+            if 'circuits' in self.enabled_modules:
+                self.circuits_tools = CircuitsTools(self.client)
+            if 'virtualization' in self.enabled_modules:
+                self.virtualization_tools = VirtualizationTools(self.client)
+            if 'tenancy' in self.enabled_modules:
+                self.tenancy_tools = TenancyTools(self.client)
+            if 'vpn' in self.enabled_modules:
+                self.vpn_tools = VPNTools(self.client)
+            if 'wireless' in self.enabled_modules:
+                self.wireless_tools = WirelessTools(self.client)
+            if 'extras' in self.enabled_modules:
+                self.extras_tools = ExtrasTools(self.client)
+
+            # Count tools that will be registered
+            tool_count = sum(
+                1 for name in TOOL_DEFINITIONS
+                if _get_tool_module(name) in self.enabled_modules
+            )
+
+            modules_str = ', '.join(sorted(self.enabled_modules))
+            logger.info(
+                f"NetBox MCP Server initialized: {tool_count} tools registered "
+                f"(modules: {modules_str})"
+            )
         except Exception as e:
             logger.error(f"Failed to initialize: {e}")
             raise
@@ -1495,9 +1562,14 @@ class NetBoxMCPServer:
 
         @self.server.list_tools()
         async def list_tools() -> list[Tool]:
-            """Return list of available tools"""
+            """Return list of available tools, filtered by enabled modules"""
             tools = []
             for name, definition in TOOL_DEFINITIONS.items():
+                # Filter tools by enabled modules
+                module = _get_tool_module(name)
+                if module not in self.enabled_modules:
+                    continue
+
                 tools.append(Tool(
                     name=name,
                     description=definition['description'],
@@ -1532,6 +1604,14 @@ class NetBoxMCPServer:
         'virtualization_list_virtual_machines') to meet the 28-character
         limit. TOOL_NAME_MAP handles the translation to actual method names.
         """
+        # Check module is enabled (routing guard)
+        module = _get_tool_module(name)
+        if module and module not in self.enabled_modules:
+            raise ValueError(
+                f"Tool '{name}' is not available (module '{module}' not enabled). "
+                f"Enabled modules: {', '.join(sorted(self.enabled_modules))}"
+            )
+
         # Check if this is a mapped short name
         if name in TOOL_NAME_MAP:
             category, method_name = TOOL_NAME_MAP[name]

mcp-servers/netbox/run.sh

@@ -1,4 +1,8 @@
 #!/bin/bash
+# Capture original working directory before any cd operations
+# This should be the user's project directory when launched by Claude Code
+export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/netbox/.venv"
 LOCAL_VENV="$SCRIPT_DIR/.venv"

mcp-servers/viz-platform/.doc-guardian-queue

@@ -0,0 +1,5 @@
+2026-01-26T11:40:11 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/registry/dmc_2_5.json | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T13:46:31 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/tests/test_chart_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T13:46:32 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/tests/test_theme_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T13:46:34 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/tests/test_theme_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
+2026-01-26T13:46:35 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/viz-platform/tests/test_theme_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md

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 [plugins/viz-platform/README.md](../../plugins/viz-platform/README.md) for usage instructions.
+This MCP server is used by the `viz-platform` plugin. See the plugin's commands in `plugins/viz-platform/commands/` for usage.

mcp-servers/viz-platform/mcp_server/accessibility_tools.py

@@ -0,0 +1,479 @@
+"""
+Accessibility validation tools for color blindness and WCAG compliance.
+
+Provides tools for validating color palettes against color blindness
+simulations and WCAG contrast requirements.
+"""
+import logging
+import math
+from typing import Dict, List, Optional, Any, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+# Color-blind safe palettes
+SAFE_PALETTES = {
+    "categorical": {
+        "name": "Paul Tol's Qualitative",
+        "colors": ["#4477AA", "#EE6677", "#228833", "#CCBB44", "#66CCEE", "#AA3377", "#BBBBBB"],
+        "description": "Distinguishable for all types of color blindness"
+    },
+    "ibm": {
+        "name": "IBM Design",
+        "colors": ["#648FFF", "#785EF0", "#DC267F", "#FE6100", "#FFB000"],
+        "description": "IBM's accessible color palette"
+    },
+    "okabe_ito": {
+        "name": "Okabe-Ito",
+        "colors": ["#E69F00", "#56B4E9", "#009E73", "#F0E442", "#0072B2", "#D55E00", "#CC79A7", "#000000"],
+        "description": "Optimized for all color vision deficiencies"
+    },
+    "tableau_colorblind": {
+        "name": "Tableau Colorblind 10",
+        "colors": ["#006BA4", "#FF800E", "#ABABAB", "#595959", "#5F9ED1",
+                   "#C85200", "#898989", "#A2C8EC", "#FFBC79", "#CFCFCF"],
+        "description": "Industry-standard accessible palette"
+    }
+}
+
+
+# Simulation matrices for color blindness (LMS color space transformation)
+# These approximate how colors appear to people with different types of color blindness
+SIMULATION_MATRICES = {
+    "deuteranopia": {
+        # Green-blind (most common)
+        "severity": "common",
+        "population": "6% males, 0.4% females",
+        "description": "Difficulty distinguishing red from green (green-blind)",
+        "matrix": [
+            [0.625, 0.375, 0.0],
+            [0.700, 0.300, 0.0],
+            [0.0, 0.300, 0.700]
+        ]
+    },
+    "protanopia": {
+        # Red-blind
+        "severity": "common",
+        "population": "2.5% males, 0.05% females",
+        "description": "Difficulty distinguishing red from green (red-blind)",
+        "matrix": [
+            [0.567, 0.433, 0.0],
+            [0.558, 0.442, 0.0],
+            [0.0, 0.242, 0.758]
+        ]
+    },
+    "tritanopia": {
+        # Blue-blind (rare)
+        "severity": "rare",
+        "population": "0.01% total",
+        "description": "Difficulty distinguishing blue from yellow",
+        "matrix": [
+            [0.950, 0.050, 0.0],
+            [0.0, 0.433, 0.567],
+            [0.0, 0.475, 0.525]
+        ]
+    }
+}
+
+
+class AccessibilityTools:
+    """
+    Color accessibility validation tools.
+
+    Validates colors for WCAG compliance and color blindness accessibility.
+    """
+
+    def __init__(self, theme_store=None):
+        """
+        Initialize accessibility tools.
+
+        Args:
+            theme_store: Optional ThemeStore for theme color extraction
+        """
+        self.theme_store = theme_store
+
+    def _hex_to_rgb(self, hex_color: str) -> Tuple[int, int, int]:
+        """Convert hex color to RGB tuple."""
+        hex_color = hex_color.lstrip('#')
+        if len(hex_color) == 3:
+            hex_color = ''.join([c * 2 for c in hex_color])
+        return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4))
+
+    def _rgb_to_hex(self, rgb: Tuple[int, int, int]) -> str:
+        """Convert RGB tuple to hex color."""
+        return '#{:02x}{:02x}{:02x}'.format(
+            max(0, min(255, int(rgb[0]))),
+            max(0, min(255, int(rgb[1]))),
+            max(0, min(255, int(rgb[2])))
+        )
+
+    def _get_relative_luminance(self, rgb: Tuple[int, int, int]) -> float:
+        """
+        Calculate relative luminance per WCAG 2.1.
+
+        https://www.w3.org/WAI/GL/wiki/Relative_luminance
+        """
+        def channel_luminance(value: int) -> float:
+            v = value / 255
+            return v / 12.92 if v <= 0.03928 else ((v + 0.055) / 1.055) ** 2.4
+
+        r, g, b = rgb
+        return (
+            0.2126 * channel_luminance(r) +
+            0.7152 * channel_luminance(g) +
+            0.0722 * channel_luminance(b)
+        )
+
+    def _get_contrast_ratio(self, color1: str, color2: str) -> float:
+        """
+        Calculate contrast ratio between two colors per WCAG 2.1.
+
+        Returns ratio between 1:1 and 21:1.
+        """
+        rgb1 = self._hex_to_rgb(color1)
+        rgb2 = self._hex_to_rgb(color2)
+
+        l1 = self._get_relative_luminance(rgb1)
+        l2 = self._get_relative_luminance(rgb2)
+
+        lighter = max(l1, l2)
+        darker = min(l1, l2)
+
+        return (lighter + 0.05) / (darker + 0.05)
+
+    def _simulate_color_blindness(
+        self,
+        hex_color: str,
+        deficiency_type: str
+    ) -> str:
+        """
+        Simulate how a color appears with a specific color blindness type.
+
+        Uses linear RGB transformation approximation.
+        """
+        if deficiency_type not in SIMULATION_MATRICES:
+            return hex_color
+
+        rgb = self._hex_to_rgb(hex_color)
+        matrix = SIMULATION_MATRICES[deficiency_type]["matrix"]
+
+        # Apply transformation matrix
+        r = rgb[0] * matrix[0][0] + rgb[1] * matrix[0][1] + rgb[2] * matrix[0][2]
+        g = rgb[0] * matrix[1][0] + rgb[1] * matrix[1][1] + rgb[2] * matrix[1][2]
+        b = rgb[0] * matrix[2][0] + rgb[1] * matrix[2][1] + rgb[2] * matrix[2][2]
+
+        return self._rgb_to_hex((r, g, b))
+
+    def _get_color_distance(self, color1: str, color2: str) -> float:
+        """
+        Calculate perceptual color distance (CIE76 approximation).
+
+        Returns a value where < 20 means colors may be hard to distinguish.
+        """
+        rgb1 = self._hex_to_rgb(color1)
+        rgb2 = self._hex_to_rgb(color2)
+
+        # Simple Euclidean distance in RGB space (approximation)
+        # For production, should use CIEDE2000
+        return math.sqrt(
+            (rgb1[0] - rgb2[0]) ** 2 +
+            (rgb1[1] - rgb2[1]) ** 2 +
+            (rgb1[2] - rgb2[2]) ** 2
+        )
+
+    async def accessibility_validate_colors(
+        self,
+        colors: List[str],
+        check_types: Optional[List[str]] = None,
+        min_contrast_ratio: float = 4.5
+    ) -> Dict[str, Any]:
+        """
+        Validate a list of colors for accessibility.
+
+        Args:
+            colors: List of hex colors to validate
+            check_types: Color blindness types to check (default: all)
+            min_contrast_ratio: Minimum WCAG contrast ratio (default: 4.5 for AA)
+
+        Returns:
+            Dict with:
+                - issues: List of accessibility issues found
+                - simulations: How colors appear under each deficiency
+                - recommendations: Suggestions for improvement
+                - safe_palettes: Color-blind safe palette suggestions
+        """
+        check_types = check_types or list(SIMULATION_MATRICES.keys())
+        issues = []
+        simulations = {}
+
+        # Normalize colors
+        normalized_colors = [c.upper() if c.startswith('#') else f'#{c.upper()}' for c in colors]
+
+        # Simulate each color blindness type
+        for deficiency in check_types:
+            if deficiency not in SIMULATION_MATRICES:
+                continue
+
+            simulated = [self._simulate_color_blindness(c, deficiency) for c in normalized_colors]
+            simulations[deficiency] = {
+                "original": normalized_colors,
+                "simulated": simulated,
+                "info": SIMULATION_MATRICES[deficiency]
+            }
+
+            # Check if any color pairs become indistinguishable
+            for i in range(len(normalized_colors)):
+                for j in range(i + 1, len(normalized_colors)):
+                    distance = self._get_color_distance(simulated[i], simulated[j])
+                    if distance < 30:  # Threshold for distinguishability
+                        issues.append({
+                            "type": "distinguishability",
+                            "severity": "warning" if distance > 15 else "error",
+                            "colors": [normalized_colors[i], normalized_colors[j]],
+                            "affected_by": [deficiency],
+                            "simulated_colors": [simulated[i], simulated[j]],
+                            "distance": round(distance, 1),
+                            "message": f"Colors may be hard to distinguish for {deficiency} ({SIMULATION_MATRICES[deficiency]['description']})"
+                        })
+
+        # Check contrast ratios against white and black backgrounds
+        for color in normalized_colors:
+            white_contrast = self._get_contrast_ratio(color, "#FFFFFF")
+            black_contrast = self._get_contrast_ratio(color, "#000000")
+
+            if white_contrast < min_contrast_ratio and black_contrast < min_contrast_ratio:
+                issues.append({
+                    "type": "contrast_ratio",
+                    "severity": "error",
+                    "colors": [color],
+                    "white_contrast": round(white_contrast, 2),
+                    "black_contrast": round(black_contrast, 2),
+                    "required": min_contrast_ratio,
+                    "message": f"Insufficient contrast against both white ({white_contrast:.1f}:1) and black ({black_contrast:.1f}:1) backgrounds"
+                })
+
+        # Generate recommendations
+        recommendations = self._generate_recommendations(issues)
+
+        # Calculate overall score
+        error_count = sum(1 for i in issues if i["severity"] == "error")
+        warning_count = sum(1 for i in issues if i["severity"] == "warning")
+
+        if error_count == 0 and warning_count == 0:
+            score = "A"
+        elif error_count == 0 and warning_count <= 2:
+            score = "B"
+        elif error_count <= 2:
+            score = "C"
+        else:
+            score = "D"
+
+        return {
+            "colors_checked": normalized_colors,
+            "overall_score": score,
+            "issue_count": len(issues),
+            "issues": issues,
+            "simulations": simulations,
+            "recommendations": recommendations,
+            "safe_palettes": SAFE_PALETTES
+        }
+
+    async def accessibility_validate_theme(
+        self,
+        theme_name: str
+    ) -> Dict[str, Any]:
+        """
+        Validate a theme's colors for accessibility.
+
+        Args:
+            theme_name: Theme name to validate
+
+        Returns:
+            Dict with accessibility validation results
+        """
+        if not self.theme_store:
+            return {
+                "error": "Theme store not configured",
+                "theme_name": theme_name
+            }
+
+        theme = self.theme_store.get_theme(theme_name)
+        if not theme:
+            available = self.theme_store.list_themes()
+            return {
+                "error": f"Theme '{theme_name}' not found. Available: {available}",
+                "theme_name": theme_name
+            }
+
+        # Extract colors from theme
+        colors = []
+        tokens = theme.get("tokens", {})
+        color_tokens = tokens.get("colors", {})
+
+        def extract_colors(obj, prefix=""):
+            """Recursively extract color values."""
+            if isinstance(obj, str) and (obj.startswith('#') or len(obj) == 6):
+                colors.append(obj if obj.startswith('#') else f'#{obj}')
+            elif isinstance(obj, dict):
+                for key, value in obj.items():
+                    extract_colors(value, f"{prefix}.{key}")
+            elif isinstance(obj, list):
+                for item in obj:
+                    extract_colors(item, prefix)
+
+        extract_colors(color_tokens)
+
+        # Validate extracted colors
+        result = await self.accessibility_validate_colors(colors)
+        result["theme_name"] = theme_name
+
+        # Add theme-specific checks
+        primary = color_tokens.get("primary")
+        background = color_tokens.get("background", {})
+        text = color_tokens.get("text", {})
+
+        if primary and background:
+            bg_color = background.get("base") if isinstance(background, dict) else background
+            if bg_color:
+                contrast = self._get_contrast_ratio(primary, bg_color)
+                if contrast < 4.5:
+                    result["issues"].append({
+                        "type": "primary_contrast",
+                        "severity": "error",
+                        "colors": [primary, bg_color],
+                        "ratio": round(contrast, 2),
+                        "required": 4.5,
+                        "message": f"Primary color has insufficient contrast ({contrast:.1f}:1) against background"
+                    })
+
+        return result
+
+    async def accessibility_suggest_alternative(
+        self,
+        color: str,
+        deficiency_type: str
+    ) -> Dict[str, Any]:
+        """
+        Suggest accessible alternative colors.
+
+        Args:
+            color: Original hex color
+            deficiency_type: Type of color blindness to optimize for
+
+        Returns:
+            Dict with alternative color suggestions
+        """
+        rgb = self._hex_to_rgb(color)
+
+        suggestions = []
+
+        # Suggest shifting hue while maintaining saturation and brightness
+        # For red-green deficiency, shift toward blue or yellow
+        if deficiency_type in ["deuteranopia", "protanopia"]:
+            # Shift toward blue
+            blue_shift = self._rgb_to_hex((
+                max(0, rgb[0] - 50),
+                max(0, rgb[1] - 30),
+                min(255, rgb[2] + 80)
+            ))
+            suggestions.append({
+                "color": blue_shift,
+                "description": "Blue-shifted alternative",
+                "preserves": "approximate brightness"
+            })
+
+            # Shift toward yellow/orange
+            yellow_shift = self._rgb_to_hex((
+                min(255, rgb[0] + 50),
+                min(255, rgb[1] + 30),
+                max(0, rgb[2] - 80)
+            ))
+            suggestions.append({
+                "color": yellow_shift,
+                "description": "Yellow-shifted alternative",
+                "preserves": "approximate brightness"
+            })
+
+        elif deficiency_type == "tritanopia":
+            # For blue-yellow deficiency, shift toward red or green
+            red_shift = self._rgb_to_hex((
+                min(255, rgb[0] + 60),
+                max(0, rgb[1] - 20),
+                max(0, rgb[2] - 40)
+            ))
+            suggestions.append({
+                "color": red_shift,
+                "description": "Red-shifted alternative",
+                "preserves": "approximate brightness"
+            })
+
+        # Add safe palette suggestions
+        for palette_name, palette in SAFE_PALETTES.items():
+            # Find closest color in safe palette
+            min_distance = float('inf')
+            closest = None
+            for safe_color in palette["colors"]:
+                distance = self._get_color_distance(color, safe_color)
+                if distance < min_distance:
+                    min_distance = distance
+                    closest = safe_color
+
+            if closest:
+                suggestions.append({
+                    "color": closest,
+                    "description": f"From {palette['name']} palette",
+                    "palette": palette_name
+                })
+
+        return {
+            "original_color": color,
+            "deficiency_type": deficiency_type,
+            "suggestions": suggestions[:5]  # Limit to 5 suggestions
+        }
+
+    def _generate_recommendations(self, issues: List[Dict[str, Any]]) -> List[str]:
+        """Generate actionable recommendations based on issues."""
+        recommendations = []
+
+        # Check for distinguishability issues
+        distinguishability_issues = [i for i in issues if i["type"] == "distinguishability"]
+        if distinguishability_issues:
+            affected_types = set()
+            for issue in distinguishability_issues:
+                affected_types.update(issue.get("affected_by", []))
+
+            if "deuteranopia" in affected_types or "protanopia" in affected_types:
+                recommendations.append(
+                    "Avoid using red and green as the only differentiators - "
+                    "add patterns, shapes, or labels"
+                )
+
+            recommendations.append(
+                "Consider using a color-blind safe palette like Okabe-Ito or IBM Design"
+            )
+
+        # Check for contrast issues
+        contrast_issues = [i for i in issues if i["type"] in ["contrast_ratio", "primary_contrast"]]
+        if contrast_issues:
+            recommendations.append(
+                "Increase contrast by darkening colors for light backgrounds "
+                "or lightening for dark backgrounds"
+            )
+            recommendations.append(
+                "Use WCAG contrast checker tools to verify text readability"
+            )
+
+        # General recommendations
+        if len(issues) > 0:
+            recommendations.append(
+                "Add secondary visual cues (icons, patterns, labels) "
+                "to not rely solely on color"
+            )
+
+        if not recommendations:
+            recommendations.append(
+                "Color palette appears accessible! Consider adding patterns "
+                "for additional distinguishability"
+            )
+
+        return recommendations

mcp-servers/viz-platform/mcp_server/chart_tools.py

@@ -3,11 +3,21 @@ Chart creation tools using Plotly.
 
 Provides tools for creating data visualizations with automatic theme integration.
 """
+import base64
 import logging
+import os
 from typing import Dict, List, Optional, Any, Union
 
 logger = logging.getLogger(__name__)
 
+# Check for kaleido availability
+KALEIDO_AVAILABLE = False
+try:
+    import kaleido
+    KALEIDO_AVAILABLE = True
+except ImportError:
+    logger.debug("kaleido not installed - chart export will be unavailable")
+
 
 # Default color palette based on Mantine theme
 DEFAULT_COLORS = [
@@ -395,3 +405,129 @@ class ChartTools:
                 "figure": figure,
                 "interactions_added": []
             }
+
+    async def chart_export(
+        self,
+        figure: Dict[str, Any],
+        format: str = "png",
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        scale: float = 2.0,
+        output_path: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Export a Plotly chart to a static image format.
+
+        Args:
+            figure: Plotly figure JSON to export
+            format: Output format - png, svg, or pdf
+            width: Image width in pixels (default: from figure or 1200)
+            height: Image height in pixels (default: from figure or 800)
+            scale: Resolution scale factor (default: 2 for retina)
+            output_path: Optional file path to save the image
+
+        Returns:
+            Dict with:
+                - image_data: Base64-encoded image (if no output_path)
+                - file_path: Path to saved file (if output_path provided)
+                - format: Export format used
+                - dimensions: {width, height, scale}
+                - error: Error message if export failed
+        """
+        # Validate format
+        valid_formats = ['png', 'svg', 'pdf']
+        format = format.lower()
+        if format not in valid_formats:
+            return {
+                "error": f"Invalid format '{format}'. Must be one of: {valid_formats}",
+                "format": format,
+                "image_data": None
+            }
+
+        # Check kaleido availability
+        if not KALEIDO_AVAILABLE:
+            return {
+                "error": "kaleido package not installed. Install with: pip install kaleido",
+                "format": format,
+                "image_data": None,
+                "install_hint": "pip install kaleido"
+            }
+
+        # Validate figure
+        if not figure or 'data' not in figure:
+            return {
+                "error": "Invalid figure: must contain 'data' key",
+                "format": format,
+                "image_data": None
+            }
+
+        try:
+            import plotly.graph_objects as go
+            import plotly.io as pio
+
+            # Create Plotly figure object
+            fig = go.Figure(figure)
+
+            # Determine dimensions
+            layout = figure.get('layout', {})
+            export_width = width or layout.get('width') or 1200
+            export_height = height or layout.get('height') or 800
+
+            # Export to bytes
+            image_bytes = pio.to_image(
+                fig,
+                format=format,
+                width=export_width,
+                height=export_height,
+                scale=scale
+            )
+
+            result = {
+                "format": format,
+                "dimensions": {
+                    "width": export_width,
+                    "height": export_height,
+                    "scale": scale,
+                    "effective_width": int(export_width * scale),
+                    "effective_height": int(export_height * scale)
+                }
+            }
+
+            # Save to file or return base64
+            if output_path:
+                # Ensure directory exists
+                output_dir = os.path.dirname(output_path)
+                if output_dir and not os.path.exists(output_dir):
+                    os.makedirs(output_dir, exist_ok=True)
+
+                # Add extension if missing
+                if not output_path.endswith(f'.{format}'):
+                    output_path = f"{output_path}.{format}"
+
+                with open(output_path, 'wb') as f:
+                    f.write(image_bytes)
+
+                result["file_path"] = output_path
+                result["file_size_bytes"] = len(image_bytes)
+            else:
+                # Return as base64
+                result["image_data"] = base64.b64encode(image_bytes).decode('utf-8')
+                result["data_uri"] = f"data:image/{format};base64,{result['image_data']}"
+
+            return result
+
+        except ImportError as e:
+            logger.error(f"Chart export failed - missing dependency: {e}")
+            return {
+                "error": f"Missing dependency for export: {e}",
+                "format": format,
+                "image_data": None,
+                "install_hint": "pip install plotly kaleido"
+            }
+        except Exception as e:
+            logger.error(f"Chart export failed: {e}")
+            return {
+                "error": str(e),
+                "format": format,
+                "image_data": None
+            }

mcp-servers/viz-platform/mcp_server/layout_tools.py

@@ -10,6 +10,46 @@ from uuid import uuid4
 logger = logging.getLogger(__name__)
 
 
+# Standard responsive breakpoints (Mantine/Bootstrap-aligned)
+DEFAULT_BREAKPOINTS = {
+    "xs": {
+        "min_width": "0px",
+        "max_width": "575px",
+        "cols": 1,
+        "spacing": "xs",
+        "description": "Extra small devices (phones, portrait)"
+    },
+    "sm": {
+        "min_width": "576px",
+        "max_width": "767px",
+        "cols": 2,
+        "spacing": "sm",
+        "description": "Small devices (phones, landscape)"
+    },
+    "md": {
+        "min_width": "768px",
+        "max_width": "991px",
+        "cols": 6,
+        "spacing": "md",
+        "description": "Medium devices (tablets)"
+    },
+    "lg": {
+        "min_width": "992px",
+        "max_width": "1199px",
+        "cols": 12,
+        "spacing": "md",
+        "description": "Large devices (desktops)"
+    },
+    "xl": {
+        "min_width": "1200px",
+        "max_width": None,
+        "cols": 12,
+        "spacing": "lg",
+        "description": "Extra large devices (large desktops)"
+    }
+}
+
+
 # Layout templates
 TEMPLATES = {
     "dashboard": {
@@ -365,3 +405,149 @@ class LayoutTools:
             }
             for name, config in FILTER_TYPES.items()
         }
+
+    async def layout_set_breakpoints(
+        self,
+        layout_ref: str,
+        breakpoints: Dict[str, Dict[str, Any]],
+        mobile_first: bool = True
+    ) -> Dict[str, Any]:
+        """
+        Configure responsive breakpoints for a layout.
+
+        Args:
+            layout_ref: Layout name to configure
+            breakpoints: Breakpoint configuration dict:
+                {
+                    "xs": {"cols": 1, "spacing": "xs"},
+                    "sm": {"cols": 2, "spacing": "sm"},
+                    "md": {"cols": 6, "spacing": "md"},
+                    "lg": {"cols": 12, "spacing": "md"},
+                    "xl": {"cols": 12, "spacing": "lg"}
+                }
+            mobile_first: If True, use min-width media queries (default)
+
+        Returns:
+            Dict with:
+                - breakpoints: Complete breakpoint configuration
+                - css_media_queries: Generated CSS media queries
+                - mobile_first: Whether mobile-first approach is used
+        """
+        # Validate layout exists
+        if layout_ref not in self._layouts:
+            return {
+                "error": f"Layout '{layout_ref}' not found. Create it first with layout_create.",
+                "breakpoints": None
+            }
+
+        layout = self._layouts[layout_ref]
+
+        # Validate breakpoint names
+        valid_breakpoints = ["xs", "sm", "md", "lg", "xl"]
+        for bp_name in breakpoints.keys():
+            if bp_name not in valid_breakpoints:
+                return {
+                    "error": f"Invalid breakpoint '{bp_name}'. Must be one of: {valid_breakpoints}",
+                    "breakpoints": layout.get("breakpoints")
+                }
+
+        # Merge with defaults
+        merged_breakpoints = {}
+        for bp_name in valid_breakpoints:
+            default = DEFAULT_BREAKPOINTS[bp_name].copy()
+            if bp_name in breakpoints:
+                default.update(breakpoints[bp_name])
+            merged_breakpoints[bp_name] = default
+
+        # Validate spacing values
+        valid_spacing = ["xs", "sm", "md", "lg", "xl"]
+        for bp_name, bp_config in merged_breakpoints.items():
+            if "spacing" in bp_config and bp_config["spacing"] not in valid_spacing:
+                return {
+                    "error": f"Invalid spacing '{bp_config['spacing']}' for breakpoint '{bp_name}'. Must be one of: {valid_spacing}",
+                    "breakpoints": layout.get("breakpoints")
+                }
+
+        # Validate column counts
+        for bp_name, bp_config in merged_breakpoints.items():
+            if "cols" in bp_config:
+                cols = bp_config["cols"]
+                if not isinstance(cols, int) or cols < 1 or cols > 24:
+                    return {
+                        "error": f"Invalid cols '{cols}' for breakpoint '{bp_name}'. Must be integer between 1 and 24.",
+                        "breakpoints": layout.get("breakpoints")
+                    }
+
+        # Generate CSS media queries
+        css_queries = self._generate_media_queries(merged_breakpoints, mobile_first)
+
+        # Store in layout
+        layout["breakpoints"] = merged_breakpoints
+        layout["mobile_first"] = mobile_first
+        layout["responsive_css"] = css_queries
+
+        return {
+            "layout_ref": layout_ref,
+            "breakpoints": merged_breakpoints,
+            "mobile_first": mobile_first,
+            "css_media_queries": css_queries
+        }
+
+    def _generate_media_queries(
+        self,
+        breakpoints: Dict[str, Dict[str, Any]],
+        mobile_first: bool
+    ) -> List[str]:
+        """Generate CSS media queries for breakpoints."""
+        queries = []
+        bp_order = ["xs", "sm", "md", "lg", "xl"]
+
+        if mobile_first:
+            # Use min-width queries (mobile-first)
+            for bp_name in bp_order[1:]:  # Skip xs (base styles)
+                bp = breakpoints[bp_name]
+                min_width = bp.get("min_width", DEFAULT_BREAKPOINTS[bp_name]["min_width"])
+                if min_width and min_width != "0px":
+                    queries.append(f"@media (min-width: {min_width}) {{ /* {bp_name} styles */ }}")
+        else:
+            # Use max-width queries (desktop-first)
+            for bp_name in reversed(bp_order[:-1]):  # Skip xl (base styles)
+                bp = breakpoints[bp_name]
+                max_width = bp.get("max_width", DEFAULT_BREAKPOINTS[bp_name]["max_width"])
+                if max_width:
+                    queries.append(f"@media (max-width: {max_width}) {{ /* {bp_name} styles */ }}")
+
+        return queries
+
+    async def layout_get_breakpoints(self, layout_ref: str) -> Dict[str, Any]:
+        """
+        Get the breakpoint configuration for a layout.
+
+        Args:
+            layout_ref: Layout name
+
+        Returns:
+            Dict with breakpoint configuration
+        """
+        if layout_ref not in self._layouts:
+            return {
+                "error": f"Layout '{layout_ref}' not found.",
+                "breakpoints": None
+            }
+
+        layout = self._layouts[layout_ref]
+
+        return {
+            "layout_ref": layout_ref,
+            "breakpoints": layout.get("breakpoints", DEFAULT_BREAKPOINTS.copy()),
+            "mobile_first": layout.get("mobile_first", True),
+            "css_media_queries": layout.get("responsive_css", [])
+        }
+
+    def get_default_breakpoints(self) -> Dict[str, Any]:
+        """Get the default breakpoint configuration."""
+        return {
+            "breakpoints": DEFAULT_BREAKPOINTS.copy(),
+            "description": "Standard responsive breakpoints aligned with Mantine/Bootstrap",
+            "mobile_first": True
+        }

mcp-servers/viz-platform/mcp_server/server.py

@@ -17,6 +17,7 @@ from .chart_tools import ChartTools
 from .layout_tools import LayoutTools
 from .theme_tools import ThemeTools
 from .page_tools import PageTools
+from .accessibility_tools import AccessibilityTools
 
 # Suppress noisy MCP validation warnings on stderr
 logging.basicConfig(level=logging.INFO)
@@ -36,6 +37,7 @@ class VizPlatformMCPServer:
         self.layout_tools = LayoutTools()
         self.theme_tools = ThemeTools()
         self.page_tools = PageTools()
+        self.accessibility_tools = AccessibilityTools(theme_store=self.theme_tools.store)
 
     async def initialize(self):
         """Initialize server and load configuration."""
@@ -198,6 +200,46 @@ class VizPlatformMCPServer:
                 }
             ))
 
+            # Chart export tool (Issue #247)
+            tools.append(Tool(
+                name="chart_export",
+                description=(
+                    "Export a Plotly chart to static image format (PNG, SVG, PDF). "
+                    "Requires kaleido package. Returns base64 image data or saves to file."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "figure": {
+                            "type": "object",
+                            "description": "Plotly figure JSON to export"
+                        },
+                        "format": {
+                            "type": "string",
+                            "enum": ["png", "svg", "pdf"],
+                            "description": "Output format (default: png)"
+                        },
+                        "width": {
+                            "type": "integer",
+                            "description": "Image width in pixels (default: 1200)"
+                        },
+                        "height": {
+                            "type": "integer",
+                            "description": "Image height in pixels (default: 800)"
+                        },
+                        "scale": {
+                            "type": "number",
+                            "description": "Resolution scale factor (default: 2 for retina)"
+                        },
+                        "output_path": {
+                            "type": "string",
+                            "description": "Optional file path to save image"
+                        }
+                    },
+                    "required": ["figure"]
+                }
+            ))
+
             # Layout tools (Issue #174)
             tools.append(Tool(
                 name="layout_create",
@@ -280,6 +322,36 @@ class VizPlatformMCPServer:
                 }
             ))
 
+            # Responsive breakpoints tool (Issue #249)
+            tools.append(Tool(
+                name="layout_set_breakpoints",
+                description=(
+                    "Configure responsive breakpoints for a layout. "
+                    "Supports xs, sm, md, lg, xl breakpoints with mobile-first approach. "
+                    "Each breakpoint can define cols, spacing, and other grid properties."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "layout_ref": {
+                            "type": "string",
+                            "description": "Layout name to configure"
+                        },
+                        "breakpoints": {
+                            "type": "object",
+                            "description": (
+                                "Breakpoint config: {xs: {cols, spacing}, sm: {...}, md: {...}, lg: {...}, xl: {...}}"
+                            )
+                        },
+                        "mobile_first": {
+                            "type": "boolean",
+                            "description": "Use mobile-first (min-width) media queries (default: true)"
+                        }
+                    },
+                    "required": ["layout_ref", "breakpoints"]
+                }
+            ))
+
             # Theme tools (Issue #175)
             tools.append(Tool(
                 name="theme_create",
@@ -451,6 +523,77 @@ class VizPlatformMCPServer:
                 }
             ))
 
+            # Accessibility tools (Issue #248)
+            tools.append(Tool(
+                name="accessibility_validate_colors",
+                description=(
+                    "Validate colors for color blind accessibility. "
+                    "Checks contrast ratios for deuteranopia, protanopia, tritanopia. "
+                    "Returns issues, simulations, and accessible palette suggestions."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "colors": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "List of hex colors to validate (e.g., ['#228be6', '#40c057'])"
+                        },
+                        "check_types": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Color blindness types to check: deuteranopia, protanopia, tritanopia (default: all)"
+                        },
+                        "min_contrast_ratio": {
+                            "type": "number",
+                            "description": "Minimum WCAG contrast ratio (default: 4.5 for AA)"
+                        }
+                    },
+                    "required": ["colors"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="accessibility_validate_theme",
+                description=(
+                    "Validate a theme's colors for accessibility. "
+                    "Extracts all colors from theme tokens and checks for color blind safety."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "theme_name": {
+                            "type": "string",
+                            "description": "Theme name to validate"
+                        }
+                    },
+                    "required": ["theme_name"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="accessibility_suggest_alternative",
+                description=(
+                    "Suggest accessible alternative colors for a given color. "
+                    "Provides alternatives optimized for specific color blindness types."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "color": {
+                            "type": "string",
+                            "description": "Hex color to find alternatives for"
+                        },
+                        "deficiency_type": {
+                            "type": "string",
+                            "enum": ["deuteranopia", "protanopia", "tritanopia"],
+                            "description": "Color blindness type to optimize for"
+                        }
+                    },
+                    "required": ["color", "deficiency_type"]
+                }
+            ))
+
             return tools
 
         @self.server.call_tool()
@@ -524,6 +667,26 @@ class VizPlatformMCPServer:
                         text=json.dumps(result, indent=2)
                     )]
 
+                elif name == "chart_export":
+                    figure = arguments.get('figure')
+                    if not figure:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "figure is required"}, indent=2)
+                        )]
+                    result = await self.chart_tools.chart_export(
+                        figure=figure,
+                        format=arguments.get('format', 'png'),
+                        width=arguments.get('width'),
+                        height=arguments.get('height'),
+                        scale=arguments.get('scale', 2.0),
+                        output_path=arguments.get('output_path')
+                    )
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
                 # Layout tools
                 elif name == "layout_create":
                     layout_name = arguments.get('name')
@@ -568,6 +731,23 @@ class VizPlatformMCPServer:
                         text=json.dumps(result, indent=2)
                     )]
 
+                elif name == "layout_set_breakpoints":
+                    layout_ref = arguments.get('layout_ref')
+                    breakpoints = arguments.get('breakpoints', {})
+                    mobile_first = arguments.get('mobile_first', True)
+                    if not layout_ref:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "layout_ref is required"}, indent=2)
+                        )]
+                    result = await self.layout_tools.layout_set_breakpoints(
+                        layout_ref, breakpoints, mobile_first
+                    )
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
                 # Theme tools
                 elif name == "theme_create":
                     theme_name = arguments.get('name')
@@ -669,6 +849,53 @@ class VizPlatformMCPServer:
                         text=json.dumps(result, indent=2)
                     )]
 
+                # Accessibility tools
+                elif name == "accessibility_validate_colors":
+                    colors = arguments.get('colors')
+                    if not colors:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "colors list is required"}, indent=2)
+                        )]
+                    result = await self.accessibility_tools.accessibility_validate_colors(
+                        colors=colors,
+                        check_types=arguments.get('check_types'),
+                        min_contrast_ratio=arguments.get('min_contrast_ratio', 4.5)
+                    )
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "accessibility_validate_theme":
+                    theme_name = arguments.get('theme_name')
+                    if not theme_name:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "theme_name is required"}, indent=2)
+                        )]
+                    result = await self.accessibility_tools.accessibility_validate_theme(theme_name)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "accessibility_suggest_alternative":
+                    color = arguments.get('color')
+                    deficiency_type = arguments.get('deficiency_type')
+                    if not color or not deficiency_type:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "color and deficiency_type are required"}, indent=2)
+                        )]
+                    result = await self.accessibility_tools.accessibility_suggest_alternative(
+                        color, deficiency_type
+                    )
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
                 raise ValueError(f"Unknown tool: {name}")
 
             except Exception as e:

mcp-servers/viz-platform/requirements.txt

@@ -5,6 +5,7 @@ mcp>=0.9.0
 plotly>=5.18.0
 dash>=2.14.0
 dash-mantine-components>=2.0.0
+kaleido>=0.2.1  # For chart export (PNG, SVG, PDF)
 
 # Utilities
 python-dotenv>=1.0.0

mcp-servers/viz-platform/run.sh

@@ -1,4 +1,8 @@
 #!/bin/bash
+# Capture original working directory before any cd operations
+# This should be the user's project directory when launched by Claude Code
+export CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/viz-platform/.venv"
 LOCAL_VENV="$SCRIPT_DIR/.venv"

mcp-servers/viz-platform/tests/test_accessibility_tools.py

@@ -0,0 +1,195 @@
+"""
+Tests for accessibility validation tools.
+"""
+import pytest
+from mcp_server.accessibility_tools import AccessibilityTools
+
+
+@pytest.fixture
+def tools():
+    """Create AccessibilityTools instance."""
+    return AccessibilityTools()
+
+
+class TestHexToRgb:
+    """Tests for _hex_to_rgb method."""
+
+    def test_hex_to_rgb_6_digit(self, tools):
+        """Test 6-digit hex conversion."""
+        assert tools._hex_to_rgb("#FF0000") == (255, 0, 0)
+        assert tools._hex_to_rgb("#00FF00") == (0, 255, 0)
+        assert tools._hex_to_rgb("#0000FF") == (0, 0, 255)
+
+    def test_hex_to_rgb_3_digit(self, tools):
+        """Test 3-digit hex conversion."""
+        assert tools._hex_to_rgb("#F00") == (255, 0, 0)
+        assert tools._hex_to_rgb("#0F0") == (0, 255, 0)
+        assert tools._hex_to_rgb("#00F") == (0, 0, 255)
+
+    def test_hex_to_rgb_lowercase(self, tools):
+        """Test lowercase hex conversion."""
+        assert tools._hex_to_rgb("#ff0000") == (255, 0, 0)
+
+
+class TestContrastRatio:
+    """Tests for _get_contrast_ratio method."""
+
+    def test_black_white_contrast(self, tools):
+        """Test black on white has maximum contrast."""
+        ratio = tools._get_contrast_ratio("#000000", "#FFFFFF")
+        assert ratio == pytest.approx(21.0, rel=0.01)
+
+    def test_same_color_contrast(self, tools):
+        """Test same color has minimum contrast."""
+        ratio = tools._get_contrast_ratio("#FF0000", "#FF0000")
+        assert ratio == pytest.approx(1.0, rel=0.01)
+
+    def test_symmetric_contrast(self, tools):
+        """Test contrast ratio is symmetric."""
+        ratio1 = tools._get_contrast_ratio("#228be6", "#FFFFFF")
+        ratio2 = tools._get_contrast_ratio("#FFFFFF", "#228be6")
+        assert ratio1 == pytest.approx(ratio2, rel=0.01)
+
+
+class TestColorBlindnessSimulation:
+    """Tests for _simulate_color_blindness method."""
+
+    def test_deuteranopia_simulation(self, tools):
+        """Test deuteranopia (green-blind) simulation."""
+        # Red and green should appear more similar
+        original_red = "#FF0000"
+        original_green = "#00FF00"
+
+        simulated_red = tools._simulate_color_blindness(original_red, "deuteranopia")
+        simulated_green = tools._simulate_color_blindness(original_green, "deuteranopia")
+
+        # They should be different from originals
+        assert simulated_red != original_red or simulated_green != original_green
+
+    def test_protanopia_simulation(self, tools):
+        """Test protanopia (red-blind) simulation."""
+        simulated = tools._simulate_color_blindness("#FF0000", "protanopia")
+        # Should return a modified color
+        assert simulated.startswith("#")
+        assert len(simulated) == 7
+
+    def test_tritanopia_simulation(self, tools):
+        """Test tritanopia (blue-blind) simulation."""
+        simulated = tools._simulate_color_blindness("#0000FF", "tritanopia")
+        # Should return a modified color
+        assert simulated.startswith("#")
+        assert len(simulated) == 7
+
+    def test_unknown_deficiency_returns_original(self, tools):
+        """Test unknown deficiency type returns original color."""
+        color = "#FF0000"
+        simulated = tools._simulate_color_blindness(color, "unknown")
+        assert simulated == color
+
+
+class TestAccessibilityValidateColors:
+    """Tests for accessibility_validate_colors method."""
+
+    @pytest.mark.asyncio
+    async def test_validate_single_color(self, tools):
+        """Test validating a single color."""
+        result = await tools.accessibility_validate_colors(["#228be6"])
+        assert "colors_checked" in result
+        assert "overall_score" in result
+        assert "issues" in result
+        assert "safe_palettes" in result
+
+    @pytest.mark.asyncio
+    async def test_validate_problematic_colors(self, tools):
+        """Test similar colors trigger warnings."""
+        # Use colors that are very close in hue, which should be harder to distinguish
+        result = await tools.accessibility_validate_colors(["#FF5555", "#FF6666"])
+        # Similar colors should trigger distinguishability warnings
+        assert "issues" in result
+        # The validation should at least run without errors
+        assert "colors_checked" in result
+        assert len(result["colors_checked"]) == 2
+
+    @pytest.mark.asyncio
+    async def test_validate_contrast_issue(self, tools):
+        """Test low contrast colors trigger contrast warnings."""
+        # Yellow on white has poor contrast
+        result = await tools.accessibility_validate_colors(["#FFFF00"])
+        # Check for contrast issues (yellow may have issues with both black and white)
+        assert "issues" in result
+
+    @pytest.mark.asyncio
+    async def test_validate_with_specific_types(self, tools):
+        """Test validating for specific color blindness types."""
+        result = await tools.accessibility_validate_colors(
+            ["#FF0000", "#00FF00"],
+            check_types=["deuteranopia"]
+        )
+        assert "simulations" in result
+        assert "deuteranopia" in result["simulations"]
+        assert "protanopia" not in result["simulations"]
+
+    @pytest.mark.asyncio
+    async def test_overall_score(self, tools):
+        """Test overall score is calculated."""
+        result = await tools.accessibility_validate_colors(["#228be6", "#ffffff"])
+        assert result["overall_score"] in ["A", "B", "C", "D"]
+
+    @pytest.mark.asyncio
+    async def test_recommendations_generated(self, tools):
+        """Test recommendations are generated for issues."""
+        result = await tools.accessibility_validate_colors(["#FF0000", "#00FF00"])
+        assert "recommendations" in result
+        assert len(result["recommendations"]) > 0
+
+
+class TestAccessibilitySuggestAlternative:
+    """Tests for accessibility_suggest_alternative method."""
+
+    @pytest.mark.asyncio
+    async def test_suggest_alternative_deuteranopia(self, tools):
+        """Test suggesting alternatives for deuteranopia."""
+        result = await tools.accessibility_suggest_alternative("#FF0000", "deuteranopia")
+        assert "original_color" in result
+        assert result["deficiency_type"] == "deuteranopia"
+        assert "suggestions" in result
+        assert len(result["suggestions"]) > 0
+
+    @pytest.mark.asyncio
+    async def test_suggest_alternative_tritanopia(self, tools):
+        """Test suggesting alternatives for tritanopia."""
+        result = await tools.accessibility_suggest_alternative("#0000FF", "tritanopia")
+        assert "suggestions" in result
+        assert len(result["suggestions"]) > 0
+
+    @pytest.mark.asyncio
+    async def test_suggestions_include_safe_palettes(self, tools):
+        """Test suggestions include colors from safe palettes."""
+        result = await tools.accessibility_suggest_alternative("#FF0000", "deuteranopia")
+        palette_suggestions = [
+            s for s in result["suggestions"]
+            if "palette" in s
+        ]
+        assert len(palette_suggestions) > 0
+
+
+class TestSafePalettes:
+    """Tests for safe palette constants."""
+
+    def test_safe_palettes_exist(self, tools):
+        """Test that safe palettes are defined."""
+        from mcp_server.accessibility_tools import SAFE_PALETTES
+        assert "categorical" in SAFE_PALETTES
+        assert "ibm" in SAFE_PALETTES
+        assert "okabe_ito" in SAFE_PALETTES
+        assert "tableau_colorblind" in SAFE_PALETTES
+
+    def test_safe_palettes_have_colors(self, tools):
+        """Test that safe palettes have color lists."""
+        from mcp_server.accessibility_tools import SAFE_PALETTES
+        for palette_name, palette in SAFE_PALETTES.items():
+            assert "colors" in palette
+            assert len(palette["colors"]) > 0
+            # All colors should be valid hex
+            for color in palette["colors"]:
+                assert color.startswith("#")

plugins/clarity-assist/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "clarity-assist",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Prompt optimization and requirement clarification with ND-friendly accommodations",
   "author": {
     "name": "Leo Miranda",

plugins/clarity-assist/README.md

@@ -1,99 +0,0 @@
-# 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]
-```
-
-## Integration
-
-For CLAUDE.md integration instructions, see `claude-md-integration.md`.
-
-## License
-
-MIT

plugins/clarity-assist/agents/clarity-coach.md

@@ -1,5 +1,23 @@
+---
+name: clarity-coach
+description: Patient, structured coach helping users articulate requirements clearly. Uses neurodivergent-friendly communication patterns.
+model: sonnet
+permissionMode: default
+disallowedTools: Write, Edit, MultiEdit
+---
+
 # Clarity Coach Agent
 
+## Visual Output Requirements
+
+**MANDATORY: Display header at start of every response.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  💬 CLARITY-ASSIST · Clarity Coach                               │
+└──────────────────────────────────────────────────────────────────┘
+```
+
 ## Role
 
 You are a patient, structured coach specializing in helping users articulate their requirements clearly. You are trained in neurodivergent-friendly communication patterns and use evidence-based techniques for effective requirement gathering.

plugins/clarity-assist/commands/clarify.md

@@ -1,5 +1,13 @@
 # /clarify - Full Prompt Optimization
 
+## Visual Output
+
+```
++----------------------------------------------------------------------+
+|  CLARITY-ASSIST - Prompt Optimization                                |
++----------------------------------------------------------------------+
+```
+
 ## Purpose
 
 Transform vague, incomplete, or ambiguous requests into clear, actionable specifications using the 4-D methodology with neurodivergent-friendly accommodations.
@@ -11,127 +19,46 @@ Transform vague, incomplete, or ambiguous requests into clear, actionable specif
 - Tasks requiring significant context gathering
 - When user seems uncertain about what they want
 
-## 4-D Methodology
+## Skills to Load
 
-### Phase 1: Deconstruct
+Load these skills before proceeding:
 
-Break down the user's request into components:
+- `skills/4d-methodology.md` - Core 4-phase process
+- `skills/nd-accommodations.md` - ND-friendly question patterns
+- `skills/clarification-techniques.md` - Anti-patterns and templates
+- `skills/escalation-patterns.md` - When to adjust approach
 
-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
+## Workflow
 
-### 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'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]
-```
+1. **Deconstruct** - Break down request into components
+2. **Diagnose** - Identify gaps and conflicts
+3. **Develop** - Gather clarifications via structured questions
+4. **Deliver** - Present refined specification
+5. **Offer RFC Creation** - For feature work, offer to save as RFC
 
 ## Output Format
 
-After gathering all necessary information, use the Deliver phase format to present the clarified specification for user confirmation.
+Use the Deliver phase template from `skills/4d-methodology.md` 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

@@ -1,5 +1,13 @@
 # /quick-clarify - Rapid Clarification Mode
 
+## Visual Output
+
+```
++----------------------------------------------------------------------+
+|  CLARITY-ASSIST - Quick Clarify                                      |
++----------------------------------------------------------------------+
+```
+
 ## Purpose
 
 Single-pass clarification for requests that are mostly clear but need minor disambiguation.
@@ -11,74 +19,27 @@ 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
 
-## Process
+## Skills to Load
 
-### Step 1: Echo Understanding
+- `skills/nd-accommodations.md` - ND-friendly question patterns
+- `skills/clarification-techniques.md` - Echo and micro-summary techniques
+- `skills/escalation-patterns.md` - When to escalate to full /clarify
 
-Restate what you understood in a single sentence:
+## Workflow
 
-```
-"I understand you want [X] that does [Y]."
-```
-
-### 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')"
-```
+1. **Echo Understanding** - Restate in a single sentence
+2. **Quick Disambiguation** - Ask ONE multiple-choice question if needed
+3. **Proceed or Confirm** - Start work or offer micro-summary
 
 ## Output Format
 
-For quick-clarify, no formal specification document is needed. Just proceed with the task after brief confirmation, documenting assumptions inline with the work.
+No formal specification document needed. Proceed 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/docs/ND-SUPPORT.md

@@ -0,0 +1,328 @@
+# Neurodivergent Support in clarity-assist
+
+This document describes how clarity-assist is designed to support users with neurodivergent traits, including ADHD, autism, anxiety, and other conditions that affect executive function, sensory processing, or cognitive style.
+
+## Overview
+
+### Purpose
+
+clarity-assist exists to help all users transform vague or incomplete requests into clear, actionable specifications. For neurodivergent users specifically, it addresses common challenges:
+
+- **Executive function difficulties** - Breaking down complex tasks, getting started, managing scope
+- **Working memory limitations** - Keeping track of context across long conversations
+- **Decision fatigue** - Facing too many open-ended choices
+- **Processing style differences** - Preferring structured, predictable interactions
+- **Anxiety around uncertainty** - Needing clear expectations and explicit confirmation
+
+### Philosophy
+
+Our design philosophy centers on three principles:
+
+1. **Reduce cognitive load** - Never force the user to hold too much in their head at once
+2. **Provide structure** - Use consistent, predictable patterns for all interactions
+3. **Respect different communication styles** - Accommodate rather than assume one "right" way to think
+
+## Features for ND Users
+
+### 1. Reduced Cognitive Load
+
+**Prompt Simplification**
+- The 4-D methodology (Deconstruct, Diagnose, Develop, Deliver) breaks down complex requests into manageable phases
+- Users never need to specify everything upfront - clarification happens incrementally
+
+**Task Breakdown**
+- Large requests are decomposed into explicit components
+- Dependencies and relationships are surfaced rather than left implicit
+- Scope boundaries are clearly defined (in-scope vs. out-of-scope)
+
+### 2. Structured Output
+
+**Consistent Formatting**
+- Every clarification session produces the same structured specification:
+  - Summary (1-2 sentences)
+  - Scope (In/Out)
+  - Requirements table (numbered, prioritized)
+  - Assumptions list
+- This predictability reduces the mental effort of parsing responses
+
+**Predictable Patterns**
+- Questions always follow the same format
+- Progress summaries appear at regular intervals
+- Escalation (simple to complex) is always offered, never forced
+
+**Bulleted Lists Over Prose**
+- Requirements are presented as scannable lists, not paragraphs
+- Options are numbered for easy reference
+- Key information is highlighted with bold labels
+
+### 3. Customizable Verbosity
+
+**Detail Levels**
+- `/clarify` - Full methodology for complex requests (more thorough, more questions)
+- `/quick-clarify` - Rapid mode for simple disambiguation (fewer questions, faster)
+
+**User Control**
+- Users can always say "that's enough detail" to end questioning early
+- The plugin offers to break sessions into smaller parts
+- "Good enough for now" is explicitly validated as an acceptable outcome
+
+### 4. Vagueness Detection
+
+The `UserPromptSubmit` hook automatically detects prompts that might benefit from clarification and gently suggests using `/clarify`.
+
+**Detection Signals**
+- Short prompts (< 10 words) without specific technical terms
+- Vague action phrases: "help me", "fix this", "make it better"
+- Ambiguous scope words: "somehow", "something", "stuff", "etc."
+- Open questions without context
+
+**Non-Blocking Approach**
+- The hook never prevents you from proceeding
+- It provides a suggestion with a vagueness score (percentage)
+- You can disable auto-suggestions entirely via environment variable
+
+### 5. Focus Aids
+
+**Task Prioritization**
+- Requirements are tagged as Must/Should/Could/Won't (MoSCoW)
+- Critical items are separated from nice-to-haves
+- Scope creep is explicitly called out and deferred
+
+**Context Switching Warnings**
+- When questions touch multiple areas, the plugin acknowledges the complexity
+- Offers to focus on one aspect at a time
+- Summarizes frequently to rebuild context after interruptions
+
+## How It Works
+
+### The UserPromptSubmit Hook
+
+When you submit a prompt, the vagueness detection hook (`hooks/vagueness-check.sh`) runs automatically:
+
+```
+User submits prompt
+       |
+       v
+Hook reads prompt from stdin
+       |
+       v
+Skip if: empty, starts with /, or contains file paths
+       |
+       v
+Calculate vagueness score (0.0 - 1.0)
+  - Short prompts: +0.3
+  - Vague action phrases: +0.2
+  - Ambiguous scope words: +0.15
+  - Missing technical specifics: +0.2
+  - Short questions without context: +0.15
+       |
+       v
+If score >= threshold (default 0.6):
+  - Output gentle suggestion with [clarity-assist] prefix
+  - Show vagueness percentage
+       |
+       v
+Exit 0 (always non-blocking)
+```
+
+### Example Hook Output
+
+```
+[clarity-assist] Your prompt could benefit from more clarity.
+[clarity-assist] Consider running /clarity-assist to refine your request.
+[clarity-assist] (Vagueness score: 65% - this is a suggestion, not a block)
+```
+
+### The 4-D Methodology
+
+| Phase | What Happens | ND Benefit |
+|-------|--------------|------------|
+| **Deconstruct** | Break request into components | Shows the full picture without overwhelming |
+| **Diagnose** | Identify gaps and conflicts | Surfaces hidden assumptions |
+| **Develop** | Ask structured questions | Option-based, chunked, contextual |
+| **Deliver** | Produce specification | Consistent, scannable format |
+
+## Usage Examples
+
+### Before: Vague Request
+
+```
+User: Make the app faster
+```
+
+This triggers vagueness detection because:
+- Short (4 words)
+- Vague action ("make")
+- No specific technical context
+- No measurable outcome
+
+### After: Clarified with /clarify
+
+```
+User: /clarify Make the app faster
+
+Claude: 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]
+```
+
+```
+User: 1
+
+Claude: Initial page load - got it.
+
+**What's an acceptable load time for you?**
+1. Under 1 second (aggressive)
+2. Under 2 seconds (standard)
+3. Under 3 seconds (relaxed)
+4. I don't have a specific target
+
+[This helps me know whether to suggest quick wins or a major optimization effort]
+```
+
+After 2-3 more questions, the user receives:
+
+```markdown
+## Clarified Request
+
+### Summary
+Optimize initial page load time to under 2 seconds by addressing bundle size and initial render blocking resources.
+
+### Scope
+**In Scope:**
+- Bundle analysis and splitting
+- Lazy loading non-critical components
+- Image optimization
+- CSS/JS minification check
+
+**Out of Scope:**
+- Backend API optimization
+- Database query performance
+- CDN setup
+
+### Requirements
+| # | Requirement | Priority | Notes |
+|---|-------------|----------|-------|
+| 1 | Page loads in < 2s on 4G | Must | Measured via Lighthouse |
+| 2 | Largest contentful paint < 1.5s | Should | Core Web Vital |
+| 3 | No layout shift after load | Should | CLS < 0.1 |
+
+### Assumptions
+- Current load time is > 3 seconds (based on "too long" description)
+- Target browsers: modern evergreen (Chrome, Firefox, Safari)
+- Build tooling already configured (webpack/vite)
+```
+
+### Common Patterns Detected
+
+| Pattern | Example | What It Triggers |
+|---------|---------|------------------|
+| Missing context | "Fix the bug" | "Which bug? In which file or feature?" |
+| Ambiguous scope | "Update the user stuff" | "What specifically needs updating?" |
+| Unclear goals | "Make it better" | "Better in what way? Faster? Cleaner? More features?" |
+| Implicit knowledge | "Do it like last time" | "I don't have context from previous sessions" |
+| Conflicting requests | "Keep it simple but add everything" | "Which matters more: simplicity or completeness?" |
+
+### Quick-Clarify Example
+
+For simpler requests that just need minor disambiguation:
+
+```
+User: /quick-clarify Add a delete button to the user list
+
+Claude: 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]
+```
+
+```
+User: 1
+
+Claude: Got it. I'll implement a delete button with confirmation dialog. Starting now.
+```
+
+## Configuration Options
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLARITY_ASSIST_AUTO_SUGGEST` | `true` | Enable/disable automatic vagueness detection |
+| `CLARITY_ASSIST_VAGUENESS_THRESHOLD` | `0.6` | Score threshold to trigger suggestion (0.0-1.0) |
+
+### Disabling Auto-Suggestions
+
+If you find the vagueness detection unhelpful, disable it in your shell profile or `.env`:
+
+```bash
+export CLARITY_ASSIST_AUTO_SUGGEST=false
+```
+
+### Adjusting Sensitivity
+
+To make detection more or less sensitive:
+
+```bash
+# More sensitive (suggests more often)
+export CLARITY_ASSIST_VAGUENESS_THRESHOLD=0.4
+
+# Less sensitive (only very vague prompts)
+export CLARITY_ASSIST_VAGUENESS_THRESHOLD=0.8
+```
+
+## Tips for ND Users
+
+### If You're Feeling Overwhelmed
+
+- Use `/quick-clarify` instead of `/clarify` for faster interactions
+- Say "let's focus on just one thing" to narrow scope
+- Ask to "pause and summarize" at any point
+- It's OK to say "I don't know" - the plugin will offer concrete alternatives
+
+### If You Have Executive Function Challenges
+
+- Start with `/clarify` even for tasks you think are simple - it helps with planning
+- The structured specification can serve as a checklist
+- Use the scope boundaries to prevent scope creep
+
+### If You Prefer Detailed Structure
+
+- The 4-D methodology provides a predictable framework
+- All output follows consistent formatting
+- Questions always offer numbered options
+
+### If You Have Anxiety About Getting It Right
+
+- The plugin validates "good enough for now" as acceptable
+- You can always revisit and change earlier answers
+- Assumptions are explicitly listed - nothing is hidden
+
+## Accessibility Notes
+
+- All output uses standard markdown that works with screen readers
+- No time pressure - take as long as you need between responses
+- Questions are designed to be answerable without deep context retrieval
+- Visual patterns (bold, bullets, tables) create scannable structure
+
+## Feedback
+
+If you have suggestions for improving neurodivergent support in clarity-assist, please open an issue at:
+
+https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/issues
+
+Include the label `clarity-assist` and describe:
+- What challenge you faced
+- What would have helped
+- Any specific accommodations you'd like to see

plugins/clarity-assist/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/vagueness-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,256 @@
+#!/bin/bash
+# clarity-assist vagueness detection hook
+# Analyzes user prompts for vagueness and suggests /clarity-assist when beneficial
+# All output MUST have [clarity-assist] prefix
+# This is a NON-BLOCKING hook - always exits 0
+
+PREFIX="[clarity-assist]"
+
+# Check if auto-suggest is enabled (default: true)
+AUTO_SUGGEST="${CLARITY_ASSIST_AUTO_SUGGEST:-true}"
+if [[ "$AUTO_SUGGEST" != "true" ]]; then
+    exit 0
+fi
+
+# Threshold for vagueness score (default: 0.6)
+THRESHOLD="${CLARITY_ASSIST_VAGUENESS_THRESHOLD:-0.6}"
+
+# Read user prompt from stdin
+PROMPT=""
+if [[ -t 0 ]]; then
+    # No stdin available
+    exit 0
+else
+    PROMPT=$(cat)
+fi
+
+# Skip empty prompts
+if [[ -z "$PROMPT" ]]; then
+    exit 0
+fi
+
+# Skip if prompt is a command (starts with /)
+if [[ "$PROMPT" =~ ^[[:space:]]*/[a-zA-Z] ]]; then
+    exit 0
+fi
+
+# Skip if prompt mentions specific files or paths
+if [[ "$PROMPT" =~ \.(py|js|ts|sh|md|json|yaml|yml|txt|css|html|go|rs|java|c|cpp|h)([[:space:]]|$|[^a-zA-Z]) ]] || \
+   [[ "$PROMPT" =~ [/\\][a-zA-Z0-9_-]+[/\\] ]] || \
+   [[ "$PROMPT" =~ (src|lib|test|docs|plugins|hooks|commands)/ ]]; then
+    exit 0
+fi
+
+# Initialize vagueness score
+SCORE=0
+
+# Count words in the prompt
+WORD_COUNT=$(echo "$PROMPT" | wc -w | tr -d ' ')
+
+# ============================================================================
+# Vagueness Signal Detection
+# ============================================================================
+
+# Signal 1: Very short prompts (< 10 words) are often vague
+if [[ "$WORD_COUNT" -lt 10 ]]; then
+    # But very short specific commands are OK
+    if [[ "$WORD_COUNT" -lt 3 ]]; then
+        # Extremely short - probably intentional or a command
+        :
+    else
+        SCORE=$(echo "$SCORE + 0.3" | bc)
+    fi
+fi
+
+# Signal 2: Vague action phrases (no specific outcome)
+VAGUE_ACTIONS=(
+    "help me"
+    "help with"
+    "do something"
+    "work on"
+    "look at"
+    "check this"
+    "fix it"
+    "fix this"
+    "make it better"
+    "make this better"
+    "improve it"
+    "improve this"
+    "update this"
+    "update it"
+    "change it"
+    "change this"
+    "can you"
+    "could you"
+    "would you"
+    "please help"
+)
+
+PROMPT_LOWER=$(echo "$PROMPT" | tr '[:upper:]' '[:lower:]')
+
+for phrase in "${VAGUE_ACTIONS[@]}"; do
+    if [[ "$PROMPT_LOWER" == *"$phrase"* ]]; then
+        SCORE=$(echo "$SCORE + 0.2" | bc)
+        break
+    fi
+done
+
+# Signal 3: Ambiguous scope indicators
+AMBIGUOUS_SCOPE=(
+    "somehow"
+    "something"
+    "somewhere"
+    "anything"
+    "whatever"
+    "stuff"
+    "things"
+    "etc"
+    "and so on"
+)
+
+for word in "${AMBIGUOUS_SCOPE[@]}"; do
+    if [[ "$PROMPT_LOWER" == *"$word"* ]]; then
+        SCORE=$(echo "$SCORE + 0.15" | bc)
+        break
+    fi
+done
+
+# Signal 4: Missing context indicators (no reference to what/where)
+# Check if prompt lacks specificity markers
+HAS_SPECIFICS=false
+
+# Specific technical terms suggest clarity
+SPECIFIC_MARKERS=(
+    "function"
+    "class"
+    "method"
+    "variable"
+    "error"
+    "bug"
+    "test"
+    "api"
+    "endpoint"
+    "database"
+    "query"
+    "component"
+    "module"
+    "service"
+    "config"
+    "install"
+    "deploy"
+    "build"
+    "run"
+    "execute"
+    "create"
+    "delete"
+    "add"
+    "remove"
+    "implement"
+    "refactor"
+    "migrate"
+    "upgrade"
+    "debug"
+    "log"
+    "exception"
+    "stack"
+    "memory"
+    "performance"
+    "security"
+    "auth"
+    "token"
+    "session"
+    "route"
+    "controller"
+    "model"
+    "view"
+    "template"
+    "schema"
+    "migration"
+    "commit"
+    "branch"
+    "merge"
+    "pull"
+    "push"
+)
+
+for marker in "${SPECIFIC_MARKERS[@]}"; do
+    if [[ "$PROMPT_LOWER" == *"$marker"* ]]; then
+        HAS_SPECIFICS=true
+        break
+    fi
+done
+
+if [[ "$HAS_SPECIFICS" == false ]] && [[ "$WORD_COUNT" -gt 3 ]]; then
+    SCORE=$(echo "$SCORE + 0.2" | bc)
+fi
+
+# Signal 5: Question without context
+if [[ "$PROMPT" =~ \?$ ]] && [[ "$WORD_COUNT" -lt 8 ]]; then
+    # Short questions without specifics are often vague
+    if [[ "$HAS_SPECIFICS" == false ]]; then
+        SCORE=$(echo "$SCORE + 0.15" | bc)
+    fi
+fi
+
+# Cap score at 1.0
+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
+# ============================================================================
+
+# Compare score to threshold using bc
+if (( $(echo "$SCORE >= $THRESHOLD" | bc -l) )); then
+    # Format score as percentage for display
+    SCORE_PCT=$(echo "$SCORE * 100" | bc | cut -d'.' -f1)
+
+    # Gentle, non-blocking suggestion
+    echo "$PREFIX Your prompt could benefit from more clarity."
+    echo "$PREFIX Consider running /clarify 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
+exit 0

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

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

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

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

@@ -0,0 +1,74 @@
+# 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/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-config-maintainer",
-  "version": "1.0.0",
-  "description": "Maintains and optimizes CLAUDE.md configuration files for Claude Code projects",
+  "version": "1.2.0",
+  "description": "Maintains and optimizes CLAUDE.md and settings.local.json configuration files for Claude Code projects",
   "author": {
     "name": "Leo Miranda",
     "email": "leobmiranda@gmail.com"
@@ -14,7 +14,9 @@
     "configuration",
     "optimization",
     "claude-md",
-    "developer-tools"
+    "developer-tools",
+    "settings",
+    "permissions"
   ],
   "commands": ["./commands/"]
 }

plugins/claude-config-maintainer/README.md

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

@@ -1,12 +1,25 @@
 ---
 name: maintainer
 description: CLAUDE.md optimization and maintenance agent
+model: sonnet
+permissionMode: acceptEdits
+skills: visual-header, settings-optimization
 ---
 
 # CLAUDE.md Maintainer Agent
 
 You are the **Maintainer Agent** - a specialist in creating and optimizing CLAUDE.md configuration files for Claude Code projects. Your role is to ensure CLAUDE.md files are clear, concise, well-structured, and follow best practices.
 
+## Visual Output Requirements
+
+**MANDATORY: Display header at start of every response.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ⚙️ CONFIG-MAINTAINER · CLAUDE.md Optimization                   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
 ## Your Personality
 
 **Optimization-Focused:**
@@ -104,7 +117,54 @@ Report plugin coverage percentage and offer to add missing integrations:
 - Display the integration content that would be added
 - Ask user for confirmation before modifying CLAUDE.md
 
-### 2. Optimize CLAUDE.md Structure
+### 2. Audit Settings Files
+
+When auditing settings files, perform:
+
+#### A. Permission Analysis
+
+Read `.claude/settings.local.json` (primary) and check `.claude/settings.json` and `~/.claude.json` project entries (secondary).
+
+Evaluate using `skills/settings-optimization.md`:
+
+**Redundancy:**
+- Duplicate entries in allow/deny arrays
+- Subset patterns covered by broader patterns
+- Patterns that could be merged
+
+**Coverage:**
+- Common safe tools missing from allow list
+- MCP server tools not covered
+- Directory scopes with no matching permission
+
+**Safety Alignment:**
+- Deny rules cover secrets and destructive commands
+- Allow rules don't bypass active review layers
+- No overly broad patterns without justification
+
+**Profile Fit:**
+- Compare against recommended profile for the project's review architecture
+- Identify specific additions/removals to reach target profile
+
+#### B. Review Layer Verification
+
+Before recommending auto-allow patterns, verify active review layers:
+
+1. Read `plugins/*/hooks/hooks.json` for each installed plugin
+2. Map hook types (PreToolUse, PostToolUse) to tool matchers (Write, Edit, Bash)
+3. Confirm plugins are listed in `.claude-plugin/marketplace.json`
+4. Only recommend auto-allow for scopes covered by ≥2 verified review layers
+
+#### C. Settings Efficiency Score (100 points)
+
+| Category | Points |
+|----------|--------|
+| Redundancy | 25 |
+| Coverage | 25 |
+| Safety Alignment | 25 |
+| Profile Fit | 25 |
+
+### 3. Optimize CLAUDE.md Structure
 
 **Recommended Structure:**
 
@@ -139,7 +199,7 @@ Common issues and solutions.
 - Use headers that scan easily
 - Include examples where they add clarity
 
-### 3. Apply Best Practices
+### 4. Apply Best Practices
 
 **DO:**
 - Use clear, direct language
@@ -156,7 +216,7 @@ Common issues and solutions.
 - Add generic advice that applies to all projects
 - Use emojis unless project requires them
 
-### 4. Generate Improvement Reports
+### 5. Generate Improvement Reports
 
 After analyzing a CLAUDE.md, provide:
 
@@ -192,7 +252,7 @@ Suggested Actions:
 Would you like me to implement these improvements?
 ```
 
-### 5. Insert Plugin Integrations
+### 6. Insert Plugin Integrations
 
 When adding plugin integration content to CLAUDE.md:
 
@@ -227,7 +287,7 @@ Add this integration to CLAUDE.md?
 - Allow users to skip specific plugins they don't want documented
 - Preserve existing CLAUDE.md structure and content
 
-### 6. Create New CLAUDE.md Files
+### 7. Create New CLAUDE.md Files
 
 When creating a new CLAUDE.md:
 
@@ -267,6 +327,39 @@ 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/claude-md-integration.md

@@ -1,6 +1,6 @@
 ## CLAUDE.md Maintenance (claude-config-maintainer)
 
-This project uses the **claude-config-maintainer** plugin to analyze and optimize CLAUDE.md configuration files.
+This project uses the **claude-config-maintainer** plugin to analyze and optimize CLAUDE.md and settings.local.json configuration files.
 
 ### Available Commands
 
@@ -9,8 +9,13 @@ This project uses the **claude-config-maintainer** plugin to analyze and optimiz
 | `/config-analyze` | Analyze CLAUDE.md for optimization opportunities with 100-point scoring |
 | `/config-optimize` | Automatically optimize CLAUDE.md structure and content |
 | `/config-init` | Initialize a new CLAUDE.md file for a project |
+| `/config-diff` | Track CLAUDE.md changes over time with behavioral impact analysis |
+| `/config-lint` | Lint CLAUDE.md for anti-patterns and best practices (31 rules) |
+| `/config-audit-settings` | Audit settings.local.json permissions with 100-point scoring |
+| `/config-optimize-settings` | Optimize permission patterns and apply named profiles |
+| `/config-permissions-map` | Visual map of review layers and permission coverage |
 
-### Scoring System
+### CLAUDE.md Scoring System
 
 The analysis uses a 100-point scoring system across four categories:
 
@@ -21,10 +26,31 @@ The analysis uses a 100-point scoring system across four categories:
 | Completeness | 25 | Overview, quick start, critical rules, workflows |
 | Conciseness | 25 | Efficiency, no repetition, appropriate length |
 
+### Settings Scoring System
+
+The settings audit uses a 100-point scoring system across four categories:
+
+| Category | Points | What It Measures |
+|----------|--------|------------------|
+| Redundancy | 25 | No duplicates, no subset patterns, efficient rules |
+| Coverage | 25 | Common tools allowed, MCP servers covered |
+| Safety Alignment | 25 | Deny rules for secrets/destructive ops, review layers verified |
+| Profile Fit | 25 | Alignment with recommended profile for review layer count |
+
+### Permission Profiles
+
+| Profile | Use Case |
+|---------|----------|
+| `conservative` | New users, minimal auto-allow, prompts for most writes |
+| `reviewed` | Projects with 2+ review layers (code-sentinel, doc-guardian, PR review) |
+| `autonomous` | Trusted CI/sandboxed environments only |
+
 ### Usage Guidelines
 
 - Run `/config-analyze` periodically to assess CLAUDE.md quality
+- Run `/config-audit-settings` to check permission efficiency
 - Target a score of **70+/100** for effective Claude Code operation
 - Address HIGH priority issues first when optimizing
 - Use `/config-init` when setting up new projects to start with best practices
+- Use `/config-permissions-map` to visualize review layer coverage
 - Re-analyze after making changes to verify improvements

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

@@ -4,17 +4,18 @@ description: Analyze CLAUDE.md for optimization opportunities and plugin integra
 
 # Analyze CLAUDE.md
 
-This command analyzes your project's CLAUDE.md file and provides a detailed report on optimization opportunities and plugin integration status.
+Analyze your CLAUDE.md and provide a scored report with recommendations.
 
-## What This Command Does
+## Skills to Load
 
-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
+- 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`
 
 ## Usage
 
@@ -22,165 +23,27 @@ This command analyzes your project's CLAUDE.md file and provides a detailed repo
 /config-analyze
 ```
 
-Or invoke the maintainer agent directly:
+## Workflow
 
-```
-Analyze the CLAUDE.md file in this project
-```
+1. Locate and parse CLAUDE.md
+2. Evaluate structure, clarity, completeness, conciseness
+3. Find redundancy, verbosity, missing sections
+4. Detect active marketplace plugins
+5. Verify plugin integration in CLAUDE.md
+6. Generate scored report with recommendations
 
-## Analysis Criteria
+## Scoring (100 points)
 
-### 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
-
-### 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
+| Category | Points |
+|----------|--------|
+| Structure | 25 |
+| Clarity | 25 |
+| Completeness | 25 |
+| Conciseness | 25 |
 
 ## Follow-Up Actions
 
-After analysis, you can:
-- Run `/config-optimize` to automatically improve the file
-- Manually address specific issues
-- 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
+1. Implement content recommendations
+2. Add missing plugin integrations
+3. Do both (recommended)
+4. Show preview first

plugins/claude-config-maintainer/commands/config-audit-settings.md

@@ -0,0 +1,204 @@
+---
+name: config-audit-settings
+description: Audit settings.local.json for permission optimization opportunities
+---
+
+# /config-audit-settings
+
+Audit Claude Code `settings.local.json` permissions with 100-point scoring across redundancy, coverage, safety alignment, and profile fit.
+
+## Skills to Load
+
+Before executing, load:
+- `skills/visual-header.md`
+- `skills/settings-optimization.md`
+
+## Visual Output
+
+```
++-----------------------------------------------------------------+
+|  CONFIG-MAINTAINER - Settings Audit                              |
++-----------------------------------------------------------------+
+```
+
+## Usage
+
+```
+/config-audit-settings              # Full audit with recommendations
+/config-audit-settings --diagram    # Include Mermaid diagram of review layer coverage
+```
+
+## Workflow
+
+### Step 1: Locate Settings Files
+
+Search in order:
+1. `.claude/settings.local.json` (primary target)
+2. `.claude/settings.json` (shared config)
+3. `~/.claude.json` project entry (legacy)
+
+Report which format is in use.
+
+### Step 2: Parse Permission Arrays
+
+Extract and analyze:
+- `permissions.allow` array
+- `permissions.deny` array
+- `permissions.ask` array (if present)
+- Legacy `allowedTools` array (if legacy format)
+
+### Step 3: Run Pattern Consolidation Analysis
+
+Using `settings-optimization.md` Section 3, detect:
+
+| Check | Description |
+|-------|-------------|
+| Duplicates | Exact same pattern appearing multiple times |
+| Subsets | Narrower patterns covered by broader ones |
+| Merge candidates | 4+ similar patterns that could be consolidated |
+| Overly broad | Unscoped tool permissions (e.g., `Bash` without pattern) |
+| Stale entries | Patterns referencing non-existent paths |
+| Conflicts | Same pattern in both allow and deny |
+
+### Step 4: Detect Active Marketplace Hooks
+
+Read `plugins/*/hooks/hooks.json` files:
+
+```bash
+# Check each plugin's hooks
+plugins/code-sentinel/hooks/hooks.json     # PreToolUse security
+plugins/doc-guardian/hooks/hooks.json      # PostToolUse drift detection
+plugins/project-hygiene/hooks/hooks.json   # PostToolUse cleanup
+plugins/data-platform/hooks/hooks.json     # PostToolUse schema diff
+plugins/contract-validator/hooks/hooks.json # Plugin validation
+```
+
+Parse each to identify:
+- Hook event type (PreToolUse, PostToolUse)
+- Tool matchers (Write, Edit, MultiEdit, Bash)
+- Whether hook is command type (reliable) or prompt type (unreliable)
+
+### Step 5: Map Review Layers to Directory Scopes
+
+For each directory scope in `settings-optimization.md` Section 4:
+1. Count how many review layers are verified active
+2. Determine if auto-allow is justified (≥2 layers required)
+3. Note any scopes that lack coverage
+
+### Step 6: Compare Against Recommended Profile
+
+Based on review layer count:
+- 0-1 layers: Recommend `conservative` profile
+- 2+ layers: Recommend `reviewed` profile
+- CI/sandboxed: May recommend `autonomous` profile
+
+Calculate profile fit percentage.
+
+### Step 7: Generate Scored Report
+
+Calculate scores using `settings-optimization.md` Section 6.
+
+## Output Format
+
+```
+Settings Efficiency Score: XX/100
+  Redundancy:       XX/25
+  Coverage:         XX/25
+  Safety Alignment: XX/25
+  Profile Fit:      XX/25
+
+Current Profile: [closest match or "custom"]
+Recommended Profile: [target based on review layers]
+
+Issues Found:
+  🔴 CRITICAL: [description]
+  🟠 HIGH: [description]
+  🟡 MEDIUM: [description]
+  🔵 LOW: [description]
+
+Active Review Layers Detected:
+  ✓ code-sentinel (PreToolUse: Write|Edit|MultiEdit)
+  ✓ doc-guardian (PostToolUse: Write|Edit|MultiEdit)
+  ✓ project-hygiene (PostToolUse: Write|Edit)
+  ✗ data-platform schema-diff (not detected)
+
+Recommendations:
+  1. [specific action with pattern]
+  2. [specific action with pattern]
+  ...
+
+Follow-Up Actions:
+  1. Run /config-optimize-settings to apply recommendations
+  2. Run /config-optimize-settings --dry-run to preview first
+  3. Run /config-optimize-settings --profile=reviewed to apply profile
+```
+
+## Diagram Output (--diagram flag)
+
+When `--diagram` is specified, generate a Mermaid flowchart showing:
+
+**Before generating:** Read `/mnt/skills/user/mermaid-diagrams/SKILL.md` for diagram requirements.
+
+**Diagram structure:**
+- Left column: File operation types (Write, Edit, Bash)
+- Middle: Review layers that intercept each operation
+- Right column: Current permission status (auto-allowed, prompted, denied)
+
+**Color coding:**
+- PreToolUse hooks: Blue
+- PostToolUse hooks: Green
+- Sprint Approval: Amber
+- PR Review: Purple
+
+Example structure:
+```mermaid
+flowchart LR
+    subgraph Operations
+        W[Write]
+        E[Edit]
+        B[Bash]
+    end
+
+    subgraph Review Layers
+        CS[code-sentinel]
+        DG[doc-guardian]
+        PR[pr-review]
+    end
+
+    subgraph Permission
+        A[Auto-allowed]
+        P[Prompted]
+        D[Denied]
+    end
+
+    W --> CS
+    W --> DG
+    E --> CS
+    E --> DG
+    CS --> A
+    DG --> A
+    B --> P
+
+    classDef preHook fill:#e3f2fd
+    classDef postHook fill:#e8f5e9
+    classDef prReview fill:#f3e5f5
+    class CS preHook
+    class DG postHook
+    class PR prReview
+```
+
+## Issue Severity Levels
+
+| Severity | Icon | Examples |
+|----------|------|----------|
+| CRITICAL | 🔴 | Unscoped `Bash` in allow, missing deny for secrets |
+| HIGH | 🟠 | Overly broad patterns, missing MCP coverage |
+| MEDIUM | 🟡 | Subset redundancy, merge candidates |
+| LOW | 🔵 | Exact duplicates, minor optimizations |
+
+## DO NOT
+
+- Modify any files (this is audit only)
+- Recommend `autonomous` profile unless explicitly sandboxed environment
+- Recommend auto-allow for scopes with <2 verified review layers
+- Skip hook verification before making recommendations

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

@@ -0,0 +1,48 @@
+---
+description: Show diff between current CLAUDE.md and last commit
+---
+
+# Compare CLAUDE.md Changes
+
+Show differences between CLAUDE.md versions to track configuration drift.
+
+## Skills to Load
+
+- skills/visual-header.md
+- skills/diff-analysis.md
+
+## Visual Output
+
+Display: `CONFIG-MAINTAINER - CLAUDE.md Diff`
+
+## Usage
+
+```
+/config-diff                           # Working vs last commit
+/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
+
+1. Find project's CLAUDE.md file
+2. Show diff against target revision
+3. Group changes by affected sections
+4. Explain behavioral implications
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--commit=REF` | Compare against specific commit |
+| `--from=REF` | Starting point |
+| `--to=REF` | Ending point (default: HEAD) |
+| `--section=NAME` | Show only specific section |
+| `--stat` | Statistics only |
+
+## When to Use
+
+- Before committing CLAUDE.md changes
+- Reviewing changes after pull
+- Debugging unexpected behavior

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

@@ -0,0 +1,48 @@
+---
+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.
+
+## Skills to Load
+
+- skills/visual-header.md
+- skills/lint-rules.md
+
+## Visual Output
+
+Display: `CONFIG-MAINTAINER - CLAUDE.md Lint`
+
+## Usage
+
+```
+/config-lint                         # Full lint
+/config-lint --fix                   # Auto-fix issues
+/config-lint --rules=security        # Check specific category
+```
+
+## Workflow
+
+1. Parse markdown structure and hierarchy
+2. Check for hardcoded paths, secrets, sensitive data
+3. Identify content anti-patterns
+4. Verify consistent formatting
+5. Generate report with fix suggestions
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--fix` | Auto-fix issues |
+| `--rules=LIST` | Check specific categories |
+| `--ignore=LIST` | Skip specified rules |
+| `--severity=LEVEL` | Filter by severity |
+| `--strict` | Treat warnings as errors |
+
+## When to Use
+
+- Before committing CLAUDE.md changes
+- During code review
+- Periodically as maintenance

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

@@ -0,0 +1,243 @@
+---
+name: config-optimize-settings
+description: Optimize settings.local.json permissions based on audit recommendations
+---
+
+# /config-optimize-settings
+
+Optimize Claude Code `settings.local.json` permission patterns and apply named profiles.
+
+## Skills to Load
+
+Before executing, load:
+- `skills/visual-header.md`
+- `skills/settings-optimization.md`
+- `skills/pre-change-protocol.md`
+
+## Visual Output
+
+```
++-----------------------------------------------------------------+
+|  CONFIG-MAINTAINER - Settings Optimization                       |
++-----------------------------------------------------------------+
+```
+
+## Usage
+
+```
+/config-optimize-settings                    # Apply audit recommendations
+/config-optimize-settings --dry-run          # Preview only, no changes
+/config-optimize-settings --profile=reviewed # Apply named profile
+/config-optimize-settings --consolidate-only # Only merge/dedupe, no new rules
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview changes without applying |
+| `--profile=NAME` | Apply named profile (`conservative`, `reviewed`, `autonomous`) |
+| `--consolidate-only` | Only deduplicate and merge patterns, don't add new rules |
+| `--no-backup` | Skip backup (not recommended) |
+
+## Workflow
+
+### Step 1: Run Audit Analysis
+
+Execute the same analysis as `/config-audit-settings`:
+1. Locate settings file
+2. Parse permission arrays
+3. Detect issues (duplicates, subsets, merge candidates, etc.)
+4. Verify active review layers
+5. Calculate current score
+
+### Step 2: Generate Optimization Plan
+
+Based on audit results, create a change plan:
+
+**For `--consolidate-only`:**
+- Remove exact duplicates
+- Remove subset patterns covered by broader patterns
+- Merge similar patterns (4+ threshold)
+- Remove stale patterns for non-existent paths
+- Remove conflicting allow entries that are already denied
+
+**For `--profile=NAME`:**
+- Calculate diff between current permissions and target profile
+- Show additions and removals
+- Preserve any custom deny rules not in profile
+
+**For default (full optimization):**
+- Apply all consolidation changes
+- Add recommended patterns based on verified review layers
+- Suggest profile alignment if appropriate
+
+### Step 3: Show Before/After Preview
+
+**MANDATORY:** Always show preview before applying changes.
+
+```
+Current Settings:
+  allow: [12 patterns]
+  deny: [4 patterns]
+
+Proposed Changes:
+
+  REMOVE from allow (redundant):
+    - Write(plugins/projman/*) [covered by Write(plugins/**)]
+    - Write(plugins/git-flow/*) [covered by Write(plugins/**)]
+    - Bash(git status) [covered by Bash(git *)]
+
+  ADD to allow (recommended):
+    + Bash(npm *) [2 review layers active]
+    + Bash(pytest *) [2 review layers active]
+
+  ADD to deny (security):
+    + Bash(curl * | bash*) [missing safety rule]
+
+After Optimization:
+  allow: [10 patterns]
+  deny: [5 patterns]
+
+Score Impact: 67/100 → 85/100 (+18 points)
+```
+
+### Step 4: Request User Approval
+
+Ask for confirmation before proceeding:
+
+```
+Apply these changes to .claude/settings.local.json?
+  [1] Yes, apply changes
+  [2] No, cancel
+  [3] Apply partial (select which changes)
+```
+
+### Step 5: Create Backup
+
+**Before any write operation:**
+
+```bash
+# Backup location
+.claude/backups/settings.local.json.{YYYYMMDD-HHMMSS}
+```
+
+Create the `.claude/backups/` directory if it doesn't exist.
+
+### Step 6: Apply Changes
+
+Write the optimized `settings.local.json` file.
+
+### Step 7: Verify
+
+Re-read the file and re-calculate the score to confirm improvement.
+
+```
+Optimization Complete!
+
+Backup saved: .claude/backups/settings.local.json.20260202-143022
+
+Settings Efficiency Score: 85/100 (+18 from 67)
+  Redundancy:       25/25 (+8)
+  Coverage:         22/25 (+5)
+  Safety Alignment: 23/25 (+3)
+  Profile Fit:      15/25 (+2)
+
+Changes applied:
+  - Removed 3 redundant patterns
+  - Added 2 recommended patterns
+  - Added 1 safety deny rule
+```
+
+## Profile Application
+
+When using `--profile=NAME`:
+
+### `conservative`
+```
+Switching to conservative profile...
+
+This profile:
+  - Allows: Read, Glob, Grep, LS, basic Bash commands
+  - Allows: Write/Edit only for docs/
+  - Denies: .env*, secrets/, rm -rf, sudo
+
+All other Write/Edit operations will prompt for approval.
+```
+
+### `reviewed`
+```
+Switching to reviewed profile...
+
+Prerequisites verified:
+  ✓ code-sentinel hook active (PreToolUse)
+  ✓ doc-guardian hook active (PostToolUse)
+  ✓ 2+ review layers detected
+
+This profile:
+  - Allows: All file operations (Edit, Write, MultiEdit)
+  - Allows: Scoped Bash commands (git, npm, python, etc.)
+  - Denies: .env*, secrets/, rm -rf, sudo, curl|bash
+```
+
+### `autonomous`
+```
+⚠️  WARNING: Autonomous profile requested
+
+This profile allows unscoped Bash execution.
+Only use in fully sandboxed environments (CI, containers).
+
+Confirm this is a sandboxed environment?
+  [1] Yes, this is sandboxed - apply autonomous profile
+  [2] No, cancel
+```
+
+## Safety Rules
+
+1. **ALWAYS backup before writing** (unless `--no-backup`)
+2. **NEVER remove deny rules without explicit confirmation**
+3. **NEVER add unscoped `Bash` to allow** — always use scoped patterns
+4. **Preview is MANDATORY** before applying changes
+5. **Verify review layers** before recommending broad permissions
+
+## Output Format
+
+### Dry Run Output
+
+```
++-----------------------------------------------------------------+
+|  CONFIG-MAINTAINER - Settings Optimization                       |
++-----------------------------------------------------------------+
+
+DRY RUN - No changes will be made
+
+[... preview content ...]
+
+To apply these changes, run:
+  /config-optimize-settings
+```
+
+### Applied Output
+
+```
++-----------------------------------------------------------------+
+|  CONFIG-MAINTAINER - Settings Optimization                       |
++-----------------------------------------------------------------+
+
+Optimization Applied Successfully
+
+Backup: .claude/backups/settings.local.json.20260202-143022
+
+[... summary of changes ...]
+
+Score: 67/100 → 85/100
+```
+
+## DO NOT
+
+- Apply changes without showing preview
+- Remove deny rules silently
+- Add unscoped `Bash` permission
+- Skip backup without explicit `--no-backup` flag
+- Apply `autonomous` profile without sandbox confirmation
+- Recommend broad permissions without verifying review layers

plugins/claude-config-maintainer/commands/config-permissions-map.md

@@ -0,0 +1,256 @@
+---
+name: config-permissions-map
+description: Generate visual map of review layers and permission coverage
+---
+
+# /config-permissions-map
+
+Generate a Mermaid diagram showing the relationship between file operations, review layers, and permission status.
+
+## Skills to Load
+
+Before executing, load:
+- `skills/visual-header.md`
+- `skills/settings-optimization.md`
+
+Also read: `/mnt/skills/user/mermaid-diagrams/SKILL.md` (for diagram requirements)
+
+## Visual Output
+
+```
++-----------------------------------------------------------------+
+|  CONFIG-MAINTAINER - Permissions Map                             |
++-----------------------------------------------------------------+
+```
+
+## Usage
+
+```
+/config-permissions-map           # Generate and display diagram
+/config-permissions-map --save    # Save diagram to .mermaid file
+```
+
+## Workflow
+
+### Step 1: Detect Active Hooks
+
+Read all plugin hooks from the marketplace:
+
+```
+plugins/code-sentinel/hooks/hooks.json
+plugins/doc-guardian/hooks/hooks.json
+plugins/project-hygiene/hooks/hooks.json
+plugins/data-platform/hooks/hooks.json
+plugins/contract-validator/hooks/hooks.json
+plugins/cmdb-assistant/hooks/hooks.json
+```
+
+For each hook, extract:
+- Event type (PreToolUse, PostToolUse, SessionStart, etc.)
+- Tool matchers (Write, Edit, MultiEdit, Bash patterns)
+- Hook command/script
+
+### Step 2: Map Hooks to File Scopes
+
+Create a mapping of which review layers cover which operations:
+
+| Operation | PreToolUse Hooks | PostToolUse Hooks | Other Gates |
+|-----------|------------------|-------------------|-------------|
+| Write | code-sentinel | doc-guardian, project-hygiene | PR review |
+| Edit | code-sentinel | doc-guardian, project-hygiene | PR review |
+| MultiEdit | code-sentinel | doc-guardian | PR review |
+| Bash(git *) | git-flow | — | — |
+
+### Step 3: Read Current Permissions
+
+Load `.claude/settings.local.json` and parse:
+- `allow` array → auto-allowed operations
+- `deny` array → blocked operations
+- `ask` array → always-prompted operations
+
+### Step 4: Generate Mermaid Flowchart
+
+**Diagram requirements (from mermaid-diagrams skill):**
+- Use `classDef` for styling
+- Maximum 3 colors (blue, green, amber/purple)
+- Semantic arrow labels
+- Left-to-right flow
+
+**Structure:**
+
+```mermaid
+flowchart LR
+    subgraph ops[File Operations]
+        direction TB
+        W[Write]
+        E[Edit]
+        ME[MultiEdit]
+        BG[Bash git]
+        BN[Bash npm]
+        BO[Bash other]
+    end
+
+    subgraph pre[PreToolUse Hooks]
+        direction TB
+        CS[code-sentinel<br/>Security Scan]
+        GF[git-flow<br/>Branch Check]
+    end
+
+    subgraph post[PostToolUse Hooks]
+        direction TB
+        DG[doc-guardian<br/>Drift Detection]
+        PH[project-hygiene<br/>Cleanup]
+        DP[data-platform<br/>Schema Diff]
+    end
+
+    subgraph perm[Permission Status]
+        direction TB
+        AA[Auto-Allowed]
+        PR[Prompted]
+        DN[Denied]
+    end
+
+    W -->|intercepted| CS
+    W -->|tracked| DG
+    E -->|intercepted| CS
+    E -->|tracked| DG
+    BG -->|checked| GF
+
+    CS -->|passed| AA
+    DG -->|logged| AA
+    GF -->|valid| AA
+    BO -->|no hook| PR
+
+    classDef preHook fill:#e3f2fd,stroke:#1976d2
+    classDef postHook fill:#e8f5e9,stroke:#388e3c
+    classDef sprint fill:#fff3e0,stroke:#f57c00
+    classDef prReview fill:#f3e5f5,stroke:#7b1fa2
+    classDef allowed fill:#c8e6c9,stroke:#2e7d32
+    classDef prompted fill:#fff9c4,stroke:#f9a825
+    classDef denied fill:#ffcdd2,stroke:#c62828
+
+    class CS,GF preHook
+    class DG,PH,DP postHook
+    class AA allowed
+    class PR prompted
+    class DN denied
+```
+
+### Step 5: Generate Coverage Summary Table
+
+```
+Review Layer Coverage Summary
+=============================
+
+| Directory Scope          | Layers | Status          | Recommendation |
+|--------------------------|--------|-----------------|----------------|
+| plugins/*/commands/*.md  |   3    | ✓ Auto-allowed  | — |
+| plugins/*/skills/*.md    |   2    | ✓ Auto-allowed  | — |
+| mcp-servers/**/*.py      |   3    | ✓ Auto-allowed  | — |
+| docs/**                  |   2    | ✓ Auto-allowed  | — |
+| scripts/*.sh             |   2    | ⚠ Prompted      | Consider auto-allow |
+| .env*                    |   0    | ✗ Denied        | Correct - secrets |
+| Root directory           |   1    | ⚠ Prompted      | Keep prompted |
+
+Legend:
+  ✓ = Covered by ≥2 review layers, auto-allowed
+  ⚠ = Fewer than 2 layers or not allowed
+  ✗ = Explicitly denied
+```
+
+### Step 6: Identify Gaps
+
+Report any gaps in coverage:
+
+```
+Coverage Gaps Detected:
+  1. Bash(npm *) — not in allow list, but npm operations are common
+     → 2 review layers active, could be auto-allowed
+
+  2. mcp__data-platform__* — MCP server configured but tools not allowed
+     → Add to allow list to avoid prompts
+
+  3. scripts/*.sh — 2 review layers but still prompted
+     → Consider adding Write(scripts/**) to allow
+```
+
+### Step 7: Output Diagram
+
+Display the Mermaid diagram inline.
+
+If `--save` flag is used:
+- Save to `.claude/permissions-map.mermaid`
+- Report the file path
+
+## Output Format
+
+```
++-----------------------------------------------------------------+
+|  CONFIG-MAINTAINER - Permissions Map                             |
++-----------------------------------------------------------------+
+
+Review Layer Status
+===================
+
+PreToolUse Hooks (intercept before operation):
+  ✓ code-sentinel — Write, Edit, MultiEdit
+  ✓ git-flow — Bash(git checkout *), Bash(git commit *)
+
+PostToolUse Hooks (track after operation):
+  ✓ doc-guardian — Write, Edit, MultiEdit
+  ✓ project-hygiene — Write, Edit
+  ✗ data-platform — not detected
+
+Other Review Gates:
+  ✓ Sprint Approval (projman milestone workflow)
+  ✓ PR Review (pr-review multi-agent)
+
+Permissions Flow Diagram
+========================
+
+```mermaid
+[diagram here]
+```
+
+Coverage Summary
+================
+
+[table here]
+
+Gaps & Recommendations
+======================
+
+[gaps list here]
+```
+
+## File Output (--save flag)
+
+When `--save` is specified:
+
+```
+Diagram saved to: .claude/permissions-map.mermaid
+
+To view:
+  - Open in VS Code with Mermaid extension
+  - Paste into https://mermaid.live
+  - Include in documentation with ```mermaid code fence
+```
+
+## Color Scheme
+
+| Element | Color | Hex |
+|---------|-------|-----|
+| PreToolUse hooks | Blue | #e3f2fd |
+| PostToolUse hooks | Green | #e8f5e9 |
+| Sprint/Planning gates | Amber | #fff3e0 |
+| PR Review | Purple | #f3e5f5 |
+| Auto-allowed | Light green | #c8e6c9 |
+| Prompted | Light yellow | #fff9c4 |
+| Denied | Light red | #ffcdd2 |
+
+## DO NOT
+
+- Generate diagrams without reading the mermaid-diagrams skill
+- Use more than 3 primary colors in the diagram
+- Skip the coverage summary table
+- Fail to identify coverage gaps

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

@@ -4,208 +4,46 @@ description: Initialize a new CLAUDE.md file for a project
 
 # Initialize CLAUDE.md
 
-This command creates a new CLAUDE.md file tailored to your project, gathering context and generating appropriate content.
+Create a new CLAUDE.md file tailored to your project.
 
-## What This Command Does
+## Skills to Load
 
-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
+- skills/visual-header.md
+- skills/claude-md-structure.md
+- skills/pre-change-protocol.md
+
+## Visual Output
+
+Display: `CONFIG-MAINTAINER - CLAUDE.md Initialization`
 
 ## Usage
 
 ```
-/config-init
+/config-init                    # Interactive
+/config-init --minimal          # Minimal version
+/config-init --comprehensive    # Detailed version
 ```
 
-Or with options:
+## Workflow
 
-```
-/config-init --template=api        # Use API project template
-/config-init --minimal             # Create minimal version
-/config-init --comprehensive       # Create detailed version
-```
-
-## 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
-```
+1. Analyze project structure, ask clarifying questions
+2. Detect technologies, frameworks, tools
+3. Generate tailored CLAUDE.md sections
+4. Allow review and customization
+5. Save file in project root
 
 ## Templates
 
-### Minimal Template
-For small projects or when starting fresh:
-- Project Overview (required)
-- Quick Start (required)
-- Critical Rules (required)
+| Template | Sections |
+|----------|----------|
+| Minimal | Overview, Quick Start, Critical Rules, Pre-Change Protocol |
+| Standard | + Architecture, Common Operations, File Structure |
+| Comprehensive | + Troubleshooting, Integration Points, Workflow |
 
-### 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
+**Note:** Pre-Change Protocol is MANDATORY in all templates.
 
 ## When to Use
 
-Run `/config-init` when:
 - Starting a new project
 - Project lacks CLAUDE.md
-- 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
-```
+- Taking over unfamiliar project

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

@@ -4,175 +4,47 @@ description: Optimize CLAUDE.md structure and content
 
 # Optimize CLAUDE.md
 
-This command automatically optimizes your project's CLAUDE.md file based on best practices and identified issues.
+Automatically optimize CLAUDE.md based on best practices.
 
-## What This Command Does
+## Skills to Load
 
-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
+- 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`
 
 ## Usage
 
 ```
-/config-optimize
+/config-optimize                # Full optimization
+/config-optimize --condense     # Reduce verbosity
+/config-optimize --dry-run      # Preview only
 ```
 
-Or specify specific optimizations:
+## Workflow
 
-```
-/config-optimize --condense        # Focus on reducing verbosity
-/config-optimize --restructure     # Focus on reorganization
-/config-optimize --add-missing     # Focus on adding missing sections
-```
-
-## 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
+1. Identify optimization opportunities
+2. Plan restructure, condense, or add actions
+3. Show before/after preview
+4. Apply changes with approval
+5. Verify improvements
 
 ## Options
 
 | Option | Description |
 |--------|-------------|
-| `--dry-run` | Show changes without applying |
-| `--no-backup` | Skip backup creation |
+| `--dry-run` | Preview without applying |
+| `--no-backup` | Skip backup |
 | `--aggressive` | Maximum condensation |
-| `--preserve-comments` | Keep all existing comments |
-| `--section=NAME` | Optimize specific section only |
+| `--section=NAME` | Optimize specific section |
 
-## When to Use
+**Priority:** Add Pre-Change Protocol if missing.
 
-Run `/config-optimize` when:
-- Analysis shows score below 70
-- File has grown too long
-- Structure needs reorganization
-- Missing critical sections
-- After major refactoring
+## Safety
 
-## Best Practices
-
-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
-```
+- Auto backup to `.claude/backups/`
+- Preview before applying

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

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

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

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

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

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

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

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

@@ -0,0 +1,83 @@
+# 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/settings-optimization.md

@@ -0,0 +1,377 @@
+# Settings Optimization Skill
+
+This skill provides comprehensive knowledge for auditing and optimizing Claude Code `settings.local.json` permission configurations.
+
+---
+
+## Section 1: Settings File Locations & Format
+
+Claude Code uses two configuration formats for permissions:
+
+### Newer Format (Recommended)
+
+**Primary target:** `.claude/settings.local.json` (project-local, gitignored)
+
+**Secondary locations:**
+- `.claude/settings.json` (shared, committed)
+- `~/.claude.json` (legacy global config)
+
+```json
+{
+  "permissions": {
+    "allow": ["Edit", "Write(plugins/**)", "Bash(git *)"],
+    "deny": ["Read(.env*)", "Bash(rm *)"],
+    "ask": ["Bash(pip install *)"]
+  }
+}
+```
+
+**Field meanings:**
+- `allow`: Operations auto-approved without prompting
+- `deny`: Operations blocked entirely
+- `ask`: Operations that always prompt (overrides allow)
+
+### Legacy Format
+
+Found in `~/.claude.json` with per-project entries:
+
+```json
+{
+  "projects": {
+    "/path/to/project": {
+      "allowedTools": ["Read", "Write", "Bash(git *)"]
+    }
+  }
+}
+```
+
+**Detection strategy:**
+1. Check `.claude/settings.local.json` first (primary)
+2. Check `.claude/settings.json` (shared)
+3. Check `~/.claude.json` for project entry (legacy)
+4. Report which format is in use
+
+---
+
+## Section 2: Permission Rule Syntax Reference
+
+| Pattern | Meaning |
+|---------|---------|
+| `Tool` or `Tool(*)` | Allow all uses of that tool |
+| `Bash(npm run build)` | Exact command match |
+| `Bash(npm run test *)` | Prefix match (space+asterisk = word boundary) |
+| `Bash(npm*)` | Prefix match without word boundary |
+| `Write(plugins/**)` | Glob — all files recursively under `plugins/` |
+| `Write(plugins/projman/*)` | Glob — direct children only |
+| `Read(.env*)` | Pattern matching `.env`, `.env.local`, etc. |
+| `mcp__gitea__*` | All tools from the gitea MCP server |
+| `mcp__netbox__list_*` | Specific MCP tool pattern |
+| `WebFetch(domain:github.com)` | Domain-restricted web fetch |
+
+### Important Nuances
+
+**Word boundary matching:**
+- `Bash(ls *)` (with space) matches `ls -la` but NOT `lsof`
+- `Bash(ls*)` (no space) matches both `ls -la` AND `lsof`
+
+**Precedence rules:**
+- `deny` rules take precedence over `allow` rules
+- `ask` rules override both (always prompts even if allowed)
+- More specific patterns do NOT override broader patterns
+
+**Command operators:**
+- Piped commands (`cmd1 | cmd2`) may not match individual command rules (known Claude Code limitation)
+- Shell operators (`&&`, `||`) — Claude Code is aware of these and won't let prefix rules bypass them
+- Commands with redirects (`>`, `>>`, `<`) are evaluated as complete strings
+
+---
+
+## Section 3: Pattern Consolidation Rules
+
+The audit detects these optimization opportunities:
+
+| Issue | Example | Recommendation |
+|-------|---------|----------------|
+| **Exact duplicates** | `Write(plugins/**)` listed twice | Remove duplicate |
+| **Subset redundancy** | `Write(plugins/projman/*)` when `Write(plugins/**)` exists | Remove the narrower pattern — already covered |
+| **Merge candidates** | `Write(plugins/projman/*)`, `Write(plugins/git-flow/*)`, `Write(plugins/pr-review/*)` ... (4+ similar patterns) | Merge to `Write(plugins/**)` |
+| **Overly broad** | `Bash` (no specifier = allows ALL bash) | Flag as security concern, suggest scoped patterns |
+| **Stale patterns** | `Write(plugins/old-plugin/**)` for a plugin that no longer exists | Remove stale entry |
+| **Missing MCP permissions** | MCP servers in `.mcp.json` but no `mcp__servername__*` in allow | Suggest adding if server is trusted |
+| **Conflicting rules** | Same pattern in both `allow` and `deny` | Flag conflict — deny wins, but allow is dead weight |
+
+### Consolidation Algorithm
+
+1. **Deduplicate:** Remove exact duplicates from each array
+2. **Subset elimination:** For each pattern, check if a broader pattern exists
+   - `Write(plugins/projman/*)` is subset of `Write(plugins/**)`
+   - `Bash(git status)` is subset of `Bash(git *)`
+3. **Merge detection:** If 4+ patterns share a common prefix, suggest merge
+   - Threshold: 4 patterns minimum before suggesting consolidation
+4. **Stale detection:** Cross-reference file patterns against actual filesystem
+5. **Conflict detection:** Check for patterns appearing in multiple arrays
+
+---
+
+## Section 4: Review-Layer-Aware Recommendations
+
+This is the key section. Map upstream review processes to directory scopes:
+
+| Directory Scope | Active Review Layers | Auto-Allow Recommendation |
+|----------------|---------------------|---------------------------|
+| `plugins/*/commands/*.md` | Sprint approval, PR review, doc-guardian PostToolUse | `Write(plugins/*/commands/**)` — 3 layers cover this |
+| `plugins/*/skills/*.md` | Sprint approval, PR review | `Write(plugins/*/skills/**)` — 2 layers |
+| `plugins/*/agents/*.md` | Sprint approval, PR review, contract-validator | `Write(plugins/*/agents/**)` — 3 layers |
+| `mcp-servers/*/mcp_server/*.py` | Code-sentinel PreToolUse, sprint approval, PR review | `Write(mcp-servers/**)` + `Edit(mcp-servers/**)` — sentinel catches secrets |
+| `docs/*.md` | Doc-guardian PostToolUse, PR review | `Write(docs/**)` + `Edit(docs/**)` |
+| `.claude-plugin/*.json` | validate-marketplace.sh, PR review | `Write(.claude-plugin/**)` |
+| `scripts/*.sh` | Code-sentinel, PR review | `Write(scripts/**)` — with caution flag |
+| `CLAUDE.md`, `CHANGELOG.md`, `README.md` | Doc-guardian, PR review | `Write(CLAUDE.md)`, `Write(CHANGELOG.md)`, `Write(README.md)` |
+
+### Critical Rule: Hook Verification
+
+**Before recommending auto-allow for a scope, the agent MUST verify the hook is actually configured.**
+
+Read the relevant `plugins/*/hooks/hooks.json` file:
+- If code-sentinel's hook is missing or disabled, do NOT recommend auto-allowing `mcp-servers/**` writes
+- If doc-guardian's hook is missing, do NOT recommend auto-allowing `docs/**` without caution
+- Count the number of verified review layers before making recommendations
+
+**Minimum threshold:** Recommend auto-allow only for scopes covered by ≥2 verified review layers.
+
+---
+
+## Section 5: Permission Profiles
+
+Three named profiles for different project contexts:
+
+### `conservative` (Default for New Users)
+
+Minimal permissions, prompts for most write operations:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Glob",
+      "Grep",
+      "LS",
+      "Write(docs/**)",
+      "Edit(docs/**)",
+      "Bash(git status *)",
+      "Bash(git diff *)",
+      "Bash(git log *)",
+      "Bash(cat *)",
+      "Bash(ls *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(wc *)",
+      "Bash(grep *)"
+    ],
+    "deny": [
+      "Read(.env*)",
+      "Read(./secrets/**)",
+      "Bash(rm -rf *)",
+      "Bash(sudo *)"
+    ]
+  }
+}
+```
+
+### `reviewed` (Projects with ≥2 Upstream Review Layers)
+
+This is the target profile for projects using the marketplace's multi-layer review architecture:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Glob",
+      "Grep",
+      "LS",
+      "Edit",
+      "Write",
+      "MultiEdit",
+      "Bash(git *)",
+      "Bash(python *)",
+      "Bash(pip install *)",
+      "Bash(cd *)",
+      "Bash(cat *)",
+      "Bash(ls *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(wc *)",
+      "Bash(grep *)",
+      "Bash(find *)",
+      "Bash(mkdir *)",
+      "Bash(cp *)",
+      "Bash(mv *)",
+      "Bash(touch *)",
+      "Bash(chmod *)",
+      "Bash(source *)",
+      "Bash(echo *)",
+      "Bash(sed *)",
+      "Bash(awk *)",
+      "Bash(sort *)",
+      "Bash(uniq *)",
+      "Bash(diff *)",
+      "Bash(jq *)",
+      "Bash(npm *)",
+      "Bash(npx *)",
+      "Bash(node *)",
+      "Bash(pytest *)",
+      "Bash(python -m *)",
+      "Bash(./scripts/*)",
+      "WebFetch",
+      "WebSearch"
+    ],
+    "deny": [
+      "Read(.env*)",
+      "Read(./secrets/**)",
+      "Bash(rm -rf *)",
+      "Bash(sudo *)",
+      "Bash(curl * | bash*)",
+      "Bash(wget * | bash*)"
+    ]
+  }
+}
+```
+
+### `autonomous` (Trusted CI/Sandboxed Environments Only)
+
+Maximum permissions for automated environments:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Glob",
+      "Grep",
+      "LS",
+      "Edit",
+      "Write",
+      "MultiEdit",
+      "Bash",
+      "WebFetch",
+      "WebSearch"
+    ],
+    "deny": [
+      "Read(.env*)",
+      "Read(./secrets/**)",
+      "Bash(rm -rf /)",
+      "Bash(sudo *)"
+    ]
+  }
+}
+```
+
+**Warning:** The `autonomous` profile allows unscoped `Bash` — only use in fully sandboxed environments.
+
+---
+
+## Section 6: Scoring Criteria (Settings Efficiency Score — 100 points)
+
+| Category | Points | What It Measures |
+|----------|--------|------------------|
+| **Redundancy** | 25 | No duplicates, no subset patterns, merged where possible |
+| **Coverage** | 25 | Common tools allowed, MCP servers covered, no unnecessary gaps |
+| **Safety Alignment** | 25 | Deny rules cover secrets, destructive commands; review layers verified |
+| **Profile Fit** | 25 | How close to recommended profile for the project's review layer count |
+
+### Scoring Breakdown
+
+**Redundancy (25 points):**
+- 25: No duplicates, no subsets, patterns are consolidated
+- 20: 1-2 minor redundancies
+- 15: 3-5 redundancies or 1 merge candidate group
+- 10: 6+ redundancies or 2+ merge candidate groups
+- 5: Significant redundancy (10+ issues)
+- 0: Severe redundancy (20+ issues)
+
+**Coverage (25 points):**
+- 25: All common tools allowed, MCP servers covered
+- 20: Missing 1-2 common tool patterns
+- 15: Missing 3-5 patterns or 1 MCP server
+- 10: Missing 6+ patterns or 2+ MCP servers
+- 5: Significant gaps causing frequent prompts
+- 0: Minimal coverage (prompts on most operations)
+
+**Safety Alignment (25 points):**
+- 25: Deny rules cover secrets + destructive ops, review layers verified
+- 20: Minor gaps (e.g., missing one secret pattern)
+- 15: Overly broad allow without review layer coverage
+- 10: Missing deny rules for secrets or destructive commands
+- 5: Unsafe patterns without review layer justification
+- 0: Security concerns (e.g., unscoped `Bash` without review layers)
+
+**Profile Fit (25 points):**
+- 25: Matches recommended profile exactly
+- 20: Within 90% of recommended profile
+- 15: Within 80% of recommended profile
+- 10: Within 70% of recommended profile
+- 5: Significant deviation from recommended profile
+- 0: No alignment with any named profile
+
+### Score Interpretation
+
+| Score Range | Status | Meaning |
+|-------------|--------|---------|
+| 90-100 | Optimized | Minimal prompt interruptions, safety maintained |
+| 70-89 | Good | Minor consolidation opportunities |
+| 50-69 | Needs Work | Significant redundancy or missing permissions |
+| Below 50 | Poor | Likely getting constant approval prompts unnecessarily |
+
+---
+
+## Section 7: Hook Detection Method
+
+To verify which review layers are active, read these files:
+
+| File | Hook Type | Tool Matcher | Purpose |
+|------|-----------|--------------|---------|
+| `plugins/code-sentinel/hooks/hooks.json` | PreToolUse | Write\|Edit\|MultiEdit | Blocks hardcoded secrets |
+| `plugins/doc-guardian/hooks/hooks.json` | PostToolUse | Write\|Edit\|MultiEdit | Tracks documentation drift |
+| `plugins/project-hygiene/hooks/hooks.json` | PostToolUse | Write\|Edit | Cleanup tracking |
+| `plugins/data-platform/hooks/hooks.json` | PostToolUse | Edit\|Write | Schema diff detection |
+| `plugins/cmdb-assistant/hooks/hooks.json` | PreToolUse | (if exists) | Input validation |
+
+### Verification Process
+
+1. **Read each hooks.json file**
+2. **Parse the JSON to find hook configurations**
+3. **Check the `type` field** — must be `"command"` (not `"prompt"`)
+4. **Check the `event` field** — maps to when hook runs
+5. **Check the `tools` array** — which operations are intercepted
+6. **Verify plugin is in marketplace** — check `.claude-plugin/marketplace.json`
+
+### Example Hook Structure
+
+```json
+{
+  "hooks": [
+    {
+      "event": "PreToolUse",
+      "type": "command",
+      "command": "./hooks/security-check.sh",
+      "tools": ["Write", "Edit", "MultiEdit"]
+    }
+  ]
+}
+```
+
+### Review Layer Count
+
+Count verified review layers for each scope:
+
+| Layer | Verification |
+|-------|-------------|
+| Sprint approval | Check if projman plugin is installed (milestone workflow) |
+| PR review | Check if pr-review plugin is installed |
+| code-sentinel PreToolUse | hooks.json exists with PreToolUse on Write/Edit |
+| doc-guardian PostToolUse | hooks.json exists with PostToolUse on Write/Edit |
+| contract-validator | Plugin installed + hooks present |
+
+**Recommendation threshold:** Only recommend auto-allow for scopes with ≥2 verified layers.

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

@@ -0,0 +1,73 @@
+# 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                    |
++-----------------------------------------------------------------+
+```
+
+### /config-audit-settings
+```
++-----------------------------------------------------------------+
+|  CONFIG-MAINTAINER - Settings Audit                              |
++-----------------------------------------------------------------+
+```
+
+### /config-optimize-settings
+```
++-----------------------------------------------------------------+
+|  CONFIG-MAINTAINER - Settings Optimization                       |
++-----------------------------------------------------------------+
+```
+
+### /config-permissions-map
+```
++-----------------------------------------------------------------+
+|  CONFIG-MAINTAINER - Permissions Map                             |
++-----------------------------------------------------------------+
+```
+
+## Usage
+
+Display the header at the start of command execution, before any analysis or output.

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

@@ -1,6 +1,6 @@
 {
   "name": "cmdb-assistant",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "NetBox CMDB integration with data quality validation - query, create, update, and manage network devices, IP addresses, sites, and more with best practices enforcement",
   "author": {
     "name": "Leo Miranda",
@@ -19,6 +19,5 @@
     "data-quality",
     "validation"
   ],
-  "commands": ["./commands/"],
-  "mcpServers": ["./.mcp.json"]
+  "commands": ["./commands/"]
 }

plugins/cmdb-assistant/.mcp.json

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

plugins/cmdb-assistant/README.md

@@ -1,205 +0,0 @@
-# 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.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) |
-
-## 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 (NEW)
-│   ├── cmdb-register.md     # Machine registration (NEW)
-│   └── cmdb-sync.md         # Machine sync (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,11 +1,27 @@
+---
+name: cmdb-assistant
+description: Infrastructure management assistant specialized in NetBox CMDB operations. Use for device management, IP addressing, and infrastructure queries.
+model: sonnet
+permissionMode: default
+---
+
 # CMDB Assistant Agent
 
-You are an infrastructure management assistant specialized in NetBox CMDB operations. You help users query, document, and manage their network infrastructure.
+You are an infrastructure management assistant specialized in NetBox CMDB operations.
+
+## Skills to Load
+
+- `skills/visual-header.md`
+- `skills/netbox-patterns/SKILL.md`
+- `skills/mcp-tools-reference.md`
+
+## Visual Output
+
+Execute `skills/visual-header.md` with context "Infrastructure Management".
 
 ## Capabilities
 
-You have full access to NetBox via MCP tools covering:
-
+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
@@ -19,183 +35,66 @@ You have full access to NetBox via MCP tools covering:
 
 ### Query Operations
 - Start with list operations to find objects
-- Use filters to narrow results (name, status, site_id, etc.)
-- Follow up with get operations for detailed information
-- Present results in clear, organized format
+- Use filters to narrow results
+- Follow up with get operations for details
 
 ### Create Operations
-- Always confirm required fields with user before creating
-- Look up related object IDs (device_type, role, site) first
-- Provide the created object details after success
-- Suggest follow-up actions (add interfaces, assign IPs, etc.)
+- Confirm required fields before creating
+- Look up related object IDs first
+- Suggest follow-up actions after success
 
 ### Update Operations
 - Show current values before updating
 - Confirm changes with user
-- Report what was changed after success
 
 ### Delete Operations
-- ALWAYS ask for explicit confirmation before deleting
-- 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
+- ALWAYS ask for explicit confirmation
+- Warn about dependent objects
 
 ## Data Quality Validation
 
-**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference.
+Reference `skills/netbox-patterns/SKILL.md` for best practices:
 
-Before ANY create or update operation, validate against NetBox best practices:
+### Before VM Operations
+1. Cluster/Site assignment required
+2. Recommend tenant if not provided
+3. Check naming convention
 
-### VM Operations
+### Before Device Operations
+1. Site is REQUIRED
+2. Recommend platform
+3. Check naming convention
+4. Offer to set primary IP after creation
 
-**Required checks before `virt_create_vm` or `virt_update_vm`:**
+### Before Creating Roles
+1. List existing roles first
+2. Recommend consolidation if >10 specific roles
 
-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:
+## Dependency Order
 
+Follow order from `skills/netbox-patterns/SKILL.md`:
 ```
-1. Regions → Sites → Locations → Racks
-2. Tenant Groups → Tenants
-3. Manufacturers → Device Types
+1. Regions -> Sites -> Locations -> Racks
+2. Tenant Groups -> Tenants
+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 assignment
+8. Interfaces -> IP Addresses -> Primary IP
 ```
 
-**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 objects, always check for existing duplicates:
-
+Before creating, check for existing:
 ```
-# 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 |
@@ -205,3 +104,6 @@ Users can invoke these commands for structured workflows:
 | `/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/claude-md-integration.md

@@ -32,9 +32,9 @@ The following NetBox MCP tools are available for infrastructure management:
 - `ipam_list_available_ips`, `ipam_create_available_ip` - IP allocation
 
 **Virtualization:**
-- `virtualization_list_virtual_machines`, `virtualization_create_virtual_machine` - VM management
-- `virtualization_list_clusters`, `virtualization_create_cluster` - Cluster management
-- `virtualization_list_vm_interfaces` - VM interface management
+- `virt_list_vms`, `virt_create_vm`, `virt_update_vm`, `virt_delete_vm` - VM management
+- `virt_list_clusters`, `virt_create_cluster`, `virt_update_cluster`, `virt_delete_cluster` - Cluster management
+- `virt_list_vm_ifaces`, `virt_create_vm_iface` - VM interface management
 
 **Circuits:**
 - `circuits_list_circuits`, `circuits_create_circuit` - Circuit management

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

@@ -0,0 +1,57 @@
+---
+description: Audit NetBox changes with filtering by date, user, or object type
+---
+
+# CMDB Change 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
+
+```
+/change-audit [filters]
+```
+
+**Filters:**
+- `last <N> days/hours` - Changes within time period
+- `by <username>` - Changes by specific user
+- `type <object-type>` - Changes to specific object type
+- `action <create|update|delete>` - Filter by action type
+- `object <name>` - Search for changes to specific object
+
+## Instructions
+
+Execute `skills/visual-header.md` with context "Change Audit".
+
+Execute `skills/change-audit.md` which covers:
+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
+
+If user asks for "security audit" or "compliance report":
+- Focus on deletions and permission-sensitive changes
+- Highlight changes to critical objects (firewalls, VRFs, prefixes)
+- Flag changes outside business hours
+- Identify users with high change counts
+
+## Examples
+
+- `/change-audit` - Recent changes (last 24 hours)
+- `/change-audit last 7 days` - Past week
+- `/change-audit by admin` - All changes by admin
+- `/change-audit type dcim.device` - Device changes only
+- `/change-audit action delete` - All deletions
+
+## User Request
+
+$ARGUMENTS

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

@@ -6,6 +6,13 @@ description: Audit NetBox data quality and identify consistency issues
 
 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
 
 ```
@@ -21,174 +28,30 @@ Analyze NetBox data for quality issues and best practice violations.
 
 ## Instructions
 
-You are a data quality auditor for NetBox. Your job is to identify consistency issues and best practice violations.
+Execute `skills/visual-header.md` with context "Data Quality Audit".
 
-**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference.
+Execute `skills/audit-workflow.md` which covers:
+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
 
-### Phase 1: Data Collection
+## Scope-Specific Focus
 
-Run these MCP tool calls to gather data for analysis:
+| 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 |
 
-```
-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
-```
+## Examples
 
-Store the results for analysis.
-
-### 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.
+- `/cmdb-audit` - Full audit
+- `/cmdb-audit vms` - VM-specific checks
+- `/cmdb-audit naming` - Naming conventions
 
 ## User Request
 

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

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

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

@@ -2,6 +2,12 @@
 
 Manage IP addresses and prefixes in NetBox.
 
+## Skills to Load
+
+- `skills/visual-header.md`
+- `skills/ip-management.md`
+- `skills/mcp-tools-reference.md`
+
 ## Usage
 
 ```
@@ -10,43 +16,36 @@ Manage IP addresses and prefixes in NetBox.
 
 ## Instructions
 
-You are an IP address management (IPAM) assistant with access to NetBox.
+Execute `skills/visual-header.md` with context "IP Management".
+
+Execute operations from `skills/ip-management.md`.
 
 ### Actions
 
 **Prefixes:**
-- `prefixes` - List all prefixes using `ipam_list_prefixes`
-- `prefix <cidr>` - Get prefix details or find prefix containing address
-- `available in <prefix>` - Show available IPs in a prefix using `ipam_list_available_ips`
-- `create prefix <cidr>` - Create new prefix using `ipam_create_prefix`
+- `prefixes` - List all prefixes
+- `prefix <cidr>` - Get prefix details
+- `available in <prefix>` - Show available IPs
+- `create prefix <cidr>` - Create new prefix
 
 **IP Addresses:**
-- `list` - List all IP addresses using `ipam_list_ip_addresses`
+- `list` - List all IP addresses
 - `show <address>` - Get IP details
-- `allocate from <prefix>` - Auto-allocate next available IP using `ipam_create_available_ip`
-- `create <address>` - Create specific IP using `ipam_create_ip_address`
-- `assign <ip> to <device>` - Assign IP to device interface
+- `allocate from <prefix>` - Auto-allocate next available
+- `create <address>` - Create specific IP
+- `assign <ip> to <device> <interface>` - Assign IP to interface
 
-**VLANs:**
-- `vlans` - List VLANs using `ipam_list_vlans`
+**VLANs and VRFs:**
+- `vlans` - List VLANs
 - `vlan <id>` - Get VLAN details
-
-**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
+- `vrfs` - List VRFs
 
 ## Examples
 
-- `/cmdb-ip prefixes` - List all prefixes
-- `/cmdb-ip available in 10.0.1.0/24` - Show available IPs
-- `/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` - Assign IP to interface
+- `/cmdb-ip prefixes`
+- `/cmdb-ip available in 10.0.1.0/24`
+- `/cmdb-ip allocate from 10.0.1.0/24`
+- `/cmdb-ip assign 10.0.1.50/24 to web-server-01 eth0`
 
 ## User Request
 

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

@@ -4,7 +4,15 @@ 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 (Docker containers, services).
+Register the current machine into NetBox, including hardware info, network interfaces, and running applications.
+
+## Skills to Load
+
+- `skills/visual-header.md`
+- `skills/device-registration.md`
+- `skills/system-discovery.md`
+- `skills/netbox-patterns/SKILL.md`
+- `skills/mcp-tools-reference.md`
 
 ## Usage
 
@@ -19,303 +27,24 @@ Register the current machine into NetBox, including hardware info, network inter
 
 ## Instructions
 
-You are registering the current machine into NetBox. This is a multi-phase process that discovers local system information and creates corresponding NetBox objects.
-
-**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference.
-
-### Phase 1: System Discovery (via Bash)
-
-Gather system information using these commands:
-
-#### 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.)
-```
+Execute `skills/visual-header.md` with context "Machine Registration".
+
+Execute `skills/device-registration.md` which covers:
+1. System discovery via Bash (use `skills/system-discovery.md`)
+2. Pre-registration checks (device exists?, site?, platform?, role?)
+3. Device creation via MCP
+4. Interface and IP creation
+5. Container registration (if Docker found)
+6. Journal entry documentation
 
 ## Error Handling
 
-- **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
+| 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 |
 
 ## User Request
 

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

@@ -1,5 +1,17 @@
 # CMDB Search
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Search                                      │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the search.
+
 Search NetBox for devices, IPs, sites, or any CMDB object.
 
 ## Usage
@@ -19,7 +31,7 @@ When the user provides a search query, determine the best approach:
 3. **Site search**: Use `dcim_list_sites` with name filter
 4. **Prefix search**: Use `ipam_list_prefixes` with prefix or within filter
 5. **VLAN search**: Use `ipam_list_vlans` with vid or name filter
-6. **VM search**: Use `virtualization_list_virtual_machines` with name filter
+6. **VM search**: Use `virt_list_vms` with name filter
 
 For broad searches, query multiple endpoints and consolidate results.
 

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

@@ -0,0 +1,74 @@
+---
+description: Interactive setup wizard for cmdb-assistant plugin
+---
+
+# CMDB Assistant Setup Wizard
+
+Configure the cmdb-assistant plugin with NetBox integration.
+
+## Skills to Load
+
+- `skills/visual-header.md`
+
+## Important Context
+
+- **Uses Bash, Read, Write, AskUserQuestion tools** - NOT MCP tools
+- **MCP tools unavailable until after setup + session restart**
+
+## Usage
+
+```
+/cmdb-setup
+```
+
+## Instructions
+
+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
+
+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
+
+1. Create config directory: `mkdir -p ~/.config/claude`
+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
+
+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
+
+$ARGUMENTS

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

@@ -2,6 +2,11 @@
 
 Manage sites and locations in NetBox.
 
+## Skills to Load
+
+- `skills/visual-header.md`
+- `skills/mcp-tools-reference.md`
+
 ## Usage
 
 ```
@@ -10,46 +15,35 @@ Manage sites and locations in NetBox.
 
 ## Instructions
 
-You are a site/location management assistant with access to NetBox.
+Execute `skills/visual-header.md` with context "Site Management".
 
 ### Actions
 
 **Sites:**
-- `list` - List all sites using `dcim_list_sites`
-- `show <name>` - Get site details using `dcim_get_site`
-- `create <name>` - Create new site using `dcim_create_site`
-- `update <name>` - Update site using `dcim_update_site`
+- `list` - List all sites: `dcim_list_sites`
+- `show <name>` - Get site details: `dcim_get_site`
+- `create <name>` - Create new site: `dcim_create_site`
+- `update <name>` - Update site: `dcim_update_site`
 - `delete <name>` - Delete site (with confirmation)
 
-**Locations (within sites):**
-- `locations at <site>` - List locations using `dcim_list_locations`
-- `create location <name> at <site>` - Create location using `dcim_create_location`
+**Locations:**
+- `locations at <site>` - List locations: `dcim_list_locations`
+- `create location <name> at <site>` - Create location
 
 **Racks:**
-- `racks at <site>` - List racks using `dcim_list_racks`
-- `create rack <name> at <site>` - Create rack using `dcim_create_rack`
+- `racks at <site>` - List racks: `dcim_list_racks`
+- `create rack <name> at <site>` - Create rack
 
 **Regions:**
-- `regions` - List regions using `dcim_list_regions`
-- `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
+- `regions` - List regions: `dcim_list_regions`
+- `create region <name>` - Create region
 
 ## Examples
 
-- `/cmdb-site list` - Show all sites
-- `/cmdb-site show headquarters` - Get HQ site details
-- `/cmdb-site create branch-office-nyc` - Create new site
-- `/cmdb-site racks at headquarters` - List racks at HQ
+- `/cmdb-site list`
+- `/cmdb-site show headquarters`
+- `/cmdb-site create branch-office-nyc`
+- `/cmdb-site racks at headquarters`
 
 ## User Request
 

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

@@ -4,7 +4,14 @@ description: Synchronize current machine state with existing NetBox record
 
 # CMDB Machine Sync
 
-Update an existing NetBox device record with the current machine state. Compares local system information with NetBox and applies changes.
+Update an existing NetBox device record with the current machine state.
+
+## Skills to Load
+
+- `skills/visual-header.md`
+- `skills/sync-workflow.md`
+- `skills/system-discovery.md`
+- `skills/mcp-tools-reference.md`
 
 ## Usage
 
@@ -18,318 +25,32 @@ Update an existing NetBox device record with the current machine state. Compares
 
 ## Instructions
 
-You are synchronizing the current machine's state with its NetBox record. This involves comparing current system state with stored data and updating differences.
-
-**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference.
-
-### Phase 1: Device Lookup (via MCP)
-
-First, find the existing device record:
-
-```bash
-# Get current hostname
-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
+Execute `skills/visual-header.md` with context "Machine Sync".
+
+Execute `skills/sync-workflow.md` which covers:
+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
+
+| Mode | Behavior |
+|------|----------|
+| Default | Show diff, ask confirmation, apply changes |
+| `--dry-run` | Show diff only, no changes applied |
+| `--full` | Skip confirmation, update all fields |
 
 ## Error Handling
 
-- **Device not found:** Suggest `/cmdb-register`
-- **Permission denied on updates:** Note which failed, continue with others
-- **Cluster not found:** Offer to create or skip container sync
-- **API errors:** Log error, continue with remaining updates
+| 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 |
 
 ## User Request