chore: release v3.2.0

Version 3.2.0 includes: - New features: netbox device params, claude-config-maintainer auto-enforce - Bug fixes: cmdb-assistant schemas, netbox tool names, API URLs - All hooks converted to command type - Versioning workflow with release script Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
feat: add versioning workflow with release script
2026-01-24 13:08:45 -05:00 · 2026-01-24 13:08:06 -05:00
4 changed files with 48 additions and 356 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -31,16 +31,11 @@ This file provides guidance to Claude Code when working with code in this reposi
 - If user asks for output, show the OUTPUT
 - **Don't interpret or summarize unless asked**
-### 5. AFTER PLUGIN UPDATES - VERIFY AND RESTART
+### 5. AFTER PLUGIN UPDATES - ALWAYS CLEAR CACHE
-
+```bash
-**⚠️ DO NOT clear cache mid-session** - this breaks MCP tools that are already loaded.
+rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/
-
+./scripts/verify-hooks.sh
-1. Run `./scripts/verify-hooks.sh` to check hook types
+```
 2. If changes affect MCP servers or hooks, inform the user:
   > "Plugin changes require a session restart to take effect. Please restart Claude Code."
 3. Cache clearing is ONLY safe **before** starting a new session (not during)
 See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing.
 **FAILURE TO FOLLOW THESE RULES = WASTED USER TIME = UNACCEPTABLE**
@@ -130,9 +125,7 @@ leo-claude-mktplace/
 │   └── project-hygiene/
 ├── scripts/
 │   ├── setup.sh, post-update.sh
-│   ├── validate-marketplace.sh   # Marketplace compliance validation
+│   └── validate-marketplace.sh   # Marketplace compliance validation
 │   ├── verify-hooks.sh           # Verify all hooks are command type
 │   └── check-venv.sh             # Check MCP server venvs exist
 └── docs/
    ├── CANONICAL-PATHS.md        # Single source of truth for paths
    └── CONFIGURATION.md          # Centralized configuration guide
@@ -179,12 +172,12 @@ leo-claude-mktplace/
 | Category | Tools |
 |----------|-------|
-| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment`, `aggregate_issues` |
+| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment` |
-| Labels | `get_labels`, `suggest_labels`, `create_label`, `create_label_smart` |
+| Labels | `get_labels`, `suggest_labels`, `create_label` |
-| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone`, `delete_milestone` |
+| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone` |
-| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `remove_issue_dependency`, `get_execution_order` |
+| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `get_execution_order` |
-| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `update_wiki_page`, `create_lesson`, `search_lessons` |
+| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `create_lesson`, `search_lessons` |
-| **Pull Requests** | `list_pull_requests`, `get_pull_request`, `get_pr_diff`, `get_pr_comments`, `create_pr_review`, `add_pr_comment` |
+| **Pull Requests** | `list_pull_requests`, `get_pull_request`, `get_pr_diff`, `get_pr_comments`, `create_pr_review`, `add_pr_comment` *(NEW v3.0.0)* |
 | Validation | `validate_repo_org`, `get_branch_protection` |
 ### Hybrid Configuration
--- a/docs/DEBUGGING-CHECKLIST.md
+++ b/docs/DEBUGGING-CHECKLIST.md
@@ -197,51 +197,6 @@ echo -e "\n=== Config Files ==="
 ---
 ## Cache Clearing: When It's Safe vs Destructive
 **⚠️ CRITICAL: Never clear plugin cache mid-session.**
 ### Why Cache Clearing Breaks MCP Tools
 When Claude Code starts a session:
 1. MCP tools are loaded from the cache directory
 2. Tool definitions include **absolute paths** to the venv (e.g., `~/.claude/plugins/cache/.../venv/`)
 3. These paths are cached in the session memory
 4. Deleting the cache removes the venv, but the session still references the old paths
 5. Any MCP tool making HTTP requests fails with TLS certificate errors
 ### When Cache Clearing is SAFE
 | Scenario | Safe? | Action |
 |----------|-------|--------|
 | Before starting Claude Code | ✅ Yes | Clear cache, then start session |
 | Between sessions | ✅ Yes | Clear cache after `/exit`, before next session |
 | During a session | ❌ NO | Never - will break MCP tools |
 | After plugin source edits | ❌ NO | Restart session instead |
 ### Recovery: MCP Tools Broken Mid-Session
 If you accidentally cleared cache during a session and MCP tools fail:
 ```
 Error: Could not find a suitable TLS CA certificate bundle, invalid path:
 /home/.../.claude/plugins/cache/.../certifi/cacert.pem
 ```
 **Fix:**
 1. Exit the current session (`/exit` or Ctrl+C)
 2. Start a new Claude Code session
 3. MCP tools will reload from the reinstalled cache
 ### Correct Workflow for Plugin Development
 1. Make changes to plugin source files
 2. Run `./scripts/verify-hooks.sh` (verifies hook types)
 3. Tell user: "Please restart Claude Code for changes to take effect"
 4. **Do NOT clear cache** - session restart handles reloading
 ---
 ## Automated Diagnostics
 Use these commands for automated checking:
