.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Project management plugins with Gitea and NetBox integrations",
-    "version": "3.1.0"
+    "version": "3.2.0"
   },
   "plugins": [
     {

CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to the Leo Claude Marketplace will be documented in this fil
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [Unreleased]
+
+*Changes staged for the next release*
+
+---
+
+## [3.2.0] - 2026-01-24
+
+### Added
+- **git-flow:** `/commit` now detects protected branches before committing
+  - Warns when on protected branch (main, master, development, staging, production)
+  - Offers to create feature branch automatically instead of committing directly
+  - Configurable via `GIT_PROTECTED_BRANCHES` environment variable
+- **netbox:** Platform and primary_ip parameters added to device update tools
+- **claude-config-maintainer:** Auto-enforce mandatory behavior rules via SessionStart hook
+- **scripts:** `release.sh` - Versioning workflow script for consistent releases
+- **scripts:** `verify-hooks.sh` - Verify all hooks are command type
+
+### Changed
+- **doc-guardian:** Hook switched from `prompt` type to `command` type
+  - Prompt hooks unreliable - Claude ignores explicit instructions
+  - New `notify.sh` bash script guarantees exact output behavior
+  - Only notifies for config file changes (commands/, agents/, skills/, hooks/)
+  - Silent exit for all other files - no blocking possible
+- **All hooks:** Converted to command type with stricter plugin prefix enforcement
+  - All hooks now mandate `[plugin-name]` prefix with "NO EXCEPTIONS" rule
+  - Simplified output formats with word limits
+  - Consistent structure across projman, pr-review, code-sentinel, doc-guardian
+- **CLAUDE.md:** Replaced destructive "ALWAYS CLEAR CACHE" rule with "VERIFY AND RESTART"
+  - Cache clearing mid-session breaks MCP tools
+  - Added guidance for proper plugin development workflow
+
+### Fixed
+- **cmdb-assistant:** Complete MCP tool schemas for update operations (#138)
+- **netbox:** Shorten tool names to meet 64-char API limit (#134)
+- **cmdb-assistant:** Correct NetBox API URL format in setup wizard (#132)
+- **gitea/projman:** Type safety for `create_label_smart`, curl-based debug-report (#124)
+- **netbox:** Add diagnostic logging for JSON parse errors (#121)
+- **labels:** Add duplicate check before creating labels (#116)
+- **hooks:** Convert ALL hooks to command type with proper prefixes (#114)
+- Protected branch workflow: Claude no longer commits directly to protected branches (fixes #109)
+- doc-guardian hook no longer blocks workflow (fixes #110)
+
+---
+
 ## [3.1.1] - 2026-01-22
 
 ### Added

CLAUDE.md

@@ -31,11 +31,16 @@ 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 - ALWAYS CLEAR CACHE
-```bash
-rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/
-./scripts/verify-hooks.sh
-```
+### 5. AFTER PLUGIN UPDATES - VERIFY AND RESTART
+
+**⚠️ DO NOT clear cache mid-session** - this breaks MCP tools that are already loaded.
+
+1. Run `./scripts/verify-hooks.sh` to check hook types
+2. If changes affect MCP servers or hooks, inform the user:
+   > "Plugin changes require a session restart to take effect. Please restart Claude Code."
+3. Cache clearing is ONLY safe **before** starting a new session (not during)
+
+See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing.
 
 **FAILURE TO FOLLOW THESE RULES = WASTED USER TIME = UNACCEPTABLE**
 
@@ -125,7 +130,9 @@ 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
@@ -172,12 +179,12 @@ leo-claude-mktplace/
 
 | Category | Tools |
 |----------|-------|
-| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment` |
-| Labels | `get_labels`, `suggest_labels`, `create_label` |
-| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone` |
-| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `get_execution_order` |
-| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `create_lesson`, `search_lessons` |
-| **Pull Requests** | `list_pull_requests`, `get_pull_request`, `get_pr_diff`, `get_pr_comments`, `create_pr_review`, `add_pr_comment` *(NEW v3.0.0)* |
+| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment`, `aggregate_issues` |
+| Labels | `get_labels`, `suggest_labels`, `create_label`, `create_label_smart` |
+| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone`, `delete_milestone` |
+| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `remove_issue_dependency`, `get_execution_order` |
+| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `update_wiki_page`, `create_lesson`, `search_lessons` |
+| **Pull Requests** | `list_pull_requests`, `get_pull_request`, `get_pr_diff`, `get_pr_comments`, `create_pr_review`, `add_pr_comment` |
 | Validation | `validate_repo_org`, `get_branch_protection` |
 
 ### Hybrid Configuration
@@ -286,13 +293,56 @@ See `docs/DEBUGGING-CHECKLIST.md` for systematic troubleshooting.
 - `/debug-report` - Run full diagnostics, create issue if needed
 - `/debug-review` - Investigate and propose fixes
 
-## Versioning Rules
+## Versioning Workflow
 
-- Version displayed ONLY in main `README.md` title: `# Leo Claude Marketplace - vX.Y.Z`
-- `CHANGELOG.md` is authoritative for version history
-- Follow [SemVer](https://semver.org/): MAJOR.MINOR.PATCH
-- On release: Update README title → CHANGELOG → marketplace.json → plugin.json files
+This project follows [SemVer](https://semver.org/) and [Keep a Changelog](https://keepachangelog.com).
+
+### Version Locations (must stay in sync)
+
+| Location | Format | Example |
+|----------|--------|---------|
+| Git tags | `vX.Y.Z` | `v3.2.0` |
+| README.md title | `# Leo Claude Marketplace - vX.Y.Z` | `v3.2.0` |
+| marketplace.json | `"version": "X.Y.Z"` | `3.2.0` |
+| CHANGELOG.md | `## [X.Y.Z] - YYYY-MM-DD` | `[3.2.0] - 2026-01-24` |
+
+### During Development
+
+**All changes go under `[Unreleased]` in CHANGELOG.md.** Never create a versioned section until release time.
+
+```markdown
+## [Unreleased]
+
+### Added
+- New feature description
+
+### Fixed
+- Bug fix description
+```
+
+### Creating a Release
+
+Use the release script to ensure consistency:
+
+```bash
+./scripts/release.sh 3.2.0
+```
+
+The script will:
+1. Validate `[Unreleased]` section has content
+2. Replace `[Unreleased]` with `[3.2.0] - YYYY-MM-DD`
+3. Update README.md title
+4. Update marketplace.json version
+5. Commit and create git tag
+
+### SemVer Guidelines
+
+| Change Type | Version Bump | Example |
+|-------------|--------------|---------|
+| Bug fixes only | PATCH (x.y.**Z**) | 3.1.1 → 3.1.2 |
+| New features (backwards compatible) | MINOR (x.**Y**.0) | 3.1.2 → 3.2.0 |
+| Breaking changes | MAJOR (**X**.0.0) | 3.2.0 → 4.0.0 |
 
 ---
 
-**Last Updated:** 2026-01-23
+**Last Updated:** 2026-01-24

README.md

@@ -1,4 +1,4 @@
-# Leo Claude Marketplace - v3.1.1
+# Leo Claude Marketplace - v3.2.0
 
 A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
 
@@ -106,11 +106,11 @@ Full Gitea API integration for project management.
 
 | Category | Tools |
 |----------|-------|
-| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment` |
-| Labels | `get_labels`, `suggest_labels`, `create_label` |
-| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `create_lesson`, `search_lessons` |
-| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone` |
-| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `get_execution_order` |
+| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment`, `aggregate_issues` |
+| Labels | `get_labels`, `suggest_labels`, `create_label`, `create_label_smart` |
+| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `update_wiki_page`, `create_lesson`, `search_lessons` |
+| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone`, `delete_milestone` |
+| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `remove_issue_dependency`, `get_execution_order` |
 | **Pull Requests** | `list_pull_requests`, `get_pull_request`, `get_pr_diff`, `get_pr_comments`, `create_pr_review`, `add_pr_comment` *(NEW in v3.0.0)* |
 | Validation | `validate_repo_org`, `get_branch_protection` |
 
@@ -245,7 +245,8 @@ leo-claude-mktplace/
 ├── docs/                          # Documentation
 │   ├── CANONICAL-PATHS.md         # Path reference
 │   └── CONFIGURATION.md           # Setup guide
-└── scripts/                       # Setup scripts
+├── scripts/                       # Setup scripts
+└── CHANGELOG.md                   # Version history
 ```
 
 ## Documentation

docs/DEBUGGING-CHECKLIST.md

@@ -197,6 +197,51 @@ 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:

scripts/release.sh

@@ -0,0 +1,172 @@
+#!/bin/bash
+# release.sh - Create a new release with version consistency
+#
+# Usage: ./scripts/release.sh X.Y.Z
+#
+# This script ensures all version references are updated consistently:
+# 1. CHANGELOG.md - [Unreleased] becomes [X.Y.Z] - YYYY-MM-DD
+# 2. README.md - Title updated to vX.Y.Z
+# 3. marketplace.json - version field updated
+# 4. Git commit and tag created
+#
+# Prerequisites:
+# - Clean working directory (no uncommitted changes)
+# - [Unreleased] section in CHANGELOG.md with content
+# - On development branch
+
+set -e
+
+VERSION=$1
+DATE=$(date +%Y-%m-%d)
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+error() { echo -e "${RED}ERROR: $1${NC}" >&2; exit 1; }
+warn() { echo -e "${YELLOW}WARNING: $1${NC}"; }
+success() { echo -e "${GREEN}$1${NC}"; }
+info() { echo -e "$1"; }
+
+# Validate arguments
+if [ -z "$VERSION" ]; then
+    echo "Usage: ./scripts/release.sh X.Y.Z"
+    echo ""
+    echo "Example: ./scripts/release.sh 3.2.0"
+    echo ""
+    echo "This will:"
+    echo "  1. Update CHANGELOG.md [Unreleased] -> [X.Y.Z] - $(date +%Y-%m-%d)"
+    echo "  2. Update README.md title to vX.Y.Z"
+    echo "  3. Update marketplace.json version to X.Y.Z"
+    echo "  4. Commit with message 'chore: release vX.Y.Z'"
+    echo "  5. Create git tag vX.Y.Z"
+    exit 1
+fi
+
+# Validate version format
+if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    error "Invalid version format. Use X.Y.Z (e.g., 3.2.0)"
+fi
+
+# Check we're in the right directory
+if [ ! -f "CHANGELOG.md" ] || [ ! -f "README.md" ] || [ ! -f ".claude-plugin/marketplace.json" ]; then
+    error "Must run from repository root (CHANGELOG.md, README.md, .claude-plugin/marketplace.json must exist)"
+fi
+
+# Check for clean working directory
+if [ -n "$(git status --porcelain)" ]; then
+    warn "Working directory has uncommitted changes"
+    echo ""
+    git status --short
+    echo ""
+    read -p "Continue anyway? [y/N] " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        exit 1
+    fi
+fi
+
+# Check current branch
+BRANCH=$(git branch --show-current)
+if [ "$BRANCH" != "development" ] && [ "$BRANCH" != "main" ]; then
+    warn "Not on development or main branch (current: $BRANCH)"
+    read -p "Continue anyway? [y/N] " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        exit 1
+    fi
+fi
+
+# Check [Unreleased] section has content
+if ! grep -q "## \[Unreleased\]" CHANGELOG.md; then
+    error "CHANGELOG.md missing [Unreleased] section"
+fi
+
+# Check if tag already exists
+if git tag -l | grep -q "^v$VERSION$"; then
+    error "Tag v$VERSION already exists"
+fi
+
+info ""
+info "=== Release v$VERSION ==="
+info ""
+
+# Show what will change
+info "Changes to be made:"
+info "  CHANGELOG.md: [Unreleased] -> [$VERSION] - $DATE"
+info "  README.md: title -> v$VERSION"
+info "  marketplace.json: version -> $VERSION"
+info "  Git: commit + tag v$VERSION"
+info ""
+
+# Preview CHANGELOG [Unreleased] content
+info "Current [Unreleased] content:"
+info "---"
+sed -n '/^## \[Unreleased\]/,/^## \[/p' CHANGELOG.md | head -30
+info "---"
+info ""
+
+read -p "Proceed with release? [y/N] " -n 1 -r
+echo
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    info "Aborted"
+    exit 0
+fi
+
+info ""
+info "Updating files..."
+
+# 1. Update CHANGELOG.md
+# Replace [Unreleased] with [X.Y.Z] - DATE and add new [Unreleased] section
+sed -i "s/^## \[Unreleased\]$/## [Unreleased]\n\n*Changes staged for the next release*\n\n---\n\n## [$VERSION] - $DATE/" CHANGELOG.md
+
+# Remove the placeholder text if it exists after the new [Unreleased]
+sed -i '/^\*Changes staged for the next release\*$/d' CHANGELOG.md
+
+# Clean up any double blank lines
+sed -i '/^$/N;/^\n$/d' CHANGELOG.md
+
+success "  CHANGELOG.md updated"
+
+# 2. Update README.md title
+sed -i "s/^# Leo Claude Marketplace - v[0-9]\+\.[0-9]\+\.[0-9]\+$/# Leo Claude Marketplace - v$VERSION/" README.md
+success "  README.md updated"
+
+# 3. Update marketplace.json version
+sed -i "s/\"version\": \"[0-9]\+\.[0-9]\+\.[0-9]\+\"/\"version\": \"$VERSION\"/" .claude-plugin/marketplace.json
+success "  marketplace.json updated"
+
+info ""
+info "Files updated. Review changes:"
+info ""
+git diff --stat
+info ""
+git diff CHANGELOG.md | head -40
+info ""
+
+read -p "Commit and tag? [y/N] " -n 1 -r
+echo
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    warn "Changes made but not committed. Run 'git checkout -- .' to revert."
+    exit 0
+fi
+
+# Commit
+git add CHANGELOG.md README.md .claude-plugin/marketplace.json
+git commit -m "chore: release v$VERSION"
+success "  Committed"
+
+# Tag
+git tag "v$VERSION"
+success "  Tagged v$VERSION"
+
+info ""
+success "=== Release v$VERSION created ==="
+info ""
+info "Next steps:"
+info "  1. Review the commit: git show HEAD"
+info "  2. Push to remote: git push && git push --tags"
+info "  3. Merge to main if on development branch"
+info ""

scripts/verify-hooks.sh

@@ -15,11 +15,11 @@ for f in $(find ~/.claude -name "hooks.json" 2>/dev/null); do
     fi
 done
 
-# Check cache specifically
+# Note about cache (informational only - do NOT clear mid-session)
 if [ -d ~/.claude/plugins/cache/leo-claude-mktplace ]; then
-    echo "❌ CACHE EXISTS: ~/.claude/plugins/cache/leo-claude-mktplace"
-    echo "   Run: rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/"
-    FAILED=1
+    echo "ℹ️  Cache exists: ~/.claude/plugins/cache/leo-claude-mktplace"
+    echo "   (This is normal - do NOT clear mid-session or MCP tools will break)"
+    echo "   To apply plugin changes: restart Claude Code session"
 fi
 
 # Verify installed hooks are command type