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

Reviewed-on: #311

.claude-plugin/marketplace.json

@@ -6,12 +6,12 @@
   },
   "metadata": {
     "description": "Project management plugins with Gitea and NetBox integrations",
-    "version": "5.1.0"
+    "version": "5.4.0"
   },
   "plugins": [
     {
       "name": "projman",
-      "version": "3.2.0",
+      "version": "3.3.0",
       "description": "Sprint planning and project management with Gitea integration",
       "source": "./plugins/projman",
       "author": {
@@ -27,7 +27,7 @@
     },
     {
       "name": "doc-guardian",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "description": "Automatic documentation drift detection and synchronization",
       "source": "./plugins/doc-guardian",
       "author": {
@@ -75,7 +75,7 @@
     },
     {
       "name": "cmdb-assistant",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "description": "NetBox CMDB integration with data quality validation and machine registration",
       "source": "./plugins/cmdb-assistant",
       "author": {
@@ -91,7 +91,7 @@
     },
     {
       "name": "claude-config-maintainer",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "description": "CLAUDE.md optimization and maintenance for Claude Code projects",
       "source": "./plugins/claude-config-maintainer",
       "author": {
@@ -106,7 +106,7 @@
     },
     {
       "name": "clarity-assist",
-      "version": "1.0.0",
+      "version": "1.2.0",
       "description": "Prompt optimization and requirement clarification with ND-friendly accommodations",
       "source": "./plugins/clarity-assist",
       "author": {
@@ -121,7 +121,7 @@
     },
     {
       "name": "git-flow",
-      "version": "1.0.0",
+      "version": "1.2.0",
       "description": "Git workflow automation with intelligent commit messages and branch management",
       "source": "./plugins/git-flow",
       "author": {
@@ -136,7 +136,7 @@
     },
     {
       "name": "pr-review",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "description": "Multi-agent pull request review with confidence scoring and actionable feedback",
       "source": "./plugins/pr-review",
       "author": {
@@ -152,7 +152,7 @@
     },
     {
       "name": "data-platform",
-      "version": "1.0.0",
+      "version": "1.2.0",
       "description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
       "source": "./plugins/data-platform",
       "author": {
@@ -168,7 +168,7 @@
     },
     {
       "name": "viz-platform",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "description": "Visualization tools with Dash Mantine Components validation, Plotly charts, and theming",
       "source": "./plugins/viz-platform",
       "author": {
@@ -184,7 +184,7 @@
     },
     {
       "name": "contract-validator",
-      "version": "1.0.0",
+      "version": "1.2.0",
       "description": "Cross-plugin compatibility validation and Claude.md agent verification",
       "source": "./plugins/contract-validator",
       "author": {

CHANGELOG.md

@@ -4,10 +4,198 @@ 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]
+## [5.4.0] - 2026-01-28
 
 ### Added
 
+#### Sprint 7: Multi-Model Agent Support
+Configurable model selection for agents with inheritance chain.
+
+**Model Configuration:**
+- Agent-level `model` field in YAML frontmatter (opus|sonnet|haiku)
+- Plugin-level `defaultModel` in plugin.json
+- Inheritance: Agent → Plugin → System default (sonnet)
+
+**Recommended Model Assignments:**
+| Model | Use Case | Agents |
+|-------|----------|--------|
+| **Opus** | Complex reasoning, security analysis | planner, code-reviewer, security-reviewer, data-analysis |
+| **Sonnet** | Implementation, coordination | orchestrator, executor, layout-builder, data-ingestion |
+| **Haiku** | Quick validation | component-check, agent-check |
+
+**Documentation:**
+- `docs/MODEL-RECOMMENDATIONS.md` - Central model selection guide
+- `docs/CONFIGURATION.md` - Added agent model configuration section
+- `CLAUDE.md` - Added model config quick reference
+
+**Agent Updates (7 files):**
+- Opus: planner, code-reviewer (projman), security-reviewer (pr-review, code-sentinel), data-analysis
+- Haiku: component-check (viz-platform), agent-check (contract-validator)
+
+**Plugin Manifest Updates (6 files):**
+- All plugins with agents now have `defaultModel: sonnet`
+- Version bumps: projman 3.3.0, pr-review 1.1.0, data-platform 1.1.0, viz-platform 1.1.0, code-sentinel 1.0.1, contract-validator 1.1.0
+
+**Validation:**
+- `scripts/validate-marketplace.sh` - Added model field validation (v5.4.0+)
+
+**Sprint Completed:**
+- Milestone: Sprint 7 - Multi-Model Agent Support
+- Issues: #302, #303, #304, #305, #306
+- PRs: #307, #308
+- Wiki: [Change V5.4.0: Multi-Model Support (Sprint 7 Implementation)](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/Change-V5.4.0%3A-Multi-Model-Support-%28Sprint-7-Implementation%29)
+
+---
+
+## [5.3.0] - 2026-01-28
+
+### Added
+
+#### Sprint 6: Visual Branding Overhaul
+Consistent visual headers and progress tracking across all plugins.
+
+**Visual Output Headers (109 files):**
+- **Projman**: Double-line headers (╔═╗) with phase indicators (🎯 PLANNING, ⚡ EXECUTION, 🏁 CLOSING)
+- **Other Plugins**: Single-line headers (┌─┐) with plugin icons
+- **All 23 agents** updated with Visual Output Requirements section
+- **All 86 commands** updated with Visual Output section and header templates
+
+**Plugin Icon Registry:**
+| Plugin | Icon |
+|--------|------|
+| projman | 📋 |
+| code-sentinel | 🔒 |
+| doc-guardian | 📝 |
+| pr-review | 🔍 |
+| clarity-assist | 💬 |
+| git-flow | 🔀 |
+| cmdb-assistant | 🖥️ |
+| data-platform | 📊 |
+| viz-platform | 🎨 |
+| contract-validator | ✅ |
+| claude-config-maintainer | ⚙️ |
+
+**Wiki Branding Specification (4 pages):**
+- [branding/visual-spec](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/branding%2Fvisual-spec) - Central specification
+- [branding/plugin-registry](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/branding%2Fplugin-registry) - Icons and styles
+- [branding/header-templates](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/branding%2Fheader-templates) - Copy-paste templates
+- [branding/progress-templates](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/branding%2Fprogress-templates) - Sprint progress blocks
+
+### Fixed
+- **Docs:** Version sync - CLAUDE.md, marketplace.json, README.md now consistent
+- **Docs:** Added 18 missing commands from Sprint 4 & 5 to README.md and COMMANDS-CHEATSHEET.md
+- **MCP:** Registered `/sprint-diagram` as invokable skill
+
+**Sprint Completed:**
+- Milestone: Sprint 6 - Visual Branding Overhaul (closed 2026-01-28)
+- Issues: #272, #273, #274, #275, #276, #277, #278
+- PRs: #284, #285
+- Wiki: [Sprint 6 Lessons](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/lessons/sprints/sprint-6---visual-branding-and-documentation-maintenance)
+
+---
+
+## [5.2.0] - 2026-01-28
+
+### Added
+
+#### Sprint 5: Documentation (V5.2.0 Plugin Enhancements)
+Documentation and guides for the plugin enhancements initiative.
+
+**git-flow v1.2.0:**
+- **Branching Strategy Guide** (`docs/BRANCHING-STRATEGY.md`) - Complete documentation of `development -> staging -> main` promotion flow with Mermaid diagrams
+
+**clarity-assist v1.2.0:**
+- **ND Support Guide** (`docs/ND-SUPPORT.md`) - Documentation of neurodivergent accommodations, features, and usage examples
+
+**Gitea MCP Server:**
+- **`update_issue` milestone parameter** - Can now assign/change milestones programmatically
+
+**Sprint Completed:**
+- Milestone: Sprint 5 - Documentation (closed 2026-01-28)
+- Issues: #266, #267, #268, #269
+- Wiki: [Change V5.2.0: Plugin Enhancements (Sprint 5 Documentation)](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/Change-V5.2.0%3A-Plugin-Enhancements-%28Sprint-5-Documentation%29)
+
+---
+
+#### Sprint 4: Commands (V5.2.0 Plugin Enhancements)
+Implementation of 18 new user-facing commands across 8 plugins.
+
+**projman v3.3.0:**
+- **`/sprint-diagram`** - Generate Mermaid diagram of sprint issues with dependencies and status
+
+**pr-review v1.1.0:**
+- **`/pr-diff`** - Formatted diff with inline review comments and annotations
+- **Confidence threshold config** - `PR_REVIEW_CONFIDENCE_THRESHOLD` env var (default: 0.7)
+
+**data-platform v1.2.0:**
+- **`/data-quality`** - DataFrame quality checks (nulls, duplicates, types, outliers) with pass/warn/fail scoring
+- **`/lineage-viz`** - dbt lineage visualization as Mermaid diagrams
+- **`/dbt-test`** - Formatted dbt test runner with summary and failure details
+
+**viz-platform v1.1.0:**
+- **`/chart-export`** - Export charts to PNG, SVG, PDF via kaleido
+- **`/accessibility-check`** - Color blind validation (WCAG contrast ratios)
+- **`/breakpoints`** - Responsive layout breakpoint configuration
+- **New MCP tools**: `chart_export`, `accessibility_validate_colors`, `accessibility_validate_theme`, `accessibility_suggest_alternative`, `layout_set_breakpoints`
+- **New dependency**: kaleido>=0.2.1 for chart rendering
+
+**contract-validator v1.2.0:**
+- **`/dependency-graph`** - Mermaid visualization of plugin dependencies with data flow
+
+**doc-guardian v1.1.0:**
+- **`/changelog-gen`** - Generate changelog from conventional commits
+- **`/doc-coverage`** - Documentation coverage metrics by function/class
+- **`/stale-docs`** - Flag documentation behind code changes
+
+**claude-config-maintainer v1.1.0:**
+- **`/config-diff`** - Track CLAUDE.md changes over time with behavioral impact analysis
+- **`/config-lint`** - 31 lint rules for CLAUDE.md (security, structure, content, format, best practices)
+
+**cmdb-assistant v1.2.0:**
+- **`/cmdb-topology`** - Infrastructure topology diagrams (rack, network, site views)
+- **`/change-audit`** - NetBox audit trail queries with filtering
+- **`/ip-conflicts`** - Detect IP conflicts and overlapping prefixes
+
+**Sprint Completed:**
+- Milestone: Sprint 4 - Commands (closed 2026-01-28)
+- Issues: #241-#258 (18/18 closed)
+- Wiki: [Change V5.2.0: Plugin Enhancements (Sprint 4 Commands)](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/Change-V5.2.0%3A-Plugin-Enhancements-%28Sprint-4-Commands%29)
+- Lessons: [Sprint 4 - Plugin Commands Implementation](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/lessons/sprints/sprint-4---plugin-commands-implementation)
+
+### Fixed
+- **MCP:** Project directory detection - all run.sh scripts now capture `CLAUDE_PROJECT_DIR` from PWD before changing directories
+- **Docs:** Added Gitea auto-close behavior and MCP session restart notes to DEBUGGING-CHECKLIST.md
+
+---
+
+#### Sprint 3: Hooks (V5.2.0 Plugin Enhancements)
+Implementation of 6 foundational hooks across 4 plugins.
+
+**git-flow v1.1.0:**
+- **Commit message enforcement hook** - PreToolUse hook validates conventional commit format on all `git commit` commands (not just `/commit`). Blocks invalid commits with format guidance.
+- **Branch name validation hook** - PreToolUse hook validates branch naming on `git checkout -b` and `git switch -c`. Enforces `type/description` format, lowercase, max 50 chars.
+
+**clarity-assist v1.1.0:**
+- **Vagueness detection hook** - UserPromptSubmit hook detects vague prompts and suggests `/clarify` when ambiguity, missing context, or unclear scope detected.
+
+**data-platform v1.1.0:**
+- **Schema diff detection hook** - PostToolUse hook monitors edits to schema files (dbt models, SQL migrations). Warns on breaking changes (column removal, type narrowing, constraint addition).
+
+**contract-validator v1.1.0:**
+- **SessionStart auto-validate hook** - Smart validation that only runs when plugin files changed since last check. Detects interface compatibility issues at session start.
+- **Breaking change detection hook** - PostToolUse hook monitors plugin interface files (README.md, plugin.json). Warns when changes would break consumers.
+
+**Sprint Completed:**
+- Milestone: Sprint 3 - Hooks (closed 2026-01-28)
+- Issues: #225, #226, #227, #228, #229, #230
+- Wiki: [Change V5.2.0: Plugin Enhancements Proposal](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/Change-V5.2.0:-Plugin-Enhancements-Proposal)
+- Lessons: Background agent permissions, agent runaway detection, MCP branch detection bug
+
+### Known Issues
+- **MCP Bug #231:** Branch detection in Gitea MCP runs from installed plugin directory, not user's project directory. Workaround: close issues via Gitea web UI.
+
+---
+
 #### Gitea MCP Server - create_pull_request Tool
 - **`create_pull_request`**: Create new pull requests via MCP
   - Parameters: title, body, head (source branch), base (target branch), labels

CLAUDE.md

@@ -1,48 +1,44 @@
 # CLAUDE.md
 
 This file provides guidance to Claude Code when working with code in this repository.
-## ⛔ MANDATORY BEHAVIOR RULES - READ FIRST
 
-**These rules are NON-NEGOTIABLE. Violating them wastes the user's time and money.**
+## ⛔ RULES - READ FIRST
 
-### 1. WHEN USER ASKS YOU TO CHECK SOMETHING - CHECK EVERYTHING
-- Search ALL locations, not just where you think it is
-- Check cache directories: `~/.claude/plugins/cache/`
-- Check installed: `~/.claude/plugins/marketplaces/`
-- Check source: `~/claude-plugins-work/`
-- **NEVER say "no" or "that's not the issue" without exhaustive verification**
+### Behavioral Rules
 
-### 2. WHEN USER SAYS SOMETHING IS WRONG - BELIEVE THEM
-- The user knows their system better than you
-- Investigate thoroughly before disagreeing
-- If user suspects cache, CHECK THE CACHE
-- If user suspects a file, READ THE FILE
-- **Your confidence is often wrong. User's instincts are often right.**
+| Rule | Summary |
+|------|---------|
+| **Check everything** | Search cache (`~/.claude/plugins/cache/`), installed (`~/.claude/plugins/marketplaces/`), and source (`~/claude-plugins-work/`) |
+| **Believe the user** | User knows their system. Investigate before disagreeing. |
+| **Verify before "done"** | Run commands, show output, check all locations. "Done" = verified working. |
+| **Show what's asked** | Don't interpret or summarize unless asked. |
 
-### 3. NEVER SAY "DONE" WITHOUT VERIFICATION
-- Run the actual command/script to verify
-- Show the output to the user
-- Check ALL affected locations
-- **"Done" means VERIFIED WORKING, not "I made changes"**
+### After Plugin Updates
 
-### 4. SHOW EXACTLY WHAT USER ASKS FOR
-- If user asks for messages, show the MESSAGES
-- If user asks for code, show the CODE
-- If user asks for output, show the OUTPUT
-- **Don't interpret or summarize unless asked**
+Run `./scripts/verify-hooks.sh`. If changes affect MCP servers or hooks, inform user to restart session.
+**DO NOT clear cache mid-session** - breaks loaded MCP tools.
 
-### 5. AFTER PLUGIN UPDATES - VERIFY AND RESTART
+### NEVER USE CLI TOOLS FOR EXTERNAL SERVICES
+- **FORBIDDEN:** `gh`, `tea`, `curl` to APIs, any CLI that talks to Gitea/GitHub/external services
+- **REQUIRED:** Use MCP tools exclusively (`mcp__plugin_projman_gitea__*`, `mcp__plugin_pr-review_gitea__*`)
+- **NO EXCEPTIONS.** Don't try CLI first. Don't fall back to CLI. MCP ONLY.
 
-**⚠️ DO NOT clear cache mid-session** - this breaks MCP tools that are already loaded.
+### NEVER PUSH DIRECTLY TO PROTECTED BRANCHES
+- **FORBIDDEN:** `git push origin development`, `git push origin main`, `git push origin master`
+- **REQUIRED:** Create feature branch → push feature branch → create PR via MCP
+- If you accidentally commit to a protected branch locally: `git checkout -b fix/branch-name` then reset the protected branch
 
-1. Run `./scripts/verify-hooks.sh` to check hook types
-2. If changes affect MCP servers or hooks, inform the user:
-   > "Plugin changes require a session restart to take effect. Please restart Claude Code."
-3. Cache clearing is ONLY safe **before** starting a new session (not during)
+### Repository Rules
 
-See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing.
+| Rule | Details |
+|------|---------|
+| **File creation** | Only in allowed paths. Use `.scratch/` for temp work. Verify against `docs/CANONICAL-PATHS.md` |
+| **plugin.json location** | Must be in `.claude-plugin/` directory |
+| **Hooks** | Use `hooks/hooks.json` (auto-discovered). Never inline in plugin.json |
+| **MCP servers** | Shared at root with symlinks. Use MCP tools, never CLI (`tea`, `gh`) |
+| **Allowed root files** | `CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example` |
 
-**FAILURE TO FOLLOW THESE RULES = WASTED USER TIME = UNACCEPTABLE**
+**Valid hook events:** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
 
 ---
 
@@ -50,24 +46,24 @@ See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing.
 ## Project Overview
 
 **Repository:** leo-claude-mktplace
-**Version:** 5.0.0
+**Version:** 5.4.0
 **Status:** Production Ready
 
 A plugin marketplace for Claude Code containing:
 
 | Plugin | Description | Version |
 |--------|-------------|---------|
-| `projman` | Sprint planning and project management with Gitea integration | 3.2.0 |
+| `projman` | Sprint planning and project management with Gitea integration | 3.3.0 |
 | `git-flow` | Git workflow automation with smart commits and branch management | 1.0.0 |
-| `pr-review` | Multi-agent PR review with confidence scoring | 1.0.0 |
+| `pr-review` | Multi-agent PR review with confidence scoring | 1.1.0 |
 | `clarity-assist` | Prompt optimization with ND-friendly accommodations | 1.0.0 |
 | `doc-guardian` | Automatic documentation drift detection and synchronization | 1.0.0 |
-| `code-sentinel` | Security scanning and code refactoring tools | 1.0.0 |
+| `code-sentinel` | Security scanning and code refactoring tools | 1.0.1 |
 | `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 1.0.0 |
-| `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 1.0.0 |
-| `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 1.0.0 |
-| `viz-platform` | DMC validation, Plotly charts, and theming for dashboards | 1.0.0 |
-| `contract-validator` | Cross-plugin compatibility validation and agent verification | 1.0.0 |
+| `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 1.2.0 |
+| `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 1.1.0 |
+| `viz-platform` | DMC validation, Plotly charts, and theming for dashboards | 1.1.0 |
+| `contract-validator` | Cross-plugin compatibility validation and agent verification | 1.1.0 |
 | `project-hygiene` | Post-task cleanup automation via hooks | 0.1.0 |
 
 ## Quick Start
@@ -85,16 +81,17 @@ A plugin marketplace for Claude Code containing:
 | Category | Commands |
 |----------|----------|
 | **Setup** | `/initial-setup`, `/project-init`, `/project-sync` |
-| **Sprint** | `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close` |
+| **Sprint** | `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/sprint-diagram` |
 | **Quality** | `/review`, `/test-check`, `/test-gen` |
 | **Versioning** | `/suggest-version` |
-| **PR Review** | `/pr-review:initial-setup`, `/pr-review:project-init` |
-| **Docs** | `/doc-audit`, `/doc-sync` |
+| **PR Review** | `/pr-review`, `/pr-summary`, `/pr-findings`, `/pr-diff` |
+| **Docs** | `/doc-audit`, `/doc-sync`, `/changelog-gen`, `/doc-coverage`, `/stale-docs` |
 | **Security** | `/security-scan`, `/refactor`, `/refactor-dry` |
-| **Config** | `/config-analyze`, `/config-optimize` |
-| **Data** | `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/run` |
-| **Visualization** | `/component`, `/chart`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css` |
-| **Validation** | `/validate-contracts`, `/check-agent`, `/list-interfaces` |
+| **Config** | `/config-analyze`, `/config-optimize`, `/config-diff`, `/config-lint` |
+| **Data** | `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/lineage-viz`, `/run`, `/dbt-test`, `/data-quality` |
+| **Visualization** | `/component`, `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/accessibility-check`, `/breakpoints` |
+| **Validation** | `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/dependency-graph` |
+| **CMDB** | `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`, `/cmdb-audit`, `/cmdb-register`, `/cmdb-sync`, `/cmdb-topology`, `/change-audit`, `/ip-conflicts` |
 | **Debug** | `/debug-report`, `/debug-review` |
 
 ## Repository Structure
@@ -161,40 +158,6 @@ leo-claude-mktplace/
     └── CONFIGURATION.md          # Centralized configuration guide
 ```
 
-## CRITICAL: Rules You MUST Follow
-
-### File Operations
-- **NEVER** create files in repository root unless listed in "Allowed Root Files"
-- **NEVER** modify `.gitignore` without explicit permission
-- **ALWAYS** use `.scratch/` for temporary/exploratory work
-- **ALWAYS** verify paths against `docs/CANONICAL-PATHS.md` before creating files
-
-### Plugin Development
-- **plugin.json MUST be in `.claude-plugin/` directory** (not plugin root)
-- **Every plugin MUST be listed in marketplace.json**
-- **MCP servers are SHARED at root** with symlinks from plugins
-- **MCP server venv path**: `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{name}/.venv/bin/python`
-- **CLI tools forbidden** - Use MCP tools exclusively (never `tea`, `gh`, etc.)
-
-#### ⚠️ plugin.json Format Rules (CRITICAL)
-- **Hooks in separate file** - Use `hooks/hooks.json` (auto-discovered), NOT inline in plugin.json
-- **NEVER reference hooks** - Don't add `"hooks": "..."` field to plugin.json at all
-- **Agents auto-discover** - NEVER add `"agents": ["./agents/"]` - .md files found automatically
-- **Always validate** - Run `./scripts/validate-marketplace.sh` before committing
-- **Working examples:** projman, pr-review, claude-config-maintainer all use `hooks/hooks.json`
-- See lesson: `lessons/patterns/plugin-manifest-validation---hooks-and-agents-format-requirements`
-
-### Hooks (Valid Events Only)
-`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
-
-**INVALID:** `task-completed`, `file-changed`, `git-commit-msg-needed`
-
-### Allowed Root Files
-`CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example`
-
-### Allowed Root Directories
-`.claude/`, `.claude-plugin/`, `.claude-plugins/`, `.scratch/`, `docs/`, `hooks/`, `mcp-servers/`, `plugins/`, `scripts/`
-
 ## Architecture
 
 ### Four-Agent Model (projman)
@@ -227,6 +190,21 @@ leo-claude-mktplace/
 
 **Note:** `GITEA_ORG` is at project level since different projects may belong to different organizations.
 
+### Agent Model Configuration
+
+Agents can specify preferred Claude models for cost/performance optimization:
+
+| Model | Use For | Agents |
+|-------|---------|--------|
+| `opus` | Complex reasoning, security | planner, code-reviewer, security-reviewer |
+| `sonnet` | Implementation, coordination | orchestrator, executor, most agents |
+| `haiku` | Simple validation | component-check, agent-check |
+
+**Configuration:** Add `model: opus|sonnet|haiku` to agent frontmatter, or `defaultModel` to plugin.json.
+**Inheritance:** Agent → Plugin default → System default (sonnet)
+
+See `docs/MODEL-RECOMMENDATIONS.md` for detailed guidance.
+
 ### Branch-Aware Security
 
 | Branch Pattern | Mode | Capabilities |
@@ -376,4 +354,4 @@ The script will:
 
 ---
 
-**Last Updated:** 2026-01-24
+**Last Updated:** 2026-01-28

README.md

@@ -1,4 +1,4 @@
-# Leo Claude Marketplace - v5.1.0
+# Leo Claude Marketplace - v5.4.0
 
 A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
 
@@ -19,7 +19,7 @@ AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sp
 - Branch-aware security (development/staging/production)
 - Pre-sprint-close code quality review and test verification
 
-**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/project-init`, `/project-sync`, `/review`, `/test-check`, `/test-gen`, `/debug-report`, `/debug-review`
+**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/sprint-diagram`, `/labels-sync`, `/initial-setup`, `/project-init`, `/project-sync`, `/review`, `/test-check`, `/test-gen`, `/debug-report`, `/debug-review`, `/suggest-version`, `/proposal-status`
 
 #### [git-flow](./plugins/git-flow/README.md) *NEW in v3.0.0*
 **Git Workflow Automation**
@@ -44,14 +44,14 @@ Comprehensive pull request review using specialized agents.
 - Actionable feedback with suggested fixes
 - Gitea integration for automated review submission
 
-**Commands:** `/pr-review`, `/pr-summary`, `/pr-findings`, `/initial-setup`, `/project-init`, `/project-sync`
+**Commands:** `/pr-review`, `/pr-summary`, `/pr-findings`, `/pr-diff`, `/initial-setup`, `/project-init`, `/project-sync`
 
 #### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md)
 **CLAUDE.md Optimization and Maintenance**
 
 Analyze, optimize, and create CLAUDE.md configuration files for Claude Code projects.
 
-**Commands:** `/config-analyze`, `/config-optimize`, `/config-init`
+**Commands:** `/config-analyze`, `/config-optimize`, `/config-init`, `/config-diff`, `/config-lint`
 
 #### [contract-validator](./plugins/contract-validator/README.md) *NEW in v5.0.0*
 **Cross-Plugin Compatibility Validation**
@@ -64,7 +64,7 @@ Validate plugin marketplaces for command conflicts, tool overlaps, and broken ag
 - Data flow validation for agent sequences
 - Markdown or JSON reports with actionable suggestions
 
-**Commands:** `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/initial-setup`
+**Commands:** `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/dependency-graph`, `/initial-setup`
 
 ### Productivity
 
@@ -84,7 +84,7 @@ Transform vague requests into clear specifications using structured methodology.
 
 Automatic documentation drift detection and synchronization.
 
-**Commands:** `/doc-audit`, `/doc-sync`
+**Commands:** `/doc-audit`, `/doc-sync`, `/changelog-gen`, `/doc-coverage`, `/stale-docs`
 
 #### [project-hygiene](./plugins/project-hygiene/README.md)
 **Post-Task Cleanup Automation**
@@ -107,7 +107,7 @@ Security vulnerability detection and code refactoring tools.
 
 Full CRUD operations for network infrastructure management directly from Claude Code.
 
-**Commands:** `/initial-setup`, `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`
+**Commands:** `/initial-setup`, `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`, `/cmdb-audit`, `/cmdb-register`, `/cmdb-sync`, `/cmdb-topology`, `/change-audit`, `/ip-conflicts`
 
 ### Data Engineering
 
@@ -122,7 +122,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`, `/run`
+**Commands:** `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/lineage-viz`, `/run`, `/dbt-test`, `/data-quality`, `/initial-setup`
 
 ### Visualization
 
@@ -138,7 +138,7 @@ Visualization toolkit with version-locked component validation and design token
 - 5 Page tools for multi-page app structure
 - Dual theme storage: user-level and project-level
 
-**Commands:** `/chart`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/initial-setup`
+**Commands:** `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/accessibility-check`, `/breakpoints`, `/initial-setup`
 
 ## MCP Servers
 

docs/CANONICAL-PATHS.md

@@ -2,7 +2,7 @@
 
 **This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
 
-Last Updated: 2026-01-26 (v5.0.0)
+Last Updated: 2026-01-27 (v5.1.0)
 
 ---
 
@@ -165,7 +165,11 @@ leo-claude-mktplace/
 │   ├── setup.sh                # Initial setup (create venvs, config templates)
 │   ├── post-update.sh          # Post-update (rebuild venvs, verify symlinks)
 │   ├── check-venv.sh           # Check if venvs exist (for hooks)
-│   └── validate-marketplace.sh # Marketplace compliance validation
+│   ├── validate-marketplace.sh # Marketplace compliance validation
+│   ├── verify-hooks.sh         # Verify all hooks use correct event types
+│   ├── setup-venvs.sh          # Setup/repair MCP server venvs
+│   ├── venv-repair.sh          # Repair broken venv symlinks
+│   └── release.sh              # Release automation with version bumping
 ├── CLAUDE.md
 ├── README.md
 ├── LICENSE

docs/COMMANDS-CHEATSHEET.md

@@ -23,6 +23,8 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **projman** | `/debug-report` | | X | Run diagnostics and create structured issue in marketplace |
 | **projman** | `/debug-review` | | X | Investigate diagnostic issues and propose fixes with approval gates |
 | **projman** | `/suggest-version` | | X | Analyze CHANGELOG and recommend semantic version bump |
+| **projman** | `/proposal-status` | | X | View proposal and implementation hierarchy with status |
+| **projman** | `/sprint-diagram` | | X | Generate Mermaid diagram of sprint issues with dependencies |
 | **git-flow** | `/commit` | | X | Create commit with auto-generated conventional message |
 | **git-flow** | `/commit-push` | | X | Commit and push to remote in one operation |
 | **git-flow** | `/commit-merge` | | X | Commit current changes, then merge into target branch |
@@ -38,10 +40,14 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **pr-review** | `/pr-review` | | X | Full multi-agent PR review with confidence scoring |
 | **pr-review** | `/pr-summary` | | X | Quick summary of PR changes |
 | **pr-review** | `/pr-findings` | | X | List and filter review findings by category/severity |
+| **pr-review** | `/pr-diff` | | X | Formatted diff with inline review comments and annotations |
 | **clarity-assist** | `/clarify` | | X | Full 4-D prompt optimization with ND accommodations |
 | **clarity-assist** | `/quick-clarify` | | X | Rapid single-pass clarification for simple requests |
 | **doc-guardian** | `/doc-audit` | | X | Full documentation audit - scans for doc drift |
 | **doc-guardian** | `/doc-sync` | | X | Synchronize pending documentation updates |
+| **doc-guardian** | `/changelog-gen` | | X | Generate changelog from conventional commits |
+| **doc-guardian** | `/doc-coverage` | | X | Documentation coverage metrics by function/class |
+| **doc-guardian** | `/stale-docs` | | X | Flag documentation behind code changes |
 | **doc-guardian** | *PostToolUse hook* | X | | Silently detects doc drift on Write/Edit |
 | **code-sentinel** | `/security-scan` | | X | Full security audit (SQL injection, XSS, secrets, etc.) |
 | **code-sentinel** | `/refactor` | | X | Apply refactoring patterns to improve code |
@@ -50,11 +56,19 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **claude-config-maintainer** | `/config-analyze` | | X | Analyze CLAUDE.md for optimization opportunities |
 | **claude-config-maintainer** | `/config-optimize` | | X | Optimize CLAUDE.md structure with preview/backup |
 | **claude-config-maintainer** | `/config-init` | | X | Initialize new CLAUDE.md for a project |
+| **claude-config-maintainer** | `/config-diff` | | X | Track CLAUDE.md changes over time with behavioral impact |
+| **claude-config-maintainer** | `/config-lint` | | X | Lint CLAUDE.md for anti-patterns and best practices |
 | **cmdb-assistant** | `/initial-setup` | | X | Setup wizard for NetBox MCP server |
 | **cmdb-assistant** | `/cmdb-search` | | X | Search NetBox for devices, IPs, sites |
 | **cmdb-assistant** | `/cmdb-device` | | X | Manage network devices (create, view, update, delete) |
 | **cmdb-assistant** | `/cmdb-ip` | | X | Manage IP addresses and prefixes |
 | **cmdb-assistant** | `/cmdb-site` | | X | Manage sites, locations, racks, and regions |
+| **cmdb-assistant** | `/cmdb-audit` | | X | Data quality analysis (VMs, devices, naming, roles) |
+| **cmdb-assistant** | `/cmdb-register` | | X | Register current machine into NetBox with running apps |
+| **cmdb-assistant** | `/cmdb-sync` | | X | Sync machine state with NetBox (detect drift, update) |
+| **cmdb-assistant** | `/cmdb-topology` | | X | Infrastructure topology diagrams (rack, network, site views) |
+| **cmdb-assistant** | `/change-audit` | | X | NetBox audit trail queries with filtering |
+| **cmdb-assistant** | `/ip-conflicts` | | X | Detect IP conflicts and overlapping prefixes |
 | **project-hygiene** | *PostToolUse hook* | X | | Removes temp files, warns about unexpected root files |
 | **data-platform** | `/ingest` | | X | Load data from CSV, Parquet, JSON into DataFrame |
 | **data-platform** | `/profile` | | X | Generate data profiling report with statistics |
@@ -62,6 +76,9 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **data-platform** | `/explain` | | X | Explain query execution plan |
 | **data-platform** | `/lineage` | | X | Show dbt model lineage and dependencies |
 | **data-platform** | `/run` | | X | Run dbt models with validation |
+| **data-platform** | `/lineage-viz` | | X | dbt lineage visualization as Mermaid diagrams |
+| **data-platform** | `/dbt-test` | | X | Formatted dbt test runner with summary and failure details |
+| **data-platform** | `/data-quality` | | X | DataFrame quality checks (nulls, duplicates, types, outliers) |
 | **data-platform** | `/initial-setup` | | X | Setup wizard for data-platform MCP servers |
 | **data-platform** | *SessionStart hook* | X | | Checks PostgreSQL connection (non-blocking warning) |
 | **viz-platform** | `/initial-setup` | | X | Setup wizard for viz-platform MCP server |
@@ -71,7 +88,15 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **viz-platform** | `/theme-new` | | X | Create new custom theme with design tokens |
 | **viz-platform** | `/theme-css` | | X | Export theme as CSS custom properties |
 | **viz-platform** | `/component` | | X | Inspect DMC component props and validation |
+| **viz-platform** | `/chart-export` | | X | Export charts to PNG, SVG, PDF via kaleido |
+| **viz-platform** | `/accessibility-check` | | X | Color blind validation (WCAG contrast ratios) |
+| **viz-platform** | `/breakpoints` | | X | Configure responsive layout breakpoints |
 | **viz-platform** | *SessionStart hook* | X | | Checks DMC version (non-blocking warning) |
+| **contract-validator** | `/validate-contracts` | | X | Full marketplace compatibility validation |
+| **contract-validator** | `/check-agent` | | X | Validate single agent definition |
+| **contract-validator** | `/list-interfaces` | | X | Show all plugin interfaces |
+| **contract-validator** | `/dependency-graph` | | X | Mermaid visualization of plugin dependencies |
+| **contract-validator** | `/initial-setup` | | X | Setup wizard for contract-validator MCP |
 
 ---
 
@@ -87,6 +112,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **Infrastructure** | cmdb-assistant | NetBox CMDB management |
 | **Data Engineering** | data-platform | pandas, PostgreSQL, dbt operations |
 | **Visualization** | viz-platform | DMC validation, Plotly charts, theming |
+| **Validation** | contract-validator | Cross-plugin compatibility checks |
 | **Maintenance** | project-hygiene | Automatic cleanup |
 
 ---
@@ -245,9 +271,10 @@ Some plugins require MCP server connectivity:
 | cmdb-assistant | NetBox | Infrastructure CMDB |
 | data-platform | pandas, PostgreSQL, dbt | DataFrames, database queries, dbt builds |
 | viz-platform | viz-platform | DMC validation, charts, layouts, themes, pages |
+| contract-validator | contract-validator | Plugin interface parsing, compatibility validation |
 
 Ensure credentials are configured in `~/.config/claude/gitea.env`, `~/.config/claude/netbox.env`, or `~/.config/claude/postgres.env`.
 
 ---
 
-*Last Updated: 2026-01-26*
+*Last Updated: 2026-01-28*

docs/CONFIGURATION.md

@@ -171,8 +171,7 @@ This marketplace uses a **hybrid configuration** approach:
 │                  PROJECT-LEVEL (once per project)              │
 │                  <project-root>/.env                            │
 ├─────────────────────────────────────────────────────────────────┤
-│  GITEA_ORG               │  Organization for this project      │
-│  GITEA_REPO              │  Repository name for this project   │
+│  GITEA_REPO              │  Repository as owner/repo format    │
 │  GIT_WORKFLOW_STYLE      │  (optional) Override system default │
 │  PR_REVIEW_*             │  (optional) PR review settings      │
 └─────────────────────────────────────────────────────────────────┘
@@ -262,8 +261,7 @@ In each project root:
 
 ```bash
 cat > .env << 'EOF'
-GITEA_ORG=your-organization
-GITEA_REPO=your-repo-name
+GITEA_REPO=your-organization/your-repo-name
 EOF
 ```
 
@@ -307,7 +305,7 @@ GITEA_API_TOKEN=your_gitea_token_here
 | `GITEA_API_URL` | Gitea API endpoint (with `/api/v1`) | `https://gitea.example.com/api/v1` |
 | `GITEA_API_TOKEN` | Personal access token | `abc123...` |
 
-**Note:** `GITEA_ORG` is configured at the project level (see below) since different projects may belong to different organizations.
+**Note:** `GITEA_REPO` is configured at the project level in `owner/repo` format since different projects may belong to different organizations.
 
 **Generating a Gitea Token:**
 1. Log into Gitea → **User Icon** → **Settings**
@@ -362,9 +360,8 @@ GIT_CO_AUTHOR=true
 Create `.env` in each project root:
 
 ```bash
-# Required for projman, pr-review
-GITEA_ORG=your-organization
-GITEA_REPO=your-repo-name
+# Required for projman, pr-review (use owner/repo format)
+GITEA_REPO=your-organization/your-repo-name
 
 # Optional: Override git-flow defaults
 GIT_WORKFLOW_STYLE=pr-required
@@ -377,8 +374,7 @@ PR_REVIEW_AUTO_SUBMIT=false
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `GITEA_ORG` | Yes | Gitea organization for this project |
-| `GITEA_REPO` | Yes | Repository name (must match Gitea exactly) |
+| `GITEA_REPO` | Yes | Repository in `owner/repo` format (e.g., `my-org/my-repo`) |
 | `GIT_WORKFLOW_STYLE` | No | Override system default |
 | `PR_REVIEW_*` | No | PR review settings |
 
@@ -388,8 +384,8 @@ PR_REVIEW_AUTO_SUBMIT=false
 
 | Plugin | System Config | Project Config | Setup Commands |
 |--------|---------------|----------------|----------------|
-| **projman** | gitea.env | .env (GITEA_ORG, GITEA_REPO) | `/initial-setup`, `/project-init`, `/project-sync` |
-| **pr-review** | gitea.env | .env (GITEA_ORG, GITEA_REPO) | `/initial-setup`, `/project-init`, `/project-sync` |
+| **projman** | gitea.env | .env (GITEA_REPO=owner/repo) | `/initial-setup`, `/project-init`, `/project-sync` |
+| **pr-review** | gitea.env | .env (GITEA_REPO=owner/repo) | `/initial-setup`, `/project-init`, `/project-sync` |
 | **git-flow** | git-flow.env (optional) | .env (optional) | None needed |
 | **clarity-assist** | None | None | None needed |
 | **cmdb-assistant** | netbox.env | None | `/initial-setup` |
@@ -441,7 +437,7 @@ This catches typos and permission issues before saving configuration.
 
 When you start a Claude Code session, a hook automatically:
 
-1. Reads `GITEA_ORG` and `GITEA_REPO` from `.env`
+1. Reads `GITEA_REPO` (in `owner/repo` format) from `.env`
 2. Compares with current `git remote get-url origin`
 3. **Warns** if mismatch detected: "Repository location mismatch. Run `/project-sync` to update."
 
@@ -520,11 +516,62 @@ deactivate
 # Check project .env
 cat .env
 
-# Verify GITEA_REPO matches the Gitea repository name exactly
+# Verify GITEA_REPO is in owner/repo format and matches Gitea exactly
+# Example: GITEA_REPO=my-org/my-repo
 ```
 
 ---
 
+## Agent Model Configuration
+
+Agents can specify which Claude model to use for optimal cost/performance.
+
+### Model Options
+
+| Model | Use For | Cost |
+|-------|---------|------|
+| `opus` | Complex reasoning, security analysis | Highest |
+| `sonnet` | Implementation, coordination (default) | Medium |
+| `haiku` | Simple validation, quick checks | Lowest |
+
+### Configuration Levels
+
+**1. Agent-Level (highest priority)**
+
+Add to agent frontmatter in `agents/*.md`:
+
+```yaml
+---
+name: planner
+description: Sprint planning agent
+model: opus
+---
+```
+
+**2. Plugin-Level (fallback)**
+
+Add to `plugin.json`:
+
+```json
+{
+  "defaultModel": "sonnet"
+}
+```
+
+**3. System Default**
+
+If neither is specified, agents use `sonnet`.
+
+### Inheritance Chain
+
+```
+Agent model → Plugin defaultModel → System default (sonnet)
+```
+
+See [Model Recommendations](MODEL-RECOMMENDATIONS.md) for detailed guidance on model selection by task type.
+
+---
+
 ## Security Best Practices
 
 1. **Never commit tokens**

docs/DEBUGGING-CHECKLIST.md

@@ -2,7 +2,7 @@
 
 **Purpose:** Systematic approach to diagnose and fix plugin loading issues.
 
-Last Updated: 2026-01-22
+Last Updated: 2026-01-28
 
 ---
 
@@ -128,7 +128,7 @@ cat ~/.config/claude/netbox.env
 
 # Project-level config (in target project)
 cat /path/to/project/.env
-# Should contain: GITEA_ORG, GITEA_REPO
+# Should contain: GITEA_REPO=owner/repo (e.g., my-org/my-repo)
 ```
 
 ---
@@ -186,6 +186,47 @@ echo -e "\n=== Config Files ==="
 | Wrong path edits | Changes don't take effect | Edit installed path or reinstall after source changes |
 | Missing credentials | MCP connection errors | Create `~/.config/claude/gitea.env` with API credentials |
 | Invalid hook events | Hooks don't fire | Use only valid event names (see Step 7) |
+| Gitea issues not closing | Merged to non-default branch | Manually close issues (see below) |
+| MCP changes not taking effect | Session caching | Restart Claude Code session (see below) |
+
+### Gitea Auto-Close Behavior
+
+**Issue:** Using `Closes #XX` or `Fixes #XX` in commit/PR messages does NOT auto-close issues when merging to `development`.
+
+**Root Cause:** Gitea only auto-closes issues when merging to the **default branch** (typically `main` or `master`). Merging to `development`, `staging`, or any other branch will NOT trigger auto-close.
+
+**Workaround:**
+1. Use the Gitea MCP tool to manually close issues after merging to development:
+   ```
+   mcp__plugin_projman_gitea__update_issue(issue_number=XX, state="closed")
+   ```
+2. Or close issues via the Gitea web UI
+3. The auto-close keywords will still work when the changes are eventually merged to `main`
+
+**Recommendation:** Include the `Closes #XX` keywords in commits anyway - they'll work when the final merge to `main` happens.
+
+### MCP Session Restart Requirement
+
+**Issue:** Changes to MCP servers, hooks, or plugin configuration don't take effect immediately.
+
+**Root Cause:** Claude Code loads MCP tools and plugin configuration at session start. These are cached in session memory and not reloaded dynamically.
+
+**What requires a session restart:**
+- MCP server code changes (Python files in `mcp-servers/`)
+- Changes to `.mcp.json` files
+- Changes to `hooks/hooks.json`
+- Changes to `plugin.json`
+- Adding new MCP tools or modifying tool signatures
+
+**What does NOT require a restart:**
+- Command/skill markdown files (`.md`) - these are read on invocation
+- Agent markdown files - read when agent is invoked
+
+**Correct workflow after plugin changes:**
+1. Make changes to source files
+2. Run `./scripts/verify-hooks.sh` to validate
+3. Inform user: "Please restart Claude Code for changes to take effect"
+4. **Do NOT clear cache mid-session** - see "Cache Clearing" section
 
 ---
 

docs/MODEL-RECOMMENDATIONS.md

@@ -0,0 +1,149 @@
+# Model Recommendations
+
+Guidelines for selecting Claude models (opus, sonnet, haiku) for plugin agents.
+
+---
+
+## Model Overview
+
+| Model | Best For | Cost | Speed |
+|-------|----------|------|-------|
+| **Opus** | Complex reasoning, architecture decisions, security analysis | Highest | Slower |
+| **Sonnet** | Implementation, coordination, standard tasks | Medium | Balanced |
+| **Haiku** | Simple validation, quick checks, status queries | Lowest | Fastest |
+
+---
+
+## Task-Type Recommendations
+
+| Task Type | Model | Rationale |
+|-----------|-------|-----------|
+| Architecture decisions | Opus | Requires deep reasoning, trade-off analysis |
+| Security analysis | Opus | Critical thinking, vulnerability pattern recognition |
+| Code review (quality) | Opus | Thorough analysis, edge case detection |
+| Sprint planning | Opus | Strategic thinking, dependency analysis |
+| Complex data analysis | Opus | Multi-step reasoning, insight generation |
+| Code implementation | Sonnet | Fast, capable code generation |
+| Coordination/dispatch | Sonnet | Task management, status tracking |
+| Data transformation | Sonnet | ETL operations, query building |
+| Documentation | Sonnet | Clear writing, structure |
+| Simple validation | Haiku | Fast prop checks, schema validation |
+| Status checks | Haiku | Quick queries, cost-effective |
+| Quick verification | Haiku | Simple pass/fail checks |
+
+---
+
+## Agent Model Assignments
+
+### projman (Sprint Management)
+
+| Agent | Model | Rationale |
+|-------|-------|-----------|
+| `planner` | opus | Architecture decisions, issue structuring |
+| `orchestrator` | sonnet | Coordination, parallel execution |
+| `executor` | sonnet | Code implementation |
+| `code-reviewer` | opus | Quality review, security analysis |
+
+### pr-review (PR Analysis)
+
+| Agent | Model | Rationale |
+|-------|-------|-----------|
+| `coordinator` | sonnet | Task dispatch, result aggregation |
+| `security-reviewer` | opus | Security vulnerability detection |
+| `performance-analyst` | sonnet | Pattern recognition |
+| `maintainability-auditor` | sonnet | Code quality checks |
+| `test-validator` | sonnet | Test coverage analysis |
+
+### code-sentinel (Security & Refactoring)
+
+| Agent | Model | Rationale |
+|-------|-------|-----------|
+| `security-reviewer` | opus | Security scanning |
+| `refactor-advisor` | sonnet | Refactoring suggestions |
+
+### data-platform (Data Engineering)
+
+| Agent | Model | Rationale |
+|-------|-------|-----------|
+| `data-analysis` | opus | Complex data insights |
+| `data-ingestion` | sonnet | ETL operations |
+
+### viz-platform (Visualization)
+
+| Agent | Model | Rationale |
+|-------|-------|-----------|
+| `component-check` | haiku | Simple prop validation |
+| `layout-builder` | sonnet | UI construction |
+| `theme-setup` | sonnet | Design configuration |
+
+### contract-validator (Compatibility)
+
+| Agent | Model | Rationale |
+|-------|-------|-----------|
+| `full-validation` | sonnet | Contract checking |
+| `agent-check` | haiku | Quick verification |
+
+---
+
+## Configuration Schema
+
+### Agent-Level (Frontmatter)
+
+Add `model` field to agent YAML frontmatter:
+
+```yaml
+---
+name: planner
+description: Sprint planning agent
+model: opus
+---
+```
+
+**Valid values:** `opus`, `sonnet`, `haiku`
+
+### Plugin-Level (plugin.json)
+
+Add `defaultModel` for plugin-wide fallback:
+
+```json
+{
+  "name": "projman",
+  "version": "3.4.0",
+  "defaultModel": "sonnet"
+}
+```
+
+---
+
+## Inheritance Chain
+
+Model selection follows this precedence:
+
+```
+1. Agent model field (highest priority)
+      ↓ if not specified
+2. Plugin defaultModel (plugin.json)
+      ↓ if not specified
+3. System default: sonnet
+```
+
+**Example:**
+- Agent has `model: opus` → Uses opus
+- Agent has no model, plugin has `defaultModel: sonnet` → Uses sonnet
+- Neither specified → Uses sonnet (system default)
+
+---
+
+## Cost Optimization Tips
+
+1. **Default to Sonnet** - Good balance for most tasks
+2. **Reserve Opus** for critical decisions (security, architecture)
+3. **Use Haiku** for validation and quick checks
+4. **Batch simple tasks** - Use haiku for parallel validation
+
+---
+
+## See Also
+
+- [Configuration Guide](CONFIGURATION.md) - Full configuration reference
+- [Plugin Development](../README.md) - Adding new plugins

mcp-servers/contract-validator/run.sh

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

mcp-servers/data-platform/run.sh

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

mcp-servers/gitea/mcp_server/gitea_client.py

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

mcp-servers/gitea/mcp_server/server.py

@@ -26,6 +26,44 @@ logging.getLogger("mcp").setLevel(logging.ERROR)
 logger = logging.getLogger(__name__)
 
 
+def _coerce_types(arguments: dict) -> dict:
+    """
+    Coerce argument types to handle MCP serialization quirks.
+
+    MCP sometimes passes integers as strings and arrays as JSON strings.
+    This function normalizes them to the expected Python types.
+    """
+    coerced = {}
+    for key, value in arguments.items():
+        if value is None:
+            coerced[key] = value
+            continue
+
+        # Coerce integer fields
+        int_fields = {'issue_number', 'milestone_id', 'pr_number', 'depends_on', 'milestone', 'limit'}
+        if key in int_fields and isinstance(value, str):
+            try:
+                coerced[key] = int(value)
+                continue
+            except ValueError:
+                pass
+
+        # Coerce array fields that might be JSON strings
+        array_fields = {'labels', 'tags', 'issue_numbers', 'comments'}
+        if key in array_fields and isinstance(value, str):
+            try:
+                parsed = json.loads(value)
+                if isinstance(parsed, list):
+                    coerced[key] = parsed
+                    continue
+            except json.JSONDecodeError:
+                pass
+
+        coerced[key] = value
+
+    return coerced
+
+
 class GiteaMCPServer:
     """MCP Server for Gitea integration"""
 
@@ -88,6 +126,10 @@ class GiteaMCPServer:
                                 "items": {"type": "string"},
                                 "description": "Filter by labels"
                             },
+                            "milestone": {
+                                "type": "string",
+                                "description": "Filter by milestone title (exact match)"
+                            },
                             "repo": {
                                 "type": "string",
                                 "description": "Repository name (for PMO mode)"
@@ -168,6 +210,10 @@ class GiteaMCPServer:
                                 "items": {"type": "string"},
                                 "description": "New labels"
                             },
+                            "milestone": {
+                                "type": "integer",
+                                "description": "Milestone ID to assign"
+                            },
                             "repo": {
                                 "type": "string",
                                 "description": "Repository name (for PMO mode)"
@@ -895,6 +941,9 @@ class GiteaMCPServer:
                 List of TextContent with results
             """
             try:
+                # Coerce types to handle MCP serialization quirks
+                arguments = _coerce_types(arguments)
+
                 # Route to appropriate tool handler
                 if name == "list_issues":
                     result = await self.issue_tools.list_issues(**arguments)

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

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

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

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

mcp-servers/gitea/run.sh

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

mcp-servers/netbox/run.sh

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

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

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

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

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

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

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

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

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

mcp-servers/viz-platform/requirements.txt

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

mcp-servers/viz-platform/run.sh

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

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

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

plugins/clarity-assist/README.md

@@ -90,6 +90,10 @@ After clarification, you receive a structured specification:
 [List of assumptions]
 ```
 
+## Documentation
+
+- [Neurodivergent Support Guide](docs/ND-SUPPORT.md) - How clarity-assist supports ND users with executive function challenges and cognitive differences
+
 ## Integration
 
 For CLAUDE.md integration instructions, see `claude-md-integration.md`.

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

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

plugins/clarity-assist/commands/clarify.md

@@ -1,5 +1,17 @@
 # /clarify - Full Prompt Optimization
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  💬 CLARITY-ASSIST · Prompt Optimization                         │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the workflow.
+
 ## Purpose
 
 Transform vague, incomplete, or ambiguous requests into clear, actionable specifications using the 4-D methodology with neurodivergent-friendly accommodations.

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

@@ -1,5 +1,17 @@
 # /quick-clarify - Rapid Clarification Mode
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  💬 CLARITY-ASSIST · Quick Clarify                               │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the workflow.
+
 ## Purpose
 
 Single-pass clarification for requests that are mostly clear but need minor disambiguation.

plugins/clarity-assist/docs/ND-SUPPORT.md

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

plugins/clarity-assist/hooks/hooks.json

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

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

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

plugins/claude-config-maintainer/README.md

@@ -37,6 +37,33 @@ Create a new CLAUDE.md tailored to your project.
 /config-init
 ```
 
+### `/config-diff`
+Show differences between current CLAUDE.md and previous versions.
+
+```
+/config-diff                    # Compare working copy vs last commit
+/config-diff --commit=abc1234   # Compare against specific commit
+/config-diff --from=v1.0 --to=v2.0  # Compare two commits
+/config-diff --section="Critical Rules"  # Focus on specific section
+```
+
+### `/config-lint`
+Lint CLAUDE.md for common anti-patterns and best practices.
+
+```
+/config-lint                    # Run all lint checks
+/config-lint --fix              # Auto-fix fixable issues
+/config-lint --rules=security   # Check only security rules
+/config-lint --severity=error   # Show only errors
+```
+
+**Lint Rule Categories:**
+- **Security (SEC)** - Hardcoded secrets, paths, credentials
+- **Structure (STR)** - Header hierarchy, required sections
+- **Content (CNT)** - Contradictions, duplicates, vague rules
+- **Format (FMT)** - Consistency, code blocks, whitespace
+- **Best Practice (BPR)** - Missing Quick Start, Critical Rules sections
+
 ## Best Practices
 
 A good CLAUDE.md should be:

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

@@ -7,6 +7,16 @@ description: CLAUDE.md optimization and maintenance agent
 
 You are the **Maintainer Agent** - a specialist in creating and optimizing CLAUDE.md configuration files for Claude Code projects. Your role is to ensure CLAUDE.md files are clear, concise, well-structured, and follow best practices.
 
+## Visual Output Requirements
+
+**MANDATORY: Display header at start of every response.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ⚙️ CONFIG-MAINTAINER · CLAUDE.md Optimization                   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
 ## Your Personality
 
 **Optimization-Focused:**

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

@@ -6,6 +6,18 @@ description: Analyze CLAUDE.md for optimization opportunities and plugin integra
 
 This command analyzes your project's CLAUDE.md file and provides a detailed report on optimization opportunities and plugin integration status.
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ⚙️ CONFIG-MAINTAINER · CLAUDE.md Analysis                       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the analysis.
+
 ## What This Command Does
 
 1. **Read CLAUDE.md** - Locates and reads the project's CLAUDE.md file

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

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

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

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

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

@@ -6,6 +6,18 @@ description: Initialize a new CLAUDE.md file for a project
 
 This command creates a new CLAUDE.md file tailored to your project, gathering context and generating appropriate content.
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ⚙️ CONFIG-MAINTAINER · CLAUDE.md Initialization                 │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the initialization.
+
 ## What This Command Does
 
 1. **Gather Context** - Analyzes project structure and asks clarifying questions

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

@@ -6,6 +6,18 @@ description: Optimize CLAUDE.md structure and content
 
 This command automatically optimizes your project's CLAUDE.md file based on best practices and identified issues.
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ⚙️ CONFIG-MAINTAINER · CLAUDE.md Optimization                   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the optimization.
+
 ## What This Command Does
 
 1. **Analyze Current File** - Identifies all optimization opportunities

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

@@ -1,6 +1,6 @@
 {
   "name": "cmdb-assistant",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "NetBox CMDB integration with data quality validation - query, create, update, and manage network devices, IP addresses, sites, and more with best practices enforcement",
   "author": {
     "name": "Leo Miranda",

plugins/cmdb-assistant/README.md

@@ -2,6 +2,12 @@
 
 A Claude Code plugin for NetBox CMDB integration - query, create, update, and manage your network infrastructure directly from Claude Code.
 
+## What's New in v1.2.0
+
+- **`/cmdb-topology`**: Generate Mermaid diagrams showing infrastructure topology (rack view, network view, site overview)
+- **`/change-audit`**: Query and analyze NetBox audit log for change tracking and compliance
+- **`/ip-conflicts`**: Detect IP address conflicts and overlapping prefixes
+
 ## What's New in v1.1.0
 
 - **Data Quality Validation**: Hooks for SessionStart and PreToolUse that check data quality and warn about missing fields
@@ -59,6 +65,9 @@ Add to your Claude Code plugins or marketplace configuration.
 | `/cmdb-audit [scope]` | Data quality analysis (all, vms, devices, naming, roles) |
 | `/cmdb-register` | Register current machine into NetBox with running apps |
 | `/cmdb-sync` | Sync machine state with NetBox (detect drift, update) |
+| `/cmdb-topology <view>` | Generate Mermaid diagrams (rack, network, site, full) |
+| `/change-audit [filters]` | Query NetBox audit log for change tracking |
+| `/ip-conflicts [scope]` | Detect IP conflicts and overlapping prefixes |
 
 ## Agent
 
@@ -140,9 +149,12 @@ cmdb-assistant/
 │   ├── cmdb-device.md       # Device management
 │   ├── cmdb-ip.md           # IP management
 │   ├── cmdb-site.md         # Site management
-│   ├── cmdb-audit.md        # Data quality audit (NEW)
-│   ├── cmdb-register.md     # Machine registration (NEW)
-│   └── cmdb-sync.md         # Machine sync (NEW)
+│   ├── cmdb-audit.md        # Data quality audit
+│   ├── cmdb-register.md     # Machine registration
+│   ├── cmdb-sync.md         # Machine sync
+│   ├── cmdb-topology.md     # Topology visualization (NEW)
+│   ├── change-audit.md      # Change audit log (NEW)
+│   └── ip-conflicts.md      # IP conflict detection (NEW)
 ├── hooks/
 │   ├── hooks.json           # Hook configuration
 │   ├── startup-check.sh     # SessionStart validation

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

@@ -2,6 +2,16 @@
 
 You are an infrastructure management assistant specialized in NetBox CMDB operations. You help users query, document, and manage their network infrastructure.
 
+## Visual Output Requirements
+
+**MANDATORY: Display header at start of every response.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Infrastructure Management                   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
 ## Capabilities
 
 You have full access to NetBox via MCP tools covering:

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

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

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

@@ -4,6 +4,18 @@ description: Audit NetBox data quality and identify consistency issues
 
 # CMDB Data Quality Audit
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Data Quality Audit                          │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the audit.
+
 Analyze NetBox data for quality issues and best practice violations.
 
 ## Usage

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

@@ -1,5 +1,17 @@
 # CMDB Device Management
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Device Management                           │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the operation.
+
 Manage network devices in NetBox - create, view, update, or delete.
 
 ## Usage

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

@@ -1,5 +1,17 @@
 # CMDB IP Management
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · IP Management                               │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the operation.
+
 Manage IP addresses and prefixes in NetBox.
 
 ## Usage

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

@@ -4,6 +4,18 @@ description: Register the current machine into NetBox with all running applicati
 
 # CMDB Machine Registration
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Machine Registration                        │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the registration.
+
 Register the current machine into NetBox, including hardware info, network interfaces, and running applications (Docker containers, services).
 
 ## Usage

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

@@ -1,5 +1,17 @@
 # CMDB Search
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Search                                      │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the search.
+
 Search NetBox for devices, IPs, sites, or any CMDB object.
 
 ## Usage

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

@@ -1,5 +1,17 @@
 # CMDB Site Management
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Site Management                             │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the operation.
+
 Manage sites and locations in NetBox.
 
 ## Usage

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

@@ -4,6 +4,18 @@ description: Synchronize current machine state with existing NetBox record
 
 # CMDB Machine Sync
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Machine Sync                                │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the synchronization.
+
 Update an existing NetBox device record with the current machine state. Compares local system information with NetBox and applies changes.
 
 ## Usage

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

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

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

@@ -4,6 +4,18 @@ description: Interactive setup wizard for cmdb-assistant plugin - configures Net
 
 # CMDB Assistant Setup Wizard
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🖥️ CMDB-ASSISTANT · Setup Wizard                                │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the setup.
+
 This command sets up the cmdb-assistant plugin with NetBox integration.
 
 ## Important Context

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

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

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

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

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

@@ -6,6 +6,16 @@ description: Code structure and refactoring specialist
 
 You are a software architect specializing in code quality, design patterns, and refactoring.
 
+## Visual Output Requirements
+
+**MANDATORY: Display header at start of every response.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🔒 CODE-SENTINEL · Refactor Advisory                            │
+└──────────────────────────────────────────────────────────────────┘
+```
+
 ## Expertise
 
 - Martin Fowler's refactoring catalog

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

@@ -1,11 +1,23 @@
 ---
+name: security-reviewer
 description: Security-focused code review agent
+model: opus
 ---
 
 # Security Reviewer Agent
 
 You are a security engineer specializing in application security and secure coding practices.
 
+## Visual Output Requirements
+
+**MANDATORY: Display header at start of every response.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🔒 CODE-SENTINEL · Security Review                              │
+└──────────────────────────────────────────────────────────────────┘
+```
+
 ## Expertise
 
 - OWASP Top 10 vulnerabilities

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

@@ -6,6 +6,18 @@ description: Preview refactoring changes without applying them
 
 Analyze and preview refactoring opportunities without making changes.
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🔒 CODE-SENTINEL · Refactor Preview                             │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the analysis.
+
 ## Usage
 ```
 /refactor-dry <target> [--all]

plugins/code-sentinel/commands/refactor.md

@@ -6,6 +6,18 @@ description: Apply refactoring patterns to improve code structure and maintainab
 
 Apply refactoring transformations to specified code.
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🔒 CODE-SENTINEL · Refactor                                     │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the refactoring workflow.
+
 ## Usage
 ```
 /refactor <target> [--pattern=<pattern>]

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

@@ -6,6 +6,18 @@ description: Full security audit of codebase - scans all files for vulnerability
 
 Comprehensive security audit of the project.
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🔒 CODE-SENTINEL · Security Scan                                │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the scan workflow.
+
 ## Process
 
 1. **File Discovery**

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

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

plugins/contract-validator/README.md

@@ -19,6 +19,7 @@ Contract-validator solves these by parsing plugin interfaces and validating comp
 - **Agent Extraction**: Parse CLAUDE.md Four-Agent Model tables and Agents sections
 - **Compatibility Checks**: Pairwise validation between all plugins in a marketplace
 - **Data Flow Validation**: Verify agent tool sequences have valid data producers/consumers
+- **Dependency Visualization**: Generate Mermaid flowcharts showing plugin relationships
 - **Comprehensive Reports**: Markdown or JSON reports with actionable suggestions
 
 ## Installation
@@ -44,6 +45,7 @@ pip install -r requirements.txt
 | `/validate-contracts` | Full marketplace compatibility validation |
 | `/check-agent` | Validate single agent definition |
 | `/list-interfaces` | Show all plugin interfaces |
+| `/dependency-graph` | Generate Mermaid flowchart of plugin dependencies |
 
 ## Agents
 
@@ -106,6 +108,16 @@ pip install -r requirements.txt
 # Data Flow: No issues detected
 ```
 
+```
+/dependency-graph
+
+# Output: Mermaid flowchart showing:
+# - Plugins grouped by shared MCP servers
+# - Data flow from data-platform to viz-platform
+# - Required vs optional dependencies
+# - Command counts per plugin
+```
+
 ## Issue Types
 
 | Type | Severity | Description |

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

@@ -1,7 +1,23 @@
+---
+name: agent-check
+description: Agent definition validator for quick verification
+model: haiku
+---
+
 # Agent Check Agent
 
 You are an agent definition validator. Your role is to verify that a specific agent's tool references and data flow are valid.
 
+## Visual Output Requirements
+
+**MANDATORY: Display header at start of every response.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ✅ CONTRACT-VALIDATOR · Agent Validation                        │
+└──────────────────────────────────────────────────────────────────┘
+```
+
 ## Capabilities
 
 - Parse agent definitions from CLAUDE.md

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

@@ -2,6 +2,16 @@
 
 You are a contract validation specialist. Your role is to perform comprehensive cross-plugin compatibility validation for the entire marketplace.
 
+## Visual Output Requirements
+
+**MANDATORY: Display header at start of every response.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ✅ CONTRACT-VALIDATOR · Full Validation                         │
+└──────────────────────────────────────────────────────────────────┘
+```
+
 ## Capabilities
 
 - Parse plugin interfaces from README.md files

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

@@ -1,5 +1,17 @@
 # /check-agent - Validate Agent Definition
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ✅ CONTRACT-VALIDATOR · Agent Check                              │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the validation.
+
 Validate a single agent's tool references and data flow.
 
 ## Usage

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

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

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

@@ -4,6 +4,18 @@ description: Interactive setup wizard for contract-validator plugin - verifies M
 
 # Contract-Validator Setup Wizard
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ✅ CONTRACT-VALIDATOR · Setup Wizard                             │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the setup.
+
 This command sets up the contract-validator plugin for cross-plugin compatibility validation.
 
 ## Important Context

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

@@ -1,5 +1,17 @@
 # /list-interfaces - Show Plugin Interfaces
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ✅ CONTRACT-VALIDATOR · List Interfaces                         │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the interface listing.
+
 Display what each plugin in the marketplace produces and accepts.
 
 ## Usage

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

@@ -1,5 +1,17 @@
 # /validate-contracts - Full Contract Validation
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  ✅ CONTRACT-VALIDATOR · Full Validation                         │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the validation.
+
 Run comprehensive cross-plugin compatibility validation for the entire marketplace.
 
 ## Usage

plugins/contract-validator/hooks/auto-validate.sh

@@ -0,0 +1,195 @@
+#!/bin/bash
+# contract-validator SessionStart auto-validate hook
+# Validates plugin contracts only when plugin files have changed since last check
+# All output MUST have [contract-validator] prefix
+
+PREFIX="[contract-validator]"
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+# Enable/disable auto-check (default: true)
+AUTO_CHECK="${CONTRACT_VALIDATOR_AUTO_CHECK:-true}"
+
+# Cache location for storing last check hash
+CACHE_DIR="$HOME/.cache/claude-plugins/contract-validator"
+HASH_FILE="$CACHE_DIR/last-check.hash"
+
+# Marketplace location (installed plugins)
+MARKETPLACE_PATH="$HOME/.claude/plugins/marketplaces/leo-claude-mktplace"
+
+# ============================================================================
+# Early exit if disabled
+# ============================================================================
+
+if [[ "$AUTO_CHECK" != "true" ]]; then
+    exit 0
+fi
+
+# ============================================================================
+# Smart mode: Check if plugin files have changed
+# ============================================================================
+
+# Function to compute hash of all plugin manifest files
+compute_plugin_hash() {
+    local hash_input=""
+
+    if [[ -d "$MARKETPLACE_PATH/plugins" ]]; then
+        # Hash all plugin.json, hooks.json, and agent files
+        while IFS= read -r -d '' file; do
+            if [[ -f "$file" ]]; then
+                hash_input+="$(md5sum "$file" 2>/dev/null | cut -d' ' -f1)"
+            fi
+        done < <(find "$MARKETPLACE_PATH/plugins" \
+            \( -name "plugin.json" -o -name "hooks.json" -o -name "*.md" -path "*/agents/*" \) \
+            -print0 2>/dev/null | sort -z)
+    fi
+
+    # Also include marketplace.json
+    if [[ -f "$MARKETPLACE_PATH/.claude-plugin/marketplace.json" ]]; then
+        hash_input+="$(md5sum "$MARKETPLACE_PATH/.claude-plugin/marketplace.json" 2>/dev/null | cut -d' ' -f1)"
+    fi
+
+    # Compute final hash
+    echo "$hash_input" | md5sum | cut -d' ' -f1
+}
+
+# Ensure cache directory exists
+mkdir -p "$CACHE_DIR" 2>/dev/null
+
+# Compute current hash
+CURRENT_HASH=$(compute_plugin_hash)
+
+# Check if we have a previous hash
+if [[ -f "$HASH_FILE" ]]; then
+    PREVIOUS_HASH=$(cat "$HASH_FILE" 2>/dev/null)
+
+    # If hashes match, no changes - skip validation
+    if [[ "$CURRENT_HASH" == "$PREVIOUS_HASH" ]]; then
+        exit 0
+    fi
+fi
+
+# ============================================================================
+# Run validation (hashes differ or no cache)
+# ============================================================================
+
+ISSUES_FOUND=0
+WARNINGS=""
+
+# Function to add warning
+add_warning() {
+    WARNINGS+="  - $1"$'\n'
+    ((ISSUES_FOUND++))
+}
+
+# 1. Check all installed plugins have valid plugin.json
+if [[ -d "$MARKETPLACE_PATH/plugins" ]]; then
+    for plugin_dir in "$MARKETPLACE_PATH/plugins"/*/; do
+        if [[ -d "$plugin_dir" ]]; then
+            plugin_name=$(basename "$plugin_dir")
+            plugin_json="$plugin_dir/.claude-plugin/plugin.json"
+
+            if [[ ! -f "$plugin_json" ]]; then
+                add_warning "$plugin_name: missing .claude-plugin/plugin.json"
+                continue
+            fi
+
+            # Basic JSON validation
+            if ! python3 -c "import json; json.load(open('$plugin_json'))" 2>/dev/null; then
+                add_warning "$plugin_name: invalid JSON in plugin.json"
+                continue
+            fi
+
+            # Check required fields
+            if ! python3 -c "
+import json
+with open('$plugin_json') as f:
+    data = json.load(f)
+required = ['name', 'version', 'description']
+missing = [r for r in required if r not in data]
+if missing:
+    exit(1)
+" 2>/dev/null; then
+                add_warning "$plugin_name: plugin.json missing required fields"
+            fi
+        fi
+    done
+fi
+
+# 2. Check hooks.json files are properly formatted
+if [[ -d "$MARKETPLACE_PATH/plugins" ]]; then
+    while IFS= read -r -d '' hooks_file; do
+        plugin_name=$(basename "$(dirname "$(dirname "$hooks_file")")")
+
+        # Validate JSON
+        if ! python3 -c "import json; json.load(open('$hooks_file'))" 2>/dev/null; then
+            add_warning "$plugin_name: invalid JSON in hooks/hooks.json"
+            continue
+        fi
+
+        # Validate hook structure
+        if ! python3 -c "
+import json
+with open('$hooks_file') as f:
+    data = json.load(f)
+if 'hooks' not in data:
+    exit(1)
+valid_events = ['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'SessionStart', 'SessionEnd', 'Notification', 'Stop', 'SubagentStop', 'PreCompact']
+for event in data['hooks']:
+    if event not in valid_events:
+        exit(1)
+    for hook in data['hooks'][event]:
+        # Support both flat structure (type at top) and nested structure (matcher + hooks array)
+        if 'type' in hook:
+            # Flat structure: {type: 'command', command: '...'}
+            pass
+        elif 'matcher' in hook and 'hooks' in hook:
+            # Nested structure: {matcher: '...', hooks: [{type: 'command', ...}]}
+            for nested_hook in hook['hooks']:
+                if 'type' not in nested_hook:
+                    exit(1)
+        else:
+            exit(1)
+" 2>/dev/null; then
+            add_warning "$plugin_name: hooks.json has invalid structure or events"
+        fi
+    done < <(find "$MARKETPLACE_PATH/plugins" -path "*/hooks/hooks.json" -print0 2>/dev/null)
+fi
+
+# 3. Check agent references are valid (agent files exist and are markdown)
+if [[ -d "$MARKETPLACE_PATH/plugins" ]]; then
+    while IFS= read -r -d '' agent_file; do
+        plugin_name=$(basename "$(dirname "$(dirname "$agent_file")")")
+        agent_name=$(basename "$agent_file")
+
+        # Check file is not empty
+        if [[ ! -s "$agent_file" ]]; then
+            add_warning "$plugin_name: empty agent file $agent_name"
+            continue
+        fi
+
+        # Check file has markdown content (at least a header)
+        if ! grep -q '^#' "$agent_file" 2>/dev/null; then
+            add_warning "$plugin_name: agent $agent_name missing markdown header"
+        fi
+    done < <(find "$MARKETPLACE_PATH/plugins" -path "*/agents/*.md" -print0 2>/dev/null)
+fi
+
+# ============================================================================
+# Store new hash and report results
+# ============================================================================
+
+# Always store the new hash (even if issues found - we don't want to recheck)
+echo "$CURRENT_HASH" > "$HASH_FILE"
+
+# Report any issues found (non-blocking warning)
+if [[ $ISSUES_FOUND -gt 0 ]]; then
+    echo "$PREFIX Plugin contract validation found $ISSUES_FOUND issue(s):"
+    echo "$WARNINGS"
+    echo "$PREFIX Run /validate-contracts for full details"
+fi
+
+# Always exit 0 (non-blocking)
+exit 0

plugins/contract-validator/hooks/breaking-change-check.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+# contract-validator breaking change detection hook
+# Warns when plugin interface changes might break consumers
+# This is a PostToolUse hook - non-blocking, warnings only
+
+PREFIX="[contract-validator]"
+
+# Check if warnings are enabled (default: true)
+if [[ "${CONTRACT_VALIDATOR_BREAKING_WARN:-true}" != "true" ]]; then
+    exit 0
+fi
+
+# Read tool input from stdin
+INPUT=$(cat)
+
+# Extract file_path from JSON input
+FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+
+# If no file_path found, exit silently
+if [ -z "$FILE_PATH" ]; then
+    exit 0
+fi
+
+# Check if file is a plugin interface file
+is_interface_file() {
+    local file="$1"
+
+    case "$file" in
+        */plugin.json) return 0 ;;
+        */.claude-plugin/plugin.json) return 0 ;;
+        */hooks.json) return 0 ;;
+        */hooks/hooks.json) return 0 ;;
+        */.mcp.json) return 0 ;;
+        */agents/*.md) return 0 ;;
+        */commands/*.md) return 0 ;;
+        */skills/*.md) return 0 ;;
+    esac
+
+    return 1
+}
+
+# Exit if not an interface file
+if ! is_interface_file "$FILE_PATH"; then
+    exit 0
+fi
+
+# Check if file exists and is in a git repo
+if [[ ! -f "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+# Get the directory containing the file
+FILE_DIR=$(dirname "$FILE_PATH")
+FILE_NAME=$(basename "$FILE_PATH")
+
+# Try to get the previous version from git
+cd "$FILE_DIR" 2>/dev/null || exit 0
+
+# Check if we're in a git repo
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    exit 0
+fi
+
+# Get previous version (HEAD version before current changes)
+PREV_CONTENT=$(git show HEAD:"$FILE_PATH" 2>/dev/null || echo "")
+
+# If no previous version, this is a new file - no breaking changes possible
+if [ -z "$PREV_CONTENT" ]; then
+    exit 0
+fi
+
+# Read current content
+CURR_CONTENT=$(cat "$FILE_PATH" 2>/dev/null || echo "")
+
+if [ -z "$CURR_CONTENT" ]; then
+    exit 0
+fi
+
+BREAKING_CHANGES=()
+
+# Detect breaking changes based on file type
+case "$FILE_PATH" in
+    */plugin.json|*/.claude-plugin/plugin.json)
+        # Check for removed or renamed fields in plugin.json
+
+        # Check if name changed
+        PREV_NAME=$(echo "$PREV_CONTENT" | grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1)
+        CURR_NAME=$(echo "$CURR_CONTENT" | grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1)
+        if [ -n "$PREV_NAME" ] && [ "$PREV_NAME" != "$CURR_NAME" ]; then
+            BREAKING_CHANGES+=("Plugin name changed - consumers may need updates")
+        fi
+
+        # Check if version had major bump (semantic versioning)
+        PREV_VER=$(echo "$PREV_CONTENT" | grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"\([0-9]*\)\..*/\1/')
+        CURR_VER=$(echo "$CURR_CONTENT" | grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"\([0-9]*\)\..*/\1/')
+        if [ -n "$PREV_VER" ] && [ -n "$CURR_VER" ] && [ "$CURR_VER" -gt "$PREV_VER" ] 2>/dev/null; then
+            BREAKING_CHANGES+=("Major version bump detected - verify breaking changes documented")
+        fi
+        ;;
+
+    */hooks.json|*/hooks/hooks.json)
+        # Check for removed hook events
+        PREV_EVENTS=$(echo "$PREV_CONTENT" | grep -oE '"(PreToolUse|PostToolUse|UserPromptSubmit|SessionStart|SessionEnd|Notification|Stop|SubagentStop|PreCompact)"' | sort -u)
+        CURR_EVENTS=$(echo "$CURR_CONTENT" | grep -oE '"(PreToolUse|PostToolUse|UserPromptSubmit|SessionStart|SessionEnd|Notification|Stop|SubagentStop|PreCompact)"' | sort -u)
+
+        # Find removed events
+        REMOVED_EVENTS=$(comm -23 <(echo "$PREV_EVENTS") <(echo "$CURR_EVENTS") 2>/dev/null)
+        if [ -n "$REMOVED_EVENTS" ]; then
+            BREAKING_CHANGES+=("Hook events removed: $(echo $REMOVED_EVENTS | tr '\n' ' ')")
+        fi
+
+        # Check for changed matchers
+        PREV_MATCHERS=$(echo "$PREV_CONTENT" | grep -o '"matcher"[[:space:]]*:[[:space:]]*"[^"]*"' | sort -u)
+        CURR_MATCHERS=$(echo "$CURR_CONTENT" | grep -o '"matcher"[[:space:]]*:[[:space:]]*"[^"]*"' | sort -u)
+        if [ "$PREV_MATCHERS" != "$CURR_MATCHERS" ]; then
+            BREAKING_CHANGES+=("Hook matchers changed - verify tool coverage")
+        fi
+        ;;
+
+    */.mcp.json)
+        # Check for removed MCP servers
+        PREV_SERVERS=$(echo "$PREV_CONTENT" | grep -o '"[^"]*"[[:space:]]*:' | grep -v "mcpServers" | sort -u)
+        CURR_SERVERS=$(echo "$CURR_CONTENT" | grep -o '"[^"]*"[[:space:]]*:' | grep -v "mcpServers" | sort -u)
+
+        REMOVED_SERVERS=$(comm -23 <(echo "$PREV_SERVERS") <(echo "$CURR_SERVERS") 2>/dev/null)
+        if [ -n "$REMOVED_SERVERS" ]; then
+            BREAKING_CHANGES+=("MCP servers removed - tools may be unavailable")
+        fi
+        ;;
+
+    */agents/*.md)
+        # Check if agent file was significantly reduced (might indicate removal of capabilities)
+        PREV_LINES=$(echo "$PREV_CONTENT" | wc -l)
+        CURR_LINES=$(echo "$CURR_CONTENT" | wc -l)
+
+        # If more than 50% reduction, warn
+        if [ "$PREV_LINES" -gt 10 ] && [ "$CURR_LINES" -lt $((PREV_LINES / 2)) ]; then
+            BREAKING_CHANGES+=("Agent definition significantly reduced - capabilities may be removed")
+        fi
+
+        # Check if agent name/description changed in frontmatter
+        PREV_DESC=$(echo "$PREV_CONTENT" | head -20 | grep -i "description" | head -1)
+        CURR_DESC=$(echo "$CURR_CONTENT" | head -20 | grep -i "description" | head -1)
+        if [ -n "$PREV_DESC" ] && [ "$PREV_DESC" != "$CURR_DESC" ]; then
+            BREAKING_CHANGES+=("Agent description changed - verify consumer expectations")
+        fi
+        ;;
+
+    */commands/*.md|*/skills/*.md)
+        # Check if command/skill was significantly changed
+        PREV_LINES=$(echo "$PREV_CONTENT" | wc -l)
+        CURR_LINES=$(echo "$CURR_CONTENT" | wc -l)
+
+        if [ "$PREV_LINES" -gt 10 ] && [ "$CURR_LINES" -lt $((PREV_LINES / 2)) ]; then
+            BREAKING_CHANGES+=("Command/skill significantly reduced - behavior may change")
+        fi
+        ;;
+esac
+
+# Output warnings if any breaking changes detected
+if [[ ${#BREAKING_CHANGES[@]} -gt 0 ]]; then
+    echo ""
+    echo "$PREFIX WARNING: Potential breaking changes in $(basename "$FILE_PATH")"
+    echo "$PREFIX ============================================"
+    for change in "${BREAKING_CHANGES[@]}"; do
+        echo "$PREFIX   - $change"
+    done
+    echo "$PREFIX ============================================"
+    echo "$PREFIX Consider updating CHANGELOG and notifying consumers"
+    echo ""
+fi
+
+# Always exit 0 - non-blocking
+exit 0

plugins/contract-validator/hooks/hooks.json

@@ -0,0 +1,21 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/auto-validate.sh"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/breaking-change-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -1,6 +1,7 @@
 {
   "name": "data-platform",
-  "version": "1.0.0",
+  "version": "1.1.0",
+  "defaultModel": "sonnet",
   "description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
   "author": {
     "name": "Leo Miranda",

plugins/data-platform/README.md

@@ -49,10 +49,13 @@ DBT_PROFILES_DIR=~/.dbt
 | `/initial-setup` | Interactive setup wizard for PostgreSQL and dbt configuration |
 | `/ingest` | Load data from files or database |
 | `/profile` | Generate data profile and statistics |
+| `/data-quality` | Data quality assessment with pass/warn/fail scoring |
 | `/schema` | Show database/DataFrame schema |
 | `/explain` | Explain dbt model lineage |
-| `/lineage` | Visualize data dependencies |
+| `/lineage` | Visualize data dependencies (ASCII) |
+| `/lineage-viz` | Generate Mermaid flowchart for dbt lineage |
 | `/run` | Execute dbt models |
+| `/dbt-test` | Run dbt tests with formatted results |
 
 ## Agents
 

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

@@ -1,7 +1,23 @@
+---
+name: data-analysis
+description: Data analysis specialist for exploration and profiling
+model: opus
+---
+
 # Data Analysis Agent
 
 You are a data analysis specialist. Your role is to help users explore, profile, and understand their data.
 
+## Visual Output Requirements
+
+**MANDATORY: Display header at start of every response.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📊 DATA-PLATFORM · Data Analysis                                │
+└──────────────────────────────────────────────────────────────────┘
+```
+
 ## Capabilities
 
 - Profile datasets with statistical summaries

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

@@ -2,6 +2,16 @@
 
 You are a data ingestion specialist. Your role is to help users load, transform, and prepare data for analysis.
 
+## Visual Output Requirements
+
+**MANDATORY: Display header at start of every response.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📊 DATA-PLATFORM · Data Ingestion                               │
+└──────────────────────────────────────────────────────────────────┘
+```
+
 ## Capabilities
 
 - Load data from CSV, Parquet, JSON files

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

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

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

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

plugins/data-platform/commands/explain.md

@@ -1,5 +1,17 @@
 # /explain - dbt Model Explanation
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📊 DATA-PLATFORM · Model Explanation                             │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the explanation.
+
 Explain a dbt model's purpose, dependencies, and SQL logic.
 
 ## Usage

plugins/data-platform/commands/ingest.md

@@ -1,5 +1,17 @@
 # /ingest - Data Ingestion
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📊 DATA-PLATFORM · Ingest                                        │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the ingestion.
+
 Load data from files or database into the data platform.
 
 ## Usage

plugins/data-platform/commands/initial-setup.md

@@ -4,6 +4,18 @@ description: Interactive setup wizard for data-platform plugin - configures MCP
 
 # Data Platform Setup Wizard
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📊 DATA-PLATFORM · Setup Wizard                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the setup.
+
 This command sets up the data-platform plugin with pandas, PostgreSQL, and dbt integration.
 
 ## Important Context

plugins/data-platform/commands/lineage-viz.md

@@ -0,0 +1,137 @@
+# /lineage-viz - Mermaid Lineage Visualization
+
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📊 DATA-PLATFORM · Lineage Visualization                         │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the visualization.
+
+Generate Mermaid flowchart syntax for dbt model lineage.
+
+## Usage
+
+```
+/lineage-viz <model_name> [--direction TB|LR] [--depth N]
+```
+
+## Workflow
+
+1. **Get lineage data**:
+   - Use `dbt_lineage` to fetch model dependencies
+   - Capture upstream sources and downstream consumers
+
+2. **Build Mermaid graph**:
+   - Create nodes for each model/source
+   - Style nodes by materialization type
+   - Add directional arrows for dependencies
+
+3. **Output**:
+   - Render Mermaid flowchart syntax
+   - Include copy-paste ready code block
+
+## Output Format
+
+```mermaid
+flowchart LR
+    subgraph Sources
+        raw_customers[(raw_customers)]
+        raw_orders[(raw_orders)]
+    end
+
+    subgraph Staging
+        stg_customers[stg_customers]
+        stg_orders[stg_orders]
+    end
+
+    subgraph Marts
+        dim_customers{{dim_customers}}
+        fct_orders{{fct_orders}}
+    end
+
+    raw_customers --> stg_customers
+    raw_orders --> stg_orders
+    stg_customers --> dim_customers
+    stg_orders --> fct_orders
+    dim_customers --> fct_orders
+```
+
+## Node Styles
+
+| Materialization | Mermaid Shape | Example |
+|-----------------|---------------|---------|
+| source | Cylinder `[( )]` | `raw_data[(raw_data)]` |
+| view | Rectangle `[ ]` | `stg_model[stg_model]` |
+| table | Double braces `{{ }}` | `dim_model{{dim_model}}` |
+| incremental | Hexagon `{{ }}` | `fct_model{{fct_model}}` |
+| ephemeral | Dashed `[/ /]` | `tmp_model[/tmp_model/]` |
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--direction TB` | Top-to-bottom layout (default: LR = left-to-right) |
+| `--depth N` | Limit lineage depth (default: unlimited) |
+
+## Examples
+
+```
+/lineage-viz dim_customers
+/lineage-viz fct_orders --direction TB
+/lineage-viz rpt_revenue --depth 2
+```
+
+## Usage Tips
+
+1. **Paste in documentation**: Copy the output directly into README.md or docs
+2. **GitHub/GitLab rendering**: Both platforms render Mermaid natively
+3. **Mermaid Live Editor**: Paste at https://mermaid.live for interactive editing
+
+## Example Output
+
+For `/lineage-viz fct_orders`:
+
+~~~markdown
+```mermaid
+flowchart LR
+    %% Sources
+    raw_customers[(raw_customers)]
+    raw_orders[(raw_orders)]
+    raw_products[(raw_products)]
+
+    %% Staging
+    stg_customers[stg_customers]
+    stg_orders[stg_orders]
+    stg_products[stg_products]
+
+    %% Marts
+    dim_customers{{dim_customers}}
+    dim_products{{dim_products}}
+    fct_orders{{fct_orders}}
+
+    %% Dependencies
+    raw_customers --> stg_customers
+    raw_orders --> stg_orders
+    raw_products --> stg_products
+    stg_customers --> dim_customers
+    stg_products --> dim_products
+    stg_orders --> fct_orders
+    dim_customers --> fct_orders
+    dim_products --> fct_orders
+
+    %% Highlight target model
+    style fct_orders fill:#f96,stroke:#333,stroke-width:2px
+```
+~~~
+
+## Available Tools
+
+Use these MCP tools:
+- `dbt_lineage` - Get model dependencies (REQUIRED)
+- `dbt_ls` - List dbt resources
+- `dbt_docs_generate` - Generate full manifest if needed

plugins/data-platform/commands/lineage.md

@@ -1,5 +1,17 @@
 # /lineage - Data Lineage Visualization
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📊 DATA-PLATFORM · Lineage                                       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the visualization.
+
 Show data lineage for dbt models or database tables.
 
 ## Usage

plugins/data-platform/commands/profile.md

@@ -1,5 +1,17 @@
 # /profile - Data Profiling
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📊 DATA-PLATFORM · Data Profile                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the profiling.
+
 Generate statistical profile and quality report for a DataFrame.
 
 ## Usage

plugins/data-platform/commands/run.md

@@ -1,5 +1,17 @@
 # /run - Execute dbt Models
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📊 DATA-PLATFORM · dbt Run                                       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the execution.
+
 Run dbt models with automatic pre-validation.
 
 ## Usage

plugins/data-platform/commands/schema.md

@@ -1,5 +1,17 @@
 # /schema - Schema Exploration
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📊 DATA-PLATFORM · Schema Explorer                               │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the exploration.
+
 Display schema information for database tables or DataFrames.
 
 ## Usage

plugins/data-platform/hooks/hooks.json

@@ -5,6 +5,17 @@
         "type": "command",
         "command": "${CLAUDE_PLUGIN_ROOT}/hooks/startup-check.sh"
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/schema-diff-check.sh"
+          }
+        ]
+      }
     ]
   }
 }

plugins/data-platform/hooks/schema-diff-check.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+# data-platform schema diff detection hook
+# Warns about potentially breaking schema changes
+# This is a command hook - non-blocking, warnings only
+
+PREFIX="[data-platform]"
+
+# Check if warnings are enabled (default: true)
+if [[ "${DATA_PLATFORM_SCHEMA_WARN:-true}" != "true" ]]; then
+    exit 0
+fi
+
+# Read tool input from stdin (JSON with file_path)
+INPUT=$(cat)
+
+# Extract file_path from JSON input
+FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+
+# If no file_path found, exit silently
+if [ -z "$FILE_PATH" ]; then
+    exit 0
+fi
+
+# Check if file is a schema-related file
+is_schema_file() {
+    local file="$1"
+
+    # Check file extension
+    case "$file" in
+        *.sql) return 0 ;;
+        */migrations/*.py) return 0 ;;
+        */migrations/*.sql) return 0 ;;
+        */models/*.py) return 0 ;;
+        */models/*.sql) return 0 ;;
+        *schema.prisma) return 0 ;;
+        *schema.graphql) return 0 ;;
+        */dbt/models/*.sql) return 0 ;;
+        */dbt/models/*.yml) return 0 ;;
+        */alembic/versions/*.py) return 0 ;;
+    esac
+
+    # Check directory patterns
+    if echo "$file" | grep -qE "(migrations?|schemas?|models)/"; then
+        return 0
+    fi
+
+    return 1
+}
+
+# Exit if not a schema file
+if ! is_schema_file "$FILE_PATH"; then
+    exit 0
+fi
+
+# Read the file content (if it exists and is readable)
+if [[ ! -f "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+FILE_CONTENT=$(cat "$FILE_PATH" 2>/dev/null || echo "")
+
+if [[ -z "$FILE_CONTENT" ]]; then
+    exit 0
+fi
+
+# Detect breaking changes
+BREAKING_CHANGES=()
+
+# Check for DROP COLUMN
+if echo "$FILE_CONTENT" | grep -qiE "DROP[[:space:]]+COLUMN"; then
+    BREAKING_CHANGES+=("DROP COLUMN detected - may break existing queries")
+fi
+
+# Check for DROP TABLE
+if echo "$FILE_CONTENT" | grep -qiE "DROP[[:space:]]+TABLE"; then
+    BREAKING_CHANGES+=("DROP TABLE detected - data loss risk")
+fi
+
+# Check for DROP INDEX
+if echo "$FILE_CONTENT" | grep -qiE "DROP[[:space:]]+INDEX"; then
+    BREAKING_CHANGES+=("DROP INDEX detected - may impact query performance")
+fi
+
+# Check for ALTER TYPE / MODIFY COLUMN type changes
+if echo "$FILE_CONTENT" | grep -qiE "ALTER[[:space:]]+.*(TYPE|COLUMN.*TYPE)"; then
+    BREAKING_CHANGES+=("Column type change detected - may cause data truncation")
+fi
+
+if echo "$FILE_CONTENT" | grep -qiE "MODIFY[[:space:]]+COLUMN"; then
+    BREAKING_CHANGES+=("MODIFY COLUMN detected - verify data compatibility")
+fi
+
+# Check for adding NOT NULL to existing column
+if echo "$FILE_CONTENT" | grep -qiE "ALTER[[:space:]]+.*SET[[:space:]]+NOT[[:space:]]+NULL"; then
+    BREAKING_CHANGES+=("Adding NOT NULL constraint - existing NULL values will fail")
+fi
+
+if echo "$FILE_CONTENT" | grep -qiE "ADD[[:space:]]+.*NOT[[:space:]]+NULL[^[:space:]]*[[:space:]]+DEFAULT"; then
+    # Adding NOT NULL with DEFAULT is usually safe - don't warn
+    :
+elif echo "$FILE_CONTENT" | grep -qiE "ADD[[:space:]]+.*NOT[[:space:]]+NULL"; then
+    BREAKING_CHANGES+=("Adding NOT NULL column without DEFAULT - INSERT may fail")
+fi
+
+# Check for RENAME TABLE/COLUMN
+if echo "$FILE_CONTENT" | grep -qiE "RENAME[[:space:]]+(TABLE|COLUMN|TO)"; then
+    BREAKING_CHANGES+=("RENAME detected - update all references")
+fi
+
+# Check for removing from Django/SQLAlchemy models (Python files)
+if [[ "$FILE_PATH" == *.py ]]; then
+    if echo "$FILE_CONTENT" | grep -qE "^-[[:space:]]*[a-z_]+[[:space:]]*=.*Field\("; then
+        BREAKING_CHANGES+=("Model field removal detected in Python ORM")
+    fi
+fi
+
+# Check for Prisma schema changes
+if [[ "$FILE_PATH" == *schema.prisma ]]; then
+    if echo "$FILE_CONTENT" | grep -qE "@relation.*onDelete.*Cascade"; then
+        BREAKING_CHANGES+=("Cascade delete detected - verify data safety")
+    fi
+fi
+
+# Output warnings if any breaking changes detected
+if [[ ${#BREAKING_CHANGES[@]} -gt 0 ]]; then
+    echo ""
+    echo "$PREFIX WARNING: Potential breaking schema changes in $(basename "$FILE_PATH")"
+    echo "$PREFIX ============================================"
+    for change in "${BREAKING_CHANGES[@]}"; do
+        echo "$PREFIX   - $change"
+    done
+    echo "$PREFIX ============================================"
+    echo "$PREFIX Review before deploying to production"
+    echo ""
+fi
+
+# Always exit 0 - non-blocking
+exit 0

plugins/doc-guardian/README.md

@@ -22,6 +22,9 @@ doc-guardian monitors your code changes via hooks:
 |---------|-------------|
 | `/doc-audit` | Full project scan - reports all drift without changing anything |
 | `/doc-sync` | Apply all pending documentation updates in one commit |
+| `/changelog-gen` | Generate changelog from conventional commits in Keep-a-Changelog format |
+| `/doc-coverage` | Calculate documentation coverage percentage for functions and classes |
+| `/stale-docs` | Detect documentation files that are stale relative to their associated code |
 
 ## Hooks
 
@@ -33,6 +36,8 @@ doc-guardian monitors your code changes via hooks:
 - **Version Drift**: Python 3.9 in docs but 3.11 in pyproject.toml
 - **Missing Docs**: Public functions without docstrings
 - **Stale Examples**: CLI examples that no longer work
+- **Low Coverage**: Undocumented functions and classes
+- **Stale Files**: Documentation that hasn't been updated alongside code changes
 
 ## Installation
 

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

@@ -6,6 +6,16 @@ description: Specialized agent for documentation analysis and drift detection
 
 You are an expert technical writer and documentation analyst. Your role is to detect discrepancies between code and documentation.
 
+## Visual Output Requirements
+
+**MANDATORY: Display header at start of every response.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📝 DOC-GUARDIAN · Documentation Analysis                        │
+└──────────────────────────────────────────────────────────────────┘
+```
+
 ## Capabilities
 
 1. **Pattern Recognition**

plugins/doc-guardian/claude-md-integration.md

@@ -11,6 +11,9 @@ This project uses doc-guardian for automatic documentation synchronization.
 - Pending updates are queued silently during work
 - Run `/doc-sync` to apply all pending documentation updates
 - Run `/doc-audit` for a full project documentation review
+- Run `/changelog-gen` to generate changelog from conventional commits
+- Run `/doc-coverage` to check documentation coverage metrics
+- Run `/stale-docs` to find documentation that may be outdated
 
 ### Documentation Files Tracked
 - README.md (root and subdirectories)

plugins/doc-guardian/commands/changelog-gen.md

@@ -0,0 +1,121 @@
+---
+description: Generate changelog from conventional commits in Keep-a-Changelog format
+---
+
+# Changelog Generation
+
+Generate a changelog entry from conventional commits.
+
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📝 DOC-GUARDIAN · Changelog Generation                          │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the generation.
+
+## Process
+
+1. **Identify Commit Range**
+   - Default: commits since last tag
+   - Optional: specify range (e.g., `v1.0.0..HEAD`)
+   - Detect if this is first release (no previous tags)
+
+2. **Parse Conventional Commits**
+   Extract from commit messages following the pattern:
+   ```
+   <type>(<scope>): <description>
+
+   [optional body]
+
+   [optional footer(s)]
+   ```
+
+   **Recognized Types:**
+   | Type | Changelog Section |
+   |------|------------------|
+   | `feat` | Added |
+   | `fix` | Fixed |
+   | `docs` | Documentation |
+   | `perf` | Performance |
+   | `refactor` | Changed |
+   | `style` | Changed |
+   | `test` | Testing |
+   | `build` | Build |
+   | `ci` | CI/CD |
+   | `chore` | Maintenance |
+   | `BREAKING CHANGE` | Breaking Changes |
+
+3. **Group by Type**
+   Organize commits into Keep-a-Changelog sections:
+   - Breaking Changes (if any `!` suffix or `BREAKING CHANGE` footer)
+   - Added (feat)
+   - Changed (refactor, style, perf)
+   - Deprecated
+   - Removed
+   - Fixed (fix)
+   - Security
+
+4. **Format Entries**
+   For each commit:
+   - Extract scope (if present) as prefix
+   - Use description as entry text
+   - Link to commit hash if repository URL available
+   - Include PR/issue references from footer
+
+5. **Output Format**
+```markdown
+## [Unreleased]
+
+### Breaking Changes
+- **scope**: Description of breaking change
+
+### Added
+- **scope**: New feature description
+- Another feature without scope
+
+### Changed
+- **scope**: Refactoring description
+
+### Fixed
+- **scope**: Bug fix description
+
+### Documentation
+- Updated README with new examples
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--from <tag>` | Start from specific tag | Latest tag |
+| `--to <ref>` | End at specific ref | HEAD |
+| `--version <ver>` | Set version header | [Unreleased] |
+| `--include-merge` | Include merge commits | false |
+| `--group-by-scope` | Group by scope within sections | false |
+
+## Integration
+
+The generated output is designed to be copied directly into CHANGELOG.md:
+- Follows [Keep a Changelog](https://keepachangelog.com) format
+- Compatible with semantic versioning
+- Excludes non-user-facing commits (chore, ci, test by default)
+
+## Example Usage
+
+```
+/changelog-gen
+/changelog-gen --from v1.0.0 --version 1.1.0
+/changelog-gen --include-merge --group-by-scope
+```
+
+## Non-Conventional Commits
+
+Commits not following conventional format are:
+- Listed under "Other" section
+- Flagged for manual categorization
+- Skipped if `--strict` flag is used

plugins/doc-guardian/commands/doc-audit.md

@@ -6,6 +6,18 @@ description: Full documentation audit - scans entire project for doc drift witho
 
 Perform a comprehensive documentation drift analysis.
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📝 DOC-GUARDIAN · Documentation Audit                          │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the audit.
+
 ## Process
 
 1. **Inventory Documentation Files**

plugins/doc-guardian/commands/doc-coverage.md

@@ -0,0 +1,140 @@
+---
+description: Calculate documentation coverage percentage for functions and classes
+---
+
+# Documentation Coverage
+
+Analyze codebase to calculate documentation coverage metrics.
+
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📝 DOC-GUARDIAN · Documentation Coverage                        │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the analysis.
+
+## Process
+
+1. **Scan Source Files**
+   Identify all documentable items:
+
+   **Python:**
+   - Functions (def)
+   - Classes
+   - Methods
+   - Module-level docstrings
+
+   **JavaScript/TypeScript:**
+   - Functions (function, arrow functions)
+   - Classes
+   - Methods
+   - JSDoc comments
+
+   **Other Languages:**
+   - Adapt patterns for Go, Rust, etc.
+
+2. **Determine Documentation Status**
+   For each item, check:
+   - Has docstring/JSDoc comment
+   - Docstring is non-empty and meaningful (not just `pass` or `TODO`)
+   - Parameters are documented (for detailed mode)
+   - Return type is documented (for detailed mode)
+
+3. **Calculate Metrics**
+   ```
+   Coverage = (Documented Items / Total Items) * 100
+   ```
+
+   **Levels:**
+   - Basic: Item has any docstring
+   - Standard: Docstring describes purpose
+   - Complete: All parameters and return documented
+
+4. **Output Format**
+```
+## Documentation Coverage Report
+
+### Summary
+- Total documentable items: 156
+- Documented: 142
+- Coverage: 91.0%
+
+### By Type
+| Type | Total | Documented | Coverage |
+|------|-------|------------|----------|
+| Functions | 89 | 85 | 95.5% |
+| Classes | 23 | 21 | 91.3% |
+| Methods | 44 | 36 | 81.8% |
+
+### By Directory
+| Path | Total | Documented | Coverage |
+|------|-------|------------|----------|
+| src/api/ | 34 | 32 | 94.1% |
+| src/utils/ | 28 | 28 | 100.0% |
+| src/models/ | 45 | 38 | 84.4% |
+| tests/ | 49 | 44 | 89.8% |
+
+### Undocumented Items
+- [ ] src/api/handlers.py:45 `create_order()`
+- [ ] src/api/handlers.py:78 `update_order()`
+- [ ] src/models/user.py:23 `UserModel.validate()`
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--path <dir>` | Scan specific directory | Project root |
+| `--exclude <glob>` | Exclude files matching pattern | `**/test_*,**/*_test.*` |
+| `--include-private` | Include private members (_prefixed) | false |
+| `--include-tests` | Include test files | false |
+| `--min-coverage <pct>` | Fail if below threshold | none |
+| `--format <fmt>` | Output format (table, json, markdown) | table |
+| `--detailed` | Check parameter/return docs | false |
+
+## Thresholds
+
+Common coverage targets:
+| Level | Coverage | Description |
+|-------|----------|-------------|
+| Minimal | 60% | Basic documentation exists |
+| Good | 80% | Most public APIs documented |
+| Excellent | 95% | Comprehensive documentation |
+
+## CI Integration
+
+Use `--min-coverage` to enforce standards:
+```bash
+# Fail if coverage drops below 80%
+claude /doc-coverage --min-coverage 80
+```
+
+Exit codes:
+- 0: Coverage meets threshold (or no threshold set)
+- 1: Coverage below threshold
+
+## Example Usage
+
+```
+/doc-coverage
+/doc-coverage --path src/
+/doc-coverage --min-coverage 85 --exclude "**/generated/**"
+/doc-coverage --detailed --include-private
+```
+
+## Language Detection
+
+File extensions mapped to documentation patterns:
+| Extension | Language | Doc Format |
+|-----------|----------|------------|
+| .py | Python | Docstrings (""") |
+| .js, .ts | JavaScript/TypeScript | JSDoc (/** */) |
+| .go | Go | // comments above |
+| .rs | Rust | /// doc comments |
+| .rb | Ruby | # comments, YARD |
+| .java | Java | Javadoc (/** */) |

plugins/doc-guardian/commands/doc-sync.md

@@ -6,6 +6,18 @@ description: Synchronize all pending documentation updates in a single commit
 
 Apply all pending documentation updates detected by doc-guardian hooks.
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📝 DOC-GUARDIAN · Documentation Sync                            │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the sync.
+
 ## Process
 
 1. **Review Pending Queue**
@@ -40,7 +52,13 @@ Apply all pending documentation updates detected by doc-guardian hooks.
    - Single commit: `docs: sync documentation with code changes`
    - Include summary of what was updated in commit body
 
-5. **Output**
+5. **Clear Queue**
+   After successful sync, clear the queue file:
+   ```bash
+   echo "# Doc Guardian Queue - cleared after sync on $(date +%Y-%m-%d)" > .doc-guardian-queue
+   ```
+
+6. **Output**
 ```
 ## Documentation Sync Complete
 

plugins/doc-guardian/commands/stale-docs.md

@@ -0,0 +1,155 @@
+---
+description: Detect documentation files that are stale relative to their associated code
+---
+
+# Stale Documentation Detection
+
+Identify documentation files that may be outdated based on commit history.
+
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  📝 DOC-GUARDIAN · Stale Documentation Check                     │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the check.
+
+## Process
+
+1. **Map Documentation to Code**
+   Build relationships between docs and code:
+
+   | Doc File | Related Code |
+   |----------|--------------|
+   | README.md | All files in same directory |
+   | API.md | src/api/**/* |
+   | CLAUDE.md | Configuration files, scripts |
+   | docs/module.md | src/module/**/* |
+   | Component.md | Component.tsx, Component.css |
+
+2. **Analyze Commit History**
+   For each doc file:
+   - Find last commit that modified the doc
+   - Find last commit that modified related code
+   - Count commits to code since doc was updated
+
+3. **Calculate Staleness**
+   ```
+   Commits Behind = Code Commits Since Doc Update
+   Days Behind = Days Since Doc Update - Days Since Code Update
+   ```
+
+4. **Apply Threshold**
+   Default: Flag if documentation is 10+ commits behind related code
+
+   **Staleness Levels:**
+   | Commits Behind | Level | Action |
+   |----------------|-------|--------|
+   | 0-5 | Fresh | No action needed |
+   | 6-10 | Aging | Review recommended |
+   | 11-20 | Stale | Update needed |
+   | 20+ | Critical | Immediate attention |
+
+5. **Output Format**
+```
+## Stale Documentation Report
+
+### Critical (20+ commits behind)
+| File | Last Updated | Commits Behind | Related Code |
+|------|--------------|----------------|--------------|
+| docs/api.md | 2024-01-15 | 34 | src/api/**/* |
+
+### Stale (11-20 commits behind)
+| File | Last Updated | Commits Behind | Related Code |
+|------|--------------|----------------|--------------|
+| README.md | 2024-02-20 | 15 | package.json, src/index.ts |
+
+### Aging (6-10 commits behind)
+| File | Last Updated | Commits Behind | Related Code |
+|------|--------------|----------------|--------------|
+| CONTRIBUTING.md | 2024-03-01 | 8 | .github/*, scripts/* |
+
+### Summary
+- Critical: 1 file
+- Stale: 1 file
+- Aging: 1 file
+- Fresh: 12 files
+- Total documentation files: 15
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--threshold <n>` | Commits behind to flag as stale | 10 |
+| `--days` | Use days instead of commits | false |
+| `--path <dir>` | Scan specific directory | Project root |
+| `--doc-pattern <glob>` | Pattern for doc files | `**/*.md,**/README*` |
+| `--ignore <glob>` | Ignore specific docs | `CHANGELOG.md,LICENSE` |
+| `--show-fresh` | Include fresh docs in output | false |
+| `--format <fmt>` | Output format (table, json) | table |
+
+## Relationship Detection
+
+How docs are mapped to code:
+
+1. **Same Directory**
+   - `src/api/README.md` relates to `src/api/**/*`
+
+2. **Name Matching**
+   - `docs/auth.md` relates to `**/auth.*`, `**/auth/**`
+
+3. **Explicit Links**
+   - Parse `[link](path)` in docs to find related files
+
+4. **Import Analysis**
+   - Track which modules are referenced in code examples
+
+## Configuration
+
+Create `.doc-guardian.yml` to customize mappings:
+```yaml
+stale-docs:
+  threshold: 10
+  mappings:
+    - doc: docs/deployment.md
+      code:
+        - Dockerfile
+        - docker-compose.yml
+        - .github/workflows/deploy.yml
+    - doc: ARCHITECTURE.md
+      code:
+        - src/**/*
+  ignore:
+    - CHANGELOG.md
+    - LICENSE
+    - vendor/**
+```
+
+## Example Usage
+
+```
+/stale-docs
+/stale-docs --threshold 5
+/stale-docs --days --threshold 30
+/stale-docs --path docs/ --show-fresh
+```
+
+## Integration with doc-audit
+
+`/stale-docs` focuses specifically on commit-based staleness, while `/doc-audit` checks content accuracy. Use both for comprehensive documentation health:
+
+```
+/doc-audit      # Check for broken references and content drift
+/stale-docs     # Check for files that may need review
+```
+
+## Exit Codes
+
+- 0: No critical or stale documentation
+- 1: Stale documentation found (useful for CI)
+- 2: Critical documentation found

plugins/doc-guardian/hooks/notify.sh

@@ -2,6 +2,10 @@
 # doc-guardian notification hook
 # Tracks documentation dependencies and queues updates
 # This is a command hook - guaranteed not to block workflow
+#
+# IMPORTANT: Output is purely informational - uses passive language
+# to avoid triggering Claude to seek user confirmation.
+# Run /doc-sync to process the queue when ready.
 
 # Read tool input from stdin (JSON with file_path)
 INPUT=$(cat)
@@ -44,6 +48,30 @@ DEPENDENT_DOCS="${DOC_DEPS[$MODIFIED_TYPE]}"
 # Queue file for tracking pending updates
 QUEUE_FILE="${CLAUDE_PROJECT_ROOT:-.}/.doc-guardian-queue"
 
+# Debounce: skip notification if same type was logged in last 5 seconds
+# This prevents 4+ rapid notifications during batch edits
+DEBOUNCE_SECONDS=5
+if [ -f "$QUEUE_FILE" ]; then
+    LAST_ENTRY=$(tail -1 "$QUEUE_FILE" 2>/dev/null || true)
+    LAST_TYPE=$(echo "$LAST_ENTRY" | cut -d'|' -f2 | tr -d ' ')
+    LAST_TIME=$(echo "$LAST_ENTRY" | cut -d'|' -f1 | tr -d ' ')
+
+    if [ "$LAST_TYPE" = "$MODIFIED_TYPE" ] && [ -n "$LAST_TIME" ]; then
+        # Convert timestamps to seconds for comparison
+        LAST_EPOCH=$(date -d "$LAST_TIME" +%s 2>/dev/null || echo "0")
+        NOW_EPOCH=$(date +%s)
+        DIFF=$((NOW_EPOCH - LAST_EPOCH))
+
+        if [ "$DIFF" -lt "$DEBOUNCE_SECONDS" ]; then
+            # Still add to queue, but skip notification
+            {
+                echo "$(date +%Y-%m-%dT%H:%M:%S) | $MODIFIED_TYPE | $FILE_PATH | $DEPENDENT_DOCS"
+            } >> "$QUEUE_FILE" 2>/dev/null || true
+            exit 0
+        fi
+    fi
+fi
+
 # Add to queue (create if doesn't exist, append if does)
 {
     echo "$(date +%Y-%m-%dT%H:%M:%S) | $MODIFIED_TYPE | $FILE_PATH | $DEPENDENT_DOCS"
@@ -52,7 +80,8 @@ QUEUE_FILE="${CLAUDE_PROJECT_ROOT:-.}/.doc-guardian-queue"
 # Count pending updates
 PENDING_COUNT=$(wc -l < "$QUEUE_FILE" 2>/dev/null | tr -d ' ' || echo "1")
 
-# Output notification with specific docs that need updating
-echo "[doc-guardian] $MODIFIED_TYPE changed → update needed: $DEPENDENT_DOCS (${PENDING_COUNT} pending)"
+# Output passive notification (no action implied)
+# Uses "queued" instead of "update needed" to avoid triggering Claude to ask about it
+echo "[doc-guardian] drift queued: $MODIFIED_TYPE → $DEPENDENT_DOCS ($PENDING_COUNT total)"
 
 exit 0

plugins/git-flow/README.md

@@ -119,6 +119,10 @@ The git-assistant agent helps resolve merge conflicts with analysis and recommen
 → Status: Clean, up-to-date
 ```
 
+## Documentation
+
+- [Branching Strategy Guide](docs/BRANCHING-STRATEGY.md) - Detailed documentation of the `development -> staging -> main` promotion flow
+
 ## Integration
 
 For CLAUDE.md integration instructions, see `claude-md-integration.md`.

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

@@ -1,5 +1,15 @@
 # Git Assistant Agent
 
+## Visual Output Requirements
+
+**MANDATORY: Display header at start of every response.**
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🔀 GIT-FLOW · Git Assistant                                     │
+└──────────────────────────────────────────────────────────────────┘
+```
+
 ## Role
 
 You are a git workflow assistant that helps users navigate complex git operations, resolve conflicts, and maintain clean repository history.

plugins/git-flow/commands/branch-cleanup.md

@@ -1,5 +1,17 @@
 # /branch-cleanup - Clean Merged and Stale Branches
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🔀 GIT-FLOW · Branch Cleanup                                     │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the workflow.
+
 ## Purpose
 
 Remove branches that have been merged OR whose remote tracking branch no longer exists, both locally and optionally on remote.

plugins/git-flow/commands/branch-start.md

@@ -1,5 +1,17 @@
 # /branch-start - Start New Branch
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🔀 GIT-FLOW · Branch Start                                      │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the workflow.
+
 ## Purpose
 
 Create a new feature/fix/chore branch with consistent naming conventions.

plugins/git-flow/commands/commit-merge.md

@@ -1,5 +1,17 @@
 # /commit-merge - Commit and Merge
 
+## Visual Output
+
+When executing this command, display the plugin header:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  🔀 GIT-FLOW · Commit & Merge                                     │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Then proceed with the workflow.
+
 ## Purpose
 
 Commit current changes, then merge the current branch into a target branch.