Merge pull request 'feat(projman): add plan-then-batch skill optimization' (#421 ) from feat/plan-then-batch-optimization into development

Reviewed-on: #421
feat(projman): add plan-then-batch skill optimization
2026-02-04 00:59:03 +00:00 · 2026-02-03 19:57:10 -05:00 · 2026-02-03 20:48:48 +00:00 · 2026-02-03 20:48:33 +00:00 · 2026-02-03 15:11:15 -05:00 · 2026-02-03 20:07:40 +00:00
330 changed files with 25744 additions and 12142 deletions
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -6,12 +6,12 @@
  },
  "metadata": {
    "description": "Project management plugins with Gitea and NetBox integrations",
-    "version": "5.0.0"
+    "version": "5.10.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,14 +20,14 @@
      },
      "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",
+      "version": "1.1.0",
      "description": "Automatic documentation drift detection and synchronization",
      "source": "./plugins/doc-guardian",
      "author": {
@@ -43,7 +43,7 @@
    },
    {
      "name": "code-sentinel",
-      "version": "1.0.0",
+      "version": "1.0.1",
      "description": "Security scanning and code refactoring tools",
      "source": "./plugins/code-sentinel",
      "author": {
@@ -75,8 +75,8 @@
    },
    {
      "name": "cmdb-assistant",
-      "version": "1.0.0",
+      "version": "1.2.0",
-      "description": "NetBox CMDB integration for infrastructure management",
+      "description": "NetBox CMDB integration with data quality validation and machine registration",
      "source": "./plugins/cmdb-assistant",
      "author": {
        "name": "Leo Miranda",
@@ -84,15 +84,15 @@
      },
      "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"],
+      "hooks": ["./hooks/hooks.json"],
      "category": "infrastructure",
-      "tags": ["cmdb", "netbox", "dcim", "ipam"],
+      "tags": ["cmdb", "netbox", "dcim", "ipam", "data-quality", "validation"],
      "license": "MIT"
    },
    {
      "name": "claude-config-maintainer",
-      "version": "1.0.0",
+      "version": "1.2.0",
-      "description": "CLAUDE.md optimization and maintenance for Claude Code projects",
+      "description": "CLAUDE.md and settings.local.json optimization for Claude Code projects",
      "source": "./plugins/claude-config-maintainer",
      "author": {
        "name": "Leo Miranda",
@@ -100,13 +100,14 @@
      },
      "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.0.0",
+      "version": "1.2.0",
      "description": "Prompt optimization and requirement clarification with ND-friendly accommodations",
      "source": "./plugins/clarity-assist",
      "author": {
@@ -115,13 +116,14 @@
      },
      "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.0.0",
+      "version": "1.2.0",
      "description": "Git workflow automation with intelligent commit messages and branch management",
      "source": "./plugins/git-flow",
      "author": {
@@ -130,13 +132,14 @@
      },
      "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.0.0",
+      "version": "1.1.0",
      "description": "Multi-agent pull request review with confidence scoring and actionable feedback",
      "source": "./plugins/pr-review",
      "author": {
@@ -145,14 +148,14 @@
      },
      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/pr-review/README.md",
      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": ["./.mcp.json"],
+      "hooks": ["./hooks/hooks.json"],
      "category": "development",
      "tags": ["code-review", "pull-requests", "security", "quality"],
      "license": "MIT"
    },
    {
      "name": "data-platform",
-      "version": "1.0.0",
+      "version": "1.3.0",
      "description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
      "source": "./plugins/data-platform",
      "author": {
@@ -161,14 +164,14 @@
      },
      "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"],
+      "hooks": ["./hooks/hooks.json"],
      "category": "data",
      "tags": ["pandas", "postgresql", "postgis", "dbt", "data-engineering", "etl"],
      "license": "MIT"
    },
    {
      "name": "viz-platform",
-      "version": "1.0.0",
+      "version": "1.1.0",
      "description": "Visualization tools with Dash Mantine Components validation, Plotly charts, and theming",
      "source": "./plugins/viz-platform",
      "author": {
@@ -177,14 +180,14 @@
      },
      "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"],
+      "hooks": ["./hooks/hooks.json"],
      "category": "visualization",
      "tags": ["dash", "plotly", "mantine", "charts", "dashboards", "theming", "dmc"],
      "license": "MIT"
    },
    {
      "name": "contract-validator",
-      "version": "1.0.0",
+      "version": "1.2.0",
      "description": "Cross-plugin compatibility validation and Claude.md agent verification",
      "source": "./plugins/contract-validator",
      "author": {
@@ -193,7 +196,7 @@
      },
      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/contract-validator/README.md",
      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": ["./.mcp.json"],
+      "hooks": ["./hooks/hooks.json"],
      "category": "development",
      "tags": ["validation", "contracts", "compatibility", "agents", "interfaces", "cross-plugin"],
      "license": "MIT"
--- a/.claude/backups/CLAUDE.md.2026-01-22_132037
+++ b/.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
--- a/.doc-guardian-queue
+++ b/.doc-guardian-queue
@@ -0,0 +1,27 @@
 # 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
--- a/.env
+++ b/.env
@@ -0,0 +1 @@
 GITEA_REPO=personal-projects/leo-claude-mktplace
--- a/.gitignore
+++ b/.gitignore
@@ -31,6 +31,8 @@ venv/
 ENV/
 env/
 .venv/
 .venv
 **/.venv
 # PyCharm
 .idea/
@@ -82,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/
--- a/.mcp.json
+++ b/.mcp.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": []
    }
  }
 }
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,609 @@ All notable changes to the Leo Claude Marketplace will be documented in this fil
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [Unreleased]
 ---
 ## [6.0.0] - YYYY-MM-DD
 ### 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
  - Branch-aware security: only allowed on development/feature branches
  - Completes the PR lifecycle (was previously missing - only had list/get/review/comment)
 #### cmdb-assistant v1.1.0 - Data Quality Validation
 - **SessionStart Hook**: Tests NetBox API connectivity at session start
  - Warns if VMs exist without site assignment
  - Warns if devices exist without platform
  - Non-blocking: displays warning, doesn't prevent work
 - **PreToolUse Hook**: Validates input parameters before VM/device operations
  - Warns about missing site, tenant, platform
  - Non-blocking: suggests best practices without blocking
 - **`/cmdb-audit` Command**: Comprehensive data quality analysis
  - Scopes: all, vms, devices, naming, roles
  - Identifies Critical/High/Medium/Low issues
  - Provides prioritized remediation recommendations
 - **`/cmdb-register` Command**: Register current machine into NetBox
  - Discovers system info: hostname, platform, hardware, network interfaces
  - Discovers running apps: Docker containers, systemd services
  - Creates device with interfaces, IPs, and sets primary IP
  - Creates cluster and VMs for Docker containers
 - **`/cmdb-sync` Command**: Sync machine state with NetBox
  - Compares current state with NetBox record
  - Shows diff of changes (interfaces, IPs, containers)
  - Updates with user confirmation
  - Supports --full and --dry-run flags
 - **NetBox Best Practices Skill**: Reference documentation
  - Dependency order for object creation
  - Naming conventions (`{role}-{site}-{number}`, `{env}-{app}-{number}`)
  - Role consolidation guidance
  - Site/tenant/platform assignment requirements
 - **Agent Enhancement**: Updated cmdb-assistant agent with validation requirements
  - Proactive suggestions for missing fields
  - Naming convention checks
  - Dependency order enforcement
  - Duplicate prevention
 ---
 ## [5.0.0] - 2026-01-26
 ### Added
--- a/CLAUDE.md
+++ b/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
+- **Do not interpret or summarize unless asked**
 - **Don't interpret or summarize unless asked**
 ### 5. AFTER PLUGIN UPDATES - VERIFY AND RESTART
 **⚠️ DO NOT clear cache mid-session** - this breaks MCP tools that are already loaded.
 1. Run `./scripts/verify-hooks.sh` to check hook types
 2. If changes affect MCP servers or hooks, inform the user:
   > "Plugin changes require a session restart to take effect. Please restart Claude Code."
 3. Cache clearing is ONLY safe **before** starting a new session (not during)
 See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing.
 **FAILURE TO FOLLOW THESE RULES = WASTED USER TIME = UNACCEPTABLE**
 ---
 This file provides guidance to Claude Code when working with code in this repository.
 ## ⛔ RULES - READ FIRST
 ### Behavioral Rules
 | Rule | Summary |
 |------|---------|
 | **Check everything** | Search cache (`~/.claude/plugins/cache/`), installed (`~/.claude/plugins/marketplaces/`), and source (`~/claude-plugins-work/`) |
 | **Believe the user** | User knows their system. Investigate before disagreeing. |
 | **Verify before "done"** | Run commands, show output, check all locations. "Done" = verified working. |
 | **Show what's asked** | Don't interpret or summarize unless asked. |
 ### After Plugin Updates
 Run `./scripts/verify-hooks.sh`. If changes affect MCP servers or hooks, inform user to restart session.
 **DO NOT clear cache mid-session** - breaks loaded MCP tools.
 ### NEVER USE CLI TOOLS FOR EXTERNAL SERVICES
 - **FORBIDDEN:** `gh`, `tea`, `curl` to APIs, any CLI that talks to Gitea/GitHub/external services
 - **REQUIRED:** Use MCP tools exclusively (`mcp__plugin_projman_gitea__*`, `mcp__plugin_pr-review_gitea__*`)
 - **NO EXCEPTIONS.** Don't try CLI first. Don't fall back to CLI. MCP ONLY.
 ### NEVER PUSH DIRECTLY TO PROTECTED BRANCHES
 - **FORBIDDEN:** `git push origin development`, `git push origin main`, `git push origin master`
 - **REQUIRED:** Create feature branch → push feature branch → create PR via MCP
 - If you accidentally commit to a protected branch locally: `git checkout -b fix/branch-name` then reset the protected branch
 ### Repository Rules
 | Rule | Details |
 |------|---------|
 | **File creation** | Only in allowed paths. Use `.scratch/` for temp work. Verify against `docs/CANONICAL-PATHS.md` |
 | **plugin.json location** | Must be in `.claude-plugin/` directory |
 | **Hooks** | Use `hooks/hooks.json` (auto-discovered). Never inline in plugin.json |
 | **MCP servers** | Defined in root `.mcp.json`. Use MCP tools, never CLI (`tea`, `gh`) |
 | **Allowed root files** | `CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example` |
 **Valid hook events:** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
 ### ⛔ MANDATORY: Before Any Code Change
 **Claude MUST show this checklist BEFORE editing any file:**
 #### 1. Impact Search Results
 Run and show output of:
 ```bash
 grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
 ```
 #### 2. Files That Will Be Affected
 Numbered list of every file to be modified, with the specific change for each.
 #### 3. Files Searched But Not Changed (and why)
 Proof that related files were checked and determined unchanged.
 #### 4. Documentation That References This
 List of docs that mention this feature/script/function.
 **User verifies this list before Claude proceeds. If Claude skips this, STOP IMMEDIATELY.**
 #### After Changes
 Run the same grep and show results proving no references remain unaddressed.
 ---
 ## ⚠️ Development Context: We Build AND Use These Plugins
 **This is a self-referential project.** We are:
 1. **BUILDING** a plugin marketplace (source code in `plugins/`)
 2. **USING** the installed marketplace to build it (dogfooding)
 ### Plugins ACTIVELY USED in This Project
 These plugins are installed and should be used during development:
 | Plugin | Used For |
 |--------|----------|
 | **projman** | Sprint planning, issue management, lessons learned |
 | **git-flow** | Commits, branch management |
 | **pr-review** | Pull request reviews |
 | **doc-guardian** | Documentation drift detection |
 | **code-sentinel** | Security scanning, refactoring |
 | **clarity-assist** | Prompt clarification |
 | **claude-config-maintainer** | CLAUDE.md optimization |
 | **contract-validator** | Cross-plugin compatibility |
 ### Plugins NOT Used Here (Development Only)
 These plugins exist in source but are **NOT relevant** to this project's workflow:
 | Plugin | Why Not Used |
 |--------|--------------|
 | **data-platform** | For data engineering projects (pandas, PostgreSQL, dbt) |
 | **viz-platform** | For dashboard projects (Dash, Plotly) |
 | **cmdb-assistant** | For infrastructure projects (NetBox) |
 **Do NOT suggest** `/ingest`, `/profile`, `/chart`, `/cmdb-*` commands - they don't apply here.
 ### Key Distinction
 | Context | Path | What To Do |
 |---------|------|------------|
 | **Editing plugin source** | `~/claude-plugins-work/plugins/` | Modify code, add features |
 | **Using installed plugins** | `~/.claude/plugins/marketplaces/` | Run commands like `/sprint-plan` |
 When user says "run /sprint-plan", use the INSTALLED plugin.
 When user says "fix the sprint-plan command", edit the SOURCE code.
 ---
 ## Project Overview
 **Repository:** leo-claude-mktplace