--- a/plugins/projman/commands/debug-report.md
+++ b/plugins/projman/commands/debug-report.md
@@ -4,7 +4,7 @@ description: Run diagnostics and create structured issue in marketplace reposito
 # Debug Report
-Create structured issues in the marketplace repository - either from automated diagnostic tests OR from user-reported problems.
+Run diagnostic checks on projman MCP tools and create a structured issue in the marketplace repository for investigation.
 ## Prerequisites
@@ -20,101 +20,6 @@ If not configured, ask the user for the marketplace repository path.
 You MUST follow these steps in order. Do NOT skip any step.
 ### Step 0: Select Report Mode
 Use AskUserQuestion to determine what the user wants to report:
 ```
 What would you like to report?
 [ ] Run automated diagnostics - Test MCP tools and report failures
 [ ] Report an issue I experienced - Describe a problem with any plugin command
 ```
 Store the selection as `REPORT_MODE`:
 - "automated" → Continue to Step 1
 - "user-reported" → Skip to Step 0.1
 ---
 ### Step 0.1: Gather User Feedback (User-Reported Mode Only)
 If `REPORT_MODE` is "user-reported", gather structured feedback.
 **Question 1: What were you trying to do?**
 Use AskUserQuestion:
 ```
 Which plugin/command were you using?
 [ ] projman (sprint planning, issues, labels)
 [ ] git-flow (commits, branches)
 [ ] pr-review (pull request review)
 [ ] cmdb-assistant (NetBox integration)
 [ ] doc-guardian (documentation)
 [ ] code-sentinel (security, refactoring)
 [ ] Other - I'll describe it
 ```
 Store as `AFFECTED_PLUGIN`.
 Then ask for the specific command (free text):
 ```
 What command or tool were you using? (e.g., /sprint-plan, virt_update_vm)
 ```
 Store as `AFFECTED_COMMAND`.
 **Question 2: What was your goal?**
 ```
 Briefly describe what you were trying to accomplish:
 ```
 Store as `USER_GOAL`.
 **Question 3: What went wrong?**
 Use AskUserQuestion:
 ```
 What type of problem did you encounter?
 [ ] Error message - Command failed with an error
 [ ] Missing feature - Tool doesn't support what I need
 [ ] Unexpected behavior - It worked but did the wrong thing
 [ ] Documentation issue - Instructions were unclear or wrong
 [ ] Other - I'll describe it
 ```
 Store as `PROBLEM_TYPE`.
 Then ask for details (free text):
 ```
 Describe what happened. Include any error messages if applicable:
 ```
 Store as `PROBLEM_DESCRIPTION`.
 **Question 4: Expected vs Actual**
 ```
 What did you expect to happen?
 ```
 Store as `EXPECTED_BEHAVIOR`.
 **Question 5: Workaround (optional)**
 ```
 Did you find a workaround? If so, describe it (or skip):
 ```
 Store as `WORKAROUND` (may be empty).
 After gathering feedback, continue to Step 1 for context gathering, then skip to Step 5.1.
 ---
 ### Step 1: Gather Project Context
 Run these Bash commands to capture project information:
@@ -186,9 +91,7 @@ grep PROJMAN_MARKETPLACE_REPO .env
 Store as `MARKETPLACE_REPO`. If not found, ask the user.
