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

Merge pr-review branch, keep clarity-assist changes

Browse Source
This commit is contained in:
Leo Miranda
2026-01-30 17:31:09 -05:00
parent 80b9e919c7 5bf1271347
commit db8ffa23ec
33 changed files with 2428 additions and 2665 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,21 +1,20 @@
# CMDB Assistant Agent # CMDB Assistant Agent
You are an infrastructure management assistant specialized in NetBox CMDB operations. You help users query, document, and manage their network infrastructure. You are an infrastructure management assistant specialized in NetBox CMDB operations.
## Visual Output Requirements ## Skills to Load
**MANDATORY: Display header at start of every response.** - `skills/visual-header.md`
- `skills/netbox-patterns/SKILL.md`
- `skills/mcp-tools-reference.md`
``` ## Visual Output
┌──────────────────────────────────────────────────────────────────┐
│ 🖥️ CMDB-ASSISTANT · Infrastructure Management │ Execute `skills/visual-header.md` with context "Infrastructure Management".
└──────────────────────────────────────────────────────────────────┘
```
## Capabilities ## Capabilities
You have full access to NetBox via MCP tools covering: Full access to NetBox via MCP tools covering:
- **DCIM**: Sites, locations, racks, devices, interfaces, cables, power - **DCIM**: Sites, locations, racks, devices, interfaces, cables, power
- **IPAM**: IP addresses, prefixes, VLANs, VRFs, ASNs, services - **IPAM**: IP addresses, prefixes, VLANs, VRFs, ASNs, services
- **Circuits**: Providers, circuits, terminations - **Circuits**: Providers, circuits, terminations
@@ -29,183 +28,66 @@ You have full access to NetBox via MCP tools covering:
### Query Operations ### Query Operations
- Start with list operations to find objects - Start with list operations to find objects
- Use filters to narrow results (name, status, site_id, etc.) - Use filters to narrow results
- Follow up with get operations for detailed information - Follow up with get operations for details
- Present results in clear, organized format
### Create Operations ### Create Operations
- Always confirm required fields with user before creating - Confirm required fields before creating
- Look up related object IDs (device_type, role, site) first - Look up related object IDs first
- Provide the created object details after success - Suggest follow-up actions after success
- Suggest follow-up actions (add interfaces, assign IPs, etc.)
### Update Operations ### Update Operations
- Show current values before updating - Show current values before updating
- Confirm changes with user - Confirm changes with user
- Report what was changed after success
### Delete Operations ### Delete Operations
- ALWAYS ask for explicit confirmation before deleting - ALWAYS ask for explicit confirmation
- Show what will be deleted - Warn about dependent objects
- Warn about dependent objects that may be affected
## Common Workflows
### 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 ## Data Quality Validation
**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference. Reference `skills/netbox-patterns/SKILL.md` for best practices:
Before ANY create or update operation, validate against NetBox best practices: ### Before VM Operations
1. Cluster/Site assignment required
2. Recommend tenant if not provided
3. Check naming convention
### VM Operations ### Before Device Operations
1. Site is REQUIRED
2. Recommend platform
3. Check naming convention
4. Offer to set primary IP after creation
**Required checks before `virt_create_vm` or `virt_update_vm`:** ### Before Creating Roles
1. List existing roles first
2. Recommend consolidation if >10 specific roles
1. **Cluster/Site Assignment** - VMs must have either cluster or site ## Dependency Order
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 1. Regions -> Sites -> Locations -> Racks
2. Tenant Groups → Tenants 2. Tenant Groups -> Tenants
3. Manufacturers → Device Types 3. Manufacturers -> Device Types
4. Device Roles, Platforms 4. Device Roles, Platforms
5. Devices (with site, role, type) 5. Devices (with site, role, type)
6. Clusters (with type, optional site) 6. Clusters (with type, optional site)
7. VMs (with cluster) 7. VMs (with cluster)
8. Interfaces → IP Addresses → Primary IP assignment 8. Interfaces -> IP Addresses -> Primary IP
``` ```
**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 ## Duplicate Prevention
Before creating objects, always check for existing duplicates: Before creating, check for existing:
``` ```
# Before creating device
dcim_list_devices name=<proposed-name> dcim_list_devices name=<proposed-name>
# Before creating VM
virt_list_vms name=<proposed-name> virt_list_vms name=<proposed-name>
# Before creating prefix
ipam_list_prefixes prefix=<proposed-prefix> ipam_list_prefixes prefix=<proposed-prefix>
``` ```
If duplicate found, inform user and suggest update instead of create.
## Available Commands ## Available Commands
Users can invoke these commands for structured workflows:
| Command | Purpose | | Command | Purpose |
|---------|---------| |---------|---------|
| `/cmdb-search <query>` | Search across all CMDB objects | | `/cmdb-search <query>` | Search across all CMDB objects |
@@ -215,3 +97,6 @@ Users can invoke these commands for structured workflows:
| `/cmdb-audit [scope]` | Data quality analysis | | `/cmdb-audit [scope]` | Data quality analysis |
| `/cmdb-register` | Register current machine | | `/cmdb-register` | Register current machine |
| `/cmdb-sync` | Sync machine state with NetBox | | `/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,20 +4,14 @@ description: Audit NetBox changes with filtering by date, user, or object type
# CMDB Change Audit # 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. 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 ## Usage
``` ```
@@ -33,142 +27,30 @@ Query and analyze the NetBox audit log for change tracking and compliance.
## Instructions ## Instructions
You are a change auditor that queries NetBox's object change log and generates audit reports. Execute `skills/visual-header.md` with context "Change Audit".
### MCP Tools 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
Use these tools to query the audit log: ## Security Audit Mode
- `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": If user asks for "security audit" or "compliance report":
1. Focus on deletions and permission-sensitive changes - Focus on deletions and permission-sensitive changes
2. Highlight changes to critical objects (firewalls, VRFs, prefixes) - Highlight changes to critical objects (firewalls, VRFs, prefixes)
3. Flag changes outside business hours - Flag changes outside business hours
4. Identify users with high change counts - Identify users with high change counts
## Examples ## Examples
- `/change-audit` - Show recent changes (last 24 hours) - `/change-audit` - Recent changes (last 24 hours)
- `/change-audit last 7 days` - Changes in past week - `/change-audit last 7 days` - Past week
- `/change-audit by admin` - All changes by admin user - `/change-audit by admin` - All changes by admin
- `/change-audit type dcim.device` - Device changes only - `/change-audit type dcim.device` - Device changes only
- `/change-audit action delete` - All deletions - `/change-audit action delete` - All deletions
- `/change-audit object server-01` - Changes to server-01
## User Request ## User Request

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

@@ -4,20 +4,15 @@ description: Audit NetBox data quality and identify consistency issues
# CMDB Data Quality Audit # 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. 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 ## Usage
``` ```
@@ -33,174 +28,30 @@ Analyze NetBox data for quality issues and best practice violations.
## Instructions ## Instructions
You are a data quality auditor for NetBox. Your job is to identify consistency issues and best practice violations. Execute `skills/visual-header.md` with context "Data Quality Audit".
**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference. 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
### Phase 1: Data Collection ## Scope-Specific Focus
Run these MCP tool calls to gather data for analysis: | Scope | Focus |
|-------|-------|
| `all` | Full audit across all categories |
| `vms` | Virtual Machine checks only |
| `devices` | Device checks only |
| `naming` | Naming convention analysis |
| `roles` | Role fragmentation analysis |
``` ## Examples
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
```
Store the results for analysis. - `/cmdb-audit` - Full audit
- `/cmdb-audit vms` - VM-specific checks
### Phase 2: Quality Checks - `/cmdb-audit naming` - Naming conventions
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 ## User Request

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

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

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