-**Version:** 5.0.0
+**Version:** 5.9.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 |
+| `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 1.2.0 |
-| `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 1.0.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.0.0 |
+| `viz-platform` | DMC validation, Plotly charts, and theming for dashboards | 1.1.0 |
-| `contract-validator` | Cross-plugin compatibility validation and agent verification | 1.0.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` |
+| **Setup** | `/setup` (modes: `--full`, `--quick`, `--sync`) |
-| **Sprint** | `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close` |
+| **Sprint** | `/sprint-plan`, `/sprint-start`, `/sprint-status` (with `--diagram`), `/sprint-close` |
-| **Quality** | `/review`, `/test-check`, `/test-gen` |
+| **Quality** | `/review`, `/test` (modes: `run`, `gen`) |
 | **Versioning** | `/suggest-version` |
-| **PR Review** | `/pr-review:initial-setup`, `/pr-review:project-init` |
+| **PR Review** | `/pr-review`, `/pr-summary`, `/pr-findings`, `/pr-diff` |
-| **Docs** | `/doc-audit`, `/doc-sync` |
+| **Docs** | `/doc-audit`, `/doc-sync`, `/changelog-gen`, `/doc-coverage`, `/stale-docs` |
 | **Security** | `/security-scan`, `/refactor`, `/refactor-dry` |
-| **Config** | `/config-analyze`, `/config-optimize` |
+| **Config** | `/config-analyze`, `/config-optimize`, `/config-diff`, `/config-lint` |
-| **Data** | `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/run` |
+| **Validation** | `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/dependency-graph` |
-| **Visualization** | `/component`, `/chart`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css` |
+| **Debug** | `/debug` (modes: `report`, `review`) |
-| **Validation** | `/validate-contracts`, `/check-agent`, `/list-interfaces` |
+
-| **Debug** | `/debug-report`, `/debug-review` |
+### Plugin Commands - NOT RELEVANT to This Project
 These commands are being developed but don't apply to this project's workflow:
 | Category | Commands | For Projects Using |
 |----------|----------|-------------------|
 | **Data** | `/ingest`, `/profile`, `/schema`, `/lineage`, `/dbt-test` | pandas, PostgreSQL, dbt |
 | **Visualization** | `/component`, `/chart`, `/dashboard`, `/theme` | Dash, Plotly dashboards |
 | **CMDB** | `/cmdb-search`, `/cmdb-device`, `/cmdb-sync` | NetBox infrastructure |
 ## Repository Structure
@@ -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
+│   │   ├── commands/             # 12 commands
-│   │   ├── mcp-servers/gitea -> ../../../mcp-servers/gitea  # SYMLINK
+│   │   ├── hooks/                # SessionStart: mismatch detection
 │   │   ├── commands/             # 14 commands (incl. setup, debug, suggest-version)
 │   │   ├── hooks/                # SessionStart: mismatch detection + sprint suggestions
 │   │   ├── 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
+│   │   ├── commands/             # 6 commands
 │   │   ├── mcp-servers/gitea -> ../../../mcp-servers/gitea  # SYMLINK
 │   │   ├── commands/             # 6 commands (incl. setup)
 │   │   ├── hooks/                # SessionStart mismatch detection
 │   │   └── agents/               # 5 agents
 │   ├── clarity-assist/           # Prompt optimization
 │   │   ├── .claude-plugin/plugin.json
 │   │   ├── commands/             # 2 commands
 │   │   └── agents/
-│   ├── data-platform/            # Data engineering (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`
+3. Create `claude-md-integration.md`
-4. If using MCP server, create symlink: `ln -s ../../../mcp-servers/{server} plugins/{name}/mcp-servers/{server}`
+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`
+2. Update marketplace description if significant
 3. 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 `/debug report` to diagnose |
 | Changes not taking effect | Editing source, not installed | Reinstall plugin or edit installed path |
 **Debug Commands:**
- `/debug-report` - Run full diagnostics, create issue if needed
+- `/debug report` - Run full diagnostics, create issue if needed
- `/debug-review` - Investigate and propose fixes
+- `/debug review` - Investigate and propose fixes
 ## Versioning Workflow
@@ -376,4 +508,4 @@ The script will:
 ---
-**Last Updated:** 2026-01-24
+**Last Updated:** 2026-02-02
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Leo Claude Marketplace - v5.0.0
+# Leo Claude Marketplace - v5.10.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`, `/setup`, `/review`, `/test`, `/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.
@@ -34,7 +35,7 @@ Smart git operations with intelligent commit messages and branch management.
 **Commands:** `/commit`, `/commit-push`, `/commit-merge`, `/commit-sync`, `/branch-start`, `/branch-cleanup`, `/git-status`, `/git-config`
-#### [pr-review](./plugins/pr-review/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,18 +45,31 @@ 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`, `/initial-setup`, `/project-init`, `/project-sync`
-#### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md)
+#### [claude-config-maintainer](./plugins/claude-config-maintainer)
-**CLAUDE.md Optimization and Maintenance**
+**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) *NEW in v5.0.0*
 **Cross-Plugin Compatibility Validation**
 Validate plugin marketplaces for command conflicts, tool overlaps, and broken agent references.
 - Interface parsing from plugin README.md files
 - Agent extraction from CLAUDE.md definitions
 - Pairwise compatibility checks between all plugins
 - Data flow validation for agent sequences
 - Markdown or JSON reports with actionable suggestions
 **Commands:** `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/dependency-graph`, `/initial-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.
@@ -66,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.
@@ -89,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:** `/initial-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*
+#### [data-platform](./plugins/data-platform) *NEW in v4.0.0*
 **pandas, PostgreSQL/PostGIS, and dbt Integration**
 Comprehensive data engineering toolkit with persistent DataFrame storage.
@@ -109,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:** `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/lineage-viz`, `/run`, `/dbt-test`, `/data-quality`, `/data-review`, `/data-gate`, `/initial-setup`
 ### Visualization
-#### [viz-platform](./plugins/viz-platform/README.md) *NEW*
+#### [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.
@@ -125,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:** `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/accessibility-check`, `/breakpoints`, `/design-review`, `/design-gate`, `/initial-setup`
 ## Domain Advisory Pattern
 The marketplace supports cross-plugin domain advisory integration:
 - **Domain Detection**: projman automatically detects when issues involve specialized domains (frontend/viz, data engineering)
 - **Acceptance Criteria**: Domain-specific acceptance criteria are added to issues during planning
 - **Execution Gates**: Domain validation gates (`/design-gate`, `/data-gate`) run before issue completion
 - **Extensible**: New domains can be added by creating advisory agents and gate commands
 **Current Domains:**
 | Domain | Plugin | Gate Command |
 |--------|--------|--------------|
 | Visualization | viz-platform | `/design-gate` |
 | Data | data-platform | `/data-gate` |
 ## MCP Servers
-MCP servers are **shared at repository root** with **symlinks** from plugins that use them.
+MCP servers are **shared at repository root** and configured in `.mcp.json`.
 ### Gitea MCP Server (shared)
@@ -157,7 +186,7 @@ Comprehensive NetBox REST API integration for infrastructure management.
 | Virtualization | Clusters, VMs, Interfaces |
 | Extras | Tags, Custom Fields, Audit Log |
-### Data Platform MCP Server (shared) *NEW*
+### Data Platform MCP Server (shared) *NEW in v4.0.0*
 pandas, PostgreSQL/PostGIS, and dbt integration for data engineering.
@@ -168,7 +197,7 @@ pandas, PostgreSQL/PostGIS, and dbt integration for data engineering.
 | PostGIS | `st_tables`, `st_geometry_type`, `st_srid`, `st_extent` |
 | dbt | `dbt_parse`, `dbt_run`, `dbt_test`, `dbt_build`, `dbt_compile`, `dbt_ls`, `dbt_docs_generate`, `dbt_lineage` |
-### Viz Platform MCP Server (shared) *NEW*
+### Viz Platform MCP Server (shared) *NEW in v4.0.0*
 Dash Mantine Components validation and visualization tools.
@@ -180,6 +209,16 @@ Dash Mantine Components validation and visualization tools.
 | Theme | `theme_create`, `theme_extend`, `theme_validate`, `theme_export_css`, `theme_list`, `theme_activate` |
 | Page | `page_create`, `page_add_navbar`, `page_set_auth`, `page_list`, `page_get_app_config` |
 ### Contract Validator MCP Server (shared) *NEW in v5.0.0*
 Cross-plugin compatibility validation tools.
 | Category | Tools |
 |----------|-------|
 | Parse | `parse_plugin_interface`, `parse_claude_md_agents` |
 | Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow`, `validate_workflow_integration` |
 | Report | `generate_compatibility_report`, `list_issues` |
 ## Installation
 ### Prerequisites
@@ -274,10 +313,11 @@ 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` |
 | contract-validator | `/contract-validator:validate-contracts` |
 ## Repository Structure
@@ -289,14 +329,16 @@ leo-claude-mktplace/
 │   ├── gitea/                     # Gitea MCP (issues, PRs, wiki)
 │   ├── netbox/                    # NetBox MCP (CMDB)
 │   ├── data-platform/             # Data engineering (pandas, PostgreSQL, dbt)
-│   └── viz-platform/              # Visualization (DMC, Plotly, theming)
+│   ├── viz-platform/              # Visualization (DMC, Plotly, theming)
 │   └── contract-validator/        # Cross-plugin validation (v5.0.0)
 ├── plugins/                       # All plugins
 │   ├── projman/                   # Sprint management
 │   ├── git-flow/                  # Git workflow automation
 │   ├── pr-review/                 # PR review
 │   ├── clarity-assist/            # Prompt optimization
 │   ├── data-platform/             # Data engineering
-│   ├── viz-platform/              # Visualization (NEW)
+│   ├── viz-platform/              # Visualization
 │   ├── contract-validator/        # Cross-plugin validation (NEW)
 │   ├── claude-config-maintainer/  # CLAUDE.md optimization
 │   ├── cmdb-assistant/            # NetBox CMDB integration
 │   ├── doc-guardian/              # Documentation drift detection
--- a/docs/CANONICAL-PATHS.md
+++ b/docs/CANONICAL-PATHS.md
@@ -2,7 +2,7 @@
 **This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
-Last Updated: 2026-01-26 (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)
+│   ├── post-update.sh          # Post-update (clear cache, show changelog)
-│   ├── check-venv.sh           # Check if venvs exist (for hooks)
+│   ├── check-venv.sh           # Check if venvs exist (read-only)
-│   └── validate-marketplace.sh # Marketplace compliance validation
+│   ├── 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/` |
+| MCP venv (local) | `mcp-servers/{server}/.venv/` | `mcp-servers/gitea/.venv/` |
 | Plugin symlink | `plugins/{plugin}/mcp-servers/{server}` | `plugins/projman/mcp-servers/gitea` |
-### 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
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/{server}/.venv/bin/python"
-ln -s ../../../mcp-servers/gitea plugins/projman/mcp-servers/gitea
+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
+.mcp.json (at repository root)
-  → Uses ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/
+  → Uses absolute installed path: ~/.claude/plugins/marketplaces/.../mcp-servers/gitea/run.sh
  → Symlink at plugins/projman/mcp-servers/gitea points to ../../../mcp-servers/gitea
 Result in .mcp.json: ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/.venv/bin/python
 ```
 From `.claude-plugin/marketplace.json` to `plugins/projman/`:
