refactor(projman): extract skills and consolidate commands
Major refactoring of projman plugin architecture: Skills Extraction (17 new files): - Extracted reusable knowledge from commands and agents into skills/ - branch-security, dependency-management, git-workflow, input-detection - issue-conventions, lessons-learned, mcp-tools-reference, planning-workflow - progress-tracking, repo-validation, review-checklist, runaway-detection - setup-workflows, sprint-approval, task-sizing, test-standards, wiki-conventions Command Consolidation (17 → 12 commands): - /setup: consolidates initial-setup, project-init, project-sync (--full/--quick/--sync) - /debug: consolidates debug-report, debug-review (report/review modes) - /test: consolidates test-check, test-gen (run/gen modes) - /sprint-status: absorbs sprint-diagram via --diagram flag Architecture Cleanup: - Remove plugin-level mcp-servers/ symlinks (6 plugins) - Remove plugin README.md files (12 files, ~2000 lines) - Update all documentation to reflect new command structure - Fix documentation drift in CONFIGURATION.md, COMMANDS-CHEATSHEET.md Commands are now thin dispatchers (~20-50 lines) that reference skills. Agents reference skills for domain knowledge instead of inline content. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,217 +0,0 @@
|
||||
# CMDB Assistant
|
||||
|
||||
A Claude Code plugin for NetBox CMDB integration - query, create, update, and manage your network infrastructure directly from Claude Code.
|
||||
|
||||
## What's New in v1.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.
|
||||
@@ -1 +0,0 @@
|
||||
../../../mcp-servers/netbox
|
||||
Reference in New Issue
Block a user