-### Step 3: Run Diagnostic Suite (Automated Mode Only)
+### Step 3: Run Diagnostic Suite
 **Skip this step if `REPORT_MODE` is "user-reported"** → Go to Step 5.1
 Run each MCP tool with explicit `repo` parameter. Record success/failure and full response.
@@ -228,9 +131,7 @@ For each test, record:
 - Status: PASS or FAIL
 - Response or error message
-### Step 4: Analyze Results (Automated Mode Only)
+### Step 4: Analyze Results
 **Skip this step if `REPORT_MODE` is "user-reported"** → Go to Step 5.1
 Count failures and categorize errors:
@@ -244,9 +145,7 @@ Count failures and categorize errors:
 For each failure, write a hypothesis about the likely cause.
-### Step 5: Generate Smart Labels (Automated Mode Only)
+### Step 5: Generate Smart Labels
 **Skip this step if `REPORT_MODE` is "user-reported"** → Go to Step 5.1
 Generate appropriate labels based on the diagnostic results.
@@ -281,53 +180,7 @@ The final label set should include:
 - **Always**: `Type: Bug`, `Source: Diagnostic`, `Agent: Claude`
 - **If detected**: `Component: *`, `Complexity: *`, `Risk: *`, `Priority: *`
-After generating labels, continue to Step 6.
+### Step 6: Generate Issue Content
 ---
 ### Step 5.1: Generate Labels (User-Reported Mode Only)
 **Only execute this step if `REPORT_MODE` is "user-reported"**
 **1. Map problem type to labels:**
 | PROBLEM_TYPE | Labels |
 |--------------|--------|
 | Error message | `Type: Bug` |
 | Missing feature | `Type: Enhancement` |
 | Unexpected behavior | `Type: Bug` |
 | Documentation issue | `Type: Documentation` |
 | Other | `Type: Bug` (default) |
 **2. Map plugin to component:**
 | AFFECTED_PLUGIN | Component Label |
 |-----------------|-----------------|
 | projman | `Component: Commands` |
 | git-flow | `Component: Commands` |
 | pr-review | `Component: Commands` |
 | cmdb-assistant | `Component: API` |
 | doc-guardian | `Component: Commands` |
 | code-sentinel | `Component: Commands` |
 | Other | *(no component label)* |
 **3. Build final labels:**
 ```
 BASE_LABELS = ["Source: User-Reported", "Agent: Claude"]
 TYPE_LABEL = [mapped from PROBLEM_TYPE]
 COMPONENT_LABEL = [mapped from AFFECTED_PLUGIN, if any]
 FINAL_LABELS = BASE_LABELS + TYPE_LABEL + COMPONENT_LABEL
 ```
 After generating labels, continue to Step 6.1.
 ---
 ### Step 6: Generate Issue Content (Automated Mode Only)
 **Skip this step if `REPORT_MODE` is "user-reported"** → Go to Step 6.1
 Use this exact template:
@@ -401,86 +254,9 @@ Use this exact template:
 ---