@@ -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/` |
+| `mcp-servers/` inside plugins | MCP servers are shared at root | Use root `mcp-servers/` |
-| Creating new mcp-servers inside plugins | Use shared + symlink | Symlink to `mcp-servers/` |
+| Plugin-level `.mcp.json` | MCP config is at root | Use root `.mcp.json` |
-| Hardcoding absolute paths | Breaks portability | Use `${CLAUDE_PLUGIN_ROOT}` |
+| 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
+- No duplication - clean plugin structure
- Symlinks work with Claude Code caching
+- Simple configuration in one place
-**Symlink Pattern:**
+**Configuration:**
-```
+All MCP servers are defined in `.mcp.json` at repository root:
-plugins/projman/mcp-servers/gitea -> ../../../mcp-servers/gitea
+```json
-plugins/cmdb-assistant/mcp-servers/netbox -> ../../../mcp-servers/netbox
+{
-plugins/pr-review/mcp-servers/gitea -> ../../../mcp-servers/gitea
+  "mcpServers": {
-plugins/data-platform/mcp-servers/data-platform -> ../../../mcp-servers/data-platform
+    "gitea": { "command": ".../mcp-servers/gitea/run.sh" },
-plugins/viz-platform/mcp-servers/viz-platform -> ../../../mcp-servers/viz-platform
+    "netbox": { "command": ".../mcp-servers/netbox/run.sh" },
-plugins/contract-validator/mcp-servers/contract-validator -> ../../../mcp-servers/contract-validator
+    "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 |
--- a/docs/COMMANDS-CHEATSHEET.md
+++ b/docs/COMMANDS-CHEATSHEET.md
@@ -9,20 +9,18 @@ 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-start` | | X | Begin sprint execution with dependency analysis and parallel task coordination (requires approval or `--force`) |
-| **projman** | `/sprint-status` | | X | Check current sprint progress and identify blockers |
+| **projman** | `/sprint-status` | | X | Check current sprint progress (add `--diagram` for Mermaid visualization) |
 | **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** | `/test` | | X | Run tests (`/test run`) or generate tests (`/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** | `/setup` | | X | Auto-detect mode or use `--full`, `--quick`, `--sync`, `--clear-cache` |
-| **projman** | `/project-init` | | X | Quick project setup (assumes system config exists) |
+| **projman** | *SessionStart hook* | X | | Detects git remote vs .env mismatch, warns to run `/setup --sync` |
-| **projman** | `/project-sync` | | X | Sync config with git remote after repo move/rename |
+| **projman** | `/debug` | | X | Diagnostics (`/debug report`) or investigate (`/debug review`) |
 | **projman** | *SessionStart hook* | X | | Detects git remote vs .env mismatch, warns to run /project-sync |
 | **projman** | `/test-gen` | | X | Generate comprehensive tests for specified code |
 | **projman** | `/debug-report` | | X | Run diagnostics and create structured issue in marketplace |
 | **projman** | `/debug-review` | | X | Investigate diagnostic issues and propose fixes with approval gates |
 | **projman** | `/suggest-version` | | X | Analyze CHANGELOG and recommend semantic version bump |
 | **projman** | `/proposal-status` | | X | View proposal and implementation hierarchy with status |
 | **projman** | `/rfc` | | X | RFC lifecycle management (`/rfc create\|list\|review\|approve\|reject`) |
 | **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 |
@@ -38,10 +36,14 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **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,11 +52,22 @@ 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 |
 | **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** | `/initial-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 |
@@ -62,6 +75,9 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **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** | `/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** | `/initial-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 |
@@ -71,7 +87,19 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **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** | `/chart-export` | | X | Export charts to PNG, SVG, PDF via kaleido |
 | **viz-platform** | `/accessibility-check` | | X | Color blind validation (WCAG contrast ratios) |
 | **viz-platform** | `/breakpoints` | | X | Configure responsive layout breakpoints |
 | **viz-platform** | `/design-review` | | X | Detailed design system audits |
 | **viz-platform** | `/design-gate` | | X | Binary pass/fail design system validation gates |
 | **viz-platform** | *SessionStart hook* | X | | Checks DMC version (non-blocking warning) |
 | **data-platform** | `/data-review` | | X | Comprehensive data integrity audits |
 | **data-platform** | `/data-gate` | | X | Binary pass/fail data integrity gates |
 | **contract-validator** | `/validate-contracts` | | X | Full marketplace compatibility validation |
 | **contract-validator** | `/check-agent` | | X | Validate single agent definition |
 | **contract-validator** | `/list-interfaces` | | X | Show all plugin interfaces |
 | **contract-validator** | `/dependency-graph` | | X | Mermaid visualization of plugin dependencies |
 | **contract-validator** | `/initial-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 | `/setup`, `/initial-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:
@@ -119,9 +164,9 @@ A typical workflow for planning and executing a feature sprint:
 5. /branch-start feat/...    # Create feature branch
   ... implement features ...
 6. /commit                   # Commit with conventional message
-7. /sprint-status            # Check progress mid-sprint
+7. /sprint-status --diagram  # Check progress with visualization
 8. /review                   # Pre-close quality review
-9. /test-check               # Verify test coverage
+9. /test run                 # Verify test coverage
 10. /sprint-close            # Capture lessons learned
 ```
@@ -168,7 +213,7 @@ 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
+4. /test run                 # Verify nothing broke
 5. /commit                   # Commit with descriptive message
 ```
@@ -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. /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. /setup --quick            # Quick project setup (auto-detected)
   # → Confirms detected repo name
   # → Creates .env
 2. /labels-sync              # Sync Gitea labels
@@ -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*
--- a/docs/CONFIGURATION.md
+++ b/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
+/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
+                              /setup --full
                          (or /setup auto-detects)
                                    │
     ┌──────────────────────────────┼──────────────────────────────┐
     ▼                              ▼                              ▼
@@ -78,8 +79,8 @@ The interactive wizard handles everything except manually adding your API tokens
                                    │
                    ┌───────────────┴───────────────┐
                    ▼                               ▼
-             /project-init                   /initial-setup
+             /setup --quick                     /setup
-             (direct path)                   (smart detection)
+             (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
+### `/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
+### `/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 |
+| Mode | When to Use | What It Does |
-|---------|-------------|--------------|
+|------|-------------|--------------|
-| `/initial-setup` | First time on a machine | Full setup: MCP server + system config + project config |
+| `/setup` | Any time | Auto-detects: runs full, quick, or sync as needed |
-| `/project-init` | Starting a new project | Quick setup: project config only (assumes system is ready) |
+| `/setup --full` | First time on a machine | Full setup: MCP server + system config + project config |
-| `/project-sync` | After repo move/rename | Updates .env to match current git remote |
+| `/setup --quick` | Starting a new project | Quick setup: project config only (assumes system is ready) |
 | `/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)
+1. Install plugin → run `/setup` (auto-runs full mode)
-2. Start new project → run `/project-init` (once per project)
+2. Start new project → run `/setup` (auto-runs quick mode)
-3. Repository moved? → run `/project-sync` (updates config)
+3. Repository moved? → run `/setup` (auto-runs sync mode)
 **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
 ---
@@ -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 as owner/repo format    │
 │  GITEA_REPO              │  Repository name for this project   │
 │  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 `/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 `/setup`:
 1. **Python 3.10+** installed
   ```bash
@@ -211,10 +213,10 @@ Before running `/initial-setup`:
 Run the setup wizard in Claude Code:
 ```
-/initial-setup
+/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-organization/your-repo-name
 GITEA_REPO=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
+# Required for projman, pr-review (use owner/repo format)
-GITEA_ORG=your-organization
+GITEA_REPO=your-organization/your-repo-name
 GITEA_REPO=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 in `owner/repo` format (e.g., `my-org/my-repo`) |
 | `GITEA_REPO` | Yes | Repository name (must match Gitea exactly) |
 | `GIT_WORKFLOW_STYLE` | No | Override system default |
 | `PR_REVIEW_*` | No | PR review settings |
@@ -386,10 +385,10 @@ PR_REVIEW_AUTO_SUBMIT=false
 ## Plugin Configuration Summary
-| Plugin | System Config | Project Config | Setup Commands |
+| Plugin | System Config | Project Config | Setup Command |
-|--------|---------------|----------------|----------------|
+|--------|---------------|----------------|---------------|
-| **projman** | gitea.env | .env (GITEA_ORG, GITEA_REPO) | `/initial-setup`, `/project-init`, `/project-sync` |
+| **projman** | gitea.env | .env (GITEA_REPO=owner/repo) | `/setup` |
-| **pr-review** | gitea.env | .env (GITEA_ORG, GITEA_REPO) | `/initial-setup`, `/project-init`, `/project-sync` |
+| **pr-review** | gitea.env | .env (GITEA_REPO=owner/repo) | `/initial-setup` |
 | **git-flow** | git-flow.env (optional) | .env (optional) | None needed |
 | **clarity-assist** | None | None | None needed |
 | **cmdb-assistant** | netbox.env | None | `/initial-setup` |
@@ -399,6 +398,7 @@ PR_REVIEW_AUTO_SUBMIT=false
 | **code-sentinel** | None | None | None needed |
 | **project-hygiene** | None | None | None needed |
 | **claude-config-maintainer** | None | None | None needed |
 | **contract-validator** | None | None | `/initial-setup` |
 ---
@@ -406,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
+/setup
 ```
-**Option 2: Use `/initial-setup` (auto-detects)**
+The command auto-detects that system config exists and runs quick project setup.
-```
+
-cd ~/projects/new-project
+---
-/initial-setup
+
-# → Detects system config exists
+## Installing Plugins to Consumer Projects
-# → Offers "Quick project setup" option
+
 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 `/setup`, the command:
-1. **Detect** organization and repository from git remote URL
+1. **Detects** organization and repository from git remote URL
-2. **Validate** via Gitea API: `GET /api/v1/repos/{org}/{repo}`
+2. **Validates** via Gitea API: `GET /api/v1/repos/{org}/{repo}`
-3. **Auto-fill** if repository exists and is accessible (no confirmation needed)
+3. **Auto-fills** if repository exists and is accessible (no confirmation needed)
-4. **Ask for confirmation** only if validation fails (404 or permission error)
+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 `/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 `/setup` wizard respects this
 4. **Rotate tokens periodically**
   - Every 6-12 months
--- a/docs/DEBUGGING-CHECKLIST.md
+++ b/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
+# Check .mcp.json exists and has valid content
-readlink -f $RUNTIME/plugins/projman/mcp-servers/gitea
+cat $RUNTIME/.mcp.json | jq '.mcpServers | keys'
 readlink -f $RUNTIME/plugins/pr-review/mcp-servers/gitea
 readlink -f $RUNTIME/plugins/cmdb-assistant/mcp-servers/netbox
-# Should resolve to:
+# Should list: gitea, netbox, data-platform, viz-platform, contract-validator
 # $RUNTIME/mcp-servers/gitea
 # $RUNTIME/mcp-servers/netbox
 ```
 **If broken:** Symlinks are relative. If directory structure differs, they'll break.
 ---
 ## Step 5: Test MCP Server Startup
@@ -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 ==="
+echo -e "\n=== MCP Configuration ==="
-[ -L "$RUNTIME/plugins/projman/mcp-servers/gitea" ] && echo "projman->gitea: OK" || echo "projman->gitea: MISSING"
+[ -f "$RUNTIME/.mcp.json" ] && echo ".mcp.json: OK" || echo ".mcp.json: MISSING"
 [ -L "$RUNTIME/plugins/pr-review/mcp-servers/gitea" ] && echo "pr-review->gitea: OK" || echo "pr-review->gitea: MISSING"
 [ -L "$RUNTIME/plugins/cmdb-assistant/mcp-servers/netbox" ] && echo "cmdb-assistant->netbox: OK" || echo "cmdb-assistant->netbox: MISSING"
 echo -e "\n=== Config Files ==="
 [ -f ~/.config/claude/gitea.env ] && echo "gitea.env: OK" || echo "gitea.env: MISSING"
@@ -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 report` - Run full diagnostics, create issue if problems found
- `/debug-review` - Investigate existing diagnostic issues and propose fixes
+- `/debug review` - Investigate existing diagnostic issues and propose fixes
 ---
--- a/docs/UPDATING.md
+++ b/docs/UPDATING.md
@@ -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
@@ -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
--- a/mcp-servers/contract-validator/.doc-guardian-queue
+++ b/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
--- a/mcp-servers/contract-validator/mcp_server/server.py
+++ b/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:
--- a/mcp-servers/contract-validator/mcp_server/validation_tools.py
+++ b/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()
--- a/mcp-servers/contract-validator/run.sh
+++ b/mcp-servers/contract-validator/run.sh
@@ -0,0 +1,21 @@
 #!/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"
 if [[ -f "$CACHE_VENV/bin/python" ]]; then
    PYTHON="$CACHE_VENV/bin/python"
 elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
    PYTHON="$LOCAL_VENV/bin/python"
 else
    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
    exit 1
 fi
 cd "$SCRIPT_DIR"
 export PYTHONPATH="$SCRIPT_DIR"
 exec "$PYTHON" -m mcp_server.server "$@"
--- a/mcp-servers/contract-validator/tests/test_validation_tools.py
+++ b/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()
--- a/mcp-servers/data-platform/mcp_server/pandas_tools.py
+++ b/mcp-servers/data-platform/mcp_server/pandas_tools.py
@@ -330,7 +330,7 @@ class PandasTools:
            return {'error': f'DataFrame not found: {data_ref}'}
        try:
-            filtered = df.query(condition)
+            filtered = df.query(condition).reset_index(drop=True)
            result_name = name or f"{data_ref}_filtered"
            return self._check_and_store(
                filtered,
--- a/mcp-servers/data-platform/run.sh
+++ b/mcp-servers/data-platform/run.sh
@@ -0,0 +1,21 @@
 #!/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"
 if [[ -f "$CACHE_VENV/bin/python" ]]; then
    PYTHON="$CACHE_VENV/bin/python"
 elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
    PYTHON="$LOCAL_VENV/bin/python"
 else
    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
    exit 1
 fi
 cd "$SCRIPT_DIR"
 export PYTHONPATH="$SCRIPT_DIR"
 exec "$PYTHON" -m mcp_server.server "$@"
--- a/mcp-servers/gitea/.doc-guardian-queue
+++ b/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
--- a/mcp-servers/gitea/CHANGELOG.md
+++ b/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
--- a/mcp-servers/gitea/README.md
+++ b/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
+│   ├── server.py              # MCP server entry point (36 tools)
-│   ├── config.py              # Configuration loader
+│   ├── config.py              # Configuration loader with auto-detection
 │   ├── gitea_client.py        # Gitea API client
 │   └── tools/
 │       ├── __init__.py
-│       ├── issues.py          # Issue tools
+│       ├── issues.py          # Issue management tools
-│       └── labels.py          # Label 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/issues.py` - Issue management with branch detection
- `tools/labels.py` - Label management and suggestion
+- `tools/labels.py` - Label management and intelligent suggestions
- `server.py` - MCP server with JSON-RPC 2.0 over stdio
+- `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:
+### Recent Updates
- Configuration management (hybrid system + project)
+
- Gitea API client with all CRUD operations
+- **v1.3.0** - Pull request tools (7 tools), label creation tools (3)
- MCP server with 8 tools
+- **v1.2.0** - Milestone management (5 tools), issue dependencies (4 tools)
- Issue tools with branch detection
+- **v1.1.0** - Wiki & lessons learned system (7 tools)
- Label tools with intelligent suggestions
+- **v1.0.0** - Initial release with core issue/label tools (8 tools)
 - Mode detection (project vs company)
 - Branch-aware security model
 - 42 unit tests (100% passing)
 - Comprehensive documentation
 ## 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
--- a/mcp-servers/gitea/TESTING.md
+++ b/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)
--- a/mcp-servers/gitea/mcp_server/init.py
+++ b/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",
 ]
--- a/mcp-servers/gitea/mcp_server/gitea_client.py
+++ b/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()
@@ -787,3 +808,42 @@ class GiteaClient:
        response = self.session.post(url, json=data)
        response.raise_for_status()
        return response.json()
    def create_pull_request(
        self,
        title: str,
        body: str,
        head: str,
        base: str,
        labels: Optional[List[str]] = None,
        repo: Optional[str] = None
    ) -> Dict:
        """
        Create a new pull request.
        Args:
            title: PR title
            body: PR description/body
            head: Source branch name (the branch with changes)
            base: Target branch name (the branch to merge into)
            labels: Optional list of label names
            repo: Repository in 'owner/repo' format
        Returns:
            Created pull request dictionary
        """
        owner, target_repo = self._parse_repo(repo)
        url = f"{self.base_url}/repos/{owner}/{target_repo}/pulls"
        data = {
            'title': title,
            'body': body,
            'head': head,
            'base': base
        }
        if labels:
            label_ids = self._resolve_label_ids(labels, owner, target_repo)
            data['labels'] = label_ids
        logger.info(f"Creating PR '{title}' in {owner}/{target_repo}: {head} -> {base}")
        response = self.session.post(url, json=data)
        response.raise_for_status()
        return response.json()
--- a/mcp-servers/gitea/mcp_server/server.py
+++ b/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 .tool_registry import get_tool_definitions, create_tool_dispatcher
 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
 # 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._dispatcher = None
        self.label_tools = None
        self.wiki_tools = None
        self.milestone_tools = None
        self.dependency_tools = None
        self.pr_tools = 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._dispatcher = create_tool_dispatcher(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)
            logger.info(f"Gitea MCP Server initialized in {self.config['mode']} mode")
        except Exception as e:
@@ -70,782 +54,7 @@ class GiteaMCPServer:
        @self.server.list_tools()
        async def list_tools() -> list[Tool]:
            """Return list of available tools"""
-            return [
+            return get_tool_definitions()
                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"]
                    }
                )
            ]
        @self.server.call_tool()
        async def call_tool(name: str, arguments: dict) -> list[TextContent]:
@@ -859,120 +68,7 @@ class GiteaMCPServer:
            Returns:
                List of TextContent with results
            """
-            try:
+            return await self._dispatcher(name, arguments)
                # 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)
                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)}"
                )]
    async def run(self):
        """Run the MCP server"""
--- a/mcp-servers/gitea/mcp_server/tool_registry.py
+++ b/mcp-servers/gitea/mcp_server/tool_registry.py
--- a/mcp-servers/gitea/mcp_server/tools/issues.py
+++ b/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:
@@ -66,7 +82,13 @@ class IssueTools:
            return operation in ['list_issues', 'get_issue', 'get_labels', 'create_issue']
        # Development branches (full access)
-        if branch in ['development', 'develop'] or branch.startswith(('feat/', 'feature/', 'dev/')):
+        # Include all common feature/fix branch patterns
        dev_prefixes = (
            'feat/', 'feature/', 'dev/',
            'fix/', 'bugfix/', 'hotfix/',
            'chore/', 'refactor/', 'docs/', 'test/'
        )
        if branch in ['development', 'develop'] or branch.startswith(dev_prefixes):
            return True
        # Unknown branch - be restrictive
@@ -76,6 +98,7 @@ class IssueTools:
        self,
        state: str = 'open',
        labels: Optional[List[str]] = None,
        milestone: Optional[str] = None,
        repo: Optional[str] = None
    ) -> List[Dict]:
        """
@@ -84,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:
@@ -102,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(
@@ -178,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:
        """
@@ -189,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:
@@ -207,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(
--- a/mcp-servers/gitea/mcp_server/tools/pull_requests.py
+++ b/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:
@@ -69,7 +85,13 @@ class PullRequestTools:
            return operation in read_ops + ['add_pr_comment']
        # Development branches (full access)
-        if branch in ['development', 'develop'] or branch.startswith(('feat/', 'feature/', 'dev/')):
+        # Include all common feature/fix branch patterns
        dev_prefixes = (
            'feat/', 'feature/', 'dev/',
            'fix/', 'bugfix/', 'hotfix/',
            'chore/', 'refactor/', 'docs/', 'test/'
        )
        if branch in ['development', 'develop'] or branch.startswith(dev_prefixes):
            return True
        # Unknown branch - be restrictive
@@ -272,3 +294,42 @@ class PullRequestTools:
            None,
            lambda: self.gitea.add_pr_comment(pr_number, body, repo)
        )
    async def create_pull_request(
        self,
        title: str,
        body: str,
        head: str,
        base: str,
        labels: Optional[List[str]] = None,
        repo: Optional[str] = None
    ) -> Dict:
        """
        Create a new pull request (async wrapper with branch check).
        Args:
            title: PR title
            body: PR description/body
            head: Source branch name (the branch with changes)
            base: Target branch name (the branch to merge into)
            labels: Optional list of label names
            repo: Override configured repo (for PMO multi-repo)
        Returns:
            Created pull request dictionary
        Raises:
            PermissionError: If operation not allowed on current branch
        """
        if not self._check_branch_permissions('create_pull_request'):
            branch = self._get_current_branch()
            raise PermissionError(
                f"Cannot create PR on branch '{branch}'. "
                f"Switch to a development or feature branch to create PRs."
            )
        loop = asyncio.get_event_loop()
        return await loop.run_in_executor(
            None,
            lambda: self.gitea.create_pull_request(title, body, head, base, labels, repo)
        )
--- a/mcp-servers/gitea/mcp_server/tools/wiki.py
+++ b/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}'
        }
--- a/mcp-servers/gitea/pyproject.toml
+++ b/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"]
--- a/mcp-servers/gitea/run.sh
+++ b/mcp-servers/gitea/run.sh
@@ -0,0 +1,21 @@
 #!/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"
 if [[ -f "$CACHE_VENV/bin/python" ]]; then
    PYTHON="$CACHE_VENV/bin/python"
 elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
    PYTHON="$LOCAL_VENV/bin/python"
 else
    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
    exit 1
 fi
 cd "$SCRIPT_DIR"
 export PYTHONPATH="$SCRIPT_DIR"
 exec "$PYTHON" -m mcp_server.server "$@"
--- a/mcp-servers/gitea/tests/test_config.py
+++ b/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
--- a/mcp-servers/gitea/tests/test_gitea_client.py
+++ b/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_owner/test_repo',  # Combined owner/repo format
            'repo': 'test_repo',
            '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_owner/test_repo'  # Combined format
    assert gitea_client.repo == 'test_repo'
    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):
+    # Mock is_org_repo to avoid network call during label resolution
-        issue = gitea_client.create_issue(
+    with patch.object(gitea_client, 'is_org_repo', return_value=True):
-            title='New Issue',
+        # Mock get_org_labels and get_labels for label resolution
-            body='Issue body',
+        with patch.object(gitea_client, 'get_org_labels', return_value=[{'name': 'Type/Bug', 'id': 1}]):
-            labels=['Type/Bug']
+            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'
+                    assert issue['title'] == 'New Issue'
-        gitea_client.session.post.assert_called_once()
+                    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)
 # ========================================
--- a/mcp-servers/gitea/tests/test_issues.py
+++ b/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):
+async def test_aggregate_issues_project_mode(issue_tools):
-    """Test that aggregate_issues fails in project mode"""
+    """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:
+        issue_tools.gitea.aggregate_issues = Mock(return_value={
-            await issue_tools.aggregate_issues()
+            '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():
--- a/mcp-servers/netbox/README.md
+++ b/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 |
+| `virt_list_clusters` | List clusters |
-| `virtualization_create_cluster` | Create a cluster |
+| `virt_create_cluster` | Create a cluster |
-| `virtualization_list_virtual_machines` | List VMs |
+| `virt_list_vms` | List VMs |
-| `virtualization_create_virtual_machine` | Create a VM |
+| `virt_create_vm` | Create a VM |
-| `virtualization_list_vm_interfaces` | List VM interfaces |
+| `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 |
+| `wlan_list_lans` | List wireless LANs |
-| `wireless_create_wireless_lan` | Create a WLAN |
+| `wlan_create_lan` | Create a WLAN |
-| `wireless_list_wireless_links` | List wireless links |
+| `wlan_list_links` | List wireless links |
 | ... and more |
 ### Extras
--- a/mcp-servers/netbox/mcp_server/config.py
+++ b/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
--- a/mcp-servers/netbox/mcp_server/server.py
+++ b/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]
--- a/mcp-servers/netbox/run.sh
+++ b/mcp-servers/netbox/run.sh
@@ -0,0 +1,21 @@
 #!/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"
 if [[ -f "$CACHE_VENV/bin/python" ]]; then
    PYTHON="$CACHE_VENV/bin/python"
 elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
    PYTHON="$LOCAL_VENV/bin/python"
 else
    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
    exit 1
 fi
 cd "$SCRIPT_DIR"
 export PYTHONPATH="$SCRIPT_DIR"
 exec "$PYTHON" -m mcp_server.server "$@"
--- a/mcp-servers/viz-platform/.doc-guardian-queue
+++ b/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
--- a/mcp-servers/viz-platform/README.md
+++ b/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.
--- a/mcp-servers/viz-platform/mcp_server/accessibility_tools.py
+++ b/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
--- a/mcp-servers/viz-platform/mcp_server/chart_tools.py
+++ b/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
            }
