personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: personal-projects:dbf3fa7e0dc23c4d02e60375c96485568586ff4e
Branches Tags
personal-projects:main personal-projects:development
personal-projects:v5.9.0 personal-projects:v5.8.0 personal-projects:v5.7.1 personal-projects:v5.7.0 personal-projects:v5.5.0 personal-projects:v5.4.0 personal-projects:v5.3.0 personal-projects:v5.2.0 personal-projects:v5.0.0 personal-projects:v4.1.0 personal-projects:v4.0.0 personal-projects:v3.2.0 personal-projects:v3.1.1 personal-projects:v3.0.0 personal-projects:v2.3.0 personal-projects:v2.2.0 personal-projects:v2.1.0 personal-projects:v2.0.1 personal-projects:v2.0.0
..
compare: personal-projects:v5.3.0
Branches Tags
personal-projects:main personal-projects:development
personal-projects:v5.9.0 personal-projects:v5.8.0 personal-projects:v5.7.1 personal-projects:v5.7.0 personal-projects:v5.5.0 personal-projects:v5.4.0 personal-projects:v5.3.0 personal-projects:v5.2.0 personal-projects:v5.0.0 personal-projects:v4.1.0 personal-projects:v4.0.0 personal-projects:v3.2.0 personal-projects:v3.1.1 personal-projects:v3.0.0 personal-projects:v2.3.0 personal-projects:v2.2.0 personal-projects:v2.1.0 personal-projects:v2.0.1 personal-projects:v2.0.0

6 Commits
dbf3fa7e0d ... v5.3.0