-*Generated by /debug-report (automated) - Labels: Type: Bug, Source: Diagnostic, Agent: Claude*
+*Generated by /debug-report - Labels: Type: Bug, Source: Diagnostic, Agent: Claude*
 ```
 After generating content, continue to Step 7.
 ---
 ### Step 6.1: Generate Issue Content (User-Reported Mode Only)
 **Only execute this step if `REPORT_MODE` is "user-reported"**
 Use this template for user-reported issues:
 ```markdown
 ## User-Reported Issue
 **Reported**: [ISO timestamp]
 **Reporter**: Claude Code via /debug-report (user feedback)
 ## Context
 | Field | Value |
 |-------|-------|
 | Plugin | `[AFFECTED_PLUGIN]` |
 | Command/Tool | `[AFFECTED_COMMAND]` |
 | Repository | `[PROJECT_REPO]` |
 | Working Directory | `[WORKING_DIR]` |
 | Branch | `[CURRENT_BRANCH]` |
 ## Problem Description
 ### Goal
 [USER_GOAL]
 ### What Happened
 **Problem Type**: [PROBLEM_TYPE]
 [PROBLEM_DESCRIPTION]
 ### Expected Behavior
 [EXPECTED_BEHAVIOR]
 ## Workaround
 [WORKAROUND if provided, otherwise "None identified"]
 ## Investigation Hints
 Based on the affected plugin/command, relevant files to check:
 [Generate based on AFFECTED_PLUGIN:]
 **projman:**
 - `plugins/projman/commands/[AFFECTED_COMMAND].md`
 - `mcp-servers/gitea/mcp_server/tools/*.py`
 **git-flow:**
 - `plugins/git-flow/commands/[AFFECTED_COMMAND].md`
 **pr-review:**
 - `plugins/pr-review/commands/[AFFECTED_COMMAND].md`
 - `mcp-servers/gitea/mcp_server/tools/pull_requests.py`
 **cmdb-assistant:**
 - `plugins/cmdb-assistant/commands/[AFFECTED_COMMAND].md`
 - `mcp-servers/netbox/mcp_server/tools/*.py`
 - `mcp-servers/netbox/mcp_server/server.py` (tool schemas)
 **doc-guardian / code-sentinel:**
 - `plugins/[plugin]/commands/[AFFECTED_COMMAND].md`
 - `plugins/[plugin]/hooks/*.md`
 ---
 *Generated by /debug-report (user feedback) - Labels: [FINAL_LABELS]*
 ```
 After generating content, continue to Step 7.
 ---
 ### Step 7: Create Issue in Marketplace
 **IMPORTANT:** Always use curl to create issues in the marketplace repo. This avoids branch protection restrictions and MCP context issues that can block issue creation when working on protected branches.
@@ -498,57 +274,46 @@ fi
 **2. Fetch label IDs from marketplace repo:**
-Labels depend on `REPORT_MODE`:
+The diagnostic labels to apply are:
 **Automated mode:**
 - `Source/Diagnostic` (always)
 - `Type/Bug` (always)
 **User-reported mode:**
 - `Source/User-Reported` (always)
 - Type label from Step 5.1 (Bug, Enhancement, or Documentation)
 - Component label from Step 5.1 (if applicable)
 ```bash
-# Fetch all labels from marketplace repo
+# Fetch all labels and extract IDs for our target labels
 LABELS_JSON=$(curl -s "${GITEA_API_URL}/repos/${MARKETPLACE_REPO}/labels" \
  -H "Authorization: token ${GITEA_API_TOKEN}")
-# Extract label IDs based on FINAL_LABELS from Step 5 or 5.1
+# Extract label IDs (handles both org and repo labels)
-# Build LABEL_IDS array with IDs of labels that exist in the repo
+SOURCE_DIAG_ID=$(echo "$LABELS_JSON" | jq -r '.[] | select(.name == "Source/Diagnostic") | .id')
-# Example for automated mode:
+TYPE_BUG_ID=$(echo "$LABELS_JSON" | jq -r '.[] | select(.name == "Type/Bug") | .id')
 SOURCE_ID=$(echo "$LABELS_JSON" | jq -r '.[] | select(.name == "Source/Diagnostic") | .id')
 TYPE_ID=$(echo "$LABELS_JSON" | jq -r '.[] | select(.name == "Type/Bug") | .id')
-# Example for user-reported mode (adjust based on FINAL_LABELS):
+# Build label array (only include IDs that were found)
-# SOURCE_ID=$(echo "$LABELS_JSON" | jq -r '.[] | select(.name == "Source/User-Reported") | .id')
+LABEL_IDS="[]"
-# TYPE_ID=$(echo "$LABELS_JSON" | jq -r '.[] | select(.name == "[TYPE_LABEL]") | .id')
+if [[ -n "$SOURCE_DIAG_ID" && -n "$TYPE_BUG_ID" ]]; then
  LABEL_IDS="[$SOURCE_DIAG_ID, $TYPE_BUG_ID]"
 elif [[ -n "$SOURCE_DIAG_ID" ]]; then
  LABEL_IDS="[$SOURCE_DIAG_ID]"
 elif [[ -n "$TYPE_BUG_ID" ]]; then
  LABEL_IDS="[$TYPE_BUG_ID]"
 fi
 # Build label array from found IDs
 LABEL_IDS="[$(echo "$SOURCE_ID,$TYPE_ID" | sed 's/,,*/,/g; s/^,//; s/,$//')]"
 echo "Label IDs to apply: $LABEL_IDS"
 ```
 **3. Create issue with labels via curl:**
 **Title format depends on `REPORT_MODE`:**
 - Automated: `[Diagnostic] [summary of main failure]`
 - User-reported: `[AFFECTED_PLUGIN] [brief summary of PROBLEM_DESCRIPTION]`
 ```bash
 # Create temp files with restrictive permissions
 DIAG_TITLE=$(mktemp -t diag-title.XXXXXX)
 DIAG_BODY=$(mktemp -t diag-body.XXXXXX)
 DIAG_PAYLOAD=$(mktemp -t diag-payload.XXXXXX)