--- a/mcp-servers/viz-platform/mcp_server/layout_tools.py
+++ b/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
        }
--- a/mcp-servers/viz-platform/mcp_server/server.py
+++ b/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:
--- a/mcp-servers/viz-platform/requirements.txt
+++ b/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
--- a/mcp-servers/viz-platform/run.sh
+++ b/mcp-servers/viz-platform/run.sh
@@ -0,0 +1,21 @@
 #!/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"
 if [[ -f "$CACHE_VENV/bin/python" ]]; then
    PYTHON="$CACHE_VENV/bin/python"
 elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
    PYTHON="$LOCAL_VENV/bin/python"
 else
    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
    exit 1
 fi
 cd "$SCRIPT_DIR"
 export PYTHONPATH="$SCRIPT_DIR"
 exec "$PYTHON" -m mcp_server.server "$@"
--- a/mcp-servers/viz-platform/tests/test_accessibility_tools.py
+++ b/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("#")
--- a/plugins/clarity-assist/.claude-plugin/plugin.json
+++ b/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",
--- a/plugins/clarity-assist/README.md
+++ b/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
--- a/plugins/clarity-assist/agents/clarity-coach.md
+++ b/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.
--- a/plugins/clarity-assist/commands/clarify.md
+++ b/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
+## Workflow
 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
