diff --git a/CLAUDE.md b/CLAUDE.md index 6b68c0e..82cdbfa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -40,8 +40,76 @@ Run `./scripts/verify-hooks.sh`. If changes affect MCP servers or hooks, inform **Valid hook events:** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact` +### ⛔ MANDATORY: Before Any Code Change + +**Claude MUST show this checklist BEFORE editing any file:** + +#### 1. Impact Search Results +Run and show output of: +```bash +grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git" +``` + +#### 2. Files That Will Be Affected +Numbered list of every file to be modified, with the specific change for each. + +#### 3. Files Searched But Not Changed (and why) +Proof that related files were checked and determined unchanged. + +#### 4. Documentation That References This +List of docs that mention this feature/script/function. + +**User verifies this list before Claude proceeds. If Claude skips this, STOP IMMEDIATELY.** + +#### After Changes +Run the same grep and show results proving no references remain unaddressed. + --- +## ⚠️ Development Context: We Build AND Use These Plugins + +**This is a self-referential project.** We are: +1. **BUILDING** a plugin marketplace (source code in `plugins/`) +2. **USING** the installed marketplace to build it (dogfooding) + +### Plugins ACTIVELY USED in This Project + +These plugins are installed and should be used during development: + +| Plugin | Used For | +|--------|----------| +| **projman** | Sprint planning, issue management, lessons learned | +| **git-flow** | Commits, branch management | +| **pr-review** | Pull request reviews | +| **doc-guardian** | Documentation drift detection | +| **code-sentinel** | Security scanning, refactoring | +| **clarity-assist** | Prompt clarification | +| **claude-config-maintainer** | CLAUDE.md optimization | +| **contract-validator** | Cross-plugin compatibility | + +### Plugins NOT Used Here (Development Only) + +These plugins exist in source but are **NOT relevant** to this project's workflow: + +| Plugin | Why Not Used | +|--------|--------------| +| **data-platform** | For data engineering projects (pandas, PostgreSQL, dbt) | +| **viz-platform** | For dashboard projects (Dash, Plotly) | +| **cmdb-assistant** | For infrastructure projects (NetBox) | + +**Do NOT suggest** `/ingest`, `/profile`, `/chart`, `/cmdb-*` commands - they don't apply here. + +### Key Distinction + +| Context | Path | What To Do | +|---------|------|------------| +| **Editing plugin source** | `~/claude-plugins-work/plugins/` | Modify code, add features | +| **Using installed plugins** | `~/.claude/plugins/marketplaces/` | Run commands like `/sprint-plan` | + +When user says "run /sprint-plan", use the INSTALLED plugin. +When user says "fix the sprint-plan command", edit the SOURCE code. + +--- ## Project Overview @@ -76,7 +144,7 @@ A plugin marketplace for Claude Code containing: ./scripts/post-update.sh # Rebuild venvs, verify symlinks ``` -### Plugin Commands by Category +### Plugin Commands - USE THESE in This Project | Category | Commands | |----------|----------| @@ -88,12 +156,19 @@ A plugin marketplace for Claude Code containing: | **Docs** | `/doc-audit`, `/doc-sync`, `/changelog-gen`, `/doc-coverage`, `/stale-docs` | | **Security** | `/security-scan`, `/refactor`, `/refactor-dry` | | **Config** | `/config-analyze`, `/config-optimize`, `/config-diff`, `/config-lint` | -| **Data** | `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/lineage-viz`, `/run`, `/dbt-test`, `/data-quality` | -| **Visualization** | `/component`, `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/accessibility-check`, `/breakpoints` | | **Validation** | `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/dependency-graph` | -| **CMDB** | `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`, `/cmdb-audit`, `/cmdb-register`, `/cmdb-sync`, `/cmdb-topology`, `/change-audit`, `/ip-conflicts` | | **Debug** | `/debug-report`, `/debug-review` | +### Plugin Commands - NOT RELEVANT to This Project + +These commands are being developed but don't apply to this project's workflow: + +| Category | Commands | For Projects Using | +|----------|----------|-------------------| +| **Data** | `/ingest`, `/profile`, `/schema`, `/lineage`, `/dbt-test` | pandas, PostgreSQL, dbt | +| **Visualization** | `/component`, `/chart`, `/dashboard`, `/theme` | Dash, Plotly dashboards | +| **CMDB** | `/cmdb-search`, `/cmdb-device`, `/cmdb-sync` | NetBox infrastructure | + ## Repository Structure ``` @@ -354,4 +429,4 @@ The script will: --- -**Last Updated:** 2026-01-28 +**Last Updated:** 2026-01-30 diff --git a/docs/CANONICAL-PATHS.md b/docs/CANONICAL-PATHS.md index 97bfb2c..3fd6c3a 100644 --- a/docs/CANONICAL-PATHS.md +++ b/docs/CANONICAL-PATHS.md @@ -163,12 +163,11 @@ leo-claude-mktplace/ │ └── claude-md-integration.md ├── scripts/ # Setup and maintenance scripts │ ├── setup.sh # Initial setup (create venvs, config templates) -│ ├── post-update.sh # Post-update (rebuild venvs, verify symlinks) -│ ├── check-venv.sh # Check if venvs exist (for hooks) +│ ├── post-update.sh # Post-update (clear cache, show changelog) +│ ├── check-venv.sh # Check if venvs exist (read-only) │ ├── validate-marketplace.sh # Marketplace compliance validation │ ├── verify-hooks.sh # Verify all hooks use correct event types -│ ├── setup-venvs.sh # Setup/repair MCP server venvs -│ ├── venv-repair.sh # Repair broken venv symlinks +│ ├── setup-venvs.sh # Setup MCP server venvs (create only, never delete) │ └── release.sh # Release automation with version bumping ├── CLAUDE.md ├── README.md diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index c278838..dfd064f 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -501,9 +501,8 @@ If you get 401, regenerate your token in Gitea. # Check venv exists ls /path/to/mcp-servers/gitea/.venv -# Reinstall if missing +# If missing, create venv (do NOT delete existing venvs) cd /path/to/mcp-servers/gitea -rm -rf .venv python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt diff --git a/docs/UPDATING.md b/docs/UPDATING.md index 17760d2..d10b271 100644 --- a/docs/UPDATING.md +++ b/docs/UPDATING.md @@ -132,10 +132,8 @@ When updating, review if changes affect the setup workflow: ### Dependencies fail to install ```bash -# Rebuild virtual environment +# Install missing dependencies (do NOT delete .venv) cd mcp-servers/gitea -rm -rf .venv -python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt deactivate diff --git a/plugins/claude-config-maintainer/agents/maintainer.md b/plugins/claude-config-maintainer/agents/maintainer.md index 513665c..71ddfa9 100644 --- a/plugins/claude-config-maintainer/agents/maintainer.md +++ b/plugins/claude-config-maintainer/agents/maintainer.md @@ -277,6 +277,39 @@ Every CLAUDE.md should have: 1. **Project Overview** - What is this? 2. **Quick Start** - How do I build/test/run? 3. **Important Rules** - What must I NOT do? +4. **Pre-Change Protocol** - Mandatory dependency check before code changes + +### Pre-Change Protocol Section (MANDATORY) + +**This section is REQUIRED in every CLAUDE.md.** It ensures Claude performs comprehensive dependency analysis before making any code changes. + +```markdown +## ⛔ MANDATORY: Before Any Code Change + +**Claude MUST show this checklist BEFORE editing any file:** + +### 1. Impact Search Results +Run and show output of: +```bash +grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git" +``` + +### 2. Files That Will Be Affected +Numbered list of every file to be modified, with the specific change for each. + +### 3. Files Searched But Not Changed (and why) +Proof that related files were checked and determined unchanged. + +### 4. Documentation That References This +List of docs that mention this feature/script/function. + +**User verifies this list before Claude proceeds. If Claude skips this, stop immediately.** + +### After Changes +Run the same grep and show results proving no references remain unaddressed. +``` + +**When analyzing a CLAUDE.md, flag as HIGH priority issue if this section is missing.** ### Optional Sections (as needed) diff --git a/plugins/claude-config-maintainer/commands/analyze.md b/plugins/claude-config-maintainer/commands/analyze.md index df914a9..3df813b 100644 --- a/plugins/claude-config-maintainer/commands/analyze.md +++ b/plugins/claude-config-maintainer/commands/analyze.md @@ -59,6 +59,7 @@ Analyze the CLAUDE.md file in this project - Quick start commands documented - Critical rules highlighted - Key workflows covered +- **Pre-Change Protocol section present** (MANDATORY - see below) ### Conciseness (25 points) - No unnecessary repetition @@ -66,6 +67,42 @@ Analyze the CLAUDE.md file in this project - Appropriate length for project size - No generic filler content +## Pre-Change Protocol Check (MANDATORY) + +**This check is CRITICAL.** The Pre-Change Protocol section ensures Claude performs comprehensive dependency analysis before making any code changes, preventing missed references and incomplete updates. + +### What to Check + +Search CLAUDE.md for: +- Section header containing "Pre-Change" or "Before Any Code Change" +- References to `grep -rn` or impact search +- Checklist with "Files That Will Be Affected" +- Requirement for user verification before proceeding + +### If Missing + +**Flag as HIGH PRIORITY issue:** + +``` +1. [HIGH] Missing Pre-Change Protocol section + CLAUDE.md lacks mandatory dependency-check protocol. + Impact: Claude may miss file references when making changes, + leading to broken dependencies and incomplete updates. + + Recommendation: Add Pre-Change Protocol section immediately. + This is the #1 cause of cascading bugs from incomplete changes. +``` + +### Required Section Content + +The Pre-Change Protocol section must include: +1. Requirement to run grep search and show results +2. List of files that will be affected +3. List of files searched but not changed (with reasoning) +4. Documentation that references the change target +5. User verification checkpoint before proceeding +6. Post-change verification step + ## Plugin Integration Analysis After the content analysis, the command detects and analyzes marketplace plugin integration: diff --git a/plugins/claude-config-maintainer/commands/init.md b/plugins/claude-config-maintainer/commands/init.md index 1f88107..43c2eb1 100644 --- a/plugins/claude-config-maintainer/commands/init.md +++ b/plugins/claude-config-maintainer/commands/init.md @@ -139,6 +139,7 @@ For small projects or when starting fresh: - Project Overview (required) - Quick Start (required) - Critical Rules (required) +- **Pre-Change Protocol (required)** ### Standard Template (default) For typical projects: @@ -146,6 +147,7 @@ For typical projects: - Quick Start - Architecture - Critical Rules +- **Pre-Change Protocol** - Common Operations - File Structure @@ -153,11 +155,44 @@ For typical projects: For large or complex projects: - All standard sections plus: - Detailed Architecture +- **Pre-Change Protocol** - Troubleshooting - Integration Points - Development Workflow - Deployment Notes +### Pre-Change Protocol Section (MANDATORY in ALL templates) + +**This section MUST be included in every generated CLAUDE.md:** + +```markdown +## ⛔ MANDATORY: Before Any Code Change + +**Claude MUST show this checklist BEFORE editing any file:** + +### 1. Impact Search Results +Run and show output of: +\`\`\`bash +grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git" +\`\`\` + +### 2. Files That Will Be Affected +Numbered list of every file to be modified, with the specific change for each. + +### 3. Files Searched But Not Changed (and why) +Proof that related files were checked and determined unchanged. + +### 4. Documentation That References This +List of docs that mention this feature/script/function. + +**User verifies this list before Claude proceeds. If Claude skips this, stop immediately.** + +### After Changes +Run the same grep and show results proving no references remain unaddressed. +``` + +**Rationale:** This protocol prevents incomplete changes where Claude modifies some files but misses others that reference the same code, causing cascading bugs. + ## Auto-Detection The command automatically detects: diff --git a/plugins/claude-config-maintainer/commands/optimize.md b/plugins/claude-config-maintainer/commands/optimize.md index 1f13c4f..e02f541 100644 --- a/plugins/claude-config-maintainer/commands/optimize.md +++ b/plugins/claude-config-maintainer/commands/optimize.md @@ -56,6 +56,7 @@ Or specify specific optimizations: ### Enhance - Add missing essential sections +- **Add Pre-Change Protocol if missing (HIGH PRIORITY)** - Improve unclear instructions - Add helpful examples - Highlight critical rules @@ -158,6 +159,49 @@ Backup saved to: .claude/backups/CLAUDE.md.2025-01-18 | `--preserve-comments` | Keep all existing comments | | `--section=NAME` | Optimize specific section only | +## Pre-Change Protocol (Mandatory Addition) + +**If CLAUDE.md is missing the Pre-Change Protocol section, optimization MUST add it.** + +This is the highest priority enhancement because it prevents cascading bugs from incomplete code changes. + +### Detection + +Search CLAUDE.md for: +- "Pre-Change" or "Before Any Code Change" in headers +- References to impact search or grep verification +- User verification checkpoint + +### If Missing + +Add this section (position: after Critical Rules, before Common Operations): + +```markdown +## ⛔ MANDATORY: Before Any Code Change + +**Claude MUST show this checklist BEFORE editing any file:** + +### 1. Impact Search Results +Run and show output of: +\`\`\`bash +grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git" +\`\`\` + +### 2. Files That Will Be Affected +Numbered list of every file to be modified, with the specific change for each. + +### 3. Files Searched But Not Changed (and why) +Proof that related files were checked and determined unchanged. + +### 4. Documentation That References This +List of docs that mention this feature/script/function. + +**User verifies this list before Claude proceeds. If Claude skips this, stop immediately.** + +### After Changes +Run the same grep and show results proving no references remain unaddressed. +``` + ## When to Use Run `/config-optimize` when: diff --git a/plugins/projman/hooks/startup-check.sh b/plugins/projman/hooks/startup-check.sh index 0491070..8491ce1 100755 --- a/plugins/projman/hooks/startup-check.sh +++ b/plugins/projman/hooks/startup-check.sh @@ -7,29 +7,6 @@ PREFIX="[projman]" # Calculate paths PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "$(realpath "$0")")")}" -# Marketplace root is 2 levels up from plugin root (plugins/projman -> .) -MARKETPLACE_ROOT="$(dirname "$(dirname "$PLUGIN_ROOT")")" -VENV_REPAIR_SCRIPT="$MARKETPLACE_ROOT/scripts/venv-repair.sh" - -# ============================================================================ -# Auto-repair MCP venvs (runs before other checks) -# ============================================================================ - -if [[ -x "$VENV_REPAIR_SCRIPT" ]]; then - # Run venv repair - this creates symlinks to cached venvs - # Only outputs messages if something needed fixing - "$VENV_REPAIR_SCRIPT" 2>/dev/null || { - echo "$PREFIX MCP venv setup failed - run: cd $MARKETPLACE_ROOT && ./scripts/setup-venvs.sh" - exit 0 - } -else - # Fallback: just check if venv exists - VENV_PATH="$PLUGIN_ROOT/mcp-servers/gitea/.venv/bin/python" - if [[ ! -f "$VENV_PATH" ]]; then - echo "$PREFIX MCP venvs missing - run setup.sh from installed marketplace" - exit 0 - fi -fi # Check git remote vs .env config (only if .env exists) if [[ -f ".env" ]]; then diff --git a/scripts/post-update.sh b/scripts/post-update.sh index bfb4987..b3868d8 100755 --- a/scripts/post-update.sh +++ b/scripts/post-update.sh @@ -6,9 +6,10 @@ # # This script: # 1. Clears Claude plugin cache (forces fresh .mcp.json reads) -# 2. Restores MCP venv symlinks (instant if cache exists) -# 3. Creates venvs in external cache if missing (first run only) -# 4. Shows recent changelog updates +# 2. Shows recent changelog updates +# +# NOTE: This script does NOT touch .venv directories. +# If venvs are missing, run ./scripts/setup.sh manually. # set -euo pipefail @@ -22,13 +23,11 @@ REPO_ROOT="$(dirname "$SCRIPT_DIR")" GREEN='\033[0;32m' YELLOW='\033[1;33m' BLUE='\033[0;34m' -RED='\033[0;31m' NC='\033[0m' log_info() { echo -e "${BLUE}[INFO]${NC} $1"; } log_success() { echo -e "${GREEN}[OK]${NC} $1"; } log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; } -log_error() { echo -e "${RED}[ERROR]${NC} $1"; } check_changelog() { if [[ -f "$REPO_ROOT/CHANGELOG.md" ]]; then @@ -52,35 +51,21 @@ main() { # Clear Claude plugin cache to force fresh .mcp.json reads # This cache holds versioned copies that become stale after updates + # NOTE: This does NOT touch .venv directories if [[ -d "$CLAUDE_PLUGIN_CACHE" ]]; then log_info "Clearing Claude plugin cache..." rm -rf "$CLAUDE_PLUGIN_CACHE" log_success "Plugin cache cleared" fi - # Run venv-repair.sh to restore symlinks to external cache - # This is instant if cache exists, or does full setup on first run - if [[ -x "$SCRIPT_DIR/venv-repair.sh" ]]; then - log_info "Restoring MCP venv symlinks..." - if "$SCRIPT_DIR/venv-repair.sh"; then - log_success "MCP venvs ready" - else - log_error "MCP venv setup failed" - log_warn "Run: $SCRIPT_DIR/setup-venvs.sh for full setup" - exit 1 - fi - else - log_error "venv-repair.sh not found at $SCRIPT_DIR" - exit 1 - fi - check_changelog echo "" log_success "Post-update complete!" echo "" echo "IMPORTANT: Restart Claude Code for changes to take effect." - echo "MCP servers will work immediately on next session start." + echo "" + echo "If MCP servers are not working, run: ./scripts/setup.sh" } main "$@" diff --git a/scripts/venv-repair.sh b/scripts/venv-repair.sh deleted file mode 100755 index 32703d7..0000000 --- a/scripts/venv-repair.sh +++ /dev/null @@ -1,169 +0,0 @@ -#!/usr/bin/env bash -# -# venv-repair.sh - Fast MCP venv auto-repair for SessionStart hooks -# -# This script is designed to run at session start. It: -# 1. Checks if venvs exist in external cache (~/.cache/claude-mcp-venvs/) -# 2. Creates symlinks from marketplace to cache (instant operation) -# 3. Only runs pip install if cache is missing (first install) -# -# Output format: All messages prefixed with [mcp-venv] for hook display -# -# Usage: -# ./scripts/venv-repair.sh # Auto-repair (default) -# ./scripts/venv-repair.sh --silent # Silent mode (no output unless error) -# - -set -euo pipefail - -# ============================================================================ -# Configuration -# ============================================================================ - -PREFIX="[mcp-venv]" -VENV_CACHE_DIR="${HOME}/.cache/claude-mcp-venvs/leo-claude-mktplace" -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -REPO_ROOT="$(dirname "$SCRIPT_DIR")" - -# MCP servers -MCP_SERVERS=(gitea netbox data-platform viz-platform contract-validator) - -# Parse args -SILENT=false -[[ "${1:-}" == "--silent" ]] && SILENT=true - -log() { - [[ "$SILENT" == true ]] && return - echo "$PREFIX $1" -} - -log_error() { - echo "$PREFIX ERROR: $1" >&2 -} - -# ============================================================================ -# Check if all venvs exist in cache -# ============================================================================ - -cache_complete() { - for server in "${MCP_SERVERS[@]}"; do - local venv_python="$VENV_CACHE_DIR/$server/.venv/bin/python" - [[ ! -f "$venv_python" ]] && return 1 - done - return 0 -} - -# ============================================================================ -# Create symlinks from marketplace to cache -# ============================================================================ - -create_symlink() { - local server_name="$1" - local server_path="$REPO_ROOT/mcp-servers/$server_name" - local venv_cache="$VENV_CACHE_DIR/$server_name/.venv" - local venv_link="$server_path/.venv" - - # Skip if server doesn't exist - [[ ! -d "$server_path" ]] && return 0 - - # Skip if cache doesn't exist - [[ ! -d "$venv_cache" ]] && return 1 - - # Already correct symlink? - if [[ -L "$venv_link" ]]; then - local target - target=$(readlink "$venv_link") - [[ "$target" == "$venv_cache" ]] && return 0 - rm "$venv_link" - elif [[ -d "$venv_link" ]]; then - # Old venv directory exists - back it up or remove - rm -rf "$venv_link" - fi - - # Create symlink - ln -s "$venv_cache" "$venv_link" - return 0 -} - -create_all_symlinks() { - local created=0 - for server in "${MCP_SERVERS[@]}"; do - if create_symlink "$server"; then - ((created++)) || true - fi - done - [[ $created -gt 0 ]] && log "Restored $created venv symlinks" -} - -# ============================================================================ -# Full setup (only if cache missing) -# ============================================================================ - -setup_server() { - local server_name="$1" - local server_path="$REPO_ROOT/mcp-servers/$server_name" - local venv_path="$VENV_CACHE_DIR/$server_name/.venv" - - [[ ! -d "$server_path" ]] && return 0 - - mkdir -p "$VENV_CACHE_DIR/$server_name" - - # Create venv - if [[ ! -d "$venv_path" ]]; then - python3 -m venv "$venv_path" - fi - - # Install dependencies - # shellcheck disable=SC1091 - source "$venv_path/bin/activate" - pip install -q --upgrade pip - - if [[ -f "$server_path/requirements.txt" ]]; then - pip install -q -r "$server_path/requirements.txt" - fi - - if [[ -f "$server_path/pyproject.toml" ]]; then - pip install -q -e "$server_path" - fi - - deactivate - - # Save hash for future quick checks - local hash_file="$VENV_CACHE_DIR/$server_name/.requirements_hash" - { - if [[ -f "$server_path/requirements.txt" ]]; then - cat "$server_path/requirements.txt" - fi - if [[ -f "$server_path/pyproject.toml" ]]; then - cat "$server_path/pyproject.toml" - fi - echo "" # Ensure non-empty input for sha256sum - } | sha256sum | cut -d' ' -f1 > "$hash_file" -} - -full_setup() { - log "First run - setting up MCP venvs (this only happens once)..." - for server in "${MCP_SERVERS[@]}"; do - log " Setting up $server..." - setup_server "$server" - done - log "Setup complete. Future sessions will be instant." -} - -# ============================================================================ -# Main -# ============================================================================ - -main() { - # Fast path: cache exists, just ensure symlinks - if cache_complete; then - create_all_symlinks - exit 0 - fi - - # Slow path: need to create venvs (first install) - full_setup - create_all_symlinks -} - -main "$@"