-# Save title (format depends on REPORT_MODE)
+# Save title
-# Automated: "[Diagnostic] [summary of main failure]"
+echo "[Diagnostic] [summary of main failure]" > "$DIAG_TITLE"
 # User-reported: "[AFFECTED_PLUGIN] [brief summary]"
 echo "[Title based on REPORT_MODE]" > "$DIAG_TITLE"
-# Save body (paste Step 6 or 6.1 content) - heredoc delimiter prevents shell expansion
+# Save body (paste Step 6 content) - heredoc delimiter prevents shell expansion
 cat > "$DIAG_BODY" << 'DIAGNOSTIC_EOF'
-[Paste the full issue content from Step 6 or 6.1 here]
+[Paste the full issue content from Step 6 here]
 DIAGNOSTIC_EOF
 # Build JSON payload with labels using jq
@@ -595,9 +360,8 @@ To create the issue manually:
 ### Step 8: Report to User
-Display summary based on `REPORT_MODE`:
+Display summary:
 **Automated Mode:**
 ```
 Debug Report Complete
 =====================
@@ -619,38 +383,18 @@ Next Steps:
  3. Select issue #[N] to investigate
 ```
 **User-Reported Mode:**
 ```
 Issue Report Complete
 =====================
 Plugin: [AFFECTED_PLUGIN]
 Command: [AFFECTED_COMMAND]
 Problem: [PROBLEM_TYPE]
 Issue Created: [issue URL]
 Your feedback has been captured. The development team will
 investigate and may follow up with questions.
 Next Steps:
  1. Switch to marketplace repo: cd [marketplace path]
  2. Run: /debug-review
  3. Select issue #[N] to investigate
 ```
 ## DO NOT
 - **DO NOT** attempt to fix anything - only report
- **DO NOT** create issues if all automated tests pass (unless in user-reported mode)
+- **DO NOT** create issues if all tests pass (just report success)
- **DO NOT** skip any diagnostic test in automated mode
+- **DO NOT** skip any diagnostic test
 - **DO NOT** call MCP tools without the `repo` parameter
- **DO NOT** skip user questions in user-reported mode - gather complete feedback
+- **DO NOT** ask user questions during execution - run autonomously
 - **DO NOT** use MCP tools to create issues in the marketplace - always use curl (avoids branch restrictions)
-## If All Tests Pass (Automated Mode Only)
+## If All Tests Pass
-If all 5 tests pass in automated mode, report success without creating an issue:
+If all 5 tests pass, report success without creating an issue:
 ```
 Debug Report Complete
@@ -663,8 +407,8 @@ Failed: 0
 All diagnostics passed. No issues to report.
-If you're experiencing a specific problem, run /debug-report again
+If you're experiencing a specific problem, please describe it
-and select "Report an issue I experienced" to describe it.
+and I can create a manual bug report.
 ```
 ## Troubleshooting
--- a/scripts/verify-hooks.sh
+++ b/scripts/verify-hooks.sh
@@ -15,11 +15,11 @@ for f in $(find ~/.claude -name "hooks.json" 2>/dev/null); do
    fi
 done
-# Note about cache (informational only - do NOT clear mid-session)
+# Check cache specifically
 if [ -d ~/.claude/plugins/cache/leo-claude-mktplace ]; then
-    echo "ℹ️  Cache exists: ~/.claude/plugins/cache/leo-claude-mktplace"
+    echo "❌ CACHE EXISTS: ~/.claude/plugins/cache/leo-claude-mktplace"
-    echo "   (This is normal - do NOT clear mid-session or MCP tools will break)"
+    echo "   Run: rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/"
-    echo "   To apply plugin changes: restart Claude Code session"
+    FAILED=1
 fi
 # Verify installed hooks are command type