+1. **Deconstruct** - Break down request into components
-
+2. **Diagnose** - Identify gaps and conflicts
-Analyze gaps and potential issues:
+3. **Develop** - Gather clarifications via structured questions
-
+4. **Deliver** - Present refined specification
-1. **Missing information** - What do we need to know?
+5. **Offer RFC Creation** - For feature work, offer to save as RFC
 2. **Conflicting requirements** - Do any stated goals contradict?
 3. **Scope boundaries** - What's in/out of scope?
 4. **Technical constraints** - Platform, language, architecture limits
 ### Phase 3: Develop
 Gather clarifications through structured questioning:
 **ND-Friendly Question Rules:**
 - Present 2-4 concrete options (never open-ended alone)
 - Include "Other" for custom responses
 - Ask 1-2 questions at a time maximum
 - Provide brief context for why you're asking
 - Check for conflicts with previous answers
 **Example Format:**
 ```
 To help me understand the scope better:
 **How should errors be handled?**
 1. Silent logging (user sees nothing)
 2. Toast notifications (brief, dismissible)
 3. Modal dialogs (requires user action)
 4. Other
 [Context: This affects both UX and how much error-handling code we need]
 ```
 ### Phase 4: Deliver
 Produce the refined specification:
 ```markdown
 ## Clarified Request
 ### Summary
 [1-2 sentence description of what will be built]
 ### Scope
 **In Scope:**
 - [Item 1]
 - [Item 2]
 **Out of Scope:**
 - [Item 1]
 ### Requirements
 | # | Requirement | Priority | Notes |
 |---|-------------|----------|-------|
 | 1 | ... | Must | ... |
 | 2 | ... | Should | ... |
 ### Assumptions
 - [Assumption made based on conversation]
 ### Open Questions
 - [Any remaining ambiguities, if any]
 ```
 ## Conflict Detection
 Before each question, review previous answers for conflicts:
 ```
 [Internal check]
 Previous: User said "keep it simple"
 Current question about: Adding configuration options
 Potential conflict: More options = more complexity
 → Acknowledge: "Earlier you mentioned keeping it simple. With that in mind..."
 ```
 ## Escalation Protocol
 If the request is particularly messy or the user seems overwhelmed:
 1. Acknowledge the complexity
 2. Offer to start with just ONE aspect
 3. Build incrementally
 ```
 "This touches a lot of areas. Rather than tackle everything at once,
 let's start with [most critical piece]. Once that's clear, we can
 add the other parts. Sound good?"
 ```
 ## Example Interaction
 **User:** Make the app faster
 **Clarify Response:**
 ```
 Let me help clarify what kind of performance improvements you're looking for.
 **What type of slowness are you experiencing?**
 1. Initial page load takes too long
 2. Interactions feel sluggish (clicking, typing)
 3. API calls are slow
 4. All of the above
 5. Other
 [I'm asking because each has very different solutions]
 ```
 ## Output Format
-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
--- a/plugins/clarity-assist/commands/quick-clarify.md
+++ b/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
-```
+1. **Echo Understanding** - Restate in a single sentence
-"I understand you want [X] that does [Y]."
+2. **Quick Disambiguation** - Ask ONE multiple-choice question if needed
-```
+3. **Proceed or Confirm** - Start work or offer micro-summary
 ### Step 2: Quick Disambiguation
 If needed, ask ONE multiple-choice question:
 ```
 **Just to confirm:** Should this [A] or [B]?
 1. [Option A with brief description]
 2. [Option B with brief description]
 3. Both
 4. Neither / Other approach
 ```
 ### Step 3: Proceed or Confirm
 If confident (>90%), proceed with a brief confirmation:
 ```
 "Got it. I'll implement [X with chosen option]. Starting now."
 ```
 If less confident, offer a micro-summary:
 ```
 "Quick summary before I start:
 - [Key point 1]
 - [Key point 2]
 - [Assumption made]
 Proceed? (Or clarify anything)"
 ```
 ## Example Interaction
 **User:** Add a delete button to the user list
 **Quick-Clarify Response:**
 ```
 I'll add a delete button to each row in the user list.
 **Should deletion require confirmation?**
 1. Yes - show confirmation dialog (Recommended)
 2. No - delete immediately
 3. Soft delete - mark as deleted but keep data
 [Asking because accidental deletions can be problematic]
 ```
 ## Escalation to Full /clarify
 If quick-clarify reveals complexity:
 ```
 "This is more involved than it first appeared - there are
 several decisions to make. Want me to switch to a more
 thorough clarification process? (Just say 'yes' or 'clarify')"
 ```
 ## Output Format
-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?"
 ```
--- a/plugins/clarity-assist/docs/ND-SUPPORT.md
+++ b/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
--- a/plugins/clarity-assist/hooks/hooks.json
+++ b/plugins/clarity-assist/hooks/hooks.json
@@ -0,0 +1,15 @@
 {
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/vagueness-check.sh"
          }
        ]
      }
    ]
  }
 }
--- a/plugins/clarity-assist/hooks/vagueness-check.sh
+++ b/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
--- a/plugins/clarity-assist/skills/4d-methodology.md
+++ b/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]
 ```
--- a/plugins/clarity-assist/skills/clarification-techniques.md
+++ b/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)"
 ```
--- a/plugins/clarity-assist/skills/escalation-patterns.md
+++ b/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
--- a/plugins/clarity-assist/skills/nd-accommodations.md
+++ b/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?"
 ```
--- a/plugins/claude-config-maintainer/.claude-plugin/plugin.json
+++ b/plugins/claude-config-maintainer/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
  "name": "claude-config-maintainer",
-  "version": "1.0.0",
+  "version": "1.2.0",
-  "description": "Maintains and optimizes CLAUDE.md configuration files for Claude Code projects",
+  "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/"]
 }
--- a/plugins/claude-config-maintainer/README.md
+++ b/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.
--- a/plugins/claude-config-maintainer/agents/maintainer.md
+++ b/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)
--- a/plugins/claude-config-maintainer/claude-md-integration.md
+++ b/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
--- a/plugins/claude-config-maintainer/commands/analyze.md
+++ b/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
+- skills/visual-header.md
-2. **Analyze Structure** - Evaluates organization, headers, and flow
+- skills/analysis-workflow.md
-3. **Check Content** - Reviews clarity, completeness, and conciseness
+- skills/optimization-patterns.md
-4. **Identify Issues** - Finds redundancy, verbosity, and missing sections
+- skills/pre-change-protocol.md
-5. **Detect Active Plugins** - Identifies marketplace plugins enabled in the project
+
-6. **Check Plugin Integration** - Verifies CLAUDE.md references active plugins
+## Visual Output
-7. **Generate Report** - Provides scored assessment with recommendations
+
 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