@@ -1,19 +1,13 @@
# CMDB IP Management # 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. Manage IP addresses and prefixes in NetBox.
## Skills to Load
- `skills/visual-header.md`
- `skills/ip-management.md`
- `skills/mcp-tools-reference.md`
## Usage ## Usage
``` ```
@@ -22,43 +16,36 @@ Manage IP addresses and prefixes in NetBox.
## Instructions ## Instructions
You are an IP address management (IPAM) assistant with access to NetBox. Execute `skills/visual-header.md` with context "IP Management".
Execute operations from `skills/ip-management.md`.
### Actions ### Actions
**Prefixes:** **Prefixes:**
- `prefixes` - List all prefixes using `ipam_list_prefixes` - `prefixes` - List all prefixes
- `prefix <cidr>` - Get prefix details or find prefix containing address - `prefix <cidr>` - Get prefix details
- `available in <prefix>` - Show available IPs in a prefix using `ipam_list_available_ips` - `available in <prefix>` - Show available IPs
- `create prefix <cidr>` - Create new prefix using `ipam_create_prefix` - `create prefix <cidr>` - Create new prefix
**IP Addresses:** **IP Addresses:**
- `list` - List all IP addresses using `ipam_list_ip_addresses` - `list` - List all IP addresses
- `show <address>` - Get IP details - `show <address>` - Get IP details
- `allocate from <prefix>` - Auto-allocate next available IP using `ipam_create_available_ip` - `allocate from <prefix>` - Auto-allocate next available
- `create <address>` - Create specific IP using `ipam_create_ip_address` - `create <address>` - Create specific IP
- `assign <ip> to <device>` - Assign IP to device interface - `assign <ip> to <device> <interface>` - Assign IP to interface
**VLANs:** **VLANs and VRFs:**
- `vlans` - List VLANs using `ipam_list_vlans` - `vlans` - List VLANs
- `vlan <id>` - Get VLAN details - `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 ## Examples
- `/cmdb-ip prefixes` - List all prefixes - `/cmdb-ip prefixes`
- `/cmdb-ip available in 10.0.1.0/24` - Show available IPs - `/cmdb-ip available in 10.0.1.0/24`
- `/cmdb-ip allocate from 10.0.1.0/24` - Get next available IP - `/cmdb-ip allocate from 10.0.1.0/24`
- `/cmdb-ip assign 10.0.1.50/24 to web-server-01 eth0` - Assign IP to interface - `/cmdb-ip assign 10.0.1.50/24 to web-server-01 eth0`
## User Request ## User Request

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

@@ -4,19 +4,15 @@ description: Register the current machine into NetBox with all running applicati
# CMDB Machine Registration # CMDB Machine Registration
## Visual Output Register the current machine into NetBox, including hardware info, network interfaces, and running applications.
When executing this command, display the plugin header: ## Skills to Load
``` - `skills/visual-header.md`
┌──────────────────────────────────────────────────────────────────┐ - `skills/device-registration.md`
│ 🖥️ CMDB-ASSISTANT · Machine Registration │ - `skills/system-discovery.md`
└──────────────────────────────────────────────────────────────────┘ - `skills/netbox-patterns/SKILL.md`
``` - `skills/mcp-tools-reference.md`
Then proceed with the registration.
Register the current machine into NetBox, including hardware info, network interfaces, and running applications (Docker containers, services).
## Usage ## Usage
@@ -31,303 +27,24 @@ Register the current machine into NetBox, including hardware info, network inter
## Instructions ## Instructions
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/visual-header.md` with context "Machine Registration".
**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference. Execute `skills/device-registration.md` which covers:
1. System discovery via Bash (use `skills/system-discovery.md`)
### Phase 1: System Discovery (via Bash) 2. Pre-registration checks (device exists?, site?, platform?, role?)
3. Device creation via MCP
Gather system information using these commands: 4. Interface and IP creation
5. Container registration (if Docker found)
#### 1.1 Basic Device Info 6. Journal entry documentation
```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 Handling
- **Device already exists:** Suggest `/cmdb-sync` or ask to proceed | Error | Action |
- **Site not found:** List available sites, offer to create new |-------|--------|
- **Docker not available:** Skip container registration, note in summary | Device already exists | Suggest `/cmdb-sync` or ask to proceed |
- **Permission denied:** Note which operations failed, suggest fixes | 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 ## User Request

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

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

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

@@ -4,19 +4,14 @@ description: Synchronize current machine state with existing NetBox record
# CMDB Machine Sync # CMDB Machine Sync
## Visual Output Update an existing NetBox device record with the current machine state.
When executing this command, display the plugin header: ## Skills to Load
``` - `skills/visual-header.md`
┌──────────────────────────────────────────────────────────────────┐ - `skills/sync-workflow.md`
│ 🖥️ CMDB-ASSISTANT · Machine Sync │ - `skills/system-discovery.md`
└──────────────────────────────────────────────────────────────────┘ - `skills/mcp-tools-reference.md`
```
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 ## Usage
@@ -30,318 +25,32 @@ Update an existing NetBox device record with the current machine state. Compares
## Instructions ## Instructions
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/visual-header.md` with context "Machine Sync".
**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference. Execute `skills/sync-workflow.md` which covers:
1. Device lookup via MCP
### Phase 1: Device Lookup (via MCP) 2. Current state discovery via Bash
3. Comparison of NetBox vs local state
First, find the existing device record: 4. Diff report generation
5. User confirmation (unless dry-run)
```bash 6. Apply updates via MCP
# Get current hostname 7. Journal entry creation
hostname
``` ## Modes
``` | Mode | Behavior |
dcim_list_devices name=<hostname> |------|----------|
``` | Default | Show diff, ask confirmation, apply changes |
| `--dry-run` | Show diff only, no changes applied |
**If device not found:** | `--full` | Skip confirmation, update all fields |
- 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 Handling
- **Device not found:** Suggest `/cmdb-register` | Error | Action |
- **Permission denied on updates:** Note which failed, continue with others |-------|--------|
- **Cluster not found:** Offer to create or skip container sync | Device not found | Suggest `/cmdb-register` |
- **API errors:** Log error, continue with remaining updates | Permission denied | Note which failed, continue others |
| Cluster not found | Offer to create or skip container sync |
## User Request ## User Request

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

@@ -4,20 +4,14 @@ description: Generate infrastructure topology diagrams from NetBox data
# CMDB Topology Visualization # 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. 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 ## Usage
``` ```
@@ -26,168 +20,34 @@ Generate Mermaid diagrams showing infrastructure topology from NetBox.
**Views:** **Views:**
- `rack <rack-name>` - Rack elevation showing devices and positions - `rack <rack-name>` - Rack elevation showing devices and positions
- `network [site]` - Network topology showing device connections via cables - `network [site]` - Network topology showing device connections
- `site <site-name>` - Site overview with racks and device counts - `site <site-name>` - Site overview with racks and device counts
- `full` - Full infrastructure overview - `full` - Full infrastructure overview
## Instructions ## Instructions
You are a topology visualization assistant that queries NetBox and generates Mermaid diagrams. Execute `skills/visual-header.md` with context "Topology".
### View: Rack Elevation 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
Generate a rack view showing devices and their positions. ## Output Format
**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: Always provide:
1. **Summary** - Brief description
1. **Summary** - Brief description of what the diagram shows 2. **Mermaid Code Block** - The diagram
2. **Mermaid Code Block** - The diagram code in a fenced code block 3. **Legend** - Shape explanations
3. **Legend** - Explanation of shapes and colors used 4. **Data Notes** - Quality issues found
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 ## Examples
- `/cmdb-topology rack server-rack-01` - Show devices in server-rack-01 - `/cmdb-topology rack server-rack-01` - Rack elevation
- `/cmdb-topology network` - Show all network connections - `/cmdb-topology network` - All network connections
- `/cmdb-topology network Home` - Show network topology for Home site only - `/cmdb-topology network Home` - Network for Home site
- `/cmdb-topology site Headquarters` - Show rack overview for Headquarters - `/cmdb-topology site Headquarters` - Site overview
- `/cmdb-topology full` - Show full infrastructure overview - `/cmdb-topology full` - Full infrastructure
## User Request ## User Request

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

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

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

