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

Reviewed-on: #421

.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Project management plugins with Gitea and NetBox integrations",
-    "version": "5.8.0"
+    "version": "5.10.0"
   },
   "plugins": [
     {
@@ -91,8 +91,8 @@
     },
     {
       "name": "claude-config-maintainer",
-      "version": "1.1.0",
-      "description": "CLAUDE.md optimization and maintenance for Claude Code projects",
+      "version": "1.2.0",
+      "description": "CLAUDE.md and settings.local.json optimization for Claude Code projects",
       "source": "./plugins/claude-config-maintainer",
       "author": {
         "name": "Leo Miranda",

.gitignore

@@ -84,6 +84,13 @@ Thumbs.db
 # Claude Code
 .claude/settings.local.json
 .claude/history/
+.claude/backups/
+
+# Doc Guardian transient files
+.doc-guardian-queue
+
+# Development convenience links
+.marketplaces-link
 
 # Logs
 logs/

CHANGELOG.md

@@ -4,10 +4,233 @@ 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.
 

CLAUDE.md

@@ -146,7 +146,7 @@ When user says "fix the sprint-plan command", edit the SOURCE code.
 ## Project Overview
 
 **Repository:** leo-claude-mktplace
-**Version:** 5.4.0
+**Version:** 5.9.0
 **Status:** Production Ready
 
 A plugin marketplace for Claude Code containing:
@@ -161,7 +161,7 @@ A plugin marketplace for Claude Code containing:
 | `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.2.0 |
-| `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 1.1.0 |
+| `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 1.3.0 |
 | `viz-platform` | DMC validation, Plotly charts, and theming for dashboards | 1.1.0 |
 | `contract-validator` | Cross-plugin compatibility validation and agent verification | 1.1.0 |
 | `project-hygiene` | Post-task cleanup automation via hooks | 0.1.0 |
@@ -271,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 |
@@ -453,4 +508,4 @@ The script will:
 
 ---
 
-**Last Updated:** 2026-01-30
+**Last Updated:** 2026-02-02

README.md

@@ -1,4 +1,4 @@
-# Leo Claude Marketplace - v5.8.0
+# Leo Claude Marketplace - v5.10.0
 
 A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
 
@@ -12,6 +12,7 @@ A collection of Claude Code plugins for project management, infrastructure autom
 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
@@ -47,11 +48,11 @@ Comprehensive pull request review using specialized agents.
 **Commands:** `/pr-review`, `/pr-summary`, `/pr-findings`, `/pr-diff`, `/initial-setup`, `/project-init`, `/project-sync`
 
 #### [claude-config-maintainer](./plugins/claude-config-maintainer)
-**CLAUDE.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`, `/config-diff`, `/config-lint`
+**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**
@@ -122,7 +123,7 @@ 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`, `/lineage-viz`, `/run`, `/dbt-test`, `/data-quality`, `/initial-setup`
+**Commands:** `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/lineage-viz`, `/run`, `/dbt-test`, `/data-quality`, `/data-review`, `/data-gate`, `/initial-setup`
 
 ### Visualization
 
@@ -312,7 +313,7 @@ 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` |

docs/CANONICAL-PATHS.md

@@ -182,10 +182,42 @@ MCP servers are **shared at repository root** and configured in `.mcp.json`.
 | 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/` |
 
 **Note:** Plugins do NOT have their own `mcp-servers/` directories. All MCP servers are shared at root and configured via `.mcp.json`.
 
+### 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
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/{server}/.venv/bin/python"
+LOCAL_VENV="$MARKETPLACE_ROOT/mcp-servers/{server}/.venv/bin/python"
+
+if [[ -f "$CACHE_VENV" ]]; then
+    VENV_PATH="$CACHE_VENV"
+elif [[ -f "$LOCAL_VENV" ]]; then
+    VENV_PATH="$LOCAL_VENV"
+else
+    echo "venv missing"
+fi
+```
+
+**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
 
 | Type | Location |

docs/COMMANDS-CHEATSHEET.md

@@ -54,6 +54,9 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **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) |

docs/CONFIGURATION.md

@@ -415,6 +415,218 @@ The command auto-detects that system config exists and runs quick project setup.
 
 ---
 
+## Installing Plugins to Consumer Projects
+
+The marketplace provides scripts to install plugins into consumer projects. This sets up the MCP server connections and adds CLAUDE.md integration snippets.
+
+### Install a Plugin
+
+```bash
+cd /path/to/leo-claude-mktplace
+./scripts/install-plugin.sh <plugin-name> <target-project-path>
+```
+
+**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)
+
+---
+
 ## Automatic Validation Features
 
 ### API Validation

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

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

mcp-servers/gitea/CHANGELOG.md

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

mcp-servers/gitea/README.md

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

mcp-servers/gitea/TESTING.md

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

mcp-servers/gitea/mcp_server/__init__.py

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

mcp-servers/gitea/pyproject.toml

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

mcp-servers/gitea/tests/test_config.py

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

mcp-servers/gitea/tests/test_gitea_client.py

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

mcp-servers/gitea/tests/test_issues.py

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

mcp-servers/netbox/README.md

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

mcp-servers/netbox/mcp_server/config.py

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

mcp-servers/netbox/mcp_server/server.py

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

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

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

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

@@ -1,3 +1,11 @@
+---
+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

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

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

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

@@ -1,6 +1,9 @@
 ---
 name: maintainer
 description: CLAUDE.md optimization and maintenance agent
+model: sonnet
+permissionMode: acceptEdits
+skills: visual-header, settings-optimization
 ---
 
 # CLAUDE.md Maintainer Agent
@@ -114,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:**
 
@@ -149,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
@@ -166,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:
 
@@ -202,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:
 
@@ -237,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:
 

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

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

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

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

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

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

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

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

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

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

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

@@ -47,6 +47,27 @@ This skill defines the standard visual header for claude-config-maintainer comma
 +-----------------------------------------------------------------+
 ```
 
+### /config-audit-settings
+```
++-----------------------------------------------------------------+
+|  CONFIG-MAINTAINER - Settings Audit                              |
++-----------------------------------------------------------------+
+```
+
+### /config-optimize-settings
+```
++-----------------------------------------------------------------+
+|  CONFIG-MAINTAINER - Settings Optimization                       |
++-----------------------------------------------------------------+
+```
+
+### /config-permissions-map
+```
++-----------------------------------------------------------------+
+|  CONFIG-MAINTAINER - Permissions Map                             |
++-----------------------------------------------------------------+
+```
+
 ## Usage
 
 Display the header at the start of command execution, before any analysis or output.

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

@@ -1,3 +1,10 @@
+---
+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.

plugins/cmdb-assistant/claude-md-integration.md

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

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

@@ -31,7 +31,7 @@ When the user provides a search query, determine the best approach:
 3. **Site search**: Use `dcim_list_sites` with name filter
 4. **Prefix search**: Use `ipam_list_prefixes` with prefix or within filter
 5. **VLAN search**: Use `ipam_list_vlans` with vid or name filter
-6. **VM search**: Use `virtualization_list_virtual_machines` with name filter
+6. **VM search**: Use `virt_list_vms` with name filter
 
 For broad searches, query multiple endpoints and consolidate results.
 

plugins/code-sentinel/agents/refactor-advisor.md

@@ -1,5 +1,8 @@
 ---
-description: Code structure and refactoring specialist
+name: refactor-advisor
+description: Code structure and refactoring specialist. Use when analyzing code quality, design patterns, or planning refactoring work.
+model: sonnet
+permissionMode: acceptEdits
 ---
 
 # Refactor Advisor Agent

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

@@ -1,6 +1,9 @@
 ---
 name: security-reviewer
 description: Security-focused code review agent
+model: sonnet
+permissionMode: plan
+disallowedTools: Write, Edit, MultiEdit
 ---
 
 # Security Reviewer Agent

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

@@ -1,6 +1,6 @@
 {
   "name": "contract-validator",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Cross-plugin compatibility validation and Claude.md agent verification",
   "author": {
     "name": "Leo Miranda",

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

@@ -1,6 +1,9 @@
 ---
 name: agent-check
 description: Agent definition validator for quick verification
+model: haiku
+permissionMode: plan
+disallowedTools: Write, Edit, MultiEdit
 ---
 
 # Agent Check Agent

plugins/contract-validator/agents/full-validation.md

@@ -1,3 +1,10 @@
+---
+name: full-validation
+description: Contract validation specialist for comprehensive cross-plugin compatibility validation of the entire marketplace.
+model: sonnet
+permissionMode: default
+---
+
 # Full Validation Agent
 
 You are a contract validation specialist. Your role is to perform comprehensive cross-plugin compatibility validation for the entire marketplace.

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

@@ -1,10 +1,8 @@
 ---
-agent: data-advisor
-description: Reviews code for data integrity, schema validity, and dbt compliance using data-platform MCP tools
-triggers:
-  - /data-review command
-  - /data-gate command
-  - projman orchestrator domain gate
+name: data-advisor
+description: Reviews code for data integrity, schema validity, and dbt compliance using data-platform MCP tools. Use when validating database operations or data pipelines.
+model: sonnet
+permissionMode: default
 ---
 
 # Data Advisor Agent

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

@@ -1,6 +1,9 @@
 ---
 name: data-analysis
 description: Data analysis specialist for exploration and profiling
+model: sonnet
+permissionMode: plan
+disallowedTools: Write, Edit, MultiEdit
 ---
 
 # Data Analysis Agent

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

@@ -1,3 +1,10 @@
+---
+name: data-ingestion
+description: Data ingestion specialist for loading, transforming, and preparing data for analysis.
+model: haiku
+permissionMode: acceptEdits
+---
+
 # Data Ingestion Agent
 
 You are a data ingestion specialist. Your role is to help users load, transform, and prepare data for analysis.

plugins/data-platform/hooks/startup-check.sh

@@ -5,11 +5,26 @@
 
 PREFIX="[data-platform]"
 
-# Check if MCP venv exists
+# Check if MCP venv exists - check cache first, then local
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/data-platform/.venv/bin/python"
 PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "$(realpath "$0")")")}"
-VENV_PATH="$PLUGIN_ROOT/mcp-servers/data-platform/.venv/bin/python"
+MARKETPLACE_ROOT="$(dirname "$(dirname "$PLUGIN_ROOT")")"
+LOCAL_VENV="$MARKETPLACE_ROOT/mcp-servers/data-platform/.venv/bin/python"
 
-if [[ ! -f "$VENV_PATH" ]]; then
+# Check cache first (preferred), then local symlink
+CACHE_VENV_DIR="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/data-platform/.venv"
+LOCAL_VENV_DIR="$MARKETPLACE_ROOT/mcp-servers/data-platform/.venv"
+
+if [[ -f "$CACHE_VENV" ]]; then
+    VENV_PATH="$CACHE_VENV"
+    # Auto-create symlink in installed marketplace if missing
+    if [[ ! -e "$LOCAL_VENV_DIR" && -d "$CACHE_VENV_DIR" ]]; then
+        mkdir -p "$(dirname "$LOCAL_VENV_DIR")" 2>/dev/null
+        ln -sf "$CACHE_VENV_DIR" "$LOCAL_VENV_DIR" 2>/dev/null
+    fi
+elif [[ -f "$LOCAL_VENV" ]]; then
+    VENV_PATH="$LOCAL_VENV"
+else
     echo "$PREFIX MCP venv missing - run /initial-setup or setup.sh"
     exit 0
 fi

plugins/doc-guardian/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "doc-guardian",
   "description": "Automatic documentation drift detection and synchronization",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": {
     "name": "Leo Miranda",
     "email": "leobmiranda@gmail.com"

plugins/doc-guardian/agents/doc-analyzer.md

@@ -1,5 +1,8 @@
 ---
-description: Specialized agent for documentation analysis and drift detection
+name: doc-analyzer
+description: Specialized agent for documentation analysis and drift detection. Use when detecting or fixing discrepancies between code and documentation.
+model: sonnet
+permissionMode: acceptEdits
 ---
 
 # Documentation Analyzer Agent

plugins/git-flow/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "git-flow",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Git workflow automation with intelligent commit messages and branch management",
   "author": {
     "name": "Leo Miranda",

plugins/git-flow/agents/git-assistant.md

@@ -1,3 +1,10 @@
+---
+name: git-assistant
+description: Git workflow assistant for complex git operations, conflict resolution, and repository history management.
+model: haiku
+permissionMode: acceptEdits
+---
+
 # Git Assistant Agent
 
 ## Visual Output Requirements

plugins/pr-review/agents/coordinator.md

@@ -1,3 +1,11 @@
+---
+name: coordinator
+description: Review coordinator that orchestrates the multi-agent PR review process. Dispatches to specialized reviewers, aggregates findings, and produces the final review report. Use proactively after code changes.
+model: sonnet
+permissionMode: plan
+disallowedTools: Write, Edit, MultiEdit
+---
+
 # Coordinator Agent
 
 ## Visual Output Requirements

plugins/pr-review/agents/maintainability-auditor.md

@@ -1,3 +1,11 @@
+---
+name: maintainability-auditor
+description: Identifies code complexity, duplication, naming issues, and architecture concerns in PR changes.
+model: haiku
+permissionMode: plan
+disallowedTools: Write, Edit, MultiEdit
+---
+
 # Maintainability Auditor Agent
 
 ## Visual Output Requirements

plugins/pr-review/agents/performance-analyst.md

@@ -1,3 +1,11 @@
+---
+name: performance-analyst
+description: Performance-focused code reviewer that identifies performance issues, inefficiencies, and optimization opportunities.
+model: sonnet
+permissionMode: plan
+disallowedTools: Write, Edit, MultiEdit
+---
+
 # Performance Analyst Agent
 
 ## Visual Output Requirements

plugins/pr-review/agents/security-reviewer.md

@@ -1,6 +1,9 @@
 ---
 name: security-reviewer
 description: Security-focused code reviewer for PR analysis
+model: sonnet
+permissionMode: plan
+disallowedTools: Write, Edit, MultiEdit
 ---
 
 # Security Reviewer Agent

plugins/pr-review/agents/test-validator.md

@@ -1,3 +1,11 @@
+---
+name: test-validator
+description: Test quality reviewer that validates test coverage, test quality, and testing practices in PR changes.
+model: haiku
+permissionMode: plan
+disallowedTools: Write, Edit, MultiEdit
+---
+
 # Test Validator Agent
 
 ## Visual Output Requirements

plugins/pr-review/hooks/startup-check.sh

@@ -5,11 +5,18 @@
 
 PREFIX="[pr-review]"
 
-# Check if MCP venv exists
+# Check if MCP venv exists - check cache first, then local
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/gitea/.venv/bin/python"
 PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "$(realpath "$0")")")}"
-VENV_PATH="$PLUGIN_ROOT/mcp-servers/gitea/.venv/bin/python"
+MARKETPLACE_ROOT="$(dirname "$(dirname "$PLUGIN_ROOT")")"
+LOCAL_VENV="$MARKETPLACE_ROOT/mcp-servers/gitea/.venv/bin/python"
 
-if [[ ! -f "$VENV_PATH" ]]; then
+# Check cache first (preferred), then local
+if [[ -f "$CACHE_VENV" ]]; then
+    VENV_PATH="$CACHE_VENV"
+elif [[ -f "$LOCAL_VENV" ]]; then
+    VENV_PATH="$LOCAL_VENV"
+else
     echo "$PREFIX MCP venvs missing - run setup.sh from installed marketplace"
     exit 0
 fi

plugins/projman/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "projman",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Sprint planning and project management with Gitea integration",
   "author": {
     "name": "Leo Miranda",

plugins/projman/agents/code-reviewer.md

@@ -1,19 +1,16 @@
 ---
 name: code-reviewer
 description: Pre-sprint code quality review agent
+model: opus
+permissionMode: default
+disallowedTools: Write, Edit, MultiEdit
+skills: review-checklist, test-standards, sprint-lifecycle, visual-output
 ---
 
 # Code Reviewer Agent
 
 You are the **Code Reviewer Agent** - a thorough, practical reviewer who ensures code quality before sprint close.
 
-## Skills to Load
-
-- skills/review-checklist.md
-- skills/test-standards.md
-- skills/sprint-lifecycle.md
-- skills/visual-output.md
-
 ## Your Personality
 
 **Thorough but Practical:**

plugins/projman/agents/executor.md

@@ -1,22 +1,15 @@
 ---
 name: executor
 description: Implementation executor agent - precise implementation guidance and code quality
+model: sonnet
+permissionMode: bypassPermissions
+skills: mcp-tools-reference, branch-security, git-workflow, progress-tracking, runaway-detection, lessons-learned, visual-output
 ---
 
 # Implementation Executor Agent
 
 You are the **Executor Agent** - an implementation-focused specialist who writes clean code and ensures quality.
 
-## Skills to Load
-
-- skills/mcp-tools-reference.md
-- skills/branch-security.md
-- skills/git-workflow.md
-- skills/progress-tracking.md
-- skills/runaway-detection.md
-- skills/lessons-learned.md
-- skills/visual-output.md
-
 ## Your Personality
 
 **Implementation-Focused:**

plugins/projman/agents/orchestrator.md

@@ -1,26 +1,37 @@
 ---
 name: orchestrator
 description: Sprint orchestration agent - coordinates execution and tracks progress
+model: sonnet
+permissionMode: acceptEdits
+skills: mcp-tools-reference, batch-execution
 ---
 
 # Sprint Orchestration Agent
 
 You are the **Orchestrator Agent** - a concise, action-oriented coordinator who keeps sprints on track.
 
-## Skills to Load
+## Skill Loading Protocol
 
-- skills/mcp-tools-reference.md
+**Frontmatter skills (auto-injected, always available — DO NOT re-read these):**
+- `mcp-tools-reference` — MCP tool signatures for all Gitea operations
+- `batch-execution` — Plan-then-batch protocol for API execution
+
+**Phase 1 skills — read ONCE at session start, before any work begins:**
 - skills/branch-security.md
 - skills/sprint-approval.md
+- skills/sprint-lifecycle.md
+- skills/visual-output.md
+- skills/runaway-detection.md
+
+**Phase 2 skills — read ONCE when sequencing and dispatching work:**
 - skills/dependency-management.md
 - skills/lessons-learned.md
 - skills/git-workflow.md
 - skills/progress-tracking.md
-- skills/runaway-detection.md
 - skills/wiki-conventions.md
 - skills/domain-consultation.md
-- skills/sprint-lifecycle.md
-- skills/visual-output.md
+
+**CRITICAL: Read each skill file exactly ONCE. Do NOT re-read skill files between MCP API calls. When posting status updates, label changes, or comments across multiple issues, use the batch-execution protocol — queue all operations, execute in a loop using only frontmatter skills.**
 
 ## Your Personality
 

plugins/projman/agents/planner.md

@@ -1,28 +1,41 @@
 ---
 name: planner
 description: Sprint planning agent - thoughtful architecture analysis and issue creation
+model: opus
+permissionMode: default
+skills: mcp-tools-reference, batch-execution
 ---
 
 # Sprint Planning Agent
 
 You are the **Planner Agent** - a methodical architect who thoroughly analyzes requirements before creating well-structured plans.
 
-## Skills to Load
+## Skill Loading Protocol
 
-- skills/mcp-tools-reference.md
+**Frontmatter skills (auto-injected, always available — DO NOT re-read these):**
+- `mcp-tools-reference` — MCP tool signatures for all Gitea operations
+- `batch-execution` — Plan-then-batch protocol for API execution
+
+**Phase 1 skills — read ONCE at session start, before any work begins:**
 - skills/branch-security.md
 - skills/repo-validation.md
+- skills/sprint-lifecycle.md
+- skills/visual-output.md
+
+**Phase 2 skills — read ONCE when entering analysis/planning work:**
 - skills/input-detection.md
 - skills/lessons-learned.md
 - skills/wiki-conventions.md
 - skills/task-sizing.md
 - skills/issue-conventions.md
-- skills/sprint-approval.md
 - skills/planning-workflow.md
 - skills/label-taxonomy/labels-reference.md
 - skills/domain-consultation.md
-- skills/sprint-lifecycle.md
-- skills/visual-output.md
+
+**Phase 3 skills — read ONCE before requesting approval:**
+- skills/sprint-approval.md
+
+**CRITICAL: Read each skill file exactly ONCE. Do NOT re-read skill files between MCP API calls. During batch execution (Step 8a of planning-workflow.md), use ONLY the frontmatter skills — no file reads.**
 
 ## Your Personality
 

plugins/projman/commands/review.md

@@ -44,10 +44,7 @@ See `skills/review-checklist.md` for complete patterns:
 
 ## Visual Output
 
-```
-╔══════════════════════════════════════════════════════════════════╗
-║  📋 PROJMAN                                                      ║
-║  🏁 CLOSING                                                      ║
-║  Code Review                                                     ║
-╚══════════════════════════════════════════════════════════════════╝
-```
+See `skills/visual-output.md`. This command invokes the **Code Reviewer** agent:
+- Phase Emoji: 🔍
+- Phase Name: REVIEW
+- Context: Sprint Name

plugins/projman/commands/sprint-plan.md

@@ -7,7 +7,8 @@ agent: planner
 
 ## Skills Required
 
-- skills/mcp-tools-reference.md
+- skills/mcp-tools-reference.md (frontmatter — auto-injected)
+- skills/batch-execution.md (frontmatter — auto-injected)
 - skills/branch-security.md
 - skills/repo-validation.md
 - skills/input-detection.md

plugins/projman/commands/sprint-start.md

@@ -7,7 +7,8 @@ agent: orchestrator
 
 ## Skills Required
 
-- skills/mcp-tools-reference.md
+- skills/mcp-tools-reference.md (frontmatter — auto-injected)
+- skills/batch-execution.md (frontmatter — auto-injected)
 - skills/branch-security.md
 - skills/sprint-approval.md
 - skills/dependency-management.md

plugins/projman/hooks/startup-check.sh

@@ -29,17 +29,19 @@ if [[ -f ".env" ]]; then
 
     if [[ -n "$GITEA_API_URL" && -n "$GITEA_API_TOKEN" && -n "$GITEA_REPO" ]]; then
         # Quick check for open issues without milestone (unplanned work)
+        # Note: grep -c returns 0 on no match but exits non-zero, causing || to also fire
+        # Use subshell to ensure single value
         OPEN_ISSUES=$(curl -s -m 5 \
             -H "Authorization: token $GITEA_API_TOKEN" \
             "${GITEA_API_URL}/repos/${GITEA_REPO}/issues?state=open&milestone=none&limit=1" 2>/dev/null | \
-            grep -c '"number"' || echo "0")
+            grep -c '"number"' 2>/dev/null) || OPEN_ISSUES=0
 
         if [[ "$OPEN_ISSUES" -gt 0 ]]; then
             # Count total unplanned issues
             TOTAL_UNPLANNED=$(curl -s -m 5 \
                 -H "Authorization: token $GITEA_API_TOKEN" \
                 "${GITEA_API_URL}/repos/${GITEA_REPO}/issues?state=open&milestone=none" 2>/dev/null | \
-                grep -c '"number"' || echo "?")
+                grep -c '"number"' 2>/dev/null) || TOTAL_UNPLANNED="?"
             echo "$PREFIX ${TOTAL_UNPLANNED} open issues without milestone - consider /sprint-plan"
         fi
     fi

plugins/projman/skills/batch-execution.md

@@ -0,0 +1,116 @@
+---
+name: batch-execution
+description: Batch MCP API execution to eliminate redundant skill reloading between repetitive operations
+---
+
+# Batch Execution Pattern
+
+## Purpose
+
+Separate cognitive work (analysis, planning, decision-making) from mechanical API execution (issue creation, dependency setup, status updates). Think once with all skills loaded, then execute repetitive API calls in a tight loop with only `mcp-tools-reference.md` needed.
+
+## When to Use
+
+- **Planner agent**: After drafting all issues, before calling `create_issue`
+- **Orchestrator agent**: When posting status updates, label changes, or comments across multiple issues
+- **Any agent**: When making 3+ similar MCP API calls in sequence
+
+## Protocol
+
+### Phase 1: Cognitive Work (all skills loaded)
+
+During analysis, architecture, and planning — use every skill you need. Read files, think deeply, ask questions, resolve ambiguity. This is where the full skill set pays for itself.
+
+**Output of this phase:** A complete, structured execution plan listing every API operation with all parameters fully resolved. No ambiguity, no placeholders that require re-analysis.
+
+### Phase 2: Execution Manifest
+
+Before entering batch mode, produce a structured manifest. This serves as both the execution plan AND a checkpoint for user visibility. Format:
+
+```
+## Execution Manifest
+
+### Issue Creation (N items)
+1. `create_issue` — title: "[Sprint XX] feat: ..." | labels: [...] | milestone: N
+2. `create_issue` — title: "[Sprint XX] fix: ..." | labels: [...] | milestone: N
+...
+
+### Dependency Setup (N items)
+1. `create_issue_dependency` — issue: $1 depends_on: $2
+...
+
+### Milestone Assignment (N items)
+1. `update_issue` — issue: $1 milestone: N
+...
+
+### Status/Label Updates (N items)
+1. `update_issue` — issue: #N labels: [add "Status/In-Progress"]
+...
+```
+
+Variable references (`$1`, `$2`) resolve to outputs from prior batch operations (e.g., `$1` = issue number returned by first `create_issue`).
+
+### Phase 3: Batch Execute
+
+Execute the manifest items in order, grouped by operation type:
+
+1. **All `create_issue` calls** — collect returned issue numbers
+2. **Resolve variable references** — map `$1` → actual issue #45, `$2` → #46, etc.
+3. **All `create_issue_dependency` calls** — using resolved numbers
+4. **All milestone assignments** — if not done during creation
+5. **All status/label updates** — using resolved numbers
+
+**Rules during batch execution:**
+- Do NOT re-read any skill files between calls
+- Do NOT re-analyze or second-guess the plan — it was finalized in Phase 1
+- Do NOT add commentary between individual API calls — batch them silently
+- DO track success/failure per operation
+- DO continue on individual failures (log and report at end)
+- DO post a progress summary after each batch group completes
+
+### Phase 4: Batch Report
+
+After all operations complete, report results:
+
+```
+## Batch Execution Complete
+
+### Issue Creation: 6/6 ✓
+- #45: [Sprint 19] feat: JWT generation
+- #46: [Sprint 19] feat: Login endpoint
+- #47: [Sprint 19] feat: Token refresh
+- #48: [Sprint 19] test: Auth unit tests
+- #49: [Sprint 19] docs: API documentation
+- #50: [Sprint 19] chore: CI pipeline
+
+### Dependencies: 4/4 ✓
+- #46 depends on #45
+- #47 depends on #45
+- #48 depends on #46, #47
+- #49 depends on #46
+
+### Milestone Assignment: 6/6 ✓
+- All issues assigned to Sprint 19
+
+### Failures: 0
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Single API call fails | Log error, continue with next item |
+| Dependency target missing (prior create failed) | Skip dependency, log as blocked |
+| All creates fail | STOP batch, report connection/auth issue |
+| Partial milestone assignment | Report which issues weren't assigned |
+
+After batch completes, if any failures: present failure summary and ask user whether to retry failed operations or continue.
+
+## Anti-Patterns
+
+| Wrong | Why | Right |
+|-------|-----|-------|
+| Re-reading `mcp-tools-reference.md` before each API call | Wastes tokens; you already know the tool signatures | Read once, execute many |
+| Interleaving analysis with API calls | Forces full context per call | Finish ALL analysis first, THEN batch execute |
+| Calling create_issue one at a time with commentary between | Token overhead per turn | Queue all creates, execute in tight loop |
+| Stopping the batch to ask user about individual items | Defeats batching purpose | Complete batch, report results, ask about failures |

plugins/projman/skills/planning-workflow.md

@@ -84,21 +84,38 @@ Think through:
 - What dependencies exist?
 - What are potential risks?
 
-### 8. Create Gitea Issues
+### 8. Draft Issue Specifications (DO NOT create yet)
 
-Follow `skills/issue-conventions.md` and `skills/task-sizing.md`:
-- Use proper title format: `[Sprint XX] <type>: <description>`
-- Include wiki implementation reference
-- Apply appropriate labels using `suggest_labels`
-- **Refuse to create L/XL tasks without breakdown**
+Follow `skills/issue-conventions.md` and `skills/task-sizing.md` to prepare the complete specification for ALL issues. **Do NOT call `create_issue` yet.**
 
-### 9. Set Up Dependencies
+For each issue, resolve completely:
+- Title: `[Sprint XX] <type>: <description>`
+- Body: Full description with wiki reference, acceptance criteria, technical notes
+- Labels: Use `suggest_labels` to determine, then finalize the list
+- Milestone: The sprint milestone (create first if needed)
+- Dependencies: Which issues depend on which (by draft order index)
 
-```python
-create_issue_dependency(repo="org/repo", issue_number=46, depends_on=45)
-```
+**Refuse to create L/XL tasks without breakdown.**
 
-### 10. Create or Select Milestone
+Output: A complete execution manifest per `skills/batch-execution.md` Phase 2 format.
+
+### 8a. Batch Execute Issue Creation
+
+Follow `skills/batch-execution.md` Phase 3:
+1. Execute all `create_issue` calls — collect returned issue numbers
+2. Execute all `create_issue_dependency` calls — using collected numbers
+3. Assign all issues to milestone
+4. Report batch results per Phase 4 format
+
+**Only `skills/mcp-tools-reference.md` is needed for this step.** Do NOT re-read other skill files.
+
+### 9. (Merged into Step 8a)
+
+Dependencies are now created as part of the batch execution in Step 8a. No separate step needed.
+
+### 10. Create or Select Milestone (before batch)
+
+**This step runs BEFORE Step 8a** — the milestone must exist before batch issue creation can assign to it.
 
 ```python
 create_milestone(
@@ -109,7 +126,7 @@ create_milestone(
 )
 ```
 
-Assign issues to the milestone.
+If milestone already exists, select it. Record the milestone ID for use in the batch manifest.
 
 ### 11. Request Sprint Approval
 

plugins/projman/skills/visual-output.md

@@ -29,10 +29,10 @@ Projman uses the double-line box drawing header style with emoji phase indicator
 
 | Agent | Phase Emoji | Phase Name | Context |
 |-------|-------------|------------|---------|
-| Planner | Target | PLANNING | Sprint Name or Goal |
-| Orchestrator | Lightning | EXECUTION | Sprint Name |
-| Executor | Wrench | IMPLEMENTING | Issue Title |
-| Code Reviewer | Magnifier | REVIEW | Sprint Name |
+| Planner | 🎯 Target | PLANNING | Sprint Name or Goal |
+| Orchestrator | ⚡ Lightning | EXECUTION | Sprint Name |
+| Executor | 🔧 Wrench | IMPLEMENTING | Issue Title |
+| Code Reviewer | 🔍 Magnifier | REVIEW | Sprint Name |
 
 ### Command Headers (Non-Agent)
 
@@ -40,14 +40,14 @@ For commands that don't invoke a specific agent phase:
 
 | Command | Phase Emoji | Phase Name |
 |---------|-------------|------------|
-| `/sprint-status` | Chart | STATUS |
-| `/setup` | Gear | SETUP |
-| `/debug` | Bug | DEBUG |
-| `/labels-sync` | Label | LABELS |
-| `/suggest-version` | Package | VERSION |
-| `/proposal-status` | Clipboard | PROPOSALS |
-| `/test` | Flask | TEST |
-| `/rfc` | Document | RFC [Sub-Command] |
+| `/sprint-status` | 📊 Chart | STATUS |
+| `/setup` | ⚙️ Gear | SETUP |
+| `/debug` | 🐛 Bug | DEBUG |
+| `/labels-sync` | 🏷️ Label | LABELS |
+| `/suggest-version` | 📦 Package | VERSION |
+| `/proposal-status` | 📋 Clipboard | PROPOSALS |
+| `/test` | 🧪 Flask | TEST |
+| `/rfc` | 📄 Document | RFC [Sub-Command] |
 
 ---
 

plugins/viz-platform/agents/component-check.md

@@ -1,6 +1,9 @@
 ---
 name: component-check
 description: DMC component validation specialist
+model: haiku
+permissionMode: plan
+disallowedTools: Write, Edit, MultiEdit
 ---
 
 # Component Check Agent

plugins/viz-platform/agents/design-reviewer.md

@@ -1,10 +1,9 @@
 ---
-agent: design-reviewer
-description: Reviews code for design system compliance using viz-platform MCP tools
-triggers:
-  - /design-review command
-  - /design-gate command
-  - projman orchestrator domain gate
+name: design-reviewer
+description: Reviews code for design system compliance using viz-platform MCP tools. Use when validating DMC components, theme tokens, or accessibility standards.
+model: sonnet
+permissionMode: plan
+disallowedTools: Write, Edit, MultiEdit
 ---
 
 # Design Reviewer Agent

plugins/viz-platform/agents/layout-builder.md

@@ -1,3 +1,10 @@
+---
+name: layout-builder
+description: Practical dashboard layout specialist for creating well-structured layouts with filtering, grid systems, and responsive design.
+model: sonnet
+permissionMode: default
+---
+
 # Layout Builder Agent
 
 You are a practical dashboard layout specialist. Your role is to help users create well-structured dashboard layouts with proper filtering, grid systems, and responsive design.

plugins/viz-platform/agents/theme-setup.md

@@ -1,3 +1,10 @@
+---
+name: theme-setup
+description: Design-focused theme setup specialist for creating consistent, brand-aligned themes for Dash Mantine Components applications.
+model: haiku
+permissionMode: acceptEdits
+---
+
 # Theme Setup Agent
 
 You are a design-focused theme setup specialist. Your role is to help users create consistent, brand-aligned themes for their Dash Mantine Components applications.

scripts/install-plugin.sh

@@ -0,0 +1,384 @@
+#!/usr/bin/env bash
+# =============================================================================
+# install-plugin.sh - Install marketplace plugin to a consumer project
+# =============================================================================
+#
+# Usage: ./scripts/install-plugin.sh <plugin-name> <target-project-path>
+#
+# This script:
+# 1. Validates plugin exists in the marketplace
+# 2. Updates target project's .mcp.json with MCP server entries (if applicable)
+# 3. Appends CLAUDE.md integration snippet to target project
+# 4. Is idempotent (safe to run multiple times)
+#
+# Examples:
+#   ./scripts/install-plugin.sh data-platform ~/projects/personal-portfolio
+#   ./scripts/install-plugin.sh projman /home/user/my-project
+#
+# =============================================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# --- Color Definitions ---
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+# --- Logging Functions ---
+log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
+log_success() { echo -e "${GREEN}[OK]${NC} $1"; }
+log_skip() { echo -e "${YELLOW}[SKIP]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
+log_warning() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+
+# --- Track Changes ---
+CHANGES_MADE=()
+SKIPPED=()
+MCP_SERVERS_INSTALLED=()
+
+# --- Usage ---
+usage() {
+    echo "Usage: $0 <plugin-name> <target-project-path>"
+    echo ""
+    echo "Install a marketplace plugin to a consumer project."
+    echo ""
+    echo "Arguments:"
+    echo "  plugin-name         Name of the plugin (e.g., data-platform, viz-platform, projman)"
+    echo "  target-project-path Path to the target project (absolute or relative)"
+    echo ""
+    echo "Available plugins:"
+    for dir in "$REPO_ROOT"/plugins/*/; do
+        if [[ -d "$dir" ]]; then
+            basename "$dir"
+        fi
+    done
+    echo ""
+    echo "Examples:"
+    echo "  $0 data-platform ~/projects/personal-portfolio"
+    echo "  $0 projman /home/user/my-project"
+    exit 1
+}
+
+# --- Prerequisite Check ---
+check_prerequisites() {
+    if ! command -v jq &> /dev/null; then
+        log_error "jq is required but not installed."
+        echo "Install with: sudo apt install jq"
+        exit 1
+    fi
+}
+
+# --- Validate Plugin Exists ---
+validate_plugin() {
+    local plugin_name="$1"
+    local plugin_dir="$REPO_ROOT/plugins/$plugin_name"
+
+    if [[ ! -d "$plugin_dir" ]]; then
+        log_error "Plugin '$plugin_name' not found in $REPO_ROOT/plugins/"
+        echo ""
+        echo "Available plugins:"
+        for dir in "$REPO_ROOT"/plugins/*/; do
+            if [[ -d "$dir" ]]; then
+                echo "  - $(basename "$dir")"
+            fi
+        done
+        exit 1
+    fi
+
+    if [[ ! -f "$plugin_dir/.claude-plugin/plugin.json" ]]; then
+        log_error "Plugin '$plugin_name' missing .claude-plugin/plugin.json"
+        exit 1
+    fi
+
+    log_success "Plugin '$plugin_name' found"
+}
+
+# --- Validate Target Project ---
+validate_target() {
+    local target_path="$1"
+
+    if [[ ! -d "$target_path" ]]; then
+        log_error "Target project path does not exist: $target_path"
+        exit 1
+    fi
+
+    log_success "Target project found: $target_path"
+
+    # Warn if no CLAUDE.md
+    if [[ ! -f "$target_path/CLAUDE.md" ]]; then
+        log_warning "Target project has no CLAUDE.md - will create one"
+    fi
+}
+
+# --- Get MCP Servers for Plugin ---
+# Reads the mcp_servers array from plugin.json
+# Returns newline-separated list of MCP server names, or empty if none
+get_mcp_servers() {
+    local plugin_name="$1"
+    local plugin_json="$REPO_ROOT/plugins/$plugin_name/.claude-plugin/plugin.json"
+
+    if [[ ! -f "$plugin_json" ]]; then
+        return
+    fi
+
+    # Read mcp_servers array from plugin.json
+    # Returns empty if field doesn't exist or is empty
+    jq -r '.mcp_servers // [] | .[]' "$plugin_json" 2>/dev/null || true
+}
+
+# --- Check if plugin has any MCP servers ---
+has_mcp_servers() {
+    local plugin_name="$1"
+    local servers
+    servers=$(get_mcp_servers "$plugin_name")
+    [[ -n "$servers" ]]
+}
+
+# --- Update .mcp.json ---
+update_mcp_json() {
+    local plugin_name="$1"
+    local target_path="$2"
+    local mcp_json="$target_path/.mcp.json"
+
+    # Get MCP servers for this plugin
+    local mcp_servers
+    mcp_servers=$(get_mcp_servers "$plugin_name")
+
+    if [[ -z "$mcp_servers" ]]; then
+        log_skip "Plugin '$plugin_name' has no MCP servers - skipping .mcp.json update"
+        SKIPPED+=(".mcp.json: No MCP servers for $plugin_name")
+        return 0
+    fi
+
+    # Create .mcp.json if it doesn't exist
+    if [[ ! -f "$mcp_json" ]]; then
+        log_info "Creating new .mcp.json"
+        echo '{"mcpServers":{}}' > "$mcp_json"
+        CHANGES_MADE+=("Created .mcp.json")
+    fi
+
+    # Add each MCP server
+    local servers_added=0
+    while IFS= read -r server_name; do
+        [[ -z "$server_name" ]] && continue
+
+        local mcp_server_path="$REPO_ROOT/mcp-servers/$server_name/run.sh"
+
+        # Verify server exists
+        if [[ ! -f "$mcp_server_path" ]]; then
+            log_warning "MCP server '$server_name' not found at $mcp_server_path"
+            continue
+        fi
+
+        # Check if entry already exists
+        if jq -e ".mcpServers[\"$server_name\"]" "$mcp_json" > /dev/null 2>&1; then
+            log_skip "MCP server '$server_name' already in .mcp.json"
+            SKIPPED+=(".mcp.json: $server_name already present")
+            continue
+        fi
+
+        # Add MCP server entry
+        log_info "Adding MCP server '$server_name' to .mcp.json"
+        local tmp_file=$(mktemp)
+        jq ".mcpServers[\"$server_name\"] = {\"command\": \"$mcp_server_path\", \"args\": []}" "$mcp_json" > "$tmp_file"
+        mv "$tmp_file" "$mcp_json"
+
+        CHANGES_MADE+=("Added $server_name to .mcp.json")
+        MCP_SERVERS_INSTALLED+=("$server_name")
+        log_success "Added MCP server entry for '$server_name'"
+        ((++servers_added))
+    done <<< "$mcp_servers"
+}
+
+# --- Update CLAUDE.md ---
+update_claude_md() {
+    local plugin_name="$1"
+    local target_path="$2"
+    local target_claude_md="$target_path/CLAUDE.md"
+    local integration_file="$REPO_ROOT/plugins/$plugin_name/claude-md-integration.md"
+
+    # Check if integration file exists
+    if [[ ! -f "$integration_file" ]]; then
+        log_skip "No claude-md-integration.md for plugin '$plugin_name'"
+        SKIPPED+=("CLAUDE.md: No integration snippet for $plugin_name")
+        return 0
+    fi
+
+    # Create CLAUDE.md if it doesn't exist
+    if [[ ! -f "$target_claude_md" ]]; then
+        log_info "Creating new CLAUDE.md"
+        cat > "$target_claude_md" << 'EOF'
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+EOF
+        CHANGES_MADE+=("Created CLAUDE.md")
+    fi
+
+    # Check if already integrated using HTML comment marker (preferred)
+    local begin_marker="<!-- BEGIN marketplace-plugin: $plugin_name -->"
+    if grep -qF "$begin_marker" "$target_claude_md" 2>/dev/null; then
+        log_skip "Plugin '$plugin_name' integration already in CLAUDE.md"
+        SKIPPED+=("CLAUDE.md: $plugin_name already present")
+        return 0
+    fi
+
+    # Fallback: check for legacy header format (backward compatibility)
+    if grep -qE "^# ${plugin_name}( Plugin)? -? ?CLAUDE\.md Integration" "$target_claude_md" 2>/dev/null; then
+        log_skip "Plugin '$plugin_name' integration already in CLAUDE.md (legacy format)"
+        SKIPPED+=("CLAUDE.md: $plugin_name already present")
+        return 0
+    fi
+
+    # Read integration content
+    local integration_content
+    integration_content=$(cat "$integration_file")
+
+    # Check for or create Marketplace Plugin Integration section
+    local section_header="## Marketplace Plugin Integration"
+
+    if ! grep -qF "$section_header" "$target_claude_md"; then
+        log_info "Creating '$section_header' section"
+        echo "" >> "$target_claude_md"
+        echo "$section_header" >> "$target_claude_md"
+        echo "" >> "$target_claude_md"
+        echo "The following plugins are installed from the leo-claude-mktplace:" >> "$target_claude_md"
+        echo "" >> "$target_claude_md"
+    fi
+
+    # Append integration content with HTML comment markers
+    log_info "Adding '$plugin_name' integration to CLAUDE.md"
+    local end_marker="<!-- END marketplace-plugin: $plugin_name -->"
+
+    echo "" >> "$target_claude_md"
+    echo "---" >> "$target_claude_md"
+    echo "" >> "$target_claude_md"
+    echo "$begin_marker" >> "$target_claude_md"
+    echo "" >> "$target_claude_md"
+    echo "$integration_content" >> "$target_claude_md"
+    echo "" >> "$target_claude_md"
+    echo "$end_marker" >> "$target_claude_md"
+
+    CHANGES_MADE+=("Added $plugin_name integration to CLAUDE.md")
+    log_success "Added CLAUDE.md integration for '$plugin_name'"
+}
+
+# --- Get Commands for Plugin ---
+get_plugin_commands() {
+    local plugin_name="$1"
+    local commands_dir="$REPO_ROOT/plugins/$plugin_name/commands"
+
+    if [[ ! -d "$commands_dir" ]]; then
+        return
+    fi
+
+    for cmd_file in "$commands_dir"/*.md; do
+        if [[ -f "$cmd_file" ]]; then
+            local cmd_name
+            cmd_name=$(basename "$cmd_file" .md)
+            echo "  /$cmd_name"
+        fi
+    done
+}
+
+# --- Print Summary ---
+print_summary() {
+    local plugin_name="$1"
+    local target_path="$2"
+
+    echo ""
+    echo "=============================================="
+    echo -e "${GREEN}Installation Summary${NC}"
+    echo "=============================================="
+    echo ""
+    echo -e "${CYAN}Plugin:${NC} $plugin_name"
+    echo -e "${CYAN}Target:${NC} $target_path"
+    echo ""
+
+    if [[ ${#CHANGES_MADE[@]} -gt 0 ]]; then
+        echo -e "${GREEN}Changes Made:${NC}"
+        for change in "${CHANGES_MADE[@]}"; do
+            echo "  ✓ $change"
+        done
+        echo ""
+    fi
+
+    if [[ ${#SKIPPED[@]} -gt 0 ]]; then
+        echo -e "${YELLOW}Skipped (already present or N/A):${NC}"
+        for skip in "${SKIPPED[@]}"; do
+            echo "  - $skip"
+        done
+        echo ""
+    fi
+
+    # Show available commands
+    echo -e "${CYAN}Commands Now Available:${NC}"
+    local commands
+    commands=$(get_plugin_commands "$plugin_name")
+    if [[ -n "$commands" ]]; then
+        echo "$commands"
+    else
+        echo "  (No commands - this plugin may be hooks-only)"
+    fi
+    echo ""
+
+    # MCP servers info
+    if [[ ${#MCP_SERVERS_INSTALLED[@]} -gt 0 ]]; then
+        echo -e "${CYAN}MCP Servers Installed:${NC}"
+        for server in "${MCP_SERVERS_INSTALLED[@]}"; do
+            echo "  - $server"
+        done
+        echo ""
+    elif has_mcp_servers "$plugin_name"; then
+        echo -e "${CYAN}MCP Tools:${NC}"
+        echo "  This plugin includes MCP server tools. Use ToolSearch to discover them."
+        echo ""
+    fi
+
+    # Important reminder
+    echo -e "${YELLOW}⚠️  IMPORTANT:${NC}"
+    echo "  Restart your Claude Code session for changes to take effect."
+    echo "  The .mcp.json changes require a session restart to load MCP servers."
+    echo ""
+}
+
+# =============================================================================
+# Main Execution
+# =============================================================================
+
+# Check arguments
+if [[ $# -lt 2 ]]; then
+    usage
+fi
+
+PLUGIN_NAME="$1"
+TARGET_PATH="$2"
+
+# Resolve target path to absolute
+TARGET_PATH=$(cd "$TARGET_PATH" 2>/dev/null && pwd || echo "$TARGET_PATH")
+
+echo ""
+echo "=============================================="
+echo -e "${BLUE}Installing Plugin: $PLUGIN_NAME${NC}"
+echo "=============================================="
+echo ""
+
+# Run checks
+check_prerequisites
+validate_plugin "$PLUGIN_NAME"
+validate_target "$TARGET_PATH"
+
+echo ""
+
+# Perform installation
+update_mcp_json "$PLUGIN_NAME" "$TARGET_PATH"
+update_claude_md "$PLUGIN_NAME" "$TARGET_PATH"
+
+# Print summary
+print_summary "$PLUGIN_NAME" "$TARGET_PATH"

scripts/list-installed.sh

@@ -0,0 +1,322 @@
+#!/usr/bin/env bash
+# =============================================================================
+# list-installed.sh - Show installed marketplace plugins in a project
+# =============================================================================
+#
+# Usage: ./scripts/list-installed.sh <target-project-path>
+#
+# This script:
+# 1. Checks .mcp.json for MCP server entries from this marketplace
+# 2. Checks CLAUDE.md for plugin integration sections
+# 3. Reports which plugins are installed
+#
+# Examples:
+#   ./scripts/list-installed.sh ~/projects/personal-portfolio
+#   ./scripts/list-installed.sh .
+#
+# =============================================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# --- Color Definitions ---
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+# --- Logging Functions ---
+log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
+log_success() { echo -e "${GREEN}[OK]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
+log_warning() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+
+# --- Usage ---
+usage() {
+    echo "Usage: $0 <target-project-path>"
+    echo ""
+    echo "Show which marketplace plugins are installed in a project."
+    echo ""
+    echo "Arguments:"
+    echo "  target-project-path Path to the target project (absolute or relative)"
+    echo ""
+    echo "Examples:"
+    echo "  $0 ~/projects/personal-portfolio"
+    echo "  $0 ."
+    exit 1
+}
+
+# --- Prerequisite Check ---
+check_prerequisites() {
+    if ! command -v jq &> /dev/null; then
+        log_error "jq is required but not installed."
+        echo "Install with: sudo apt install jq"
+        exit 1
+    fi
+}
+
+# --- Get Available Plugins ---
+get_available_plugins() {
+    for dir in "$REPO_ROOT"/plugins/*/; do
+        if [[ -d "$dir" ]]; then
+            basename "$dir"
+        fi
+    done
+}
+
+# --- Get MCP Servers for Plugin ---
+# Reads the mcp_servers array from plugin.json
+get_mcp_servers() {
+    local plugin_name="$1"
+    local plugin_json="$REPO_ROOT/plugins/$plugin_name/.claude-plugin/plugin.json"
+
+    if [[ ! -f "$plugin_json" ]]; then
+        return
+    fi
+
+    jq -r '.mcp_servers // [] | .[]' "$plugin_json" 2>/dev/null || true
+}
+
+# --- Check if plugin has any MCP servers defined ---
+has_mcp_servers() {
+    local plugin_name="$1"
+    local servers
+    servers=$(get_mcp_servers "$plugin_name")
+    [[ -n "$servers" ]]
+}
+
+# --- Check MCP Installation ---
+check_mcp_installed() {
+    local plugin_name="$1"
+    local target_path="$2"
+    local mcp_json="$target_path/.mcp.json"
+
+    if [[ ! -f "$mcp_json" ]]; then
+        return 1
+    fi
+
+    # Get MCP servers for this plugin from plugin.json
+    local mcp_servers
+    mcp_servers=$(get_mcp_servers "$plugin_name")
+
+    if [[ -z "$mcp_servers" ]]; then
+        # Plugin has no MCP servers defined, so MCP check passes
+        return 0
+    fi
+
+    # Check if ALL required MCP servers are present
+    while IFS= read -r server_name; do
+        [[ -z "$server_name" ]] && continue
+
+        if ! jq -e ".mcpServers[\"$server_name\"]" "$mcp_json" > /dev/null 2>&1; then
+            # Also check if any entry points to this marketplace's mcp-servers
+            if ! grep -q "mcp-servers/$server_name" "$mcp_json" 2>/dev/null; then
+                return 1
+            fi
+        fi
+    done <<< "$mcp_servers"
+
+    return 0
+}
+
+# --- Check CLAUDE.md Integration ---
+check_claude_md_installed() {
+    local plugin_name="$1"
+    local target_path="$2"
+    local target_claude_md="$target_path/CLAUDE.md"
+
+    if [[ ! -f "$target_claude_md" ]]; then
+        return 1
+    fi
+
+    # Check for HTML comment marker (preferred, new format)
+    local begin_marker="<!-- BEGIN marketplace-plugin: $plugin_name -->"
+    if grep -qF "$begin_marker" "$target_claude_md" 2>/dev/null; then
+        return 0
+    fi
+
+    # Fallback: check for legacy header format
+    if grep -qE "^# ${plugin_name}( Plugin)? -? ?CLAUDE\.md Integration" "$target_claude_md" 2>/dev/null; then
+        return 0
+    fi
+
+    return 1
+}
+
+# --- Get Plugin Version ---
+get_plugin_version() {
+    local plugin_name="$1"
+    local plugin_json="$REPO_ROOT/plugins/$plugin_name/.claude-plugin/plugin.json"
+
+    if [[ -f "$plugin_json" ]]; then
+        jq -r '.version // "unknown"' "$plugin_json"
+    else
+        echo "unknown"
+    fi
+}
+
+# --- Get Plugin Description ---
+get_plugin_description() {
+    local plugin_name="$1"
+    local plugin_json="$REPO_ROOT/plugins/$plugin_name/.claude-plugin/plugin.json"
+
+    if [[ -f "$plugin_json" ]]; then
+        jq -r '.description // "No description"' "$plugin_json" | cut -c1-60
+    else
+        echo "No description"
+    fi
+}
+
+# =============================================================================
+# Main Execution
+# =============================================================================
+
+# Check arguments
+if [[ $# -lt 1 ]]; then
+    usage
+fi
+
+TARGET_PATH="$1"
+
+# Resolve target path to absolute
+if [[ -d "$TARGET_PATH" ]]; then
+    TARGET_PATH=$(cd "$TARGET_PATH" && pwd)
+else
+    log_error "Target project path does not exist: $TARGET_PATH"
+    exit 1
+fi
+
+check_prerequisites
+
+echo ""
+echo "=============================================="
+echo -e "${BLUE}Installed Plugins: $(basename "$TARGET_PATH")${NC}"
+echo "=============================================="
+echo -e "${CYAN}Target:${NC} $TARGET_PATH"
+echo ""
+
+# Collect results
+declare -A INSTALLED_MCP
+declare -A INSTALLED_CLAUDE_MD
+INSTALLED_PLUGINS=()
+PARTIAL_PLUGINS=()
+NOT_INSTALLED=()
+
+# Check each available plugin
+for plugin in $(get_available_plugins); do
+    mcp_installed=false
+    claude_installed=false
+    needs_mcp=false
+
+    # Check if plugin has MCP servers defined
+    if has_mcp_servers "$plugin"; then
+        needs_mcp=true
+    fi
+
+    # Check MCP installation
+    if check_mcp_installed "$plugin" "$TARGET_PATH"; then
+        mcp_installed=true
+        INSTALLED_MCP[$plugin]=true
+    fi
+
+    # Check CLAUDE.md integration
+    if check_claude_md_installed "$plugin" "$TARGET_PATH"; then
+        claude_installed=true
+        INSTALLED_CLAUDE_MD[$plugin]=true
+    fi
+
+    # Categorize
+    if $claude_installed; then
+        if $needs_mcp; then
+            if $mcp_installed; then
+                INSTALLED_PLUGINS+=("$plugin")
+            else
+                PARTIAL_PLUGINS+=("$plugin")
+            fi
+        else
+            # Plugins without MCP servers just need CLAUDE.md
+            INSTALLED_PLUGINS+=("$plugin")
+        fi
+    elif $mcp_installed && $needs_mcp; then
+        # Has MCP but missing CLAUDE.md
+        PARTIAL_PLUGINS+=("$plugin")
+    else
+        NOT_INSTALLED+=("$plugin")
+    fi
+done
+
+# Print fully installed plugins
+if [[ ${#INSTALLED_PLUGINS[@]} -gt 0 ]]; then
+    echo -e "${GREEN}✓ Fully Installed:${NC}"
+    echo ""
+    printf "  %-24s %-10s %s\n" "PLUGIN" "VERSION" "DESCRIPTION"
+    printf "  %-24s %-10s %s\n" "------" "-------" "-----------"
+    for plugin in "${INSTALLED_PLUGINS[@]}"; do
+        version=$(get_plugin_version "$plugin")
+        desc=$(get_plugin_description "$plugin")
+        printf "  %-24s %-10s %s\n" "$plugin" "$version" "$desc"
+    done
+    echo ""
+fi
+
+# Print partially installed plugins
+if [[ ${#PARTIAL_PLUGINS[@]} -gt 0 ]]; then
+    echo -e "${YELLOW}⚠ Partially Installed:${NC}"
+    echo ""
+    for plugin in "${PARTIAL_PLUGINS[@]}"; do
+        version=$(get_plugin_version "$plugin")
+        echo "  $plugin (v$version)"
+        if [[ -v INSTALLED_MCP[$plugin] ]]; then
+            echo "    ✓ MCP server configured in .mcp.json"
+        else
+            # Show which MCP servers are missing
+            mcp_servers=$(get_mcp_servers "$plugin")
+            if [[ -n "$mcp_servers" ]]; then
+                echo "    ✗ MCP server(s) NOT in .mcp.json: $mcp_servers"
+            fi
+        fi
+        if [[ -v INSTALLED_CLAUDE_MD[$plugin] ]]; then
+            echo "    ✓ Integration in CLAUDE.md"
+        else
+            echo "    ✗ Integration NOT in CLAUDE.md"
+        fi
+        echo ""
+    done
+    echo "  Run install-plugin.sh to complete installation."
+    echo ""
+fi
+
+# Print available but not installed
+if [[ ${#NOT_INSTALLED[@]} -gt 0 ]]; then
+    echo -e "${BLUE}○ Available (not installed):${NC}"
+    echo ""
+    for plugin in "${NOT_INSTALLED[@]}"; do
+        version=$(get_plugin_version "$plugin")
+        desc=$(get_plugin_description "$plugin")
+        printf "  %-24s %-10s %s\n" "$plugin" "$version" "$desc"
+    done
+    echo ""
+fi
+
+# Summary
+echo "----------------------------------------------"
+total_available=$(get_available_plugins | wc -l)
+total_installed=${#INSTALLED_PLUGINS[@]}
+total_partial=${#PARTIAL_PLUGINS[@]}
+
+echo -e "Total: ${GREEN}$total_installed installed${NC}"
+if [[ $total_partial -gt 0 ]]; then
+    echo -e "       ${YELLOW}$total_partial partial${NC}"
+fi
+echo "       $((total_available - total_installed - total_partial)) available"
+echo ""
+
+# Install hint
+if [[ ${#NOT_INSTALLED[@]} -gt 0 ]]; then
+    echo "To install a plugin:"
+    echo "  $SCRIPT_DIR/install-plugin.sh <plugin-name> $TARGET_PATH"
+    echo ""
+fi

scripts/uninstall-plugin.sh

@@ -0,0 +1,363 @@
+#!/usr/bin/env bash
+# =============================================================================
+# uninstall-plugin.sh - Remove marketplace plugin from a consumer project
+# =============================================================================
+#
+# Usage: ./scripts/uninstall-plugin.sh <plugin-name> <target-project-path>
+#
+# This script:
+# 1. Removes MCP server entries from target project's .mcp.json
+# 2. Removes CLAUDE.md integration section for the plugin
+# 3. Is idempotent (safe to run multiple times)
+#
+# Examples:
+#   ./scripts/uninstall-plugin.sh data-platform ~/projects/personal-portfolio
+#   ./scripts/uninstall-plugin.sh projman /home/user/my-project
+#
+# =============================================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# --- Color Definitions ---
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+# --- Logging Functions ---
+log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
+log_success() { echo -e "${GREEN}[OK]${NC} $1"; }
+log_skip() { echo -e "${YELLOW}[SKIP]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
+log_warning() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+
+# --- Track Changes ---
+CHANGES_MADE=()
+SKIPPED=()
+
+# --- Usage ---
+usage() {
+    echo "Usage: $0 <plugin-name> <target-project-path>"
+    echo ""
+    echo "Remove a marketplace plugin from a consumer project."
+    echo ""
+    echo "Arguments:"
+    echo "  plugin-name         Name of the plugin (e.g., data-platform, viz-platform, projman)"
+    echo "  target-project-path Path to the target project (absolute or relative)"
+    echo ""
+    echo "Examples:"
+    echo "  $0 data-platform ~/projects/personal-portfolio"
+    echo "  $0 projman /home/user/my-project"
+    exit 1
+}
+
+# --- Prerequisite Check ---
+check_prerequisites() {
+    if ! command -v jq &> /dev/null; then
+        log_error "jq is required but not installed."
+        echo "Install with: sudo apt install jq"
+        exit 1
+    fi
+}
+
+# --- Validate Target Project ---
+validate_target() {
+    local target_path="$1"
+
+    if [[ ! -d "$target_path" ]]; then
+        log_error "Target project path does not exist: $target_path"
+        exit 1
+    fi
+
+    log_success "Target project found: $target_path"
+}
+
+# --- Get MCP Servers for Plugin ---
+# Reads the mcp_servers array from plugin.json
+# Returns newline-separated list of MCP server names, or empty if none
+get_mcp_servers() {
+    local plugin_name="$1"
+    local plugin_json="$REPO_ROOT/plugins/$plugin_name/.claude-plugin/plugin.json"
+
+    if [[ ! -f "$plugin_json" ]]; then
+        return
+    fi
+
+    # Read mcp_servers array from plugin.json
+    # Returns empty if field doesn't exist or is empty
+    jq -r '.mcp_servers // [] | .[]' "$plugin_json" 2>/dev/null || true
+}
+
+# --- Remove from .mcp.json ---
+remove_from_mcp_json() {
+    local plugin_name="$1"
+    local target_path="$2"
+    local mcp_json="$target_path/.mcp.json"
+
+    # Check if .mcp.json exists
+    if [[ ! -f "$mcp_json" ]]; then
+        log_skip "No .mcp.json found - nothing to remove"
+        SKIPPED+=(".mcp.json: File does not exist")
+        return 0
+    fi
+
+    # Get MCP servers for this plugin
+    local mcp_servers
+    mcp_servers=$(get_mcp_servers "$plugin_name")
+
+    if [[ -z "$mcp_servers" ]]; then
+        # Fallback: try to remove entry with plugin name (backward compatibility)
+        if jq -e ".mcpServers[\"$plugin_name\"]" "$mcp_json" > /dev/null 2>&1; then
+            log_info "Removing MCP server '$plugin_name' from .mcp.json"
+            local tmp_file=$(mktemp)
+            jq "del(.mcpServers[\"$plugin_name\"])" "$mcp_json" > "$tmp_file"
+            mv "$tmp_file" "$mcp_json"
+            CHANGES_MADE+=("Removed $plugin_name from .mcp.json")
+            log_success "Removed MCP server entry for '$plugin_name'"
+        else
+            log_skip "Plugin '$plugin_name' has no MCP servers configured"
+            SKIPPED+=(".mcp.json: No MCP servers for $plugin_name")
+        fi
+        return 0
+    fi
+
+    # Remove each MCP server
+    local servers_removed=0
+    while IFS= read -r server_name; do
+        [[ -z "$server_name" ]] && continue
+
+        # Check if entry exists
+        if ! jq -e ".mcpServers[\"$server_name\"]" "$mcp_json" > /dev/null 2>&1; then
+            log_skip "MCP server '$server_name' not in .mcp.json"
+            SKIPPED+=(".mcp.json: $server_name not present")
+            continue
+        fi
+
+        # Remove MCP server entry
+        log_info "Removing MCP server '$server_name' from .mcp.json"
+        local tmp_file=$(mktemp)
+        jq "del(.mcpServers[\"$server_name\"])" "$mcp_json" > "$tmp_file"
+        mv "$tmp_file" "$mcp_json"
+
+        CHANGES_MADE+=("Removed $server_name from .mcp.json")
+        log_success "Removed MCP server entry for '$server_name'"
+        ((++servers_removed))
+    done <<< "$mcp_servers"
+}
+
+# --- Remove from CLAUDE.md ---
+remove_from_claude_md() {
+    local plugin_name="$1"
+    local target_path="$2"
+    local target_claude_md="$target_path/CLAUDE.md"
+
+    # Check if CLAUDE.md exists
+    if [[ ! -f "$target_claude_md" ]]; then
+        log_skip "No CLAUDE.md found - nothing to remove"
+        SKIPPED+=("CLAUDE.md: File does not exist")
+        return 0
+    fi
+
+    # Try HTML comment markers first (preferred method)
+    local begin_marker="<!-- BEGIN marketplace-plugin: $plugin_name -->"
+    local end_marker="<!-- END marketplace-plugin: $plugin_name -->"
+
+    if grep -qF "$begin_marker" "$target_claude_md" 2>/dev/null; then
+        log_info "Removing '$plugin_name' section from CLAUDE.md (using markers)"
+
+        # Remove everything between markers (inclusive) and preceding ---
+        local tmp_file=$(mktemp)
+        awk -v begin="$begin_marker" -v end="$end_marker" '
+        BEGIN { skip = 0; prev_hr = 0; buffer = "" }
+        {
+            is_hr = /^---[[:space:]]*$/
+
+            if ($0 == begin) {
+                skip = 1
+                # If previous line was ---, dont print it
+                if (prev_hr) {
+                    buffer = ""
+                }
+                next
+            }
+
+            if (skip) {
+                if ($0 == end) {
+                    skip = 0
+                }
+                next
+            }
+
+            # Print buffered content
+            if (buffer != "") {
+                print buffer
+            }
+
+            # Buffer current line (in case its --- before a marker)
+            buffer = $0
+            prev_hr = is_hr
+        }
+        END {
+            # Print final buffered content
+            if (buffer != "") {
+                print buffer
+            }
+        }
+        ' "$target_claude_md" > "$tmp_file"
+
+        # Clean up multiple consecutive blank lines
+        awk 'NF{blank=0} !NF{blank++} blank<=2' "$tmp_file" > "${tmp_file}.clean"
+        mv "${tmp_file}.clean" "$target_claude_md"
+        rm -f "$tmp_file"
+
+        CHANGES_MADE+=("Removed $plugin_name section from CLAUDE.md")
+        log_success "Removed CLAUDE.md section for '$plugin_name'"
+        return 0
+    fi
+
+    # Fallback: try legacy header-based detection
+    local section_header
+    section_header=$(grep -E "^# ${plugin_name}( Plugin)? -? ?CLAUDE\.md Integration" "$target_claude_md" 2>/dev/null | head -1)
+
+    if [[ -z "$section_header" ]]; then
+        log_skip "Plugin '$plugin_name' section not found in CLAUDE.md"
+        SKIPPED+=("CLAUDE.md: $plugin_name section not found")
+        return 0
+    fi
+
+    log_info "Removing '$plugin_name' section from CLAUDE.md (legacy format)"
+
+    # Create temp file and use awk to remove section
+    local tmp_file=$(mktemp)
+
+    awk -v header="$section_header" '
+    BEGIN { skip = 0; found = 0; in_code_block = 0 }
+    {
+        # Track code blocks (``` markers)
+        if (/^```/) {
+            in_code_block = !in_code_block
+        }
+
+        # Check if this is the section header we want to remove
+        if ($0 == header) {
+            skip = 1
+            found = 1
+            next
+        }
+
+        # Check if this is a horizontal rule (---) - only count if not in code block
+        is_hr = /^---[[:space:]]*$/ && !in_code_block
+
+        # Check if this is a new plugin section header (only outside code blocks)
+        is_new_plugin_section = /^# [a-z-]+( Plugin)? -? ?CLAUDE\.md Integration/ && !in_code_block && $0 != header
+
+        # Check for HTML marker (new format)
+        is_begin_marker = /^<!-- BEGIN marketplace-plugin:/ && !in_code_block
+
+        if (skip) {
+            # Stop skipping when we hit --- or a new section
+            if (is_hr) {
+                skip = 0
+                next
+            }
+            if (is_new_plugin_section || is_begin_marker) {
+                skip = 0
+                print
+            }
+            next
+        }
+
+        print
+    }
+    END { if (!found) exit 1 }
+    ' "$target_claude_md" > "$tmp_file" 2>/dev/null
+
+    if [[ $? -eq 0 ]]; then
+        # Clean up multiple consecutive blank lines
+        awk 'NF{blank=0} !NF{blank++} blank<=2' "$tmp_file" > "${tmp_file}.clean"
+        mv "${tmp_file}.clean" "$target_claude_md"
+        rm -f "$tmp_file"
+        CHANGES_MADE+=("Removed $plugin_name section from CLAUDE.md")
+        log_success "Removed CLAUDE.md section for '$plugin_name'"
+    else
+        rm -f "$tmp_file"
+        log_skip "Could not locate exact section boundaries in CLAUDE.md"
+        log_warning "You may need to manually remove the $plugin_name section"
+        SKIPPED+=("CLAUDE.md: Manual removal may be needed")
+    fi
+}
+
+# --- Print Summary ---
+print_summary() {
+    local plugin_name="$1"
+    local target_path="$2"
+
+    echo ""
+    echo "=============================================="
+    echo -e "${GREEN}Uninstallation Summary${NC}"
+    echo "=============================================="
+    echo ""
+    echo -e "${CYAN}Plugin:${NC} $plugin_name"
+    echo -e "${CYAN}Target:${NC} $target_path"
+    echo ""
+
+    if [[ ${#CHANGES_MADE[@]} -gt 0 ]]; then
+        echo -e "${GREEN}Changes Made:${NC}"
+        for change in "${CHANGES_MADE[@]}"; do
+            echo "  ✓ $change"
+        done
+        echo ""
+    fi
+
+    if [[ ${#SKIPPED[@]} -gt 0 ]]; then
+        echo -e "${YELLOW}Skipped (not present or N/A):${NC}"
+        for skip in "${SKIPPED[@]}"; do
+            echo "  - $skip"
+        done
+        echo ""
+    fi
+
+    if [[ ${#CHANGES_MADE[@]} -gt 0 ]]; then
+        echo -e "${YELLOW}⚠️  IMPORTANT:${NC}"
+        echo "  Restart your Claude Code session for changes to take effect."
+        echo ""
+    fi
+}
+
+# =============================================================================
+# Main Execution
+# =============================================================================
+
+# Check arguments
+if [[ $# -lt 2 ]]; then
+    usage
+fi
+
+PLUGIN_NAME="$1"
+TARGET_PATH="$2"
+
+# Resolve target path to absolute
+TARGET_PATH=$(cd "$TARGET_PATH" 2>/dev/null && pwd || echo "$TARGET_PATH")
+
+echo ""
+echo "=============================================="
+echo -e "${BLUE}Uninstalling Plugin: $PLUGIN_NAME${NC}"
+echo "=============================================="
+echo ""
+
+# Run checks
+check_prerequisites
+validate_target "$TARGET_PATH"
+
+echo ""
+
+# Perform uninstallation
+remove_from_mcp_json "$PLUGIN_NAME" "$TARGET_PATH"
+remove_from_claude_md "$PLUGIN_NAME" "$TARGET_PATH"
+
+# Print summary
+print_summary "$PLUGIN_NAME" "$TARGET_PATH"