-```
+1. Locate and parse CLAUDE.md
-Analyze the CLAUDE.md file in this project
+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)
+| Category | Points |
- Logical section ordering
+|----------|--------|
- Clear header hierarchy
+| Structure | 25 |
- Easy navigation
+| Clarity | 25 |
- Appropriate grouping
+| Completeness | 25 |
-
+| Conciseness | 25 |
 ### Clarity (25 points)
 - Clear instructions
 - Good examples
 - Unambiguous language
 - Appropriate detail level
 ### Completeness (25 points)
 - Project overview present
 - Quick start commands documented
 - Critical rules highlighted
 - Key workflows covered
 ### Conciseness (25 points)
 - No unnecessary repetition
 - Efficient information density
 - Appropriate length for project size
 - No generic filler content
 ## Plugin Integration Analysis
 After the content analysis, the command detects and analyzes marketplace plugin integration:
 ### Detection Method
 1. **Read `.claude/settings.local.json`** - Check for enabled MCP servers
 2. **Map MCP servers to plugins** - Use marketplace registry to identify active plugins:
   - `gitea` → projman
   - `netbox` → cmdb-assistant
 3. **Check for hooks** - Identify hook-based plugins (project-hygiene)
 4. **Scan CLAUDE.md** - Look for plugin integration content
 ### Plugin Coverage Scoring
 For each detected plugin, verify CLAUDE.md contains:
 - Plugin section header or mention
 - Available commands documentation
 - MCP tools reference (if applicable)
 - Usage guidelines
 Coverage is reported as percentage: `(plugins referenced / plugins detected) * 100`
 ## Expected Output
 ```
 CLAUDE.md Analysis Report
 =========================
 File: /path/to/project/CLAUDE.md
 Lines: 245
 Last Modified: 2025-01-18
 Overall Score: 72/100
 Category Scores:
 - Structure:    20/25 (Good)
 - Clarity:      18/25 (Good)
 - Completeness: 22/25 (Excellent)
 - Conciseness:  12/25 (Needs Work)
 Strengths:
 + Clear project overview with good context
 + Critical rules prominently displayed
 + Comprehensive coverage of workflows
 Issues Found:
 1. [HIGH] Verbose explanations (lines 45-78)
   Section "Running Tests" has 34 lines that could be 8 lines.
   Impact: Harder to scan, important info buried
 2. [MEDIUM] Duplicate content (lines 102-115, 189-200)
   Same git workflow documented twice.
   Impact: Maintenance burden, inconsistency risk
 3. [MEDIUM] Missing Quick Start section
   No clear "how to get started" instructions.
   Impact: Slower onboarding for Claude
 4. [LOW] Inconsistent header formatting
   Mix of "## Title" and "## Title:" styles.
   Impact: Minor readability issue
 Recommendations:
 1. Add Quick Start section at top (priority: high)
 2. Condense Testing section to essentials (priority: high)
 3. Remove duplicate git workflow (priority: medium)
 4. Standardize header formatting (priority: low)
 Estimated improvement: 15-20 points after changes
 ---
 Plugin Integration Analysis
 ===========================
 Detected Active Plugins:
  ✓ projman (via gitea MCP server)
  ✓ cmdb-assistant (via netbox MCP server)
  ✓ project-hygiene (via PostToolUse hook)
 Plugin Coverage: 33% (1/3 plugins referenced)
  ✓ projman - Referenced in CLAUDE.md
  ✗ cmdb-assistant - NOT referenced
  ✗ project-hygiene - NOT referenced
 Missing Integration Content:
 1. cmdb-assistant
   Add infrastructure management commands and NetBox MCP tools reference.
 2. project-hygiene
   Add cleanup hook documentation and configuration options.
 ---
 Would you like me to:
 [1] Implement all content recommendations
 [2] Add missing plugin integrations to CLAUDE.md
 [3] Do both (recommended)
 [4] Show preview of changes first
 ```
 ## When to Use
 Run `/config-analyze` when:
 - Setting up a new project with existing CLAUDE.md
 - CLAUDE.md feels too long or hard to use
 - Claude seems to miss instructions
 - Before major project changes
 - Periodic maintenance (quarterly)
 - After installing new marketplace plugins
 - When Claude doesn't seem to use available plugin tools
 ## Follow-Up Actions
-After analysis, you can:
+1. Implement content recommendations
- Run `/config-optimize` to automatically improve the file
+2. Add missing plugin integrations
- Manually address specific issues
+3. Do both (recommended)
- Request detailed recommendations for any section
+4. Show preview first
 - 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
--- a/plugins/claude-config-maintainer/commands/config-audit-settings.md
+++ b/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
--- a/plugins/claude-config-maintainer/commands/config-diff.md
+++ b/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
--- a/plugins/claude-config-maintainer/commands/config-lint.md
+++ b/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
--- a/plugins/claude-config-maintainer/commands/config-optimize-settings.md
+++ b/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
--- a/plugins/claude-config-maintainer/commands/config-permissions-map.md
+++ b/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
--- a/plugins/claude-config-maintainer/commands/init.md
+++ b/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
+- skills/visual-header.md
-2. **Detect Stack** - Identifies technologies, frameworks, and tools
+- skills/claude-md-structure.md
-3. **Generate Content** - Creates tailored CLAUDE.md sections
+- skills/pre-change-protocol.md
-4. **Review & Refine** - Allows customization before saving
+
-5. **Save File** - Creates the CLAUDE.md in project root
+## 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
-```
+1. Analyze project structure, ask clarifying questions
-/config-init --template=api        # Use API project template
+2. Detect technologies, frameworks, tools
-/config-init --minimal             # Create minimal version
+3. Generate tailored CLAUDE.md sections
-/config-init --comprehensive       # Create detailed version
+4. Allow review and customization
-```
+5. Save file in project root
 ## Initialization Workflow
 ```
 CLAUDE.md Initialization
 ========================
 Step 1: Project Analysis
 ------------------------
 Scanning project structure...
 Detected:
 - Language: Python 3.11
 - Framework: FastAPI
 - Package Manager: pip (requirements.txt found)
 - Testing: pytest
 - Docker: Yes (Dockerfile found)
 - Git: Yes (.git directory)
 Step 2: Clarifying Questions
 ----------------------------
 1. Project Description:
   What does this project do? (1-2 sentences)
   > [User provides description]
 2. Build/Run Commands:
   Detected commands - are these correct?
   - Install: pip install -r requirements.txt
   - Test: pytest
   - Run: uvicorn main:app --reload
   [Y/n/edit]
 3. Critical Rules:
   Any rules Claude MUST follow?
   Examples: "Never modify migrations", "Always use type hints"
   > [User provides rules]
 4. Sensitive Areas:
   Any files/directories Claude should be careful with?
   > [User provides or skips]
 Step 3: Generate CLAUDE.md
 --------------------------
 Generating content based on:
 - Project type: FastAPI web API
 - Detected technologies
 - Your provided context
 Preview:
 ---
 # CLAUDE.md
 ## Project Overview
 [Generated description]
 ## Quick Start
 ```bash
 pip install -r requirements.txt  # Install dependencies
 pytest                           # Run tests
 uvicorn main:app --reload        # Start dev server
 ```
 ## Architecture
 [Generated based on structure]
 ## Critical Rules
 [Your provided rules]
 ## File Structure
 [Generated from analysis]
 ---
 Save this CLAUDE.md? [Y/n/edit]
 Step 4: Complete
 ----------------
 CLAUDE.md created successfully!
 Location: /path/to/project/CLAUDE.md
 Lines: 87
 Score: 85/100 (following best practices)
 Recommendations:
 - Run /config-analyze periodically to maintain quality
 - Update when adding major features
 - Add troubleshooting section as issues are discovered
 ```
 ## Templates
-### Minimal Template
+| Template | Sections |
-For small projects or when starting fresh:
+|----------|----------|
- Project Overview (required)
+| Minimal | Overview, Quick Start, Critical Rules, Pre-Change Protocol |
- Quick Start (required)
+| Standard | + Architecture, Common Operations, File Structure |
- Critical Rules (required)
+| Comprehensive | + Troubleshooting, Integration Points, Workflow |
-### Standard Template (default)
+**Note:** Pre-Change Protocol is MANDATORY in all templates.
 For typical projects:
 - Project Overview
 - Quick Start
 - Architecture
 - Critical Rules
 - Common Operations
 - File Structure
 ### Comprehensive Template
 For large or complex projects:
 - All standard sections plus:
 - Detailed Architecture
 - Troubleshooting
 - Integration Points
 - Development Workflow
 - Deployment Notes
 ## Auto-Detection
 The command automatically detects:
 | What | How |
 |------|-----|
 | Language | File extensions, config files |
 | Framework | package.json, requirements.txt, etc. |
 | Build system | Makefile, package.json scripts, etc. |
 | Testing | pytest.ini, jest.config, etc. |
 | Docker | Dockerfile, docker-compose.yml |
 | Database | Connection strings, ORM configs |
 ## Customization
 After generation, you can:
 - Edit any section before saving
 - Add additional sections
 - Remove unnecessary sections
 - Adjust detail level
 - Add project-specific content
 ## When to Use
 Run `/config-init` when:
 - Starting a new project
 - Project lacks CLAUDE.md
- Existing CLAUDE.md is outdated/poor quality
+- Taking over unfamiliar project
 - 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
 ```
--- a/plugins/claude-config-maintainer/commands/optimize.md
+++ b/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
+- skills/visual-header.md
-2. **Plan Changes** - Determines what to restructure, condense, or add
+- skills/optimization-patterns.md
-3. **Show Preview** - Displays before/after comparison
+- skills/pre-change-protocol.md
-4. **Apply Changes** - Updates the file with your approval
+- skills/claude-md-structure.md
-5. **Verify Results** - Confirms improvements achieved
+
 ## 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
-```
+1. Identify optimization opportunities
-/config-optimize --condense        # Focus on reducing verbosity
+2. Plan restructure, condense, or add actions
-/config-optimize --restructure     # Focus on reorganization
+3. Show before/after preview
-/config-optimize --add-missing     # Focus on adding missing sections
+4. Apply changes with approval
-```
+5. Verify improvements
 ## Optimization Actions
 ### Restructure
 - Reorder sections by importance
 - Group related content together
 - Improve header hierarchy
 - Add navigation aids
 ### Condense
 - Remove redundant explanations
 - Convert verbose text to bullet points
 - Eliminate duplicate content
 - Shorten overly detailed sections
 ### Enhance
 - Add missing essential sections
 - Improve unclear instructions
 - Add helpful examples
 - Highlight critical rules
 ### Format
 - Standardize header styles
 - Fix code block formatting
 - Align list formatting
 - Improve table layouts
 ## Expected Output
 ```
 CLAUDE.md Optimization
 ======================
 Current Analysis:
 - Score: 72/100
 - Lines: 245
 - Issues: 4
 Planned Optimizations:
 1. ADD: Quick Start section (new, ~15 lines)
   + Build command
   + Test command
   + Run command
 2. CONDENSE: Testing section (34 → 8 lines)
   Before: Verbose explanation with redundant setup info
   After: Concise command reference with comments
 3. REMOVE: Duplicate git workflow (lines 189-200)
   Keeping: Original at lines 102-115
 4. FORMAT: Standardize headers
   Changing 12 headers from "## Title:" to "## Title"
 Preview Changes? [Y/n] y
 --- CLAUDE.md (before)
 +++ CLAUDE.md (after)
@@ -1,5 +1,20 @@
 # CLAUDE.md
 +## Quick Start
 +
 +```bash
 +# Install dependencies
 +pip install -r requirements.txt
 +
 +# Run tests
 +pytest
 +
 +# Start development server
 +python manage.py runserver
 +```
 +
 ## Project Overview
 ...
 [Full diff shown]
 Apply these changes? [Y/n] y
 Optimization Complete!
 - Previous score: 72/100
 - New score: 89/100
 - Lines reduced: 245 → 198 (-19%)
 - Issues resolved: 4/4
 Backup saved to: .claude/backups/CLAUDE.md.2025-01-18
 ```
 ## Safety Features
 ### Backup Creation
 - Automatic backup before changes
 - Stored in `.claude/backups/`
 - Easy restoration if needed
 ### Preview Mode
 - All changes shown before applying
 - Diff format for easy review
 - Option to approve/reject
 ### Selective Application
 - Can apply individual changes
 - Skip specific optimizations
 - Iterative refinement
 ## Options
 | Option | Description |
 |--------|-------------|
-| `--dry-run` | Show changes without applying |
+| `--dry-run` | Preview without applying |
-| `--no-backup` | Skip backup creation |
+| `--no-backup` | Skip backup |
 | `--aggressive` | Maximum condensation |
-| `--preserve-comments` | Keep all existing comments |
+| `--section=NAME` | Optimize specific section |
 | `--section=NAME` | Optimize specific section only |
-## When to Use
+**Priority:** Add Pre-Change Protocol if missing.
-Run `/config-optimize` when:
+## Safety
 - Analysis shows score below 70
 - File has grown too long
 - Structure needs reorganization
 - Missing critical sections
 - After major refactoring
-## Best Practices
+- Auto backup to `.claude/backups/`
-
+- Preview before applying
 1. **Run analysis first** - Understand current state
 2. **Review preview carefully** - Ensure nothing important lost
 3. **Test after changes** - Verify Claude follows instructions
 4. **Keep backups** - Restore if issues arise
 5. **Iterate** - Multiple small optimizations beat one large one
 ## Rollback
 If optimization causes issues:
 ```bash
 # Restore from backup
 cp .claude/backups/CLAUDE.md.TIMESTAMP ./CLAUDE.md
 ```
 Or ask:
 ```
 Restore CLAUDE.md from the most recent backup
 ```