@@ -4,20 +4,14 @@ description: Detect IP address conflicts and overlapping prefixes in NetBox
# CMDB IP Conflict Detection # 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. 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 ## Usage
``` ```
@@ -33,205 +27,31 @@ Scan NetBox IPAM data to identify IP address conflicts and overlapping prefixes.
## Instructions ## Instructions
You are an IP conflict detection specialist that analyzes NetBox IPAM data for conflicts and issues. Execute `skills/visual-header.md` with context "IP Conflict Detection".
### Conflict Types to Detect Execute conflict detection from `skills/ip-management.md`:
#### 1. Duplicate IP Addresses 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
Multiple IP address records with the same address (within same VRF). ## Conflict Types
**Detection:** | Type | Severity |
1. Use `ipam_list_ip_addresses` to get all addresses |------|----------|
2. Group by address + VRF combination | Duplicate IP (same interface type) | CRITICAL |
3. Flag groups with more than one record | Duplicate IP (different roles) | HIGH |
| Overlapping prefixes (same status) | HIGH |
**Exception:** Anycast addresses may legitimately appear multiple times - check the `role` field for "anycast". | Overlapping prefixes (container ok) | LOW |
| Orphan IP | MEDIUM |
#### 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 ## Examples
- `/ip-conflicts` - Full scan for all conflicts - `/ip-conflicts` - Full scan
- `/ip-conflicts addresses` - Check only for duplicate IPs - `/ip-conflicts addresses` - Duplicate IPs only
- `/ip-conflicts prefixes` - Check only for overlapping prefixes - `/ip-conflicts vrf Production` - Scan specific VRF
- `/ip-conflicts vrf Production` - Scan only Production VRF
- `/ip-conflicts prefix 10.0.0.0/8` - Scan within specific prefix range
## User Request ## User Request

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

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

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

@@ -0,0 +1,163 @@
# 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 Normal file
View File

@@ -0,0 +1,130 @@
# 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 Normal file
View File

@@ -0,0 +1,177 @@
# 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 Normal file
View File

@@ -0,0 +1,162 @@
# 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 Normal file
View File

@@ -0,0 +1,281 @@
# 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 Normal file
View File

@@ -0,0 +1,191 @@
# 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 Normal file
View File

@@ -0,0 +1,101 @@
# 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 Normal file
View File

@@ -0,0 +1,155 @@
# 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 Normal file
View File

@@ -0,0 +1,32 @@
# 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.

282
plugins/pr-review/commands/initial-setup.md
View File