Author SHA1 Message Date
Leo Miranda
2173f3389a Merge pull request 'development' (#289) from development into main 
Reviewed-on: #289
 2026-01-28 22:49:18 +00:00
Leo Miranda
fab1345bcb Merge pull request 'development' (#286) from development into main 
Reviewed-on: #286
 2026-01-28 22:41:07 +00:00
Leo Miranda
36e6ac2dd0 Merge pull request 'development' (#283) from development into main 
Reviewed-on: #283
 2026-01-28 21:48:57 +00:00
Leo Miranda
3e0e779803 Merge pull request 'development' (#280) from development into main 
Reviewed-on: #280
 2026-01-28 20:37:52 +00:00
Leo Miranda
74198743ab Merge pull request 'development' (#271) from development into main 
Reviewed-on: #271
 2026-01-28 19:27:45 +00:00
Leo Miranda
d57bff184e Merge pull request 'development' (#265) from development into main 
Reviewed-on: #265
 2026-01-28 18:45:38 +00:00
287 changed files with 16861 additions and 18347 deletions
Expand all files Collapse all files

27
.claude-plugin/marketplace.json
View File

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

249
.claude/backups/CLAUDE.md.2026-01-22_132037
View File

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

27
.doc-guardian-queue
View File

@@ -1,27 +0,0 @@
# Doc Guardian Queue - cleared after sync on 2026-02-02
2026-02-02T11:41:00 | .claude-plugin | /home/lmiranda/claude-plugins-work/.claude-plugin/marketplace.json | CLAUDE.md .claude-plugin/marketplace.json
2026-02-02T13:35:48 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/sprint-approval.md | README.md
2026-02-02T13:36:03 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-start.md | docs/COMMANDS-CHEATSHEET.md README.md
2026-02-02T13:36:16 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/orchestrator.md | README.md CLAUDE.md
2026-02-02T13:39:07 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/rfc.md | docs/COMMANDS-CHEATSHEET.md README.md
2026-02-02T13:39:15 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/setup.md | docs/COMMANDS-CHEATSHEET.md README.md
2026-02-02T13:39:32 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/rfc-workflow.md | README.md
2026-02-02T13:43:14 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/rfc-templates.md | README.md
2026-02-02T13:44:55 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/sprint-lifecycle.md | README.md
2026-02-02T13:45:04 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/label-taxonomy/labels-reference.md | README.md
2026-02-02T13:45:14 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-plan.md | docs/COMMANDS-CHEATSHEET.md README.md
2026-02-02T13:45:48 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/review.md | docs/COMMANDS-CHEATSHEET.md README.md
2026-02-02T13:46:07 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-close.md | docs/COMMANDS-CHEATSHEET.md README.md
2026-02-02T13:46:21 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-status.md | docs/COMMANDS-CHEATSHEET.md README.md
2026-02-02T13:46:38 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/planner.md | README.md CLAUDE.md
2026-02-02T13:46:57 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/code-reviewer.md | README.md CLAUDE.md
2026-02-02T13:49:13 | commands | /home/lmiranda/claude-plugins-work/plugins/viz-platform/commands/design-gate.md | docs/COMMANDS-CHEATSHEET.md README.md
2026-02-02T13:49:24 | commands | /home/lmiranda/claude-plugins-work/plugins/data-platform/commands/data-gate.md | docs/COMMANDS-CHEATSHEET.md README.md
2026-02-02T13:49:35 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/domain-consultation.md | README.md
2026-02-02T13:50:04 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/validation_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
2026-02-02T13:50:59 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/mcp_server/server.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
2026-02-02T13:51:32 | mcp-servers | /home/lmiranda/claude-plugins-work/mcp-servers/contract-validator/tests/test_validation_tools.py | docs/COMMANDS-CHEATSHEET.md CLAUDE.md
2026-02-02T13:51:49 | skills | /home/lmiranda/claude-plugins-work/plugins/contract-validator/skills/validation-rules.md | README.md
2026-02-02T13:52:07 | skills | /home/lmiranda/claude-plugins-work/plugins/contract-validator/skills/mcp-tools-reference.md | README.md
2026-02-02T13:59:09 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/progress-tracking.md | README.md
2026-02-02T14:01:34 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/test.md | docs/COMMANDS-CHEATSHEET.md README.md

1
.env
View File

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

24
.mcp.json
View File

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

286
CHANGELOG.md
View File

@@ -4,292 +4,6 @@ All notable changes to the Leo Claude Marketplace will be documented in this fil
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [Unreleased]
### Added
#### Plugin Installation Scripts
New scripts for installing marketplace plugins into consumer projects:
- **`scripts/install-plugin.sh`** — Install a plugin to a consumer project
- Adds MCP server entry to target's `.mcp.json` (if plugin has MCP server)
- Appends integration snippet to target's `CLAUDE.md`
- Idempotent: safe to run multiple times
- Validates plugin exists and target path is valid
- **`scripts/uninstall-plugin.sh`** — Remove a plugin from a consumer project
- Removes MCP server entry from `.mcp.json`
- Removes integration section from `CLAUDE.md`
- **`scripts/list-installed.sh`** — Show installed plugins in a project
- Lists fully installed, partially installed, and available plugins
- Shows plugin versions and descriptions
**Usage:**
```bash
./scripts/install-plugin.sh data-platform ~/projects/personal-portfolio
./scripts/list-installed.sh ~/projects/personal-portfolio
./scripts/uninstall-plugin.sh data-platform ~/projects/personal-portfolio
```
**Documentation:** `docs/CONFIGURATION.md` updated with "Installing Plugins to Consumer Projects" section.
### Fixed
#### Plugin Installation Scripts — MCP Mapping & Section Markers
**MCP Server Mapping:**
- Added `mcp_servers` field to plugin.json for plugins that use shared MCP servers
- `projman` and `pr-review` now correctly install `gitea` MCP server
- `cmdb-assistant` now correctly installs `netbox` MCP server
- Scripts read MCP server names from plugin.json instead of assuming plugin name = server name
**CLAUDE.md Section Markers:**
- Install script now wraps integration content with HTML comment markers:
`<!-- BEGIN marketplace-plugin: {name} -->` and `<!-- END marketplace-plugin: {name} -->`
- Uninstall script uses markers for precise section removal (no more code block false positives)
- Backward compatible: falls back to legacy header detection for pre-marker installations
**Plugins updated with `mcp_servers` field:**
- `projman` → `["gitea"]`
- `pr-review` → `["gitea"]`
- `cmdb-assistant` → `["netbox"]`
- `data-platform` → `["data-platform"]`
- `viz-platform` → `["viz-platform"]`
- `contract-validator` → `["contract-validator"]`
#### Agent Model Selection
Per-agent model selection using Claude Code's now-supported `model` frontmatter field.
- All 25 marketplace agents assigned appropriate model (`sonnet`, `haiku`, or `inherit`)
- Model assignment based on reasoning depth, tool complexity, and latency requirements
- Documentation added to `CLAUDE.md` and `docs/CONFIGURATION.md`
**Supported values:** `sonnet` (default), `opus`, `haiku`, `inherit`
**Model assignments:**
| Model | Agent Types |
|-------|-------------|
| sonnet | Planner, Orchestrator, Executor, Code Reviewer, Coordinator, Security Reviewers, Data Advisor, Design Reviewer, etc. |
| haiku | Maintainability Auditor, Test Validator, Component Check, Theme Setup, Git Assistant, Data Ingestion, Agent Check |
### Fixed
#### Agent Frontmatter Standardization
- Fixed viz-platform and data-platform agents using non-standard `agent:` field (now `name:`)
- Removed non-standard `triggers:` field from domain agents (trigger info already in agent body)
- Added missing frontmatter to 13 agents across pr-review, viz-platform, contract-validator, clarity-assist, git-flow, doc-guardian, code-sentinel, cmdb-assistant, and data-platform
- All 25 agents now have consistent `name`, `description`, and `model` fields
---
## [5.8.0] - 2026-02-02
### Added
#### claude-config-maintainer v1.2.0 - Settings Audit Feature
New commands for auditing and optimizing `settings.local.json` permission configurations:
- **`/config-audit-settings`** — Audit `settings.local.json` permissions with 100-point scoring across redundancy, coverage, safety alignment, and profile fit
- **`/config-optimize-settings`** — Apply permission optimizations with dry-run, named profiles (`conservative`, `reviewed`, `autonomous`), and consolidation modes
- **`/config-permissions-map`** — Generate Mermaid diagram of review layer coverage and permission gaps
- **`skills/settings-optimization.md`** — Comprehensive skill for permission pattern analysis, consolidation rules, review-layer-aware recommendations, and named profiles
**Key Features:**
- Settings Efficiency Score (100 points) alongside existing CLAUDE.md score
- Review layer verification — agent reads `hooks/hooks.json` from installed plugins before recommending auto-allow patterns
- Three named profiles: `conservative` (prompts for most writes), `reviewed` (for projects with ≥2 review layers), `autonomous` (sandboxed environments)
- Pattern consolidation detection: duplicates, subsets, merge candidates, stale entries, conflicts
#### Projman Hardening Sprint
Targeted improvements to safety gates, command structure, lifecycle tracking, and cross-plugin contracts.
**Sprint Lifecycle State Machine:**
- New `skills/sprint-lifecycle.md` - defines valid states and transitions via milestone metadata
- States: idle -> Sprint/Planning -> Sprint/Executing -> Sprint/Reviewing -> idle
- All sprint commands check and set lifecycle state on entry/exit
- Out-of-order calls produce warnings with guidance, `--force` override available
**Sprint Dispatch Log:**
- Orchestrator now maintains a structured dispatch log during execution
- Records task dispatch, completion, failure, gate checks, and resume events
- Enables timeline reconstruction after interrupted sessions
**Gate Contract Versioning:**
- Gate commands (`/design-gate`, `/data-gate`) declare `gate_contract: v1` in frontmatter
- `domain-consultation.md` Gate Command Reference includes expected contract version
- `validate_workflow_integration` now checks contract version compatibility
- Mismatch produces WARNING, missing contract produces INFO suggestion
**Shared Visual Output Skill:**
- New `skills/visual-output.md` - single source of truth for projman visual headers
- All 4 agent files reference the skill instead of inline templates
- Phase Registry maps agents to emoji and phase names
### Changed
**Sprint Approval Gate Hardened:**
- Approval is now a hard block, not a warning (was "recommended", now required)
- `--force` flag added to bypass in emergencies (logged to milestone)
- Consistent language across sprint-approval.md, sprint-start.md, and orchestrator.md
**RFC Commands Normalized:**
- 5 individual commands (`/rfc-create`, `/rfc-list`, `/rfc-review`, `/rfc-approve`, `/rfc-reject`) consolidated into `/rfc create|list|review|approve|reject`
- `/clear-cache` absorbed into `/setup --clear-cache`
- Command count reduced from 17 to 12
**`/test` Command Documentation Expanded:**
- Sprint integration section (pre-close verification workflow)
- Concrete usage examples for all modes
- Edge cases table
- DO NOT rules for both modes
### Removed
- `plugins/projman/commands/rfc-create.md` (replaced by `/rfc create`)
- `plugins/projman/commands/rfc-list.md` (replaced by `/rfc list`)
- `plugins/projman/commands/rfc-review.md` (replaced by `/rfc review`)
- `plugins/projman/commands/rfc-approve.md` (replaced by `/rfc approve`)
- `plugins/projman/commands/rfc-reject.md` (replaced by `/rfc reject`)
- `plugins/projman/commands/clear-cache.md` (replaced by `/setup --clear-cache`)
---
## [5.7.1] - 2026-02-02
### Added
- **contract-validator**: New `validate_workflow_integration` MCP tool — validates domain plugins expose required advisory interfaces (gate command, review command, advisory agent)
- **contract-validator**: New `MISSING_INTEGRATION` issue type for workflow integration validation
### Fixed
- `scripts/setup.sh` banner version updated from v5.1.0 to v5.7.1
### Reverted
- **marketplace.json**: Removed `integrates_with` field — Claude Code schema does not support custom plugin fields (causes marketplace load failure)
---
## [5.7.0] - 2026-02-02
### Added
- **data-platform**: New `data-advisor` agent for data integrity, schema, and dbt compliance validation
- **data-platform**: New `data-integrity-audit.md` skill defining audit rules, severity levels, and scanning strategies
- **data-platform**: New `/data-gate` command for binary pass/fail data integrity gates (projman integration)
- **data-platform**: New `/data-review` command for comprehensive data integrity audits
### Changed
- Domain Advisory Pattern now fully operational for both Viz and Data domains
- projman orchestrator `Domain/Data` gates now resolve to live `/data-gate` command (previously fell through to "gate unavailable" warning)
---
## [5.6.0] - 2026-02-01
### Added
- **Domain Advisory Pattern**: Cross-plugin integration enabling projman to consult domain-specific plugins during sprint lifecycle
- **projman**: New `domain-consultation.md` skill for domain detection and gate protocols
- **viz-platform**: New `design-reviewer` agent for design system compliance auditing
- **viz-platform**: New `design-system-audit.md` skill defining audit rules and severity levels
- **viz-platform**: New `/design-review` command for detailed design system audits
- **viz-platform**: New `/design-gate` command for binary pass/fail validation gates
- **Labels**: New `Domain/Viz` and `Domain/Data` labels for domain routing
### Changed
- **projman planner**: Now loads domain-consultation skill and performs domain detection during planning
- **projman orchestrator**: Now runs domain gates before marking Domain/* labeled issues as complete
---
## [5.5.0] - 2026-02-01
### Added
#### RFC System for Feature Tracking
Wiki-based Request for Comments (RFC) system for capturing, reviewing, and tracking feature ideas through their lifecycle.
**New Commands (projman):**
- `/rfc-create` - Create new RFC from conversation or clarified specification
- `/rfc-list` - List all RFCs grouped by status (Draft, Review, Approved, Implementing, Implemented, Rejected, Stale)
- `/rfc-review` - Submit Draft RFC for maintainer review
- `/rfc-approve` - Approve RFC, making it available for sprint planning
- `/rfc-reject` - Reject RFC with documented reason
**RFC Lifecycle:**
- Draft → Review → Approved → Implementing → Implemented
- Terminal states: Rejected, Superseded
- Stale: Drafts with no activity >90 days
**Sprint Integration:**
- `/sprint-plan` now detects approved RFCs and offers selection
- `/sprint-close` updates RFC status to Implemented on completion
- RFC-Index wiki page auto-maintained with status sections
**Clarity-Assist Integration:**
- Vagueness hook now detects feature request patterns
- Suggests `/rfc-create` for feature ideas
- `/clarify` offers RFC creation after delivering clarified spec
**New MCP Tool:**
- `allocate_rfc_number` - Allocates next sequential RFC number
**New Skills:**
- `skills/rfc-workflow.md` - RFC lifecycle and state transitions
- `skills/rfc-templates.md` - RFC page template specifications
### Changed
#### Sprint 8: Hook Efficiency Quick Wins
Performance optimizations for plugin hooks to reduce overhead on every command.
**Changes:**
- **viz-platform:** Remove SessionStart hook that only echoed "loaded" (zero value)
- **git-flow:** Add early exit to `branch-check.sh` for non-git commands (skip JSON parsing)
- **git-flow:** Add early exit to `commit-msg-check.sh` for non-git commands (skip Python spawn)
- **project-hygiene:** Add 60-second cooldown to `cleanup.sh` (reduce find operations)
**Impact:** Hooks now exit immediately for 90%+ of Bash commands that don't need processing.
**Issues:** #321, #322, #323, #324
**PR:** #334
---
## [5.4.1] - 2026-01-30
### Removed
#### Multi-Model Agent Support (REVERTED)
**Reason:** Claude Code does not support `defaultModel` in plugin.json or `model` in agent frontmatter. The schema validation rejects these as "Unrecognized key".
**Removed:**
- `defaultModel` field from all plugin.json files (6 plugins)
- `model` field references from agent frontmatter
- `docs/MODEL-RECOMMENDATIONS.md` - Deleted entirely
- Model configuration sections from `docs/CONFIGURATION.md` and `CLAUDE.md`
**Lesson:** Do not implement features without verifying they are supported by Claude Code's plugin schema.
---
## [5.4.0] - 2026-01-28 [REVERTED]
### Added (NOW REMOVED - See 5.4.1)
#### Sprint 7: Multi-Model Agent Support
~~Configurable model selection for agents with inheritance chain.~~
**This feature was reverted in 5.4.1 - Claude Code does not support these fields.**
Original sprint work:
- Issues: #302, #303, #304, #305, #306
- PRs: #307, #308
---
## [5.3.0] - 2026-01-28
### Added

300
CLAUDE.md
View File

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

59
README.md
View File

@@ -1,4 +1,4 @@
# Leo Claude Marketplace - v5.8.0
# Leo Claude Marketplace - v5.3.0
A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
@@ -6,7 +6,7 @@ A collection of Claude Code plugins for project management, infrastructure autom
### Development & Project Management
#### [projman](./plugins/projman)
#### [projman](./plugins/projman/README.md)
**Sprint Planning and Project Management**
AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sprint workflow into a distributable plugin.
@@ -19,9 +19,9 @@ AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sp
- Branch-aware security (development/staging/production)
- Pre-sprint-close code quality review and test verification
**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/setup`, `/review`, `/test`, `/debug`, `/suggest-version`, `/proposal-status`, `/rfc`
**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/sprint-diagram`, `/labels-sync`, `/initial-setup`, `/project-init`, `/project-sync`, `/review`, `/test-check`, `/test-gen`, `/debug-report`, `/debug-review`, `/suggest-version`, `/proposal-status`
#### [git-flow](./plugins/git-flow) *NEW in v3.0.0*
#### [git-flow](./plugins/git-flow/README.md) *NEW in v3.0.0*
**Git Workflow Automation**
Smart git operations with intelligent commit messages and branch management.
@@ -34,7 +34,7 @@ Smart git operations with intelligent commit messages and branch management.
**Commands:** `/commit`, `/commit-push`, `/commit-merge`, `/commit-sync`, `/branch-start`, `/branch-cleanup`, `/git-status`, `/git-config`
#### [pr-review](./plugins/pr-review) *NEW in v3.0.0*
#### [pr-review](./plugins/pr-review/README.md) *NEW in v3.0.0*
**Multi-Agent PR Review**
Comprehensive pull request review using specialized agents.
@@ -46,14 +46,14 @@ Comprehensive pull request review using specialized agents.
**Commands:** `/pr-review`, `/pr-summary`, `/pr-findings`, `/pr-diff`, `/initial-setup`, `/project-init`, `/project-sync`
#### [claude-config-maintainer](./plugins/claude-config-maintainer)
**CLAUDE.md and Settings Optimization**
#### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md)
**CLAUDE.md Optimization and Maintenance**
Analyze, optimize, and create CLAUDE.md configuration files. Audit and optimize settings.local.json permissions.
Analyze, optimize, and create CLAUDE.md configuration files for Claude Code projects.
**Commands:** `/analyze`, `/optimize`, `/init`, `/config-diff`, `/config-lint`, `/config-audit-settings`, `/config-optimize-settings`, `/config-permissions-map`
**Commands:** `/config-analyze`, `/config-optimize`, `/config-init`, `/config-diff`, `/config-lint`
#### [contract-validator](./plugins/contract-validator) *NEW in v5.0.0*
#### [contract-validator](./plugins/contract-validator/README.md) *NEW in v5.0.0*
**Cross-Plugin Compatibility Validation**
Validate plugin marketplaces for command conflicts, tool overlaps, and broken agent references.
@@ -68,7 +68,7 @@ Validate plugin marketplaces for command conflicts, tool overlaps, and broken ag
### Productivity
#### [clarity-assist](./plugins/clarity-assist) *NEW in v3.0.0*
#### [clarity-assist](./plugins/clarity-assist/README.md) *NEW in v3.0.0*
**Prompt Optimization with ND Accommodations**
Transform vague requests into clear specifications using structured methodology.
@@ -79,21 +79,21 @@ Transform vague requests into clear specifications using structured methodology.
**Commands:** `/clarify`, `/quick-clarify`
#### [doc-guardian](./plugins/doc-guardian)
#### [doc-guardian](./plugins/doc-guardian/README.md)
**Documentation Lifecycle Management**
Automatic documentation drift detection and synchronization.
**Commands:** `/doc-audit`, `/doc-sync`, `/changelog-gen`, `/doc-coverage`, `/stale-docs`
#### [project-hygiene](./plugins/project-hygiene)
#### [project-hygiene](./plugins/project-hygiene/README.md)
**Post-Task Cleanup Automation**
Hook-based cleanup that runs after Claude completes work.
### Security
#### [code-sentinel](./plugins/code-sentinel)
#### [code-sentinel](./plugins/code-sentinel/README.md)
**Security Scanning & Refactoring**
Security vulnerability detection and code refactoring tools.
@@ -102,7 +102,7 @@ Security vulnerability detection and code refactoring tools.
### Infrastructure
#### [cmdb-assistant](./plugins/cmdb-assistant)
#### [cmdb-assistant](./plugins/cmdb-assistant/README.md)
**NetBox CMDB Integration**
Full CRUD operations for network infrastructure management directly from Claude Code.
@@ -111,7 +111,7 @@ Full CRUD operations for network infrastructure management directly from Claude
### Data Engineering
#### [data-platform](./plugins/data-platform) *NEW in v4.0.0*
#### [data-platform](./plugins/data-platform/README.md) *NEW in v4.0.0*
**pandas, PostgreSQL/PostGIS, and dbt Integration**
Comprehensive data engineering toolkit with persistent DataFrame storage.
@@ -122,11 +122,11 @@ Comprehensive data engineering toolkit with persistent DataFrame storage.
- 100k row limit with chunking support
- Auto-detection of dbt projects
**Commands:** `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/lineage-viz`, `/run`, `/dbt-test`, `/data-quality`, `/data-review`, `/data-gate`, `/initial-setup`
**Commands:** `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/lineage-viz`, `/run`, `/dbt-test`, `/data-quality`, `/initial-setup`
### Visualization
#### [viz-platform](./plugins/viz-platform) *NEW in v4.0.0*
#### [viz-platform](./plugins/viz-platform/README.md) *NEW in v4.0.0*
**Dash Mantine Components Validation and Theming**
Visualization toolkit with version-locked component validation and design token theming.
@@ -138,26 +138,11 @@ Visualization toolkit with version-locked component validation and design token
- 5 Page tools for multi-page app structure
- Dual theme storage: user-level and project-level
**Commands:** `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/accessibility-check`, `/breakpoints`, `/design-review`, `/design-gate`, `/initial-setup`
## Domain Advisory Pattern
The marketplace supports cross-plugin domain advisory integration:
- **Domain Detection**: projman automatically detects when issues involve specialized domains (frontend/viz, data engineering)
- **Acceptance Criteria**: Domain-specific acceptance criteria are added to issues during planning
- **Execution Gates**: Domain validation gates (`/design-gate`, `/data-gate`) run before issue completion
- **Extensible**: New domains can be added by creating advisory agents and gate commands
**Current Domains:**
| Domain | Plugin | Gate Command |
|--------|--------|--------------|
| Visualization | viz-platform | `/design-gate` |
| Data | data-platform | `/data-gate` |
**Commands:** `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/accessibility-check`, `/breakpoints`, `/initial-setup`
## MCP Servers
MCP servers are **shared at repository root** and configured in `.mcp.json`.
MCP servers are **shared at repository root** with **symlinks** from plugins that use them.
### Gitea MCP Server (shared)
@@ -215,7 +200,7 @@ Cross-plugin compatibility validation tools.
| Category | Tools |
|----------|-------|
| Parse | `parse_plugin_interface`, `parse_claude_md_agents` |
| Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow`, `validate_workflow_integration` |
| Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow` |
| Report | `generate_compatibility_report`, `list_issues` |
## Installation
@@ -312,7 +297,7 @@ After installing plugins, the `/plugin` command may show `(no content)` - this i
| clarity-assist | `/clarity-assist:clarify` |
| doc-guardian | `/doc-guardian:doc-audit` |
| code-sentinel | `/code-sentinel:security-scan` |
| claude-config-maintainer | `/claude-config-maintainer:analyze` |
| claude-config-maintainer | `/claude-config-maintainer:config-analyze` |
| cmdb-assistant | `/cmdb-assistant:cmdb-search` |
| data-platform | `/data-platform:ingest` |
| viz-platform | `/viz-platform:chart` |

129
docs/CANONICAL-PATHS.md
View File

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

55
docs/COMMANDS-CHEATSHEET.md
View File

@@ -9,18 +9,22 @@ Quick reference for all commands in the Leo Claude Marketplace.
| Plugin | Command | Auto | Manual | Description |
|--------|---------|:----:|:------:|-------------|
| **projman** | `/sprint-plan` | | X | Start sprint planning with AI-guided architecture analysis and issue creation |
| **projman** | `/sprint-start` | | X | Begin sprint execution with dependency analysis and parallel task coordination (requires approval or `--force`) |
| **projman** | `/sprint-status` | | X | Check current sprint progress (add `--diagram` for Mermaid visualization) |
| **projman** | `/sprint-start` | | X | Begin sprint execution with dependency analysis and parallel task coordination |
| **projman** | `/sprint-status` | | X | Check current sprint progress and identify blockers |
| **projman** | `/review` | | X | Pre-sprint-close code quality review (debug artifacts, security, error handling) |
| **projman** | `/test` | | X | Run tests (`/test run`) or generate tests (`/test gen <target>`) |
| **projman** | `/test-check` | | X | Run tests and verify coverage before sprint close |
| **projman** | `/sprint-close` | | X | Complete sprint and capture lessons learned to Gitea Wiki |
| **projman** | `/labels-sync` | | X | Synchronize label taxonomy from Gitea |
| **projman** | `/setup` | | X | Auto-detect mode or use `--full`, `--quick`, `--sync`, `--clear-cache` |
| **projman** | *SessionStart hook* | X | | Detects git remote vs .env mismatch, warns to run `/setup --sync` |
| **projman** | `/debug` | | X | Diagnostics (`/debug report`) or investigate (`/debug review`) |
| **projman** | `/initial-setup` | | X | Full setup wizard: MCP server + system config + project config |
| **projman** | `/project-init` | | X | Quick project setup (assumes system config exists) |
| **projman** | `/project-sync` | | X | Sync config with git remote after repo move/rename |
| **projman** | *SessionStart hook* | X | | Detects git remote vs .env mismatch, warns to run /project-sync |
| **projman** | `/test-gen` | | X | Generate comprehensive tests for specified code |
| **projman** | `/debug-report` | | X | Run diagnostics and create structured issue in marketplace |
| **projman** | `/debug-review` | | X | Investigate diagnostic issues and propose fixes with approval gates |
| **projman** | `/suggest-version` | | X | Analyze CHANGELOG and recommend semantic version bump |
| **projman** | `/proposal-status` | | X | View proposal and implementation hierarchy with status |
| **projman** | `/rfc` | | X | RFC lifecycle management (`/rfc create\|list\|review\|approve\|reject`) |
| **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 |
@@ -54,9 +58,6 @@ Quick reference for all commands in the Leo Claude Marketplace.
| **claude-config-maintainer** | `/config-init` | | X | Initialize new CLAUDE.md for a project |
| **claude-config-maintainer** | `/config-diff` | | X | Track CLAUDE.md changes over time with behavioral impact |
| **claude-config-maintainer** | `/config-lint` | | X | Lint CLAUDE.md for anti-patterns and best practices |
| **claude-config-maintainer** | `/config-audit-settings` | | X | Audit settings.local.json permissions (100-point score) |
| **claude-config-maintainer** | `/config-optimize-settings` | | X | Optimize permissions (profiles, consolidation, dry-run) |
| **claude-config-maintainer** | `/config-permissions-map` | | X | Visual review layer + permission coverage map |
| **cmdb-assistant** | `/initial-setup` | | X | Setup wizard for NetBox MCP server |
| **cmdb-assistant** | `/cmdb-search` | | X | Search NetBox for devices, IPs, sites |
| **cmdb-assistant** | `/cmdb-device` | | X | Manage network devices (create, view, update, delete) |
@@ -90,11 +91,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
| **viz-platform** | `/chart-export` | | X | Export charts to PNG, SVG, PDF via kaleido |
| **viz-platform** | `/accessibility-check` | | X | Color blind validation (WCAG contrast ratios) |
| **viz-platform** | `/breakpoints` | | X | Configure responsive layout breakpoints |
| **viz-platform** | `/design-review` | | X | Detailed design system audits |
| **viz-platform** | `/design-gate` | | X | Binary pass/fail design system validation gates |
| **viz-platform** | *SessionStart hook* | X | | Checks DMC version (non-blocking warning) |
| **data-platform** | `/data-review` | | X | Comprehensive data integrity audits |
| **data-platform** | `/data-gate` | | X | Binary pass/fail data integrity gates |
| **contract-validator** | `/validate-contracts` | | X | Full marketplace compatibility validation |
| **contract-validator** | `/check-agent` | | X | Validate single agent definition |
| **contract-validator** | `/list-interfaces` | | X | Show all plugin interfaces |
@@ -107,7 +104,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
| Category | Plugins | Primary Use |
|----------|---------|-------------|
| **Setup** | projman, pr-review, cmdb-assistant, data-platform | `/setup`, `/initial-setup` |
| **Setup** | projman, pr-review, cmdb-assistant, data-platform | `/initial-setup`, `/project-init` |
| **Task Planning** | projman, clarity-assist | Sprint management, requirement clarification |
| **Code Quality** | code-sentinel, pr-review | Security scanning, PR reviews |
| **Documentation** | doc-guardian, claude-config-maintainer | Doc sync, CLAUDE.md maintenance |
@@ -136,22 +133,6 @@ Quick reference for all commands in the Leo Claude Marketplace.
## Dev Workflow Examples
### Example 0: RFC-Driven Feature Development
Full workflow from idea to implementation using RFCs:
```
1. /clarify # Clarify the feature idea
2. /rfc create # Create RFC from clarified spec
... refine RFC content ...
3. /rfc review 0001 # Submit RFC for review
... review discussion ...
4. /rfc approve 0001 # Approve RFC for implementation
5. /sprint-plan # Select approved RFC for sprint
... implement feature ...
6. /sprint-close # Complete sprint, RFC marked Implemented
```
### Example 1: Starting a New Feature Sprint
A typical workflow for planning and executing a feature sprint:
@@ -164,9 +145,9 @@ A typical workflow for planning and executing a feature sprint:
5. /branch-start feat/... # Create feature branch
... implement features ...
6. /commit # Commit with conventional message
7. /sprint-status --diagram # Check progress with visualization
7. /sprint-status # Check progress mid-sprint
8. /review # Pre-close quality review
9. /test run # Verify test coverage
9. /test-check # Verify test coverage
10. /sprint-close # Capture lessons learned
```
@@ -213,7 +194,7 @@ Safe refactoring with preview:
1. /refactor-dry # Preview opportunities
2. /security-scan # Baseline security check
3. /refactor # Apply improvements
4. /test run # Verify nothing broke
4. /test-check # Verify nothing broke
5. /commit # Commit with descriptive message
```
@@ -246,7 +227,7 @@ Working with data pipelines:
Setting up the marketplace for the first time:
```
1. /setup --full # Full setup: MCP + system config + project
1. /initial-setup # Full setup: MCP + system config + project
# → Follow prompts for Gitea URL, org
# → Add token manually when prompted
# → Confirm repository name
@@ -260,7 +241,7 @@ Setting up the marketplace for the first time:
Adding a new project when system config exists:
```
1. /setup --quick # Quick project setup (auto-detected)
1. /project-init # Quick project setup
# → Confirms detected repo name
# → Creates .env
2. /labels-sync # Sync Gitea labels
@@ -296,4 +277,4 @@ Ensure credentials are configured in `~/.config/claude/gitea.env`, `~/.config/cl
---
*Last Updated: 2026-02-02*
*Last Updated: 2026-01-28*

226
docs/CONFIGURATION.md
View File

@@ -9,10 +9,10 @@ Centralized configuration documentation for all plugins and MCP servers in the L
**After installing the marketplace and plugins via Claude Code:**
```
/setup
/initial-setup
```
The interactive wizard auto-detects what's needed and handles everything except manually adding your API tokens.
The interactive wizard handles everything except manually adding your API tokens.
---
@@ -25,8 +25,7 @@ The interactive wizard auto-detects what's needed and handles everything except
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
/setup --full
(or /setup auto-detects)
/initial-setup
│
┌──────────────────────────────┼──────────────────────────────┐
▼ ▼ ▼
@@ -79,8 +78,8 @@ The interactive wizard auto-detects what's needed and handles everything except
│
┌───────────────┴───────────────┐
▼ ▼
/setup --quick /setup
(explicit mode) (auto-detects mode)
/project-init /initial-setup
(direct path) (smart detection)
│ │
│ ┌──────────┴──────────┐
│ ▼ ▼
@@ -109,7 +108,7 @@ The interactive wizard auto-detects what's needed and handles everything except
## What Runs Automatically vs User Interaction
### `/setup --full` - Full Setup
### `/initial-setup` - Full Setup
| Phase | Type | What Happens |
|-------|------|--------------|
@@ -121,7 +120,7 @@ The interactive wizard auto-detects what's needed and handles everything except
| **6. Project Config** | Automated | Creates `.env` file, checks `.gitignore` |
| **7. Validation** | Automated | Tests API connectivity, shows summary |
### `/setup --quick` - Quick Project Setup
### `/project-init` - Quick Project Setup
| Phase | Type | What Happens |
|-------|------|--------------|
@@ -132,25 +131,23 @@ The interactive wizard auto-detects what's needed and handles everything except
---
## One Command, Three Modes
## Three Commands for Different Scenarios
| Mode | When to Use | What It Does |
|------|-------------|--------------|
| `/setup` | Any time | Auto-detects: runs full, quick, or sync as needed |
| `/setup --full` | First time on a machine | Full setup: MCP server + system config + project config |
| `/setup --quick` | Starting a new project | Quick setup: project config only (assumes system is ready) |
| `/setup --sync` | After repo move/rename | Updates .env to match current git remote |
**Auto-detection logic:**
1. No system config → **full** mode
2. System config exists, no project config → **quick** mode
3. Both exist, git remote differs → **sync** mode
4. Both exist, match → already configured, offer to reconfigure
| Command | When to Use | What It Does |
|---------|-------------|--------------|
| `/initial-setup` | First time on a machine | Full setup: MCP server + system config + project config |
| `/project-init` | Starting a new project | Quick setup: project config only (assumes system is ready) |
| `/project-sync` | After repo move/rename | Updates .env to match current git remote |
**Typical workflow:**
1. Install plugin → run `/setup` (auto-runs full mode)
2. Start new project → run `/setup` (auto-runs quick mode)
3. Repository moved? → run `/setup` (auto-runs sync mode)
1. Install plugin → run `/initial-setup` (once per machine)
2. Start new project → run `/project-init` (once per project)
3. Repository moved? → run `/project-sync` (updates config)
**Smart features:**
- `/initial-setup` detects existing system config and offers quick project setup
- All commands validate org/repo via Gitea API before saving (auto-fills if verified)
- SessionStart hook automatically detects git remote vs .env mismatches
---
@@ -182,7 +179,7 @@ This marketplace uses a **hybrid configuration** approach:
**Benefits:**
- Single token per service (update once, use everywhere)
- Easy multi-project setup (just run `/setup` in each project)
- Easy multi-project setup (just run `/project-init` in each project)
- Security (tokens never committed to git, never typed into AI chat)
- Project isolation (each project can override defaults)
@@ -190,7 +187,7 @@ This marketplace uses a **hybrid configuration** approach:
## Prerequisites
Before running `/setup`:
Before running `/initial-setup`:
1. **Python 3.10+** installed
```bash
@@ -213,10 +210,10 @@ Before running `/setup`:
Run the setup wizard in Claude Code:
```
/setup
/initial-setup
```
The wizard will guide you through each step interactively and auto-detect the appropriate mode.
The wizard will guide you through each step interactively.
**Note:** After first-time setup, you'll need to restart your Claude Code session for MCP tools to become available.
@@ -385,10 +382,10 @@ PR_REVIEW_AUTO_SUBMIT=false
## Plugin Configuration Summary
| Plugin | System Config | Project Config | Setup Command |
|--------|---------------|----------------|---------------|
| **projman** | gitea.env | .env (GITEA_REPO=owner/repo) | `/setup` |
| **pr-review** | gitea.env | .env (GITEA_REPO=owner/repo) | `/initial-setup` |
| Plugin | System Config | Project Config | Setup Commands |
|--------|---------------|----------------|----------------|
| **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` |
@@ -398,7 +395,6 @@ PR_REVIEW_AUTO_SUBMIT=false
| **code-sentinel** | None | None | None needed |
| **project-hygiene** | None | None | None needed |
| **claude-config-maintainer** | None | None | None needed |
| **contract-validator** | None | None | `/initial-setup` |
---
@@ -406,150 +402,21 @@ PR_REVIEW_AUTO_SUBMIT=false
Once system-level config is set up, adding new projects is simple:
**Option 1: Use `/project-init` (faster)**
```
cd ~/projects/new-project
/setup
/project-init
```
The command auto-detects that system config exists and runs quick project setup.
---
## Installing Plugins to Consumer Projects
The marketplace provides scripts to install plugins into consumer projects. This sets up the MCP server connections and adds CLAUDE.md integration snippets.
### Install a Plugin
```bash
cd /path/to/leo-claude-mktplace
./scripts/install-plugin.sh <plugin-name> <target-project-path>
**Option 2: Use `/initial-setup` (auto-detects)**
```
cd ~/projects/new-project
/initial-setup
# → Detects system config exists
# → Offers "Quick project setup" option
```
**Examples:**
```bash
# Install data-platform to a portfolio project
./scripts/install-plugin.sh data-platform ~/projects/personal-portfolio
# Install multiple plugins
./scripts/install-plugin.sh viz-platform ~/projects/personal-portfolio
./scripts/install-plugin.sh projman ~/projects/personal-portfolio
```
**What it does:**
1. Validates the plugin exists in the marketplace
2. Adds MCP server entry to target's `.mcp.json` (if plugin has MCP server)
3. Appends integration snippet to target's `CLAUDE.md`
4. Reports changes and lists available commands
**After installation:** Restart your Claude Code session for MCP tools to become available.
### Uninstall a Plugin
```bash
./scripts/uninstall-plugin.sh <plugin-name> <target-project-path>
```
Removes the MCP server entry and CLAUDE.md integration section.
### List Installed Plugins
```bash
./scripts/list-installed.sh <target-project-path>
```
Shows which marketplace plugins are installed, partially installed, or available.
**Output example:**
```
✓ Fully Installed:
PLUGIN VERSION DESCRIPTION
------ ------- -----------
data-platform 1.3.0 pandas, PostgreSQL, and dbt integration...
viz-platform 1.1.0 DMC validation, Plotly charts, and theming...
○ Available (not installed):
projman 3.4.0 Sprint planning and project management...
```
### Plugins with MCP Servers
Not all plugins have MCP servers. The install script handles this automatically:
| Plugin | Has MCP Server | Notes |
|--------|---------------|-------|
| data-platform | ✓ | pandas, PostgreSQL, dbt tools |
| viz-platform | ✓ | DMC validation, chart, theme tools |
| contract-validator | ✓ | Plugin compatibility validation |
| cmdb-assistant | ✓ (via netbox) | NetBox CMDB tools |
| projman | ✓ (via gitea) | Issue, wiki, PR tools |
| pr-review | ✓ (via gitea) | PR review tools |
| git-flow | ✗ | Commands only |
| doc-guardian | ✗ | Commands and hooks only |
| code-sentinel | ✗ | Commands and hooks only |
| clarity-assist | ✗ | Commands only |
### Script Requirements
- **jq** must be installed (`sudo apt install jq`)
- Scripts are idempotent (safe to run multiple times)
---
## Agent Model Selection
Marketplace agents specify their preferred model using Claude Code's `model` frontmatter field. This allows cost/performance optimization per agent.
### Supported Values
| Value | Description |
|-------|-------------|
| `sonnet` | Default. Balanced performance and cost. |
| `opus` | Higher reasoning depth. Use for complex analysis. |
| `haiku` | Faster, lower cost. Use for mechanical tasks. |
| `inherit` | Use session's current model setting. |
### How It Works
Each agent in `plugins/{plugin}/agents/{agent}.md` has frontmatter like:
```yaml
---
name: planner
description: Sprint planning agent - thoughtful architecture analysis
model: sonnet
---
```
Claude Code reads this field when invoking the agent as a subagent.
### Model Assignments
Agents are assigned models based on their task complexity:
| Model | Agents | Rationale |
|-------|--------|-----------|
| **sonnet** | Planner, Orchestrator, Executor, Code Reviewer, Coordinator, Security Reviewers, Performance Analyst, Data Advisor, Data Analysis, Design Reviewer, Layout Builder, Full Validation, Doc Analyzer, Clarity Coach, Maintainer, CMDB Assistant, Refactor Advisor | Standard reasoning, tool orchestration, code generation |
| **haiku** | Maintainability Auditor, Test Validator, Component Check, Theme Setup, Agent Check, Data Ingestion, Git Assistant | Pattern matching, quick validation, mechanical tasks |
### Overriding Model Selection
**Per-agent override:** Edit the `model:` field in the agent file:
```bash
# Change executor to use opus for heavy implementation work
nano plugins/projman/agents/executor.md
# Change model: sonnet to model: opus
```
**Session-level:** Users on Opus subscription can change the agent's model to `inherit` to use whatever model the session is using.
### Best Practices
1. **Default to sonnet** - Good balance for most tasks
2. **Use haiku for speed-sensitive agents** - Sub-agents dispatched in parallel, read-only tasks
3. **Reserve opus for heavy analysis** - Only when sonnet's reasoning isn't sufficient
4. **Use inherit sparingly** - Only when you want session-level control
Both approaches work. Use `/project-init` when you know the system is already configured.
---
@@ -557,12 +424,12 @@ nano plugins/projman/agents/executor.md
### API Validation
When running `/setup`, the command:
When running `/initial-setup`, `/project-init`, or `/project-sync`, the commands:
1. **Detects** organization and repository from git remote URL
2. **Validates** via Gitea API: `GET /api/v1/repos/{org}/{repo}`
3. **Auto-fills** if repository exists and is accessible (no confirmation needed)
4. **Asks for confirmation** only if validation fails (404 or permission error)
1. **Detect** organization and repository from git remote URL
2. **Validate** via Gitea API: `GET /api/v1/repos/{org}/{repo}`
3. **Auto-fill** if repository exists and is accessible (no confirmation needed)
4. **Ask for confirmation** only if validation fails (404 or permission error)
This catches typos and permission issues before saving configuration.
@@ -572,7 +439,7 @@ When you start a Claude Code session, a hook automatically:
1. Reads `GITEA_REPO` (in `owner/repo` format) from `.env`
2. Compares with current `git remote get-url origin`
3. **Warns** if mismatch detected: "Repository location mismatch. Run `/setup --sync` to update."
3. **Warns** if mismatch detected: "Repository location mismatch. Run `/project-sync` to update."
This helps when you:
- Move a repository to a different organization
@@ -634,8 +501,9 @@ If you get 401, regenerate your token in Gitea.
# Check venv exists
ls /path/to/mcp-servers/gitea/.venv
# If missing, create venv (do NOT delete existing venvs)
# Reinstall if missing
cd /path/to/mcp-servers/gitea
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
@@ -667,7 +535,7 @@ cat .env
3. **Never type tokens into AI chat**
- Always edit config files directly in your editor
- The `/setup` wizard respects this
- The `/initial-setup` wizard respects this
4. **Rotate tokens periodically**
- Every 6-12 months

28
docs/DEBUGGING-CHECKLIST.md
View File

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

6
docs/UPDATING.md
View File

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

20
mcp-servers/contract-validator/.doc-guardian-queue
View File

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

35
mcp-servers/contract-validator/mcp_server/server.py
View File

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

155
mcp-servers/contract-validator/mcp_server/validation_tools.py
View File

@@ -26,7 +26,6 @@ class IssueType(str, Enum):
OPTIONAL_DEPENDENCY = "optional_dependency"
UNDECLARED_OUTPUT = "undeclared_output"
INVALID_SEQUENCE = "invalid_sequence"
MISSING_INTEGRATION = "missing_integration"
class ValidationIssue(BaseModel):
@@ -66,18 +65,6 @@ class DataFlowResult(BaseModel):
issues: list[ValidationIssue] = []
class WorkflowIntegrationResult(BaseModel):
"""Result of workflow integration validation for domain plugins"""
plugin_name: str
domain_label: str
valid: bool
gate_command_found: bool
gate_contract: Optional[str] = None # Contract version declared by gate command
review_command_found: bool
advisory_agent_found: bool
issues: list[ValidationIssue] = []
class ValidationTools:
"""Tools for validating plugin compatibility and agent references"""
@@ -349,145 +336,3 @@ class ValidationTools:
)
return result.model_dump()
async def validate_workflow_integration(
self,
plugin_path: str,
domain_label: str,
expected_contract: Optional[str] = None
) -> dict:
"""
Validate that a domain plugin exposes required advisory interfaces.
Checks for:
- Gate command (e.g., /design-gate, /data-gate) - REQUIRED
- Gate contract version (gate_contract in frontmatter) - INFO if missing
- Review command (e.g., /design-review, /data-review) - recommended
- Advisory agent referencing the domain label - recommended
Args:
plugin_path: Path to the domain plugin directory
domain_label: The Domain/* label it claims to handle (e.g., Domain/Viz)
expected_contract: Expected contract version (e.g., 'v1'). If provided,
validates the gate command's contract matches.
Returns:
Validation result with found interfaces and issues
"""
import re
plugin_path_obj = Path(plugin_path)
issues = []
# Extract plugin name from path
plugin_name = plugin_path_obj.name
if not plugin_path_obj.exists():
return {
"error": f"Plugin directory not found: {plugin_path}",
"plugin_path": plugin_path,
"domain_label": domain_label
}
# Extract domain short name from label (e.g., "Domain/Viz" -> "viz", "Domain/Data" -> "data")
domain_short = domain_label.split("/")[-1].lower() if "/" in domain_label else domain_label.lower()
# Check for gate command
commands_dir = plugin_path_obj / "commands"
gate_command_found = False
gate_contract = None
gate_patterns = ["pass", "fail", "PASS", "FAIL", "Binary pass/fail", "gate"]
if commands_dir.exists():
for cmd_file in commands_dir.glob("*.md"):
if "gate" in cmd_file.name.lower():
# Verify it's actually a gate command by checking content
content = cmd_file.read_text()
if any(pattern in content for pattern in gate_patterns):
gate_command_found = True
# Parse frontmatter for gate_contract
frontmatter_match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
if frontmatter_match:
frontmatter = frontmatter_match.group(1)
contract_match = re.search(r'gate_contract:\s*(\S+)', frontmatter)
if contract_match:
gate_contract = contract_match.group(1)
break
if not gate_command_found:
issues.append(ValidationIssue(
severity=IssueSeverity.ERROR,
issue_type=IssueType.MISSING_INTEGRATION,
message=f"Plugin '{plugin_name}' lacks a gate command for domain '{domain_label}'",
location=str(commands_dir),
suggestion=f"Create commands/{domain_short}-gate.md with binary PASS/FAIL output"
))
# Check for review command
review_command_found = False
if commands_dir.exists():
for cmd_file in commands_dir.glob("*.md"):
if "review" in cmd_file.name.lower() and "gate" not in cmd_file.name.lower():
review_command_found = True
break
if not review_command_found:
issues.append(ValidationIssue(
severity=IssueSeverity.WARNING,
issue_type=IssueType.MISSING_INTEGRATION,
message=f"Plugin '{plugin_name}' lacks a review command for domain '{domain_label}'",
location=str(commands_dir),
suggestion=f"Create commands/{domain_short}-review.md for detailed audits"
))
# Check for advisory agent
agents_dir = plugin_path_obj / "agents"
advisory_agent_found = False
if agents_dir.exists():
for agent_file in agents_dir.glob("*.md"):
content = agent_file.read_text()
# Check if agent references the domain label or gate command
if domain_label in content or f"{domain_short}-gate" in content.lower() or "advisor" in agent_file.name.lower() or "reviewer" in agent_file.name.lower():
advisory_agent_found = True
break
if not advisory_agent_found:
issues.append(ValidationIssue(
severity=IssueSeverity.WARNING,
issue_type=IssueType.MISSING_INTEGRATION,
message=f"Plugin '{plugin_name}' lacks an advisory agent for domain '{domain_label}'",
location=str(agents_dir) if agents_dir.exists() else str(plugin_path_obj),
suggestion=f"Create agents/{domain_short}-advisor.md referencing '{domain_label}'"
))
# Check gate contract version
if gate_command_found:
if not gate_contract:
issues.append(ValidationIssue(
severity=IssueSeverity.INFO,
issue_type=IssueType.MISSING_INTEGRATION,
message=f"Gate command does not declare a contract version",
location=str(commands_dir),
suggestion="Consider adding `gate_contract: v1` to frontmatter for version tracking"
))
elif expected_contract and gate_contract != expected_contract:
issues.append(ValidationIssue(
severity=IssueSeverity.WARNING,
issue_type=IssueType.INTERFACE_MISMATCH,
message=f"Contract version mismatch: gate declares {gate_contract}, projman expects {expected_contract}",
location=str(commands_dir),
suggestion=f"Update domain-consultation.md Gate Command Reference table to {gate_contract}, or update gate command to {expected_contract}"
))
result = WorkflowIntegrationResult(
plugin_name=plugin_name,
domain_label=domain_label,
valid=gate_command_found, # Only gate is required for validity
gate_command_found=gate_command_found,
gate_contract=gate_contract,
review_command_found=review_command_found,
advisory_agent_found=advisory_agent_found,
issues=issues
)
return result.model_dump()

258
mcp-servers/contract-validator/tests/test_validation_tools.py
View File

@@ -254,261 +254,3 @@ async def test_validate_data_flow_missing_producer(validation_tools, tmp_path):
# Should have warning about missing producer
warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
assert len(warning_issues) > 0
# --- Workflow Integration Tests ---
@pytest.fixture
def domain_plugin_complete(tmp_path):
"""Create a complete domain plugin with gate, review, and advisory agent"""
plugin_dir = tmp_path / "viz-platform"
plugin_dir.mkdir()
(plugin_dir / ".claude-plugin").mkdir()
(plugin_dir / "commands").mkdir()
(plugin_dir / "agents").mkdir()
# Gate command with PASS/FAIL pattern
gate_cmd = plugin_dir / "commands" / "design-gate.md"
gate_cmd.write_text("""# /design-gate
Binary pass/fail validation gate for design system compliance.
## Output
- **PASS**: All design system checks passed
- **FAIL**: Design system violations detected
""")
# Review command
review_cmd = plugin_dir / "commands" / "design-review.md"
review_cmd.write_text("""# /design-review
Comprehensive design system audit.
""")
# Advisory agent
agent = plugin_dir / "agents" / "design-reviewer.md"
agent.write_text("""# design-reviewer
Design system compliance auditor.
Handles issues with `Domain/Viz` label.
""")
return str(plugin_dir)
@pytest.fixture
def domain_plugin_missing_gate(tmp_path):
"""Create domain plugin with review and agent but no gate command"""
plugin_dir = tmp_path / "data-platform"
plugin_dir.mkdir()
(plugin_dir / ".claude-plugin").mkdir()
(plugin_dir / "commands").mkdir()
(plugin_dir / "agents").mkdir()
# Review command (but no gate)
review_cmd = plugin_dir / "commands" / "data-review.md"
review_cmd.write_text("""# /data-review
Data integrity audit.
""")
# Advisory agent
agent = plugin_dir / "agents" / "data-advisor.md"
agent.write_text("""# data-advisor
Data integrity advisor for Domain/Data issues.
""")
return str(plugin_dir)
@pytest.fixture
def domain_plugin_minimal(tmp_path):
"""Create minimal plugin with no commands or agents"""
plugin_dir = tmp_path / "minimal-plugin"
plugin_dir.mkdir()
(plugin_dir / ".claude-plugin").mkdir()
readme = plugin_dir / "README.md"
readme.write_text("# Minimal Plugin\n\nNo commands or agents.")
return str(plugin_dir)
@pytest.mark.asyncio
async def test_validate_workflow_integration_complete(validation_tools, domain_plugin_complete):
"""Test complete domain plugin returns valid with all interfaces found"""
result = await validation_tools.validate_workflow_integration(
domain_plugin_complete,
"Domain/Viz"
)
assert "error" not in result
assert result["valid"] is True
assert result["gate_command_found"] is True
assert result["review_command_found"] is True
assert result["advisory_agent_found"] is True
# May have INFO issue about missing contract version (not an error/warning)
error_or_warning = [i for i in result["issues"]
if i["severity"].value in ("error", "warning")]
assert len(error_or_warning) == 0
@pytest.mark.asyncio
async def test_validate_workflow_integration_missing_gate(validation_tools, domain_plugin_missing_gate):
"""Test plugin missing gate command returns invalid with ERROR"""
result = await validation_tools.validate_workflow_integration(
domain_plugin_missing_gate,
"Domain/Data"
)
assert "error" not in result
assert result["valid"] is False
assert result["gate_command_found"] is False
assert result["review_command_found"] is True
assert result["advisory_agent_found"] is True
# Should have one ERROR for missing gate
error_issues = [i for i in result["issues"] if i["severity"].value == "error"]
assert len(error_issues) == 1
assert "gate" in error_issues[0]["message"].lower()
@pytest.mark.asyncio
async def test_validate_workflow_integration_minimal(validation_tools, domain_plugin_minimal):
"""Test minimal plugin returns invalid with multiple issues"""
result = await validation_tools.validate_workflow_integration(
domain_plugin_minimal,
"Domain/Test"
)
assert "error" not in result
assert result["valid"] is False
assert result["gate_command_found"] is False
assert result["review_command_found"] is False
assert result["advisory_agent_found"] is False
# Should have one ERROR (gate) and two WARNINGs (review, agent)
error_issues = [i for i in result["issues"] if i["severity"].value == "error"]
warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
assert len(error_issues) == 1
assert len(warning_issues) == 2
@pytest.mark.asyncio
async def test_validate_workflow_integration_nonexistent_plugin(validation_tools, tmp_path):
"""Test error when plugin directory doesn't exist"""
result = await validation_tools.validate_workflow_integration(
str(tmp_path / "nonexistent"),
"Domain/Test"
)
assert "error" in result
assert "not found" in result["error"].lower()
# --- Gate Contract Version Tests ---
@pytest.fixture
def domain_plugin_with_contract(tmp_path):
"""Create domain plugin with gate_contract: v1 in frontmatter"""
plugin_dir = tmp_path / "viz-platform-versioned"
plugin_dir.mkdir()
(plugin_dir / ".claude-plugin").mkdir()
(plugin_dir / "commands").mkdir()
(plugin_dir / "agents").mkdir()
# Gate command with gate_contract in frontmatter
gate_cmd = plugin_dir / "commands" / "design-gate.md"
gate_cmd.write_text("""---
description: Design system compliance gate (pass/fail)
gate_contract: v1
---
# /design-gate
Binary pass/fail validation gate for design system compliance.
## Output
- **PASS**: All design system checks passed
- **FAIL**: Design system violations detected
""")
# Review command
review_cmd = plugin_dir / "commands" / "design-review.md"
review_cmd.write_text("""# /design-review
Comprehensive design system audit.
""")
# Advisory agent
agent = plugin_dir / "agents" / "design-reviewer.md"
agent.write_text("""# design-reviewer
Design system compliance auditor for Domain/Viz issues.
""")
return str(plugin_dir)
@pytest.mark.asyncio
async def test_validate_workflow_contract_match(validation_tools, domain_plugin_with_contract):
"""Test that matching expected_contract produces no warning"""
result = await validation_tools.validate_workflow_integration(
domain_plugin_with_contract,
"Domain/Viz",
expected_contract="v1"
)
assert "error" not in result
assert result["valid"] is True
assert result["gate_contract"] == "v1"
# Should have no warnings about contract mismatch
warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
contract_warnings = [i for i in warning_issues if "contract" in i["message"].lower()]
assert len(contract_warnings) == 0
@pytest.mark.asyncio
async def test_validate_workflow_contract_mismatch(validation_tools, domain_plugin_with_contract):
"""Test that mismatched expected_contract produces WARNING"""
result = await validation_tools.validate_workflow_integration(
domain_plugin_with_contract,
"Domain/Viz",
expected_contract="v2" # Gate has v1
)
assert "error" not in result
assert result["valid"] is True # Contract mismatch doesn't affect validity
assert result["gate_contract"] == "v1"
# Should have warning about contract mismatch
warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
contract_warnings = [i for i in warning_issues if "contract" in i["message"].lower()]
assert len(contract_warnings) == 1
assert "mismatch" in contract_warnings[0]["message"].lower()
assert "v1" in contract_warnings[0]["message"]
assert "v2" in contract_warnings[0]["message"]
@pytest.mark.asyncio
async def test_validate_workflow_no_contract(validation_tools, domain_plugin_complete):
"""Test that missing gate_contract produces INFO suggestion"""
result = await validation_tools.validate_workflow_integration(
domain_plugin_complete,
"Domain/Viz"
)
assert "error" not in result
assert result["valid"] is True
assert result["gate_contract"] is None
# Should have info issue about missing contract
info_issues = [i for i in result["issues"] if i["severity"].value == "info"]
contract_info = [i for i in info_issues if "contract" in i["message"].lower()]
assert len(contract_info) == 1
assert "does not declare" in contract_info[0]["message"].lower()

55
mcp-servers/gitea/mcp_server/server.py
View File

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

38
mcp-servers/gitea/mcp_server/tools/wiki.py
View File

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

5
mcp-servers/viz-platform/.doc-guardian-queue
View File

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

2
mcp-servers/viz-platform/README.md
View File

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

2
plugins/clarity-assist/.claude-plugin/plugin.json
View File

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

103
plugins/clarity-assist/README.md Normal file
View File

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

6
plugins/clarity-assist/agents/clarity-coach.md
View File

@@ -1,9 +1,3 @@
---
name: clarity-coach
description: Patient, structured coach helping users articulate requirements clearly. Uses neurodivergent-friendly communication patterns.
model: sonnet
---
# Clarity Coach Agent
## Visual Output Requirements

163
plugins/clarity-assist/commands/clarify.md
View File

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

93
plugins/clarity-assist/commands/quick-clarify.md
View File

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

9
plugins/clarity-assist/hooks/hooks.json
View File

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

42
plugins/clarity-assist/hooks/vagueness-check.sh
View File

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

76
plugins/clarity-assist/skills/4d-methodology.md
View File

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

86
plugins/clarity-assist/skills/clarification-techniques.md
View File

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

57
plugins/clarity-assist/skills/escalation-patterns.md
View File

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

74
plugins/clarity-assist/skills/nd-accommodations.md
View File

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

8
plugins/claude-config-maintainer/.claude-plugin/plugin.json
View File

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

126
plugins/claude-config-maintainer/README.md Normal file
View File

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

91
plugins/claude-config-maintainer/agents/maintainer.md
View File

@@ -1,7 +1,6 @@
---
name: maintainer
description: CLAUDE.md optimization and maintenance agent
model: sonnet
---
# CLAUDE.md Maintainer Agent
@@ -115,54 +114,7 @@ Report plugin coverage percentage and offer to add missing integrations:
- Display the integration content that would be added
- Ask user for confirmation before modifying CLAUDE.md
### 2. Audit Settings Files
When auditing settings files, perform:
#### A. Permission Analysis
Read `.claude/settings.local.json` (primary) and check `.claude/settings.json` and `~/.claude.json` project entries (secondary).
Evaluate using `skills/settings-optimization.md`:
**Redundancy:**
- Duplicate entries in allow/deny arrays
- Subset patterns covered by broader patterns
- Patterns that could be merged
**Coverage:**
- Common safe tools missing from allow list
- MCP server tools not covered
- Directory scopes with no matching permission
**Safety Alignment:**
- Deny rules cover secrets and destructive commands
- Allow rules don't bypass active review layers
- No overly broad patterns without justification
**Profile Fit:**
- Compare against recommended profile for the project's review architecture
- Identify specific additions/removals to reach target profile
#### B. Review Layer Verification
Before recommending auto-allow patterns, verify active review layers:
1. Read `plugins/*/hooks/hooks.json` for each installed plugin
2. Map hook types (PreToolUse, PostToolUse) to tool matchers (Write, Edit, Bash)
3. Confirm plugins are listed in `.claude-plugin/marketplace.json`
4. Only recommend auto-allow for scopes covered by ≥2 verified review layers
#### C. Settings Efficiency Score (100 points)
| Category | Points |
|----------|--------|
| Redundancy | 25 |
| Coverage | 25 |
| Safety Alignment | 25 |
| Profile Fit | 25 |
### 3. Optimize CLAUDE.md Structure
### 2. Optimize CLAUDE.md Structure
**Recommended Structure:**
@@ -197,7 +149,7 @@ Common issues and solutions.
- Use headers that scan easily
- Include examples where they add clarity
### 4. Apply Best Practices
### 3. Apply Best Practices
**DO:**
- Use clear, direct language
@@ -214,7 +166,7 @@ Common issues and solutions.
- Add generic advice that applies to all projects
- Use emojis unless project requires them
### 5. Generate Improvement Reports
### 4. Generate Improvement Reports
After analyzing a CLAUDE.md, provide:
@@ -250,7 +202,7 @@ Suggested Actions:
Would you like me to implement these improvements?
```
### 6. Insert Plugin Integrations
### 5. Insert Plugin Integrations
When adding plugin integration content to CLAUDE.md:
@@ -285,7 +237,7 @@ Add this integration to CLAUDE.md?
- Allow users to skip specific plugins they don't want documented
- Preserve existing CLAUDE.md structure and content
### 7. Create New CLAUDE.md Files
### 6. Create New CLAUDE.md Files
When creating a new CLAUDE.md:
@@ -325,39 +277,6 @@ Every CLAUDE.md should have:
1. **Project Overview** - What is this?
2. **Quick Start** - How do I build/test/run?
3. **Important Rules** - What must I NOT do?
4. **Pre-Change Protocol** - Mandatory dependency check before code changes
### Pre-Change Protocol Section (MANDATORY)
**This section is REQUIRED in every CLAUDE.md.** It ensures Claude performs comprehensive dependency analysis before making any code changes.
```markdown
## ⛔ MANDATORY: Before Any Code Change
**Claude MUST show this checklist BEFORE editing any file:**
### 1. Impact Search Results
Run and show output of:
```bash
grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
```
### 2. Files That Will Be Affected
Numbered list of every file to be modified, with the specific change for each.
### 3. Files Searched But Not Changed (and why)
Proof that related files were checked and determined unchanged.
### 4. Documentation That References This
List of docs that mention this feature/script/function.
**User verifies this list before Claude proceeds. If Claude skips this, stop immediately.**
### After Changes
Run the same grep and show results proving no references remain unaddressed.
```
**When analyzing a CLAUDE.md, flag as HIGH priority issue if this section is missing.**
### Optional Sections (as needed)

30
plugins/claude-config-maintainer/claude-md-integration.md
View File

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

203
plugins/claude-config-maintainer/commands/analyze.md
View File

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

204
plugins/claude-config-maintainer/commands/config-audit-settings.md
View File

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

249
plugins/claude-config-maintainer/commands/config-diff.md
View File

@@ -4,45 +4,248 @@ description: Show diff between current CLAUDE.md and last commit
# Compare CLAUDE.md Changes
Show differences between CLAUDE.md versions to track configuration drift.
## Skills to Load
- skills/visual-header.md
- skills/diff-analysis.md
This command shows differences between your current CLAUDE.md file and previous versions, helping track configuration drift and review changes before committing.
## Visual Output
Display: `CONFIG-MAINTAINER - CLAUDE.md Diff`
When executing this command, display the plugin header:
```
┌──────────────────────────────────────────────────────────────────┐
│ ⚙️ CONFIG-MAINTAINER · CLAUDE.md Diff │
└──────────────────────────────────────────────────────────────────┘
```
Then proceed with the diff.
## What This Command Does
1. **Detect CLAUDE.md Location** - Finds the project's CLAUDE.md file
2. **Compare Versions** - Shows diff against last commit or specified revision
3. **Highlight Sections** - Groups changes by affected sections
4. **Summarize Impact** - Explains what the changes mean for Claude's behavior
## Usage
```
/config-diff # Working vs last commit
/config-diff --commit=abc1234 # Working vs specific commit
/config-diff --from=v1.0 --to=v2.0 # Compare two commits
/config-diff --section="Critical Rules" # Specific section only
/config-diff
```
## Workflow
Compare against a specific commit:
1. Find project's CLAUDE.md file
2. Show diff against target revision
3. Group changes by affected sections
4. Explain behavioral implications
```
/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 against specific commit |
| `--from=REF` | Starting point |
| `--to=REF` | Ending point (default: HEAD) |
| `--section=NAME` | Show only specific section |
| `--stat` | Statistics only |
| `--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 changes after pull
- Debugging unexpected behavior
- 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

342
plugins/claude-config-maintainer/commands/config-lint.md
View File

@@ -4,45 +4,343 @@ description: Lint CLAUDE.md for common anti-patterns and best practices
# Lint CLAUDE.md
Check CLAUDE.md against best practices and detect common anti-patterns.
## Skills to Load
- skills/visual-header.md
- skills/lint-rules.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
Display: `CONFIG-MAINTAINER - CLAUDE.md Lint`
When executing this command, display the plugin header:
```
┌──────────────────────────────────────────────────────────────────┐
│ ⚙️ CONFIG-MAINTAINER · CLAUDE.md Lint │
└──────────────────────────────────────────────────────────────────┘
```
Then proceed with the linting.
## What This Command Does
1. **Parse Structure** - Validates markdown structure and hierarchy
2. **Check Security** - Detects hardcoded paths, secrets, and sensitive data
3. **Validate Content** - Identifies anti-patterns and problematic instructions
4. **Verify Format** - Ensures consistent formatting and style
5. **Generate Report** - Provides actionable findings with fix suggestions
## Usage
```
/config-lint # Full lint
/config-lint --fix # Auto-fix issues
/config-lint --rules=security # Check specific category
/config-lint
```
## Workflow
Lint with auto-fix:
1. Parse markdown structure and hierarchy
2. Check for hardcoded paths, secrets, sensitive data
3. Identify content anti-patterns
4. Verify consistent formatting
5. Generate report with fix suggestions
```
/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` | Auto-fix issues |
| `--rules=LIST` | Check specific categories |
| `--ignore=LIST` | Skip specified rules |
| `--severity=LEVEL` | Filter by severity |
| `--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
- Periodically as maintenance
- 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) |

243
plugins/claude-config-maintainer/commands/config-optimize-settings.md
View File

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

256
plugins/claude-config-maintainer/commands/config-permissions-map.md
View File

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

222
plugins/claude-config-maintainer/commands/init.md
View File

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

190
plugins/claude-config-maintainer/commands/optimize.md
View File

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

9
plugins/claude-config-maintainer/hooks/hooks.json
View File

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

112
plugins/claude-config-maintainer/skills/analysis-workflow.md
View File

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

113
plugins/claude-config-maintainer/skills/claude-md-structure.md
View File

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

97
plugins/claude-config-maintainer/skills/diff-analysis.md
View File

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

136
plugins/claude-config-maintainer/skills/lint-rules.md
View File

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

136
plugins/claude-config-maintainer/skills/optimization-patterns.md
View File

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

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

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

377
plugins/claude-config-maintainer/skills/settings-optimization.md
View File

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

73
plugins/claude-config-maintainer/skills/visual-header.md
View File

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

3
plugins/cmdb-assistant/.claude-plugin/plugin.json
View File

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

8
plugins/cmdb-assistant/.mcp.json Normal file
View File

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

217
plugins/cmdb-assistant/README.md Normal file
View File

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

199
plugins/cmdb-assistant/agents/cmdb-assistant.md
View File

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

160
plugins/cmdb-assistant/commands/change-audit.md
View File

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

201
plugins/cmdb-assistant/commands/cmdb-audit.md
View File

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

47
plugins/cmdb-assistant/commands/cmdb-device.md
View File

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

61
plugins/cmdb-assistant/commands/cmdb-ip.md
View File

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

325
plugins/cmdb-assistant/commands/cmdb-register.md
View File

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

60
plugins/cmdb-assistant/commands/cmdb-site.md
View File

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

343
plugins/cmdb-assistant/commands/cmdb-sync.md
View File

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

184
plugins/cmdb-assistant/commands/cmdb-topology.md
View File

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

200
plugins/cmdb-assistant/commands/initial-setup.md
View File

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

228
plugins/cmdb-assistant/commands/ip-conflicts.md
View File

@@ -4,14 +4,20 @@ description: Detect IP address conflicts and overlapping prefixes in NetBox
# CMDB IP Conflict Detection
## Visual Output
When executing this command, display the plugin header:
```
┌──────────────────────────────────────────────────────────────────┐
│ 🖥️ CMDB-ASSISTANT · IP Conflict Detection │
└──────────────────────────────────────────────────────────────────┘
```
Then proceed with the analysis.
Scan NetBox IPAM data to identify IP address conflicts and overlapping prefixes.
## Skills to Load
- `skills/visual-header.md`
- `skills/ip-management.md`
- `skills/mcp-tools-reference.md`
## Usage
```
@@ -27,31 +33,205 @@ Scan NetBox IPAM data to identify IP address conflicts and overlapping prefixes.
## Instructions
Execute `skills/visual-header.md` with context "IP Conflict Detection".
You are an IP conflict detection specialist that analyzes NetBox IPAM data for conflicts and issues.
Execute conflict detection from `skills/ip-management.md`:
### Conflict Types to Detect
1. **Data Collection** - Fetch IPs, prefixes, VRFs via MCP
2. **Duplicate Detection** - Group by address+VRF, flag >1 record
3. **Overlap Detection** - Compare prefixes pairwise using CIDR math
4. **Orphan IP Detection** - Find IPs without containing prefix
5. **Generate Report** - Use template from skill
#### 1. Duplicate IP Addresses
## Conflict Types
Multiple IP address records with the same address (within same VRF).
| Type | Severity |
|------|----------|
| Duplicate IP (same interface type) | CRITICAL |
| Duplicate IP (different roles) | HIGH |
| Overlapping prefixes (same status) | HIGH |
| Overlapping prefixes (container ok) | LOW |
| Orphan IP | MEDIUM |
**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
- `/ip-conflicts addresses` - Duplicate IPs only
- `/ip-conflicts vrf Production` - Scan specific VRF
- `/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

9
plugins/cmdb-assistant/hooks/hooks.json
View File

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

41
plugins/cmdb-assistant/hooks/startup-check.sh
View File

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

1
plugins/cmdb-assistant/mcp-servers/netbox Symbolic link
View File

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

163
plugins/cmdb-assistant/skills/audit-workflow.md
View File

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

130
plugins/cmdb-assistant/skills/change-audit.md
View File

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

177
plugins/cmdb-assistant/skills/device-registration.md
View File

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

162
plugins/cmdb-assistant/skills/ip-management.md
View File

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

281
plugins/cmdb-assistant/skills/mcp-tools-reference.md
View File

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

191
plugins/cmdb-assistant/skills/sync-workflow.md
View File

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

101
plugins/cmdb-assistant/skills/system-discovery.md
View File

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

155
plugins/cmdb-assistant/skills/topology-generation.md
View File

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

32
plugins/cmdb-assistant/skills/visual-header.md
View File

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

2
plugins/code-sentinel/.claude-plugin/plugin.json
View File

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

47
plugins/code-sentinel/README.md Normal file
View File

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

4
plugins/code-sentinel/agents/refactor-advisor.md
View File

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

2
plugins/code-sentinel/agents/security-reviewer.md
View File

@@ -1,7 +1,5 @@
---
name: security-reviewer
description: Security-focused code review agent
model: sonnet
---
# Security Reviewer Agent

57
plugins/code-sentinel/commands/refactor-dry.md
View File

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

71
plugins/code-sentinel/commands/refactor.md
View File

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

66
plugins/code-sentinel/commands/security-scan.md
View File

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

99
plugins/code-sentinel/skills/dry-run-workflow.md
View File

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

119
plugins/code-sentinel/skills/refactoring-patterns.md
View File

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

5
plugins/contract-validator/.claude-plugin/plugin.json
View File

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

9
plugins/contract-validator/.mcp.json Normal file
View File

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

169
plugins/contract-validator/README.md Normal file
View File

@@ -0,0 +1,169 @@
# contract-validator Plugin
Cross-plugin compatibility validation and CLAUDE.md agent verification for Claude Code plugin marketplaces.
## Problem Statement
As plugin marketplaces grow, several compatibility issues emerge:
- **Command conflicts**: Multiple plugins defining the same slash command (e.g., `/initial-setup`)
- **Tool name overlaps**: Different plugins using identical tool names with incompatible interfaces
- **Undocumented dependencies**: Agents referencing tools that don't exist
- **Broken data flows**: Agent sequences that expect outputs not produced by prior steps
Contract-validator solves these by parsing plugin interfaces and validating compatibility before runtime.
## Features
- **Interface Parsing**: Extract commands, agents, and tools from plugin README.md files
- **Agent Extraction**: Parse CLAUDE.md Four-Agent Model tables and Agents sections
- **Compatibility Checks**: Pairwise validation between all plugins in a marketplace
- **Data Flow Validation**: Verify agent tool sequences have valid data producers/consumers
- **Dependency Visualization**: Generate Mermaid flowcharts showing plugin relationships
- **Comprehensive Reports**: Markdown or JSON reports with actionable suggestions
## Installation
This plugin is part of the leo-claude-mktplace. Install via:
```bash
# From marketplace
claude plugins install leo-claude-mktplace/contract-validator
# Setup MCP server venv
cd ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/contract-validator
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
## Commands
| Command | Description |
|---------|-------------|
| `/initial-setup` | Interactive setup wizard |
| `/validate-contracts` | Full marketplace compatibility validation |
| `/check-agent` | Validate single agent definition |
| `/list-interfaces` | Show all plugin interfaces |
| `/dependency-graph` | Generate Mermaid flowchart of plugin dependencies |
## Agents
| Agent | Description |
|-------|-------------|
| `full-validation` | Complete cross-plugin compatibility validation |
| `agent-check` | Single agent definition verification |
## Tools Summary
### Parse Tools (2)
- `parse_plugin_interface` - Extract interface from plugin README.md
- `parse_claude_md_agents` - Extract agents from CLAUDE.md
### Validation Tools (3)
- `validate_compatibility` - Check two plugins for conflicts
- `validate_agent_refs` - Verify agent tool references exist
- `validate_data_flow` - Check data flow through agent sequences
### Report Tools (2)
- `generate_compatibility_report` - Full marketplace validation report
- `list_issues` - Filter issues by severity or type
## Example Workflow
```
/validate-contracts ~/claude-plugins-work
# Output:
# Contract Validation Report
#
# | Metric | Count |
# |------------|-------|
# | Plugins | 12 |
# | Commands | 39 |
# | Tools | 32 |
# | **Issues** | **7** |
# | - Errors | 3 |
# | - Warnings | 0 |
# | - Info | 4 |
#
# ## Issues Found
# [ERROR] Command conflict: projman and data-platform both define /initial-setup
# [ERROR] Command conflict: projman and pr-review both define /initial-setup
# ...
```
```
/check-agent Planner ./CLAUDE.md
# Output:
# Agent: Planner
# Status: VALID
#
# Tool References Found (3):
# - create_issue ✓
# - search_lessons ✓
# - get_execution_order ✓
#
# Data Flow: No issues detected
```
```
/dependency-graph
# Output: Mermaid flowchart showing:
# - Plugins grouped by shared MCP servers
# - Data flow from data-platform to viz-platform
# - Required vs optional dependencies
# - Command counts per plugin
```
## Issue Types
| Type | Severity | Description |
|------|----------|-------------|
| `interface_mismatch` | ERROR | Command name conflict between plugins |
| `missing_tool` | ERROR | Agent references non-existent tool |
| `interface_mismatch` | WARNING | Tool name overlap (different plugins) |
| `optional_dependency` | WARNING | Agent uses tool from non-required plugin |
| `undeclared_output` | INFO | Agent has no documented tool references |
## Parsed Interface Structure
When parsing a plugin README.md, the following structure is extracted:
```json
{
"plugin_name": "data-platform",
"description": "Data engineering tools...",
"commands": [
{"name": "/ingest", "description": "Load data..."}
],
"agents": [
{"name": "data-analysis", "description": "..."}
],
"tools": [
{"name": "read_csv", "category": "pandas"}
],
"tool_categories": {
"pandas": ["read_csv", "to_csv", ...],
"PostgreSQL": ["pg_query", ...]
},
"features": ["pandas Operations", "PostgreSQL/PostGIS", ...]
}
```
## Best Practices
### For Plugin Authors
1. **Use unique command names**: Prefix with plugin name if generic (e.g., `/data-setup` vs `/initial-setup`)
2. **Document all tools**: Include tool names in README.md with backticks
3. **Specify tool categories**: Use `### Category (N tools)` headers
4. **Declare agent tools**: List tools used by agents in their definitions
### For Marketplace Maintainers
1. **Run validation before merging**: Use `/validate-contracts` in CI/CD
2. **Review warnings**: Tool overlaps may indicate design issues
3. **Track issues over time**: Use JSON format for programmatic tracking

6
plugins/contract-validator/agents/agent-check.md
View File

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

6
plugins/contract-validator/agents/full-validation.md
View File

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

55
plugins/contract-validator/commands/check-agent.md
View File

@@ -1,10 +1,18 @@
# /check-agent - Validate Agent Definition
## Skills to Load
- skills/visual-output.md
- skills/interface-parsing.md
- skills/validation-rules.md
- skills/mcp-tools-reference.md
## 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
@@ -14,26 +22,30 @@
## Parameters
- `agent_name` (required): Agent to validate (e.g., "Planner", "Orchestrator")
- `claude_md_path` (optional): Path to CLAUDE.md. Defaults to `./CLAUDE.md`
- `agent_name` (required): Name of the agent to validate (e.g., "Planner", "Orchestrator")
- `claude_md_path` (optional): Path to CLAUDE.md file. Defaults to `./CLAUDE.md`
## Workflow
1. **Display header** per `skills/visual-output.md`
1. **Parse agent definition**:
- Locate agent in CLAUDE.md (Four-Agent Model table or Agents section)
- Extract responsibilities, tool references, workflow steps
2. **Parse agent** per `skills/interface-parsing.md`
- Use `parse_claude_md_agents` to extract agent definition
- Get responsibilities, tool references, workflow steps
2. **Validate tool references**:
- Check each referenced tool exists in available plugins
- Report missing or misspelled tool names
- Suggest corrections for common mistakes
3. **Validate** per `skills/validation-rules.md`
- Use `validate_agent_refs` - check all tools exist
- Use `validate_data_flow` - verify producer/consumer order
3. **Validate data flow**:
- Analyze sequence of tools in agent workflow
- Verify data producers precede data consumers
- Check for orphaned data references
4. **Report findings**:
- Tool references found
- Missing tools (with suggestions)
- Data flow issues
- Recommendations
- List all tool references found
- List any missing tools
- Data flow validation results
- Suggestions for improvement
## Examples
@@ -42,3 +54,10 @@
/check-agent Orchestrator ./CLAUDE.md
/check-agent data-analysis ~/project/CLAUDE.md
```
## Available Tools
Use these MCP tools:
- `validate_agent_refs` - Check agent tool references exist
- `validate_data_flow` - Verify data flow through agent sequence
- `parse_claude_md_agents` - Parse all agents from CLAUDE.md

254
plugins/contract-validator/commands/dependency-graph.md
View File

@@ -1,11 +1,18 @@
# /dependency-graph - Generate Dependency Visualization
## Skills to Load
- skills/visual-output.md
- skills/plugin-discovery.md
- skills/interface-parsing.md
- skills/dependency-analysis.md
- skills/mcp-tools-reference.md
## 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
@@ -21,35 +28,236 @@
## Workflow
1. **Display header** per `skills/visual-output.md`
1. **Discover plugins**:
- Scan plugins directory for all plugins with `.claude-plugin/` marker
- Parse each plugin's README.md to extract interface
- Parse CLAUDE.md for agent definitions and tool sequences
2. **Discover plugins** per `skills/plugin-discovery.md`
2. **Analyze dependencies**:
- Identify shared MCP servers (plugins using same server)
- Detect tool dependencies (which plugins produce vs consume data)
- Find agent tool references across plugins
- Categorize as required (ERROR if missing) or optional (WARNING if missing)
3. **Parse interfaces** per `skills/interface-parsing.md`
- Use `parse_plugin_interface` for each plugin
- Use `parse_claude_md_agents` for CLAUDE.md
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. **Analyze dependencies** per `skills/dependency-analysis.md`
- Identify shared MCP servers
- Detect data producers/consumers
- Categorize as required or optional
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
5. **Generate output**:
- Mermaid: Create flowchart TD diagram with styled edges
- Text: Create text summary with counts and lists
## 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
```
## Integration
Analyze marketplace at specified path.
Use with `/validate-contracts`:
1. Run `/dependency-graph` to visualize
2. Run `/validate-contracts` to find issues
3. Fix and regenerate
## 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
```

177
plugins/contract-validator/commands/initial-setup.md
View File

@@ -1,49 +1,164 @@
---
description: Interactive setup wizard for contract-validator plugin
description: Interactive setup wizard for contract-validator plugin - verifies MCP server and shows capabilities
---
# /initial-setup - Contract-Validator Setup Wizard
# Contract-Validator Setup Wizard
## Skills to Load
- skills/visual-output.md
- skills/mcp-tools-reference.md
## Visual Output
**Important:** This command uses Bash, Read, Write tools - NOT MCP tools (they work only after setup + restart).
When executing this command, display the plugin header:
## Workflow
```
┌──────────────────────────────────────────────────────────────────┐
│ ✅ CONTRACT-VALIDATOR · Setup Wizard │
└──────────────────────────────────────────────────────────────────┘
```
1. **Display header** per `skills/visual-output.md`
Then proceed with the setup.
2. **Check Python version**:
```bash
python3 --version
```
Requires 3.10+. Stop if below.
This command sets up the contract-validator plugin for cross-plugin compatibility validation.
3. **Locate MCP server**:
- Installed: `~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/contract-validator/`
- Source: `~/claude-plugins-work/mcp-servers/contract-validator/`
## Important Context
4. **Check/create venv**:
```bash
ls .venv/bin/python || (python3 -m venv .venv && .venv/bin/pip install -r requirements.txt)
```
- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools
- **MCP tools won't work until after setup + session restart**
- **No external credentials required** - this plugin validates local files only
5. **Verify MCP server**:
```bash
.venv/bin/python -c "from mcp_server.server import ContractValidatorMCPServer; print('OK')"
```
---
6. **Display success** per `skills/visual-output.md`
## Phase 1: Environment Validation
7. **Inform user**: Session restart required for MCP tools.
### Step 1.1: Check Python Version
## Post-Setup Commands
```bash
python3 --version
```
- `/validate-contracts` - Full marketplace validation
- `/check-agent` - Validate single agent
- `/list-interfaces` - Show all plugin interfaces
Requires Python 3.10+. If below, stop setup and inform user:
```
Python 3.10 or higher is required. Please install it and run /initial-setup again.
```
---
## Phase 2: MCP Server Setup
### Step 2.1: Locate Contract-Validator MCP Server
```bash
# If running from installed marketplace
ls -la ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/contract-validator/ 2>/dev/null || echo "NOT_FOUND_INSTALLED"
# If running from source
ls -la ~/claude-plugins-work/mcp-servers/contract-validator/ 2>/dev/null || echo "NOT_FOUND_SOURCE"
```
Determine which path exists and use that as the MCP server path.
### Step 2.2: Check Virtual Environment
```bash
ls -la /path/to/mcp-servers/contract-validator/.venv/bin/python 2>/dev/null && echo "VENV_EXISTS" || echo "VENV_MISSING"
```
### Step 2.3: Create Virtual Environment (if missing)
```bash
cd /path/to/mcp-servers/contract-validator && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate
```
**If pip install fails:**
- Show the error to the user
- Suggest: "Check your internet connection and try again."
---
## Phase 3: Validation
### Step 3.1: Verify MCP Server
```bash
cd /path/to/mcp-servers/contract-validator && .venv/bin/python -c "from mcp_server.server import ContractValidatorMCPServer; print('MCP Server OK')"
```
If this fails, check the error and report it to the user.
### Step 3.2: Summary
Display:
```
╔════════════════════════════════════════════════════════════════╗
║ CONTRACT-VALIDATOR SETUP COMPLETE ║
╠════════════════════════════════════════════════════════════════╣
║ MCP Server: ✓ Ready ║
║ Parse Tools: ✓ Available (2 tools) ║
║ Validation Tools: ✓ Available (3 tools) ║
║ Report Tools: ✓ Available (2 tools) ║
╚════════════════════════════════════════════════════════════════╝
```
### Step 3.3: Session Restart Notice
---
**Session Restart Required**
Restart your Claude Code session for MCP tools to become available.
**After restart, you can:**
- Run `/validate-contracts` to check all plugins for compatibility issues
- Run `/check-agent` to validate a single agent definition
- Run `/list-interfaces` to see all plugin commands and tools
---
## Available Tools
| Category | Tools | Description |
|----------|-------|-------------|
| Parse | `parse_plugin_interface`, `parse_claude_md_agents` | Extract interfaces from README.md and agents from CLAUDE.md |
| Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow` | Check conflicts, tool references, and data flows |
| Report | `generate_compatibility_report`, `list_issues` | Generate reports and filter issues |
---
## Available Commands
| Command | Description |
|---------|-------------|
| `/validate-contracts` | Full marketplace compatibility validation |
| `/check-agent` | Validate single agent definition |
| `/list-interfaces` | Show all plugin interfaces |
---
## Use Cases
### 1. Pre-Release Validation
Run `/validate-contracts` before releasing a new marketplace version to catch:
- Command name conflicts between plugins
- Missing tool references in agents
- Broken data flows
### 2. Agent Development
Run `/check-agent` when creating or modifying agents to verify:
- All referenced tools exist
- Data flows are valid
- No undeclared dependencies
### 3. Plugin Audit
Run `/list-interfaces` to get a complete view of:
- All commands across plugins
- All tools available
- Potential overlap areas
---
## No Configuration Required
This plugin reads plugin manifests and README files directly - no credentials needed.
This plugin doesn't require any configuration files. It reads plugin manifests and README files directly from the filesystem.
**Paths it scans:**
- Marketplace: `~/.claude/plugins/marketplaces/leo-claude-mktplace/plugins/`
- Source (if available): `~/claude-plugins-work/plugins/`

64
plugins/contract-validator/commands/list-interfaces.md
View File

@@ -1,10 +1,18 @@
# /list-interfaces - Show Plugin Interfaces
## Skills to Load
- skills/visual-output.md
- skills/plugin-discovery.md
- skills/interface-parsing.md
- skills/mcp-tools-reference.md
## 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
@@ -18,25 +26,35 @@
## Workflow
1. **Display header** per `skills/visual-output.md`
1. **Discover plugins**:
- Scan plugins directory for all plugins with `.claude-plugin/` marker
- Read each plugin's README.md
2. **Discover plugins** per `skills/plugin-discovery.md`
2. **Parse interfaces**:
- Extract commands (slash commands offered by plugin)
- Extract agents (autonomous agents defined)
- Extract tools (MCP tools provided)
- Identify tool categories and features
3. **Parse interfaces** per `skills/interface-parsing.md`
- Use `parse_plugin_interface` for each plugin README.md
- Extract commands, agents, tools
3. **Display summary**:
- Table of plugins with command/agent/tool counts
- Detailed breakdown per plugin
- Tool categories and their contents
4. **Display summary table**:
```
| Plugin | Commands | Agents | Tools |
|-------------|----------|--------|-------|
| projman | 12 | 4 | 26 |
```
## Output Format
5. **Display per-plugin details**:
- List of commands
- List of agents
- Tool categories
```
| Plugin | Commands | Agents | Tools |
|-------------|----------|--------|-------|
| projman | 12 | 4 | 26 |
| data-platform| 7 | 2 | 32 |
| ... | ... | ... | ... |
## projman
- Commands: /sprint-plan, /sprint-start, ...
- Agents: Planner, Orchestrator, Executor, Code Reviewer
- Tools: list_issues, create_issue, ...
```
## Examples
@@ -44,3 +62,9 @@
/list-interfaces
/list-interfaces ~/claude-plugins-work
```
## Available Tools
Use these MCP tools:
- `parse_plugin_interface` - Parse individual plugin README
- `generate_compatibility_report` - Get full interface data (JSON format)

57
plugins/contract-validator/commands/validate-contracts.md
View File

@@ -1,11 +1,18 @@
# /validate-contracts - Full Contract Validation
## Skills to Load
- skills/visual-output.md
- skills/plugin-discovery.md
- skills/interface-parsing.md
- skills/validation-rules.md
- skills/mcp-tools-reference.md
## 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
@@ -19,23 +26,25 @@
## Workflow
1. **Display header** per `skills/visual-output.md`
1. **Discover plugins**:
- Scan plugins directory for all plugins with `.claude-plugin/` marker
- Parse each plugin's README.md to extract interface
2. **Discover plugins** per `skills/plugin-discovery.md`
2. **Run compatibility checks**:
- Perform pairwise compatibility validation between all plugins
- Check for command name conflicts
- Check for tool name overlaps
- Identify interface mismatches
3. **Parse interfaces** per `skills/interface-parsing.md`
- Use `parse_plugin_interface` for each plugin
3. **Validate CLAUDE.md agents**:
- Parse agent definitions from CLAUDE.md
- Validate all tool references exist
- Check data flow through agent sequences
4. **Run validations** per `skills/validation-rules.md`
- Use `validate_compatibility` for pairwise checks
- Use `validate_agent_refs` for CLAUDE.md agents
- Use `validate_data_flow` for data sequences
- Use `validate_workflow_integration` for domain plugin advisory interfaces
5. **Generate report**:
- Use `generate_compatibility_report` for full report
- Use `list_issues` to filter by severity
- Display summary and actionable suggestions
4. **Generate report**:
- Summary statistics (plugins, commands, tools, issues)
- Detailed findings by severity (error, warning, info)
- Actionable suggestions for each issue
## Examples
@@ -43,3 +52,11 @@
/validate-contracts
/validate-contracts ~/claude-plugins-work
```
## Available Tools
Use these MCP tools:
- `generate_compatibility_report` - Generate full marketplace report
- `list_issues` - Filter issues by severity or type
- `parse_plugin_interface` - Parse individual plugin interface
- `validate_compatibility` - Check two plugins for conflicts

9
plugins/contract-validator/hooks/hooks.json
View File

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

1
plugins/contract-validator/mcp-servers/contract-validator Symbolic link
View File

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

Some files were not shown because too many files have changed in this diff Show More