--- a/plugins/claude-config-maintainer/hooks/hooks.json
+++ b/plugins/claude-config-maintainer/hooks/hooks.json
@@ -2,8 +2,13 @@
  "hooks": {
    "SessionStart": [
      {
-        "type": "command",
+        "matcher": "",
-        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/enforce-rules.sh"
+        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/enforce-rules.sh"
          }
        ]
      }
    ]
  }
--- a/plugins/claude-config-maintainer/skills/analysis-workflow.md
+++ b/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
--- a/plugins/claude-config-maintainer/skills/claude-md-structure.md
+++ b/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
--- a/plugins/claude-config-maintainer/skills/diff-analysis.md
+++ b/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
--- a/plugins/claude-config-maintainer/skills/lint-rules.md
+++ b/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 |
--- a/plugins/claude-config-maintainer/skills/optimization-patterns.md
+++ b/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
--- a/plugins/claude-config-maintainer/skills/pre-change-protocol.md
+++ b/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
--- a/plugins/claude-config-maintainer/skills/settings-optimization.md
+++ b/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.
--- a/plugins/claude-config-maintainer/skills/visual-header.md
+++ b/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.
--- a/plugins/cmdb-assistant/.claude-plugin/plugin.json
+++ b/plugins/cmdb-assistant/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
  "name": "cmdb-assistant",
-  "version": "1.0.0",
+  "version": "1.2.0",
-  "description": "NetBox CMDB integration for infrastructure management - query, create, update, and manage network devices, IP addresses, sites, and more",
+  "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",
    "email": "leobmiranda@gmail.com"
@@ -15,8 +15,9 @@
    "infrastructure",
    "network",
    "ipam",
-    "dcim"
+    "dcim",
    "data-quality",
    "validation"
  ],
-  "commands": ["./commands/"],
+  "commands": ["./commands/"]
  "mcpServers": ["./.mcp.json"]
 }
--- a/plugins/cmdb-assistant/.mcp.json
+++ b/plugins/cmdb-assistant/.mcp.json
@@ -1,12 +0,0 @@
 {
  "mcpServers": {
    "netbox": {
      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/netbox/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/netbox",
      "env": {
        "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/netbox"
      }
    }
  }
 }
--- a/plugins/cmdb-assistant/README.md
+++ b/plugins/cmdb-assistant/README.md
@@ -1,171 +0,0 @@
 # CMDB Assistant
 A Claude Code plugin for NetBox CMDB integration - query, create, update, and manage your network infrastructure directly from Claude Code.
 ## 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
 ## 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 |
 |---------|-------------|
 | `/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 |
 ## 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
 ## 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
 ├── 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.
--- a/plugins/cmdb-assistant/agents/cmdb-assistant.md
+++ b/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,60 +35,75 @@ 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.)
+- Use filters to narrow results
- Follow up with get operations for detailed information
+- Follow up with get operations for details
 - Present results in clear, organized format
 ### Create Operations
- Always confirm required fields with user before creating
+- Confirm required fields before creating
- Look up related object IDs (device_type, role, site) first
+- Look up related object IDs first
- Provide the created object details after success
+- Suggest follow-up actions after success
 - Suggest follow-up actions (add interfaces, assign IPs, etc.)
 ### Update Operations
 - Show current values before updating
 - Confirm changes with user
 - Report what was changed after success
 ### Delete Operations
- ALWAYS ask for explicit confirmation before deleting
+- ALWAYS ask for explicit confirmation
- Show what will be deleted
+- Warn about dependent objects
 - Warn about dependent objects that may be affected
-## Common Workflows
+## Data Quality Validation
-### Document a New Server
+Reference `skills/netbox-patterns/SKILL.md` for best practices:
 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
+### Before VM Operations
-1. Find available prefixes with `ipam_list_available_prefixes`
+1. Cluster/Site assignment required
-2. Create prefix with `ipam_create_prefix` or `ipam_create_available_prefix`
+2. Recommend tenant if not provided
-3. Allocate IPs with `ipam_create_available_ip`
+3. Check naming convention
-### Audit Infrastructure
+### Before Device Operations
-1. List recent changes with `extras_list_object_changes`
+1. Site is REQUIRED
-2. Review devices by site with `dcim_list_devices`
+2. Recommend platform
-3. Check IP utilization with prefix operations
+3. Check naming convention
 4. Offer to set primary IP after creation
-### Cable Management
+### Before Creating Roles
-1. List interfaces with `dcim_list_interfaces`
+1. List existing roles first
-2. Create cable with `dcim_create_cable`
+2. Recommend consolidation if >10 specific roles
 3. Verify connectivity
-## Response Format
+## Dependency Order
-When presenting data:
+Follow order from `skills/netbox-patterns/SKILL.md`:
- Use tables for lists
+```
- Highlight key fields (name, status, IPs)
+1. Regions -> Sites -> Locations -> Racks
- Include IDs for reference in follow-up operations
+2. Tenant Groups -> Tenants
- Suggest next steps when appropriate
+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
 ```
-## Error Handling
+## Duplicate Prevention
- If an operation fails, explain why clearly
+Before creating, check for existing:
- Suggest corrective actions
+```
- For permission errors, note what access is needed
+dcim_list_devices name=<proposed-name>
- For validation errors, explain required fields/formats
+virt_list_vms name=<proposed-name>
 ipam_list_prefixes prefix=<proposed-prefix>
 ```
 ## Available Commands
 | Command | Purpose |
 |---------|---------|
 | `/cmdb-search <query>` | Search across all CMDB objects |
 | `/cmdb-device <action>` | Device CRUD operations |
 | `/cmdb-ip <action>` | IP address and prefix management |
 | `/cmdb-site <action>` | Site and location management |
 | `/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 |
--- a/plugins/cmdb-assistant/claude-md-integration.md
+++ b/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
+- `virt_list_vms`, `virt_create_vm`, `virt_update_vm`, `virt_delete_vm` - VM management
- `virtualization_list_clusters`, `virtualization_create_cluster` - Cluster management
+- `virt_list_clusters`, `virt_create_cluster`, `virt_update_cluster`, `virt_delete_cluster` - Cluster management
- `virtualization_list_vm_interfaces` - VM interface management
+- `virt_list_vm_ifaces`, `virt_create_vm_iface` - VM interface management
 **Circuits:**
 - `circuits_list_circuits`, `circuits_create_circuit` - Circuit management
--- a/plugins/cmdb-assistant/commands/change-audit.md
+++ b/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
--- a/plugins/cmdb-assistant/commands/cmdb-audit.md
+++ b/plugins/cmdb-assistant/commands/cmdb-audit.md
@@ -0,0 +1,58 @@
 ---
 description: Audit NetBox data quality and identify consistency issues
 ---
 # CMDB Data Quality Audit
 Analyze NetBox data for quality issues and best practice violations.
 ## Skills to Load
 - `skills/visual-header.md`
 - `skills/audit-workflow.md`
 - `skills/netbox-patterns/SKILL.md`
 - `skills/mcp-tools-reference.md`
 ## Usage
 ```
 /cmdb-audit [scope]
 ```
 **Scopes:**
 - `all` (default) - Full audit across all categories
 - `vms` - Virtual machines only
 - `devices` - Physical devices only
 - `naming` - Naming convention analysis
 - `roles` - Role fragmentation analysis
 ## Instructions
 Execute `skills/visual-header.md` with context "Data Quality Audit".
 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
 ## Scope-Specific Focus
 | Scope | Focus |
 |-------|-------|
 | `all` | Full audit across all categories |
 | `vms` | Virtual Machine checks only |
 | `devices` | Device checks only |
 | `naming` | Naming convention analysis |
 | `roles` | Role fragmentation analysis |
 ## Examples
 - `/cmdb-audit` - Full audit
 - `/cmdb-audit vms` - VM-specific checks
 - `/cmdb-audit naming` - Naming conventions
 ## User Request
 $ARGUMENTS
--- a/plugins/cmdb-assistant/commands/cmdb-device.md
+++ b/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`
+- `list` or `show all` - List all devices: `dcim_list_devices`
- `show <name>` - Get device details using `dcim_list_devices` with name filter, then `dcim_get_device`
+- `show <name>` - Get device details: `dcim_get_device`
- `at <site>` - List devices at a specific site
+- `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
+- Use `dcim_list_device_types`, `dcim_list_device_roles`, `dcim_list_sites` to find IDs
 - Then use `dcim_create_device`
 **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)
+- `delete <name>` - Delete device (ask confirmation first)
 - Use `dcim_delete_device`
 ### Related Operations
 After creating a device, offer to:
- Add interfaces with `dcim_create_interface`
+- Add interfaces: `dcim_create_interface`
- Assign IP addresses with `ipam_create_ip_address`
+- Assign IP addresses: `ipam_create_ip_address`
- Add to a rack with `dcim_update_device`
+- Add to rack: `dcim_update_device`
 ## Examples
- `/cmdb-device list` - Show all devices
+- `/cmdb-device list`
- `/cmdb-device show core-router-01` - Get details for specific device
+- `/cmdb-device show core-router-01`
- `/cmdb-device create web-server-03` - Create a new device
+- `/cmdb-device create web-server-03`
- `/cmdb-device at headquarters` - List devices at headquarters site
+- `/cmdb-device at headquarters`
 ## User Request
--- a/plugins/cmdb-assistant/commands/cmdb-ip.md
+++ b/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`
+- `prefixes` - List all prefixes
- `prefix <cidr>` - Get prefix details or find prefix containing address
+- `prefix <cidr>` - Get prefix details
- `available in <prefix>` - Show available IPs in a prefix using `ipam_list_available_ips`
+- `available in <prefix>` - Show available IPs
- `create prefix <cidr>` - Create new prefix using `ipam_create_prefix`
+- `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`
+- `allocate from <prefix>` - Auto-allocate next available
- `create <address>` - Create specific IP using `ipam_create_ip_address`
+- `create <address>` - Create specific IP
- `assign <ip> to <device>` - Assign IP to device interface
+- `assign <ip> to <device> <interface>` - Assign IP to interface
-**VLANs:**
+**VLANs and VRFs:**
- `vlans` - List VLANs using `ipam_list_vlans`
+- `vlans` - List VLANs
 - `vlan <id>` - Get VLAN details
-
+- `vrfs` - List VRFs
 **VRFs:**
 - `vrfs` - List VRFs using `ipam_list_vrfs`
 ### Workflow Examples
 **Allocate IP to new server:**
 1. Find available IPs in target prefix
 2. Create the IP address
 3. Assign to device interface
 ## Examples
- `/cmdb-ip prefixes` - List all prefixes
+- `/cmdb-ip prefixes`
- `/cmdb-ip available in 10.0.1.0/24` - Show available IPs
+- `/cmdb-ip available in 10.0.1.0/24`
- `/cmdb-ip allocate from 10.0.1.0/24` - Get next available IP
+- `/cmdb-ip allocate from 10.0.1.0/24`
- `/cmdb-ip assign 10.0.1.50/24 to web-server-01 eth0` - Assign IP to interface
+- `/cmdb-ip assign 10.0.1.50/24 to web-server-01 eth0`
 ## User Request
--- a/plugins/cmdb-assistant/commands/cmdb-register.md
+++ b/plugins/cmdb-assistant/commands/cmdb-register.md
@@ -0,0 +1,51 @@
 ---
 description: Register the current machine into NetBox with all running applications
 ---
 # CMDB Machine Registration
 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
 ```
 /cmdb-register [--site <site-name>] [--tenant <tenant-name>] [--role <role-name>]
 ```
 **Options:**
 - `--site <name>`: Site to assign (will prompt if not provided)
 - `--tenant <name>`: Tenant for resource isolation (optional)
 - `--role <name>`: Device role (default: auto-detect based on services)
 ## Instructions
 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
 | 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
 $ARGUMENTS
--- a/plugins/cmdb-assistant/commands/cmdb-search.md
+++ b/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.
--- a/plugins/cmdb-assistant/commands/cmdb-site.md
+++ b/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`
+- `list` - List all sites: `dcim_list_sites`
- `show <name>` - Get site details using `dcim_get_site`
+- `show <name>` - Get site details: `dcim_get_site`
- `create <name>` - Create new site using `dcim_create_site`
+- `create <name>` - Create new site: `dcim_create_site`
- `update <name>` - Update site using `dcim_update_site`
+- `update <name>` - Update site: `dcim_update_site`
 - `delete <name>` - Delete site (with confirmation)