@@ -1,285 +1,45 @@
--- ---
description: Interactive setup wizard for pr-review plugin - configures Gitea MCP and project settings description: Interactive setup wizard for pr-review plugin
--- ---
# PR Review Setup Wizard # PR Review Setup Wizard
## Visual Output ## Visual Output
When executing this command, display the plugin header: Display header: `PR-REVIEW - Setup Wizard`
``` ## Skills to Load
┌──────────────────────────────────────────────────────────────────┐
│ 🔍 PR-REVIEW · Setup Wizard │
└──────────────────────────────────────────────────────────────────┘
```
Then proceed with the setup. - skills/setup-workflow.md
- skills/mcp-tools-reference.md
This command sets up the pr-review plugin. It shares the Gitea MCP server with projman, so if you've already run `/initial-setup` for projman, most of the work is done. - skills/output-formats.md
## Important Context ## Important Context
- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools - Uses Bash, Read, Write, AskUserQuestion - NOT MCP tools
- **MCP tools won't work until after setup + session restart** - MCP tools won't work until after setup + session restart
- **Shares Gitea MCP server with projman plugin** - Shares Gitea MCP server with projman plugin
--- ## Workflow
## Phase 1: Check Existing Setup ### Phase 1: Check Existing Setup
### Step 1.1: Check if Gitea MCP is Already Configured Check `~/.config/claude/gitea.env`. If valid, skip to Phase 3.
First, check if the system configuration already exists (from projman or previous setup): ### Phase 2: System Setup (if needed)
```bash Execute `skills/setup-workflow.md`: verify Python, create gitea.env, prompt for token
cat ~/.config/claude/gitea.env 2>/dev/null || echo "FILE_NOT_FOUND"
```
**If file exists with valid values (no placeholders):** ### Phase 3: Project Configuration
- Skip to Phase 3 (Project Configuration)
- Inform user: "Gitea configuration found. Skipping system setup."
**If file doesn't exist or has placeholders:** Execute `skills/setup-workflow.md`: auto-detect org/repo, validate via API, create .env
- Continue to Phase 2
### Step 1.2: Check if projman is Installed ### Phase 4: Validation
Check if projman plugin exists (they share MCP server): Test API connection, display completion summary, remind to restart session
```bash
find ~/.claude ~/.config/claude -name "projman" -type d 2>/dev/null | head -1
```
**If projman exists:**
- Suggest: "The projman plugin is installed and shares the same Gitea MCP server. Consider running `/initial-setup` from projman for the full setup wizard."
Use AskUserQuestion:
- Question: "How would you like to proceed with setup?"
- Header: "Setup"
- Options:
- "Continue with pr-review setup (Recommended if not using projman)"
- "I'll use projman's /initial-setup instead"
**If user chooses projman setup:** End here with instructions to run projman's setup.
---
## Phase 2: System Setup (if needed)
This is a condensed version focusing on what pr-review needs.
### Step 2.1: Python and MCP Server
Check Python version:
```bash
python3 --version
```
If below 3.10, stop and inform user.
Locate and set up the MCP server:
```bash
find ~/.claude ~/.config/claude -name "mcp_server" -path "*gitea*" 2>/dev/null | head -5
```
If venv doesn't exist, create it:
```bash
cd /path/to/mcp-servers/gitea && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate
```
### Step 2.2: Gitea Configuration
Create config directory:
```bash
mkdir -p ~/.config/claude
```
Use AskUserQuestion:
- Question: "What is your Gitea server URL?"
- Header: "Gitea URL"
- Options:
- "https://gitea.hotserv.cloud"
- "Other (I'll provide the URL)"
Create configuration file (credentials only, org is per-project):
```bash
cat > ~/.config/claude/gitea.env << 'EOF'
# Gitea API Configuration
# Generated by pr-review /initial-setup
# Note: GITEA_ORG is configured per-project in .env
GITEA_API_URL=<USER_PROVIDED_URL>
GITEA_API_TOKEN=PASTE_YOUR_TOKEN_HERE
EOF
chmod 600 ~/.config/claude/gitea.env
```
### Step 2.3: Token Instructions
Display these instructions:
---
**Action Required: Add Your Gitea API Token**
I've created `~/.config/claude/gitea.env` but you need to add your API token manually.
**Steps:**
1. Open: `nano ~/.config/claude/gitea.env`
2. Generate token in Gitea: Settings → Applications → Generate New Token
- Permissions needed: `repo`, `read:org`, `read:user`
3. Replace `PASTE_YOUR_TOKEN_HERE` with your token
4. Save the file
---
Use AskUserQuestion:
- Question: "Have you added your Gitea token?"
- Header: "Token"
- Options:
- "Yes, I've added the token"
- "Skip for now"
---
## Phase 3: Project Configuration
### Step 3.1: Check Current Directory
```bash
pwd && git rev-parse --show-toplevel 2>/dev/null || echo "NOT_A_GIT_REPO"
```
### Step 3.2: Check Existing Project Config
```bash
cat .env 2>/dev/null | grep GITEA_REPO || echo "NOT_FOUND"
```
If `GITEA_REPO` is already set, skip to Phase 4.
### Step 3.3: Detect Organization and Repository
Extract organization:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\/[^/]*$/\1/'
```
Extract repository:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/'
```
### Step 3.4: Validate Repository via Gitea API
```bash
source ~/.config/claude/gitea.env
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/repos/<detected-org>/<detected-repo>"
```
| HTTP Code | Action |
|-----------|--------|
| **200** | Auto-fill - "Verified: <org>/<repo> exists" - skip to Step 3.7 |
| **404** | Not found - proceed to Step 3.5 |
| **401/403** | Permission issue - warn, proceed to Step 3.5 |
### Step 3.5: Confirm Organization (only if validation failed)
Use AskUserQuestion:
- Question: "Repository not found. Is '<detected-org>' the correct organization?"
- Header: "Organization"
- Options:
- "Yes, that's correct"
- "No, let me specify"
### Step 3.6: Confirm Repository (only if validation failed)
Use AskUserQuestion:
- Question: "Is '<detected-repo-name>' the correct repository?"
- Header: "Repository"
- Options:
- "Yes, that's correct"
- "No, let me specify"
**After corrections, re-validate via API (Step 3.4).**
### Step 3.7: Create/Update Project Config
If `.env` exists, append:
```bash
echo "GITEA_ORG=<ORG_NAME>" >> .env
echo "GITEA_REPO=<REPO_NAME>" >> .env
```
If `.env` doesn't exist:
```bash
cat > .env << 'EOF'
# Project Configuration
GITEA_ORG=<ORG_NAME>
GITEA_REPO=<REPO_NAME>
EOF
```
### Step 3.5: PR Review Settings (Optional)
Use AskUserQuestion:
- Question: "Do you want to configure PR review settings?"
- Header: "Settings"
- Options:
- "Use defaults (Recommended)"
- "Let me customize"
If customize, ask about:
- `PR_REVIEW_CONFIDENCE_THRESHOLD` (default: 0.5)
- `PR_REVIEW_AUTO_SUBMIT` (default: false)
---
## Phase 4: Validation and Next Steps
### Step 4.1: Test Configuration (if token was added)
```bash
source ~/.config/claude/gitea.env && curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/user"
```
Report result:
- 200: Success
- 401: Invalid token
- Other: Connection issue
### Step 4.2: Summary
```
╔════════════════════════════════════════════════════════════╗
║ PR-REVIEW SETUP COMPLETE ║
╠════════════════════════════════════════════════════════════╣
║ MCP Server (Gitea): ✓ Ready ║
║ System Config: ✓ ~/.config/claude/gitea.env ║
║ Project Config: ✓ ./.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 `/pr-review <PR_NUMBER>` to review a pull request
- Run `/pr-summary <PR_NUMBER>` for a quick summary
- Run `/pr-findings <PR_NUMBER>` to list actionable findings
---
## Available Commands After Setup ## Available Commands After Setup
| Command | Description | - `/pr-review <number>` - Full multi-agent review
|---------|-------------| - `/pr-summary <number>` - Quick summary
| `/pr-review <number>` | Full multi-agent PR review with confidence scoring | - `/pr-findings <number>` - List findings
| `/pr-summary <number>` | Quick PR summary |
| `/pr-findings <number>` | List findings with severity and line numbers |

160
plugins/pr-review/commands/pr-diff.md
View File

@@ -2,165 +2,47 @@
## Visual Output ## Visual Output
When executing this command, display the plugin header: Display header: `PR-REVIEW - Diff Viewer`
``` ## Skills to Load
┌──────────────────────────────────────────────────────────────────┐
│ 🔍 PR-REVIEW · Diff Viewer │
└──────────────────────────────────────────────────────────────────┘
```
Then proceed with the diff display. - skills/mcp-tools-reference.md
- skills/pr-analysis.md
## Purpose - skills/output-formats.md
Display the PR diff with inline annotations from review comments, making it easy to see what feedback has been given alongside the code changes.
## Usage ## Usage
``` ```
/pr-diff <pr-number> [--repo owner/repo] [--context <lines>] /pr-diff <pr-number> [--repo owner/repo] [--context <n>] [--no-comments] [--file <pattern>]
``` ```
### Options ## Workflow
``` ### Step 1: Fetch Data
--repo <owner/repo> Override repository (default: from .env)
--context <n> Lines of context around changes (default: 3)
--no-comments Show diff without comment annotations
--file <pattern> Filter to specific files (glob pattern)
```
## Behavior Load MCP tools, then: `get_pr_diff`, `get_pr_comments`
### Step 1: Fetch PR Data
Using Gitea MCP tools:
1. `get_pr_diff` - Unified diff of all changes
2. `get_pr_comments` - All review comments on the PR
### Step 2: Parse and Annotate ### Step 2: Parse and Annotate
Parse the diff and overlay comments at their respective file/line positions: Execute `skills/pr-analysis.md` Annotated Diff Display:
- Overlay comments at file/line positions
- Show commenter, timestamp, replies
- Mark resolved vs open
``` ### Step 3: Display
═══════════════════════════════════════════════════
PR #123 Diff - Add user authentication
═══════════════════════════════════════════════════
Branch: feat/user-auth → development Use annotated diff format from `skills/output-formats.md`
Files: 12 changed (+234 / -45)
───────────────────────────────────────────────────
src/api/users.ts (+85 / -12)
───────────────────────────────────────────────────
@@ -42,6 +42,15 @@ export async function getUser(id: string) {
42 │ const db = getDatabase();
43 │
44 │- const user = db.query("SELECT * FROM users WHERE id = " + id);
│ ┌─────────────────────────────────────────────────────────────
│ │ COMMENT by @reviewer (2h ago):
│ │ This is a SQL injection vulnerability. Use parameterized
│ │ queries instead: `db.query("SELECT * FROM users WHERE id = ?", [id])`
│ └─────────────────────────────────────────────────────────────
45 │+ const query = "SELECT * FROM users WHERE id = ?";
46 │+ const user = db.query(query, [id]);
47 │
48 │ if (!user) {
49 │ throw new NotFoundError("User not found");
50 │ }
@@ -78,3 +87,12 @@ export async function updateUser(id: string, data: UserInput) {
87 │+ // Validate input before update
88 │+ validateUserInput(data);
89 │+
90 │+ const result = db.query(
91 │+ "UPDATE users SET name = ?, email = ? WHERE id = ?",
92 │+ [data.name, data.email, id]
93 │+ );
│ ┌─────────────────────────────────────────────────────────────
│ │ COMMENT by @maintainer (1h ago):
│ │ Good use of parameterized query here!
│ │
│ │ REPLY by @author (30m ago):
│ │ Thanks! Applied the same pattern throughout.
│ └─────────────────────────────────────────────────────────────
───────────────────────────────────────────────────
src/components/LoginForm.tsx (+65 / -0) [NEW FILE]
───────────────────────────────────────────────────
@@ -0,0 +1,65 @@
1 │+import React, { useState } from 'react';
2 │+import { useAuth } from '../context/AuthContext';
3 │+
4 │+export function LoginForm() {
5 │+ const [email, setEmail] = useState('');
6 │+ const [password, setPassword] = useState('');
7 │+ const { login } = useAuth();
... (remaining diff content)
═══════════════════════════════════════════════════
Comment Summary: 5 comments, 2 resolved
═══════════════════════════════════════════════════
```
### Step 3: Filter by Confidence (Optional)
If `PR_REVIEW_CONFIDENCE_THRESHOLD` is set, also annotate with high-confidence findings from previous reviews:
```
44 │- const user = db.query("SELECT * FROM users WHERE id = " + id);
│ ┌─── REVIEW FINDING (0.95 HIGH) ─────────────────────────────
│ │ [SEC-001] SQL Injection Vulnerability
│ │ Use parameterized queries to prevent injection attacks.
│ └─────────────────────────────────────────────────────────────
│ ┌─── COMMENT by @reviewer ────────────────────────────────────
│ │ This is a SQL injection vulnerability...
│ └─────────────────────────────────────────────────────────────
```
## Output Formats
### Default (Annotated Diff)
Full diff with inline comments as shown above.
### Plain (--no-comments)
```
/pr-diff 123 --no-comments
# Standard unified diff output without annotations
```
### File Filter (--file)
```
/pr-diff 123 --file "src/api/*"
# Shows diff only for files matching pattern
```
## Use Cases ## Use Cases
- **Review preparation**: See the full context of changes with existing feedback - Review preparation with existing feedback
- **Followup work**: Understand what was commented on and where - Followup work - see what was commented
- **Discussion context**: View threaded conversations alongside the code - Progress tracking on resolved comments
- **Progress tracking**: See which comments have been resolved
## Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `PR_REVIEW_CONFIDENCE_THRESHOLD` | `0.7` | Minimum confidence for showing review findings |
## Related Commands ## Related Commands
| Command | Purpose | | Command | Purpose |
|---------|---------| |---------|---------|
| `/pr-summary` | Quick overview without diff | | `/pr-summary` | Quick overview |
| `/pr-review` | Full multi-agent review | | `/pr-review` | Full review |
| `/pr-findings` | Filter review findings by category | | `/pr-findings` | Filter findings |

146
plugins/pr-review/commands/pr-findings.md
View File

@@ -2,148 +2,44 @@
## Visual Output ## Visual Output
When executing this command, display the plugin header: Display header: `PR-REVIEW - Findings`
``` ## Skills to Load
┌──────────────────────────────────────────────────────────────────┐
│ 🔍 PR-REVIEW · Findings │
└──────────────────────────────────────────────────────────────────┘
```
Then proceed with the findings display. - skills/mcp-tools-reference.md
- skills/review-patterns/confidence-scoring.md
## Purpose - skills/output-formats.md
List and filter findings from a previous PR review by category, severity, or confidence level.
## Usage ## Usage
``` ```
/pr-findings <pr-number> [filters] /pr-findings <pr-number> [--category <cat>] [--severity <sev>] [--confidence <min>] [--file <pattern>] [--compact] [--json]
``` ```
### Filters ## Workflow
```
--category <cat> Filter by category (security, performance, maintainability, tests)
--severity <sev> Filter by severity (critical, major, minor, suggestion)
--confidence <min> Minimum confidence score (0.0-1.0)
--file <pattern> Filter by file path pattern
```
## Examples
```
# Show only security findings
/pr-findings 123 --category security
# Show critical and major issues only
/pr-findings 123 --severity critical,major
# Show high-confidence findings only
/pr-findings 123 --confidence 0.8
# Show findings in specific files
/pr-findings 123 --file src/api/*
```
## Behavior
### Without Previous Review ### Without Previous Review
If no review exists for this PR: Prompt: "No review found. Run /pr-review, /pr-summary, or cancel?"
```
No review found for PR #123.
Would you like to:
1. Run full /pr-review now
2. Run quick /pr-summary
3. Cancel
```
### With Previous Review ### With Previous Review
Display filtered findings: 1. Load findings from previous review
2. Apply filters (category, severity, confidence, file)
``` 3. Display using format from `skills/output-formats.md`
═══════════════════════════════════════════════════
PR #123 Findings (filtered: security)
═══════════════════════════════════════════════════
Showing 3 of 8 total findings
───────────────────────────────────────────────────
[SEC-001] SQL Injection Vulnerability
Confidence: 0.95 (HIGH) | Severity: Critical
File: src/api/users.ts:45
The query uses string interpolation without parameterization.
Fix: Use parameterized queries.
───────────────────────────────────────────────────
[SEC-002] Missing Input Validation
Confidence: 0.88 (MEDIUM) | Severity: Major
File: src/api/auth.ts:23
User input is passed directly to database without validation.
Fix: Add input validation middleware.
───────────────────────────────────────────────────
[SEC-003] Sensitive Data in Logs
Confidence: 0.72 (MEDIUM) | Severity: Minor
File: src/utils/logger.ts:15
Password field may be logged in debug mode.
Fix: Sanitize sensitive fields before logging.
═══════════════════════════════════════════════════
```
## Output Formats ## Output Formats
### Default (Detailed) Reference `skills/output-formats.md`:
- **Detailed** (default) - Full finding
- **Compact** (`--compact`) - Single line
- **JSON** (`--json`) - Structured data
Full finding details with descriptions and fixes. ## Examples
### Compact (--compact)
```bash
/pr-findings 123 --category security
/pr-findings 123 --severity critical,major
/pr-findings 123 --confidence 0.8
/pr-findings 123 --file src/api/*
``` ```
SEC-001 | Critical | 0.95 | src/api/users.ts:45 | SQL Injection
SEC-002 | Major | 0.88 | src/api/auth.ts:23 | Missing Validation
SEC-003 | Minor | 0.72 | src/utils/logger.ts | Sensitive Logs
```
### JSON (--json)
```json
{
"pr": 123,
"findings": [
{
"id": "SEC-001",
"category": "security",
"severity": "critical",
"confidence": 0.95,
"file": "src/api/users.ts",
"line": 45,
"title": "SQL Injection Vulnerability",
"description": "...",
"fix": "..."
}
]
}
```
## Use Cases
- Focus on specific issue types
- Track resolution of findings
- Export findings for tracking
- Quick reference during fixes

144
plugins/pr-review/commands/pr-review.md
View File

@@ -2,19 +2,14 @@
## Visual Output ## Visual Output
When executing this command, display the plugin header: Display header: `PR-REVIEW - Full Review`
``` ## Skills to Load
┌──────────────────────────────────────────────────────────────────┐
│ 🔍 PR-REVIEW · Full Review │
└──────────────────────────────────────────────────────────────────┘
```
Then proceed with the review. - skills/mcp-tools-reference.md
- skills/review-workflow.md
## Purpose - skills/review-patterns/confidence-scoring.md
- skills/output-formats.md
Conduct a comprehensive pull request review using specialized agents for security, performance, maintainability, and test coverage.
## Usage ## Usage
@@ -22,132 +17,37 @@ Conduct a comprehensive pull request review using specialized agents for securit
/pr-review <pr-number> [--repo owner/repo] /pr-review <pr-number> [--repo owner/repo]
``` ```
## Behavior ## Workflow
### Step 1: Fetch PR Data ### Step 1: Fetch PR Data
Using Gitea MCP tools: Load MCP tools, then: `get_pull_request`, `get_pr_diff`, `get_pr_comments`
1. `get_pull_request` - PR metadata
2. `get_pr_diff` - Code changes
3. `get_pr_comments` - Existing discussion
### Step 2: Dispatch to Agents ### Step 2: Dispatch to Agents
The coordinator dispatches review tasks to specialized agents: Execute `skills/review-workflow.md` - dispatch to Security, Performance, Maintainability, Test agents
``` ### Step 3: Aggregate and Filter
PR Review: #123 - Add user authentication
═══════════════════════════════════════════════════
Dispatching to review agents: Apply confidence threshold (default: 0.7). See `skills/review-patterns/confidence-scoring.md`
├─ Security Reviewer → analyzing...
├─ Performance Analyst → analyzing...
├─ Maintainability Auditor → analyzing...
└─ Test Validator → analyzing...
```
### Step 3: Aggregate Findings ### Step 4: Generate Report
Collect findings from all agents, each with: Use format from `skills/output-formats.md`. Group by severity: critical > major > minor > suggestion
- Category (security, performance, maintainability, tests)
- Severity (critical, major, minor, suggestion)
- Confidence score (0.0 - 1.0)
- File and line reference
- Description
- Suggested fix (if applicable)
### Step 4: Filter by Confidence ### Step 5: Determine Verdict
Filter findings based on `PR_REVIEW_CONFIDENCE_THRESHOLD` (default: 0.7): - Any critical or 2+ major: REQUEST_CHANGES
- Only minor/suggestions: COMMENT
| Confidence | Label | Description | - No significant findings: APPROVE
|------------|-------|-------------|
| 0.9 - 1.0 | HIGH | Definite issue, must address |
| 0.7 - 0.89 | MEDIUM | Likely issue, should address |
| 0.5 - 0.69 | LOW | Possible concern, consider addressing |
| < threshold | (filtered) | Below configured threshold |
**Note:** With the default threshold of 0.7, only MEDIUM and HIGH confidence findings are shown. Adjust `PR_REVIEW_CONFIDENCE_THRESHOLD` to include more or fewer findings.
### Step 5: Generate Report
```
═══════════════════════════════════════════════════
PR Review Report: #123
═══════════════════════════════════════════════════
Summary:
Files changed: 12
Lines added: 234
Lines removed: 45
Findings: 8 total
🔴 Critical: 1
🟠 Major: 2
🟡 Minor: 3
💡 Suggestions: 2
───────────────────────────────────────────────────
CRITICAL FINDINGS
───────────────────────────────────────────────────
[SEC-001] SQL Injection Vulnerability (Confidence: 0.95)
File: src/api/users.ts:45
Category: Security
The query uses string interpolation without parameterization:
```ts
const query = `SELECT * FROM users WHERE id = ${userId}`;
```
Suggested fix:
```ts
const query = 'SELECT * FROM users WHERE id = ?';
db.query(query, [userId]);
```
───────────────────────────────────────────────────
MAJOR FINDINGS
───────────────────────────────────────────────────
[PERF-001] N+1 Query Pattern (Confidence: 0.82)
...
───────────────────────────────────────────────────
VERDICT
───────────────────────────────────────────────────
❌ REQUEST_CHANGES
This PR has 1 critical security issue that must be addressed
before merging. See SEC-001 above.
───────────────────────────────────────────────────
```
### Step 6: Submit Review (Optional) ### Step 6: Submit Review (Optional)
``` Ask user to submit as REQUEST_CHANGES, COMMENT, or skip. Use `create_pr_review` MCP tool.
Submit this review to Gitea?
1. Yes, with REQUEST_CHANGES
2. Yes, as COMMENT only
3. No, just show me the report
```
If yes, use `create_pr_review` MCP tool.
## Output
Full review report with:
- Summary statistics
- Findings grouped by severity
- Code snippets with context
- Suggested fixes
- Overall verdict
## Configuration ## Configuration
| Variable | Default | Description | | Variable | Default |
|----------|---------|-------------| |----------|---------|
| `PR_REVIEW_CONFIDENCE_THRESHOLD` | `0.7` | Minimum confidence to report (0.0-1.0) | | `PR_REVIEW_CONFIDENCE_THRESHOLD` | `0.7` |
| `PR_REVIEW_AUTO_SUBMIT` | `false` | Auto-submit to Gitea | | `PR_REVIEW_AUTO_SUBMIT` | `false` |

104
plugins/pr-review/commands/pr-summary.md
View File

@@ -2,19 +2,13 @@
## Visual Output ## Visual Output
When executing this command, display the plugin header: Display header: `PR-REVIEW - Quick Summary`
``` ## Skills to Load
┌──────────────────────────────────────────────────────────────────┐
│ 🔍 PR-REVIEW · Quick Summary │
└──────────────────────────────────────────────────────────────────┘
```
Then proceed with the summary. - skills/mcp-tools-reference.md
- skills/pr-analysis.md
## Purpose - skills/output-formats.md
Generate a quick summary of PR changes without conducting a full multi-agent review.
## Usage ## Usage
@@ -22,94 +16,26 @@ Generate a quick summary of PR changes without conducting a full multi-agent rev
/pr-summary <pr-number> [--repo owner/repo] /pr-summary <pr-number> [--repo owner/repo]
``` ```
## Behavior ## Workflow
### Step 1: Fetch PR Data ### Step 1: Fetch PR Data
Using Gitea MCP tools: Load MCP tools, then: `get_pull_request`, `get_pr_diff`
1. `get_pull_request` - PR metadata
2. `get_pr_diff` - Code changes
### Step 2: Analyze Changes ### Step 2: Analyze Changes
Quick analysis of: Execute `skills/pr-analysis.md`:
- Files modified - Categorize changes (feature, fix, refactor)
- Types of changes (features, fixes, refactoring) - Calculate statistics
- Scope and impact - Identify key files
- Assess scope and risk
### Step 3: Generate Summary ### Step 3: Generate Summary
``` Use summary format from `skills/output-formats.md`
═══════════════════════════════════════════════════
PR Summary: #123 - Add user authentication
═══════════════════════════════════════════════════
Author: @johndoe
Branch: feat/user-auth → development
Status: Open (ready for review)
───────────────────────────────────────────────────
CHANGES OVERVIEW
───────────────────────────────────────────────────
Files: 12 changed
+ 8 new files
~ 3 modified files
- 1 deleted file
Lines: +234 / -45 (net +189)
───────────────────────────────────────────────────
WHAT THIS PR DOES
───────────────────────────────────────────────────
This PR adds user authentication functionality:
1. **New API endpoints**
- POST /api/auth/login
- POST /api/auth/register
- POST /api/auth/logout
2. **Frontend components**
- LoginForm component
- RegisterForm component
- Auth context provider
3. **Database changes**
- New users table
- Sessions table
───────────────────────────────────────────────────
KEY FILES
───────────────────────────────────────────────────
• src/api/auth/login.ts (+85) - Login endpoint
• src/api/auth/register.ts (+120) - Registration
• src/components/LoginForm.tsx (+65) - Login UI
• src/db/migrations/001_users.sql (+45) - Schema
───────────────────────────────────────────────────
QUICK ASSESSMENT
───────────────────────────────────────────────────
Scope: Medium (authentication feature)
Risk: Medium (new security-sensitive code)
Recommendation: Full /pr-review suggested
═══════════════════════════════════════════════════
```
## Output
Summary report with:
- PR metadata
- Change statistics
- Plain-language description of changes
- Key files list
- Quick risk assessment
## When to Use ## When to Use
- Get quick overview before full review - Quick overview before full review
- Triage multiple PRs - Triage multiple PRs
- Understand PR scope - Decide if /pr-review is needed

151
plugins/pr-review/commands/project-init.md
View File

@@ -1,148 +1,45 @@
--- ---
description: Quick project setup - configures only project-level settings for PR review description: Quick project setup - configures only project-level settings
--- ---
# Project Initialization (PR Review) # Project Initialization (PR Review)
## Visual Output ## Visual Output
When executing this command, display the plugin header: Display header: `PR-REVIEW - Project Setup`
``` ## Skills to Load
┌──────────────────────────────────────────────────────────────────┐
│ 🔍 PR-REVIEW · Project Setup │
└──────────────────────────────────────────────────────────────────┘
```
Then proceed with the setup. - skills/setup-workflow.md
- skills/output-formats.md
Fast setup for a new project when system-level configuration is already complete. ## Purpose
**Use this when:** Fast setup when system-level config already exists.
- You've already run `/initial-setup` on this machine
- You're starting work on a new project/repository
- You just need to configure this project for PR reviews
--- **Use when:** Already ran `/initial-setup`, starting new project
## Pre-Flight Check ## Workflow
### Step 1: Verify System Configuration ### Pre-Flight Check
```bash Verify `~/.config/claude/gitea.env` exists. If missing: redirect to `/initial-setup`
cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep -v "PASTE_YOUR" | grep "GITEA_API_TOKEN=" && echo "SYSTEM_OK" || echo "SYSTEM_MISSING"
```
**If SYSTEM_MISSING:** ### Project Setup
--- Execute `skills/setup-workflow.md`:
1. Verify git repo
2. Check existing .env
3. Auto-detect org/repo from git remote
4. Validate via Gitea API
5. Create/update .env
**System configuration not found.** ### Complete
Please run `/initial-setup` first to configure Gitea credentials. Display project configured format from `skills/output-formats.md`
--- ## Ready Commands
**If SYSTEM_OK:** Continue. - `/pr-review <number>` - Full review
- `/pr-summary <number>` - Quick summary
--- - `/pr-findings <number>` - List findings
## Project Setup
### Step 2: Verify Current Directory
```bash
pwd && git rev-parse --show-toplevel 2>/dev/null || echo "NOT_A_GIT_REPO"
```
### Step 3: Check Existing Configuration
```bash
cat .env 2>/dev/null | grep "GITEA_REPO=" || echo "NOT_CONFIGURED"
```
If already configured, ask if user wants to keep or reconfigure.
### Step 4: Detect Organization and Repository
Extract organization:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\/[^/]*$/\1/'
```
Extract repository:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/'
```
### Step 5: Validate Repository via Gitea API
```bash
source ~/.config/claude/gitea.env
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/repos/<detected-org>/<detected-repo>"
```
| HTTP Code | Action |
|-----------|--------|
| **200** | Auto-fill - "Verified: <org>/<repo> exists" - skip to Step 8 |
| **404** | Not found - proceed to Step 6 |
| **401/403** | Permission issue - warn, proceed to Step 6 |
### Step 6: Confirm Organization (only if validation failed)
Use AskUserQuestion:
- Question: "Repository not found. Is '<detected-org>' the correct organization?"
- Header: "Organization"
- Options:
- "Yes, that's correct"
- "No, let me specify"
### Step 7: Confirm Repository (only if validation failed)
Use AskUserQuestion:
- Question: "Is '<detected-repo-name>' the correct repository?"
- Header: "Repository"
- Options:
- "Yes, that's correct"
- "No, let me specify"
**After corrections, re-validate via API (Step 5).**
### Step 8: Create/Update .env
```bash
echo "GITEA_ORG=<ORG_NAME>" >> .env
echo "GITEA_REPO=<REPO_NAME>" >> .env
```
### Step 9: Optional PR Review Settings
Use AskUserQuestion:
- Question: "Configure PR review settings?"
- Header: "Settings"
- Options:
- "Use defaults (Recommended)"
- "Customize settings"
If customize:
- `PR_REVIEW_CONFIDENCE_THRESHOLD` (default: 0.5)
- `PR_REVIEW_AUTO_SUBMIT` (default: false)
---
## Complete
```
╔══════════════════════════════════════════════════════════════╗
║ PROJECT CONFIGURED ║
╠══════════════════════════════════════════════════════════════╣
║ Organization: <ORG_NAME> ║
║ Repository: <REPO_NAME> ║
║ Config file: ./.env ║
╚══════════════════════════════════════════════════════════════╝
Ready to review PRs:
• /pr-review <number> - Full multi-agent review
• /pr-summary <number> - Quick summary
• /pr-findings <number> - List findings
```

107
plugins/pr-review/commands/project-sync.md
View File

@@ -1,105 +1,32 @@
--- ---
description: Sync project configuration with current git remote - use after changing repository location description: Sync project configuration with current git remote
--- ---
# Project Sync (PR Review) # Project Sync (PR Review)
## Visual Output ## Visual Output
When executing this command, display the plugin header: Display header: `PR-REVIEW - Project Sync`
``` ## Skills to Load
┌──────────────────────────────────────────────────────────────────┐
│ 🔍 PR-REVIEW · Project Sync │
└──────────────────────────────────────────────────────────────────┘
```
Then proceed with the synchronization. - skills/setup-workflow.md
- skills/output-formats.md
Updates project configuration when the git remote URL has changed. ## Purpose
**Use this when:** Updates config when git remote URL changed.
- Repository was moved to a different organization
- Repository was renamed
- Git remote URL changed
- SessionStart hook detected a mismatch
--- **Use when:** Repo moved/renamed, SessionStart detected mismatch
## Step 1: Verify System Configuration ## Workflow
```bash Execute `skills/setup-workflow.md` Sync Workflow:
cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep -v "PASTE_YOUR" | grep "GITEA_API_TOKEN=" && echo "SYSTEM_OK" || echo "SYSTEM_MISSING"
```
**If SYSTEM_MISSING:** Run `/initial-setup` first. 1. Verify system config exists
2. Read current .env values
--- 3. Detect org/repo from git remote
4. Compare - if match, exit; if mismatch, continue
## Step 2: Read Current .env 5. Validate new values via API
6. Update .env with sed
```bash 7. Display confirmation from `skills/output-formats.md`
cat .env 2>/dev/null
```
Extract `GITEA_ORG` and `GITEA_REPO` values.
**If missing:** Redirect to `/project-init`.
---
## Step 3: Detect Git Remote
```bash
git remote get-url origin 2>/dev/null
```
Extract organization and repository from URL.
---
## Step 4: Compare Values
| Scenario | Action |
|----------|--------|
| **Match** | "Configuration in sync" - exit |
| **Mismatch** | Show diff, proceed to validation |
---
## Step 5: Validate via Gitea API
```bash
source ~/.config/claude/gitea.env
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/repos/<NEW_ORG>/<NEW_REPO>"
```
| Code | Action |
|------|--------|
| **200** | Verified - proceed to update |
| **404** | Not found - ask to confirm |
| **401/403** | Permission issue - warn |
---
## Step 6: Confirm and Update
Use AskUserQuestion to confirm, then update .env:
```bash
sed -i 's/^GITEA_ORG=.*/GITEA_ORG=<NEW_ORG>/' .env
sed -i 's/^GITEA_REPO=.*/GITEA_REPO=<NEW_REPO>/' .env
```
---
## Step 7: Confirm Success
```
╔══════════════════════════════════════════════════════════════╗
║ CONFIGURATION UPDATED ║
╠══════════════════════════════════════════════════════════════╣
║ Organization: <NEW_ORG> ║
║ Repository: <NEW_REPO> ║
╚══════════════════════════════════════════════════════════════╝
```

80
plugins/pr-review/skills/mcp-tools-reference.md Normal file
View File

@@ -0,0 +1,80 @@
# MCP Tools Reference - Gitea PR Operations
## Available Tools
Use `ToolSearch` to load these tools before use.
### Pull Request Tools
| Tool | Purpose |
|------|---------|
| `mcp__gitea__list_pull_requests` | List PRs (open, closed, all) |
| `mcp__gitea__get_pull_request` | Get PR metadata, status, labels |
| `mcp__gitea__get_pr_diff` | Get unified diff of changes |
| `mcp__gitea__get_pr_comments` | Get review comments and discussions |
| `mcp__gitea__create_pr_review` | Submit review (approve, comment, request changes) |
| `mcp__gitea__add_pr_comment` | Add single comment to PR |
| `mcp__gitea__create_pull_request` | Create new PR |
### Supporting Tools
| Tool | Purpose |
|------|---------|
| `mcp__gitea__get_issue` | Get linked issue details |
| `mcp__gitea__get_labels` | Get available labels |
| `mcp__gitea__validate_repo_org` | Validate repository exists |
## Loading Tools
Before using MCP tools, load them:
```
Use ToolSearch with query: "+gitea pull_request"
```
## Common Operations
### Fetch PR for Review
```
1. get_pull_request(pr_number) -> metadata
2. get_pr_diff(pr_number) -> code changes
3. get_pr_comments(pr_number) -> existing feedback
```
### Submit Review
```
create_pr_review:
pr_number: number
body: string (review summary)
event: "APPROVE" | "COMMENT" | "REQUEST_CHANGES"
comments: [{path, line, body}] (optional inline comments)
```
### Add Comment
```
add_pr_comment:
pr_number: number
body: string
```
## Environment Variables
Required in `.env`:
- `GITEA_ORG` - Organization/owner name
- `GITEA_REPO` - Repository name
Required in `~/.config/claude/gitea.env`:
- `GITEA_API_URL` - Gitea server URL
- `GITEA_API_TOKEN` - API token with repo permissions
## Error Handling
| Error | Cause | Resolution |
|-------|-------|------------|
| Tool not found | MCP not loaded | Run ToolSearch first |
| 401 Unauthorized | Invalid/expired token | Regenerate token |
| 404 Not Found | Wrong org/repo or PR doesn't exist | Check .env settings |
| 403 Forbidden | Insufficient permissions | Check token scopes |

200
plugins/pr-review/skills/output-formats.md Normal file
View File

@@ -0,0 +1,200 @@
# Output Formats
## Visual Header
All commands display this header:
```
+----------------------------------------------------------------------+
| PR-REVIEW [Command Name] |
+----------------------------------------------------------------------+
```
## Review Report Format
```
===================================================
PR Review Report: #<number>
===================================================
Summary:
Files changed: <n>
Lines: +<added> / -<removed>
Agents consulted: <list>
Findings: <total>
Critical: <n>
Major: <n>
Minor: <n>
Suggestions: <n>
---------------------------------------------------
CRITICAL FINDINGS
---------------------------------------------------
[<ID>] <Title> (Confidence: <score>)
File: <path>:<line>
Category: <category>
<Description>
Suggested fix:
<code block>
---------------------------------------------------
VERDICT: <APPROVE|COMMENT|REQUEST_CHANGES>
---------------------------------------------------
<Justification>
```
## Summary Format
```
===================================================
PR Summary: #<number> - <title>
===================================================
Author: @<username>
Branch: <head> -> <base>
Status: <status>
---------------------------------------------------
CHANGES OVERVIEW
---------------------------------------------------
Files: <n> changed
+ <n> new files
~ <n> modified files
- <n> deleted files
Lines: +<added> / -<removed> (net +<diff>)
---------------------------------------------------
WHAT THIS PR DOES
---------------------------------------------------
<Plain-language description>
---------------------------------------------------
KEY FILES
---------------------------------------------------
* <path> (+<lines>) - <description>
---------------------------------------------------
QUICK ASSESSMENT
---------------------------------------------------
Scope: <Small|Medium|Large>
Risk: <Low|Medium|High>
Recommendation: <action>
===================================================
```
## Findings List Format
### Detailed (default)
```
===================================================
PR #<number> Findings (filtered: <filter>)
===================================================
Showing <n> of <total> findings
---------------------------------------------------
[<ID>] <Title>
Confidence: <score> (<label>) | Severity: <level>
File: <path>:<line>
<Description>
Fix: <suggestion>
---------------------------------------------------
```
### Compact (--compact)
```
<ID> | <Severity> | <Confidence> | <File>:<Line> | <Title>
```
### JSON (--json)
```json
{
"pr": <number>,
"findings": [
{
"id": "<ID>",
"category": "<category>",
"severity": "<severity>",
"confidence": <score>,
"file": "<path>",
"line": <number>,
"title": "<title>",
"description": "<description>",
"fix": "<suggestion>"
}
]
}
```
## Setup Complete Format
```
+============================================================+
| PR-REVIEW SETUP COMPLETE |
+============================================================+
| MCP Server (Gitea): Ready |
| System Config: ~/.config/claude/gitea.env |
| Project Config: ./.env |
+============================================================+
```
## Project Configured Format
```
+============================================================+
| PROJECT CONFIGURED |
+============================================================+
| Organization: <org> |
| Repository: <repo> |
| Config file: ./.env |
+============================================================+
Ready to review PRs:
- /pr-review <number> Full multi-agent review
- /pr-summary <number> Quick summary
- /pr-findings <number> List findings
```
## Annotated Diff Format
```
===================================================
PR #<number> Diff - <title>
===================================================
Branch: <head> -> <base>
Files: <n> changed (+<added> / -<removed>)
---------------------------------------------------
<file> (+<added> / -<removed>)
---------------------------------------------------
@@ -<old>,<ctx> +<new>,<ctx> @@ <context>
<line> | existing code
<line> |- removed code
| +--- COMMENT by @<user> (<time>) ---
| | <comment text>
| +-----------------------------------
<line> |+ added code
===================================================
Comment Summary: <n> comments, <n> resolved
===================================================
```

135
plugins/pr-review/skills/pr-analysis.md Normal file
View File

@@ -0,0 +1,135 @@
# PR Analysis Patterns
## Data Collection
### Step 1: Fetch PR Metadata
```
get_pull_request(pr_number) returns:
- title, description
- author, assignees
- base/head branches
- status (open, closed, merged)
- labels, milestone
- created_at, updated_at
```
### Step 2: Get Code Changes
```
get_pr_diff(pr_number) returns:
- Unified diff format
- File paths with +/- indicators
- Hunk headers with line numbers
```
### Step 3: Get Existing Feedback
```
get_pr_comments(pr_number) returns:
- Review comments with file/line
- General comments
- Author, timestamp
- Thread context (replies)
```
## Change Analysis
### Categorize Changes
| Pattern | Category |
|---------|----------|
| New files only | Feature addition |
| Modified test files | Test updates |
| Modified + deleted | Refactoring |
| Single file fix | Bug fix |
| Config/docs only | Infrastructure |
### Calculate Statistics
- Files changed count
- Lines added/removed
- Net change (+added - removed)
- New vs modified vs deleted files
### Identify Key Files
Priority order:
1. Security-sensitive (`auth`, `crypto`, `sql`)
2. API endpoints
3. Database migrations
4. Core business logic
5. Utilities and helpers
6. Tests
7. Documentation
## Risk Assessment
### Scope Assessment
| Files Changed | Lines Changed | Scope |
|---------------|---------------|-------|
| 1-3 | < 50 | Small |
| 4-10 | 50-200 | Medium |
| 10+ | 200+ | Large |
### Risk Indicators
| Indicator | Risk Level |
|-----------|------------|
| Security-sensitive files | High |
| Database migrations | High |
| API changes | Medium |
| New dependencies | Medium |
| Test-only changes | Low |
| Docs-only changes | Low |
## Summary Generation
### Quick Summary Template
```
This PR [adds|updates|fixes|removes] [feature/component]:
1. **[Category 1]**
- Change description
2. **[Category 2]**
- Change description
Key files:
- path/to/important/file.ts (+lines)
```
### Assessment Template
```
Scope: [Small|Medium|Large]
Risk: [Low|Medium|High]
Recommendation: [/pr-review suggested | Looks good to merge]
```
## Annotated Diff Display
### Format
```
File: src/api/users.ts (+85 / -12)
----------------------------------------
@@ -42,6 +42,15 @@ function description
42 | existing line
43 |
44 |- removed line
| [COMMENT by @user (time ago)]
| Comment text here
45 |+ added line
46 |+ another added line
```
### Comment Overlay
Position comments at their file/line locations:
- Show commenter username and time
- Include reply threads
- Mark resolved vs open

78
plugins/pr-review/skills/review-workflow.md Normal file
View File

@@ -0,0 +1,78 @@
# Multi-Agent Review Workflow
## Overview
PR reviews use specialized agents that analyze different aspects of code changes. The coordinator dispatches to relevant agents and aggregates findings.
## Agent Roles
| Agent | Focus Area | File Patterns |
|-------|------------|---------------|
| **Security Reviewer** | Vulnerabilities, auth, injection | `*.ts`, `*.js`, `*.sql`, `*.py` |
| **Performance Analyst** | N+1, inefficient algorithms, memory | `*.ts`, `*.js`, `*.py`, `*.go` |
| **Maintainability Auditor** | Complexity, readability, DRY | All code files |
| **Test Validator** | Coverage, edge cases, assertions | `*.test.*`, `*_test.*`, `*_spec.*` |
## Dispatch Logic
1. **Analyze changed files** - Identify file types and patterns
2. **Select agents** - Match files to relevant agents
3. **Parallel dispatch** - Send review tasks to agents
4. **Collect findings** - Aggregate results from all agents
5. **Filter by confidence** - Apply threshold (default: 0.7)
6. **Generate report** - Structure findings by severity
### Skip Patterns
Don't dispatch agents for:
- `*.md`, `*.txt` - Documentation only
- `*.json` (config) - Unless security-sensitive
- Generated files - `*.min.js`, `*.d.ts`, etc.
## Finding Structure
Each finding includes:
```
{
id: "SEC-001",
category: "security" | "performance" | "maintainability" | "tests",
severity: "critical" | "major" | "minor" | "suggestion",
confidence: 0.0 - 1.0,
file: "src/api/users.ts",
line: 45,
title: "SQL Injection Vulnerability",
description: "Detailed explanation...",
fix: "Suggested code fix..." (optional)
}
```
## Verdict Logic
| Condition | Verdict |
|-----------|---------|
| Any critical finding | REQUEST_CHANGES |
| 2+ major findings | REQUEST_CHANGES |
| Only minor/suggestions | COMMENT |
| No significant findings | APPROVE |
## Confidence Thresholds
Reference: `skills/review-patterns/confidence-scoring.md`
| Range | Label | Action |
|-------|-------|--------|
| 0.9 - 1.0 | HIGH | Must address |
| 0.7 - 0.89 | MEDIUM | Should address |
| 0.5 - 0.69 | LOW | Consider addressing |
| < threshold | Filtered | Not shown |
Default threshold: 0.7 (MEDIUM and above)
## Aggregation Rules
When multiple agents find the same issue:
1. Keep highest confidence score
2. Merge descriptions
3. Use most severe category
4. Deduplicate fixes

104
plugins/pr-review/skills/setup-workflow.md Normal file
View File

@@ -0,0 +1,104 @@
# Setup Workflow
## Configuration Hierarchy
| Level | Location | Contents |
|-------|----------|----------|
| System | `~/.config/claude/gitea.env` | API URL, token (shared across projects) |
| Project | `.env` in project root | Org, repo name (per project) |
## System Configuration
### Check Existing
```bash
cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep "GITEA_API_TOKEN=" && echo "OK" || echo "MISSING"
```
### Create New
```bash
mkdir -p ~/.config/claude
cat > ~/.config/claude/gitea.env << 'EOF'
# Gitea API Configuration
GITEA_API_URL=https://your-gitea-server.com
GITEA_API_TOKEN=PASTE_YOUR_TOKEN_HERE
EOF
chmod 600 ~/.config/claude/gitea.env
```
### Token Generation
1. Gitea: Settings > Applications > Generate New Token
2. Required scopes: `repo`, `read:org`, `read:user`
## Project Configuration
### Auto-Detect from Git Remote
Extract organization:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\/[^/]*$/\1/'
```
Extract repository:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/'
```
### Validate via API
```bash
source ~/.config/claude/gitea.env
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/repos/<org>/<repo>"
```
| Code | Meaning |
|------|---------|
| 200 | Repository verified |
| 404 | Not found - check org/repo names |
| 401/403 | Auth issue - check token |
### Create/Update .env
```bash
# New file
cat > .env << EOF
GITEA_ORG=<org>
GITEA_REPO=<repo>
EOF
# Or append to existing
echo "GITEA_ORG=<org>" >> .env
echo "GITEA_REPO=<repo>" >> .env
```
## PR Review Settings (Optional)
| Variable | Default | Description |
|----------|---------|-------------|
| `PR_REVIEW_CONFIDENCE_THRESHOLD` | `0.7` | Minimum confidence to report |
| `PR_REVIEW_AUTO_SUBMIT` | `false` | Auto-submit reviews to Gitea |
## Sync Workflow
When git remote changes:
1. Detect new org/repo from git remote
2. Compare with .env values
3. Validate new values via API
4. Update .env with sed:
```bash
sed -i 's/^GITEA_ORG=.*/GITEA_ORG=<new_org>/' .env
sed -i 's/^GITEA_REPO=.*/GITEA_REPO=<new_repo>/' .env
```
## Shared with projman
The Gitea MCP server is shared with the projman plugin. If projman is already configured, system-level setup can be skipped.
Check for projman:
```bash
find ~/.claude ~/.config/claude -name "projman" -type d 2>/dev/null | head -1
```