-**Locations (within sites):**
+**Locations:**
- `locations at <site>` - List locations using `dcim_list_locations`
+- `locations at <site>` - List locations: `dcim_list_locations`
- `create location <name> at <site>` - Create location using `dcim_create_location`
+- `create location <name> at <site>` - Create location
 **Racks:**
- `racks at <site>` - List racks using `dcim_list_racks`
+- `racks at <site>` - List racks: `dcim_list_racks`
- `create rack <name> at <site>` - Create rack using `dcim_create_rack`
+- `create rack <name> at <site>` - Create rack
 **Regions:**
- `regions` - List regions using `dcim_list_regions`
+- `regions` - List regions: `dcim_list_regions`
- `create region <name>` - Create region using `dcim_create_region`
+- `create region <name>` - Create region
 ### Site Properties
 When creating/updating sites:
 - name (required)
 - slug (required, auto-generated if not provided)
 - status: active, planned, staging, decommissioning, retired
 - region: parent region ID
 - facility: datacenter/building name
 - physical_address, shipping_address
 - time_zone
 ## Examples
- `/cmdb-site list` - Show all sites
+- `/cmdb-site list`
- `/cmdb-site show headquarters` - Get HQ site details
+- `/cmdb-site show headquarters`
- `/cmdb-site create branch-office-nyc` - Create new site
+- `/cmdb-site create branch-office-nyc`
- `/cmdb-site racks at headquarters` - List racks at HQ
+- `/cmdb-site racks at headquarters`
 ## User Request
--- a/plugins/cmdb-assistant/commands/cmdb-sync.md
+++ b/plugins/cmdb-assistant/commands/cmdb-sync.md
@@ -0,0 +1,57 @@
 ---
 description: Synchronize current machine state with existing NetBox record
 ---
 # CMDB Machine Sync
 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
 ```
 /cmdb-sync [--full] [--dry-run]
 ```
 **Options:**
 - `--full`: Force refresh all fields, even unchanged ones
 - `--dry-run`: Show what would change without applying updates
 ## Instructions
 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
 | 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
 $ARGUMENTS
--- a/plugins/cmdb-assistant/commands/cmdb-topology.md
+++ b/plugins/cmdb-assistant/commands/cmdb-topology.md
@@ -0,0 +1,54 @@
 ---
 description: Generate infrastructure topology diagrams from NetBox data
 ---
 # CMDB Topology Visualization
 Generate Mermaid diagrams showing infrastructure topology from NetBox.
 ## Skills to Load
 - `skills/visual-header.md`
 - `skills/topology-generation.md`
 - `skills/mcp-tools-reference.md`
 ## Usage
 ```
 /cmdb-topology <view> [scope]
 ```
 **Views:**
 - `rack <rack-name>` - Rack elevation showing devices and positions
 - `network [site]` - Network topology showing device connections
 - `site <site-name>` - Site overview with racks and device counts
 - `full` - Full infrastructure overview
 ## Instructions
 Execute `skills/visual-header.md` with context "Topology".
 Execute `skills/topology-generation.md` which covers:
 - Data collection via MCP for each view type
 - Mermaid diagram generation with proper shapes
 - Legend and data notes
 ## Output Format
 Always provide:
 1. **Summary** - Brief description
 2. **Mermaid Code Block** - The diagram
 3. **Legend** - Shape explanations
 4. **Data Notes** - Quality issues found
 ## Examples
 - `/cmdb-topology rack server-rack-01` - Rack elevation
 - `/cmdb-topology network` - All network connections
 - `/cmdb-topology network Home` - Network for Home site
 - `/cmdb-topology site Headquarters` - Site overview
 - `/cmdb-topology full` - Full infrastructure
 ## User Request
 $ARGUMENTS
--- a/plugins/cmdb-assistant/commands/initial-setup.md
+++ b/plugins/cmdb-assistant/commands/initial-setup.md
@@ -1,164 +1,74 @@
 ---
-description: Interactive setup wizard for cmdb-assistant plugin - configures NetBox MCP server
+description: Interactive setup wizard for cmdb-assistant plugin
 ---
 # CMDB Assistant Setup Wizard
-This command sets up the cmdb-assistant plugin with NetBox integration.
+Configure the cmdb-assistant plugin with NetBox integration.
 ## Skills to Load
 - `skills/visual-header.md`
 ## Important Context
- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools
+- **Uses Bash, Read, Write, AskUserQuestion tools** - NOT MCP tools
- **MCP tools won't work until after setup + session restart**
+- **MCP tools unavailable until after setup + session restart**
 - **Uses NetBox MCP server (separate from Gitea MCP)**
---
+## Usage
-## Phase 1: Environment Validation
+```
 /initial-setup
 ```
-### Step 1.1: Check Python Version
+## 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.
-If below 3.10, stop setup 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 2: MCP Server Setup
+### Phase 3: System Configuration
-### Step 2.1: Locate NetBox MCP Server
+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
-```bash
+### Phase 4: Validation
 find ~/.claude ~/.config/claude -name "mcp_server" -path "*netbox*" 2>/dev/null | head -5
 ```
-If not found, ask user for marketplace location.
+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
-### Step 2.2: Check Virtual Environment
+## Completion Summary
 ```bash
 ls -la /path/to/mcp-servers/netbox/.venv/bin/python 2>/dev/null && echo "VENV_EXISTS" || echo "VENV_MISSING"
 ```
 ### Step 2.3: Create Virtual Environment (if missing)
 ```bash
 cd /path/to/mcp-servers/netbox && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate
 ```
 ---
 ## Phase 3: System Configuration
 ### Step 3.1: Create Config Directory
 ```bash
 mkdir -p ~/.config/claude
 ```
 ### Step 3.2: Check NetBox Configuration
 ```bash
 cat ~/.config/claude/netbox.env 2>/dev/null || echo "FILE_NOT_FOUND"
 ```
 **If file exists with valid values:** Skip to Phase 4.
 **If missing or has placeholders:** Continue.
 ### Step 3.3: Gather NetBox Information
 Use AskUserQuestion:
 - Question: "What is your NetBox API URL? (e.g., https://netbox.company.com/api)"
 - Header: "NetBox URL"
 - Options:
  - "Other (I'll provide the URL)"
 Ask user to provide the URL.
 **Important:** The URL must include `/api` at the end. If the user provides a URL without `/api`, append it automatically.
 ### Step 3.4: Create Configuration File
 ```bash
 cat > ~/.config/claude/netbox.env << 'EOF'
 # NetBox API Configuration
 # Generated by cmdb-assistant /initial-setup
 NETBOX_API_URL=<USER_PROVIDED_URL>
 NETBOX_API_TOKEN=PASTE_YOUR_TOKEN_HERE
 EOF
 chmod 600 ~/.config/claude/netbox.env
 ```
 ### Step 3.5: Token Instructions
 ---
 **Action Required: Add Your NetBox API Token**
 I've created `~/.config/claude/netbox.env` but you need to add your API token manually.
 **Steps:**
 1. Open: `nano ~/.config/claude/netbox.env`
 2. Generate token in NetBox: Admin → API Tokens → Add Token
 3. Replace `PASTE_YOUR_TOKEN_HERE` with your token
 4. Save the file
 ---
 Use AskUserQuestion:
 - Question: "Have you added your NetBox token?"
 - Header: "Token"
 - Options:
  - "Yes, I've added the token"
  - "Skip for now"
 ---
 ## Phase 4: Validation
 ### Step 4.1: Test Configuration (if token was added)
 ```bash
 source ~/.config/claude/netbox.env && curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Token $NETBOX_API_TOKEN" "$NETBOX_API_URL/"
 ```
 **Note:** The URL already includes `/api`, so we just append `/` for the root API endpoint.
 Report result:
 - 200: Success
 - 403: Invalid token
 - Other: Connection issue
 ### Step 4.2: Summary
 ```
-╔════════════════════════════════════════════════════════════╗
+CMDB-ASSISTANT SETUP COMPLETE
-║              CMDB-ASSISTANT SETUP COMPLETE                 ║
+MCP Server (NetBox):   Ready
-╠════════════════════════════════════════════════════════════╣
+System Config:         ~/.config/claude/netbox.env
-║ 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>
 ```
-### Step 4.3: Session Restart Notice
+## User Request
---
+$ARGUMENTS
 **⚠️ Session Restart Required**
 Restart your Claude Code session for MCP tools to become available.
 **After restart, you can:**
 - Run `/cmdb-device <hostname>` to look up a device
 - Run `/cmdb-ip <address>` to look up an IP address
 - Run `/cmdb-site <name>` to look up a site
 - Run `/cmdb-search <query>` for general search
 ---
 ## Note on Project Configuration
 cmdb-assistant does not require project-level configuration. The NetBox connection is system-wide and not tied to specific repositories.
--- a/plugins/cmdb-assistant/commands/ip-conflicts.md
+++ b/plugins/cmdb-assistant/commands/ip-conflicts.md
@@ -0,0 +1,58 @@
 ---
 description: Detect IP address conflicts and overlapping prefixes in NetBox
 ---
 # CMDB IP Conflict Detection
 Scan NetBox IPAM data to identify IP address conflicts and overlapping prefixes.
 ## Skills to Load
 - `skills/visual-header.md`
 - `skills/ip-management.md`
 - `skills/mcp-tools-reference.md`
 ## Usage
 ```
 /ip-conflicts [scope]
 ```
 **Scopes:**
 - `all` (default) - Full scan of all IP data
 - `addresses` - Check for duplicate IP addresses only
 - `prefixes` - Check for overlapping prefixes only
 - `vrf <name>` - Scan specific VRF only
 - `prefix <cidr>` - Scan within specific prefix
 ## Instructions
 Execute `skills/visual-header.md` with context "IP Conflict Detection".
 Execute conflict detection from `skills/ip-management.md`:
 1. **Data Collection** - Fetch IPs, prefixes, VRFs via MCP
 2. **Duplicate Detection** - Group by address+VRF, flag >1 record
 3. **Overlap Detection** - Compare prefixes pairwise using CIDR math
 4. **Orphan IP Detection** - Find IPs without containing prefix
 5. **Generate Report** - Use template from skill
 ## Conflict Types
 | Type | Severity |
 |------|----------|
 | Duplicate IP (same interface type) | CRITICAL |
 | Duplicate IP (different roles) | HIGH |
 | Overlapping prefixes (same status) | HIGH |
 | Overlapping prefixes (container ok) | LOW |
 | Orphan IP | MEDIUM |
 ## Examples
 - `/ip-conflicts` - Full scan
 - `/ip-conflicts addresses` - Duplicate IPs only
 - `/ip-conflicts vrf Production` - Scan specific VRF
 ## User Request
 $ARGUMENTS
--- a/plugins/cmdb-assistant/hooks/hooks.json
+++ b/plugins/cmdb-assistant/hooks/hooks.json
@@ -0,0 +1,26 @@
 {
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/startup-check.sh"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "mcp__plugin_cmdb-assistant_netbox__virt_create|mcp__plugin_cmdb-assistant_netbox__virt_update|mcp__plugin_cmdb-assistant_netbox__dcim_create|mcp__plugin_cmdb-assistant_netbox__dcim_update",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/validate-input.sh"
          }
        ]
      }
    ]
  }
 }
--- a/Show More
+++ b/Show More
		`@@ -0,0 +1 @@`
							`GITEA_REPO=personal-projects/leo-claude-mktplace`
`@@ -112,4 +112,4 @@ pytest tests/ -v`

	`## Usage`